Pull Request

Description

Standardized all PowerShell entry point guards across the repository to use a single canonical pattern: if ($MyInvocation.InvocationName -ne '.') wrapping try/catch. Removed the legacy $script:SkipMain / HVE_SKIP_MAIN environment variable mechanism and extracted orchestrator functions from scripts that previously embedded logic directly in their main blocks.

Key changes:

• Adopted canonical if-wraps-try guard pattern (if ($MyInvocation.InvocationName -ne '.') { try { ... } catch { ... } }) across 16 production scripts
• Removed $script:SkipMain and $env:HVE_SKIP_MAIN from 6 scripts that used the environment variable mechanism
• Extracted named orchestrator functions (Invoke-VideoConversion, Invoke-PSScriptAnalyzerCore, Invoke-YamlLintCore, Invoke-LinkLanguageCheck, Invoke-MarkdownLinkCheck, Invoke-CopyrightHeaderCheck, Invoke-ActionVersionConsistencyCheck, Invoke-DependencyPinningAnalysis) for direct testability
• Swapped if/try ordering to canonical form in scripts that had try-wraps-if
• Added [CmdletBinding()] to functions missing the attribute
• Updated 9 test files to use dot-source pattern instead of HVE_SKIP_MAIN env var manipulation
• Documented the canonical guard pattern in scripts/README.md and scripts/linting/README.md

Related Issue(s)

Closes #325
Closes #327

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Testing

• All 900 Pester tests pass (npm run test:ps)
• All linters clean: npm run lint:md, npm run lint:ps, npm run lint:frontmatter, npm run lint:md-links
• Test files updated to call extracted orchestrator functions directly instead of using HVE_SKIP_MAIN env var
• Verified scripts execute correctly when run directly and produce no output when dot-sourced

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

Additional Notes

• This is a breaking change for any external consumers that relied on $env:HVE_SKIP_MAIN = '1' to suppress script main block execution. The new pattern uses $MyInvocation.InvocationName -ne '.' which requires dot-sourcing for function isolation.
• Test-DependencyPinning.ps1 was normalized in a separate preparatory commit (9252b08) before the main standardization commit (2a18d9a).
• Six follow-up items were identified during task review and documented for future backlog triage.

🔧 - Generated by Copilot