fix(scripts): include CIHelpers module + packaging script testability

[WilliamBerryiii]

Pull Request

Description

Add CIHelpers.psm1 to the VS Code extension package so Generate-PrReference.ps1 can resolve its module import when run from the installed extension. The script requires this module for Git operations and fails when the module is missing from the package.

Initial Bug Fix:

• Add whitelist entry !scripts/lib/Modules/CIHelpers.psm1 to .vscodeignore
• Add copy logic in Package-Extension.ps1 to include the module during staging
• Fix vsce execution bug where PowerShell misinterpreted @ in @vscode/vsce as splatting operator by wrapping npx calls with cmd /c

Scope Expansion: Packaging Script Testability

During code review, Copilot identified that the CIHelpers validation could fail silently. Investigation revealed broader testability issues with Invoke-PackageExtension:

Metric	Before	After
Function length	~200 lines	~80 lines
Cyclomatic complexity	18-22	8-10
Test coverage	~50%	80%+

Refactoring Changes:

• Explicit error when CIHelpers.psm1 is missing during packaging
• Extract pure validation and specification functions
• Make platform-specific code injectable for testing
• Add individual Pester tests for extracted functions

Research document: .copilot-tracking/research/package-extension-testability.md

Related Issue(s)

Fixes #400

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

• PSScriptAnalyzer linting passed (all 41 files)
• All Package-Extension.ps1 tests pass
• Extension packaging verified working (produces hve-core-2.1.0.vsix, 227.14 KB)
• CIHelpers.psm1 confirmed present in packaged extension
• Individual tests for extracted helper functions

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

Root cause of vsce execution fix: PowerShell interprets @ at the start of arguments as splatting syntax. When npx @vscode/vsce was invoked via & $executable $args, PowerShell tried to expand @vscode as a variable. The fix uses cmd /c to pass arguments through Windows command processor, bypassing PowerShell's parsing.

Testability refactoring rationale: The monolithic Invoke-PackageExtension function has 13 distinct responsibilities and cyclomatic complexity 18-22, making comprehensive testing difficult. Extracting pure functions for validation and specifications enables unit testing without filesystem mocking.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.46835% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.41%. Comparing base (f3bb787) to head (4473606).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
scripts/extension/Package-Extension.ps1	97.46%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #420      +/-   ##
==========================================
+ Coverage   75.15%   75.41%   +0.26%     
==========================================
  Files          20       20              
  Lines        3481     3527      +46     
==========================================
+ Hits         2616     2660      +44     
- Misses        865      867       +2     

Flag	Coverage Δ
pester	75.41% <97.46%> (+0.26%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
scripts/extension/Package-Extension.ps1	93.24% <97.46%> (+1.10%)	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR fixes a critical bug where the VS Code extension package was missing the CIHelpers.psm1 module required by Generate-PrReference.ps1, causing the script to fail when run from the installed extension. The fix ensures the module is included in the extension package and addresses a PowerShell command execution issue with npx.

Changes:

• Added CIHelpers.psm1 to extension package via .vscodeignore whitelist and copy logic in Package-Extension.ps1
• Fixed npx execution to use cmd /c wrapper to bypass PowerShell's argument parsing issues
• Added --yes flag to npx to suppress interactive prompts

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
extension/.vscodeignore	Added whitelist entry for scripts/lib/Modules/CIHelpers.psm1 to include the module in the vsce package
scripts/extension/Package-Extension.ps1	Added copy logic for CIHelpers module, added --yes flag to npx arguments, and wrapped npx calls with cmd /c to prevent PowerShell argument parsing issues

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[katriendg]

This is great, thanks for the extensive implementation.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[Copilot]

The Invoke-VsceCommand function outputs both command stdout/stderr and a return hashtable to the pipeline. When assigned to a variable at line 756, $vsceResult could become an array containing text output plus the hashtable, causing line 762's property access ($vsceResult.Success) to fail.

Consider suppressing command output by redirecting to $null or using Out-Null within the function, or explicitly filtering the return value. The test at line 647-655 shows awareness of this by filtering for hashtable type, but the production code at line 756-762 doesn't apply the same filtering.

Suggested change

	& cmd @cmdArgs
	} else {
	& $Executable @Arguments
	& cmd @cmdArgs *> $null
	} else {
	& $Executable @Arguments *> $null