refactor(scripts): move collection scripts from plugins to collections

[WilliamBerryiii]

Extracted 11 collection-management functions from PluginHelpers.psm1 into a dedicated CollectionHelpers.psm1 module under scripts/collections/Modules/, establishing a clear separation between collection and plugin concerns. Relocated collection validation scripts and their tests alongside the new module, updated all consumer imports, and expanded test coverage with new suites for both the extracted module and the previously untested Validate-Marketplace.ps1 script.

Description

Module Extraction and Restructuring

The core of this change split PluginHelpers.psm1 into two focused modules. Eleven collection-related functions moved to the new CollectionHelpers.psm1: Get-AllCollections, Get-ArtifactFiles, Get-ArtifactFrontmatter, Get-CollectionArtifactKey, Get-CollectionManifest, Resolve-CollectionItemMaturity, Test-ArtifactDeprecated, Test-DeprecatedPath, Test-HveCoreRepoRelativePath, Test-HveCoreRepoSpecificPath, and Update-HveCoreAllCollection. The trimmed PluginHelpers.psm1 retained only plugin-specific operations (symlink, manifest, packaging) and added a backward-compatible re-import of CollectionHelpers.psm1 so existing consumers continue to work during transition.

Script Relocation and Consumer Updates

Renamed Validate-Collections.ps1 from scripts/plugins/ to scripts/collections/ and updated its import to reference CollectionHelpers.psm1. The previously local Resolve-ItemMaturity helper was consolidated into the extracted Resolve-CollectionItemMaturity function. Four consumer scripts received import path updates:

• Package-Extension.ps1 and Prepare-Extension.ps1 switched from PluginHelpers.psm1 to CollectionHelpers.psm1
• Generate-Plugins.ps1 added CollectionHelpers.psm1 as a second import alongside PluginHelpers.psm1
• Updated the lint:collections-metadata npm script path in package.json

Test Coverage Expansion

Created CollectionHelpers.Tests.ps1 (564 lines) covering all 11 extracted functions with Describe blocks for path exclusion, deprecated handling, maturity resolution, frontmatter parsing, and Update-HveCoreAllCollection workflows including DryRun safety. Relocated Validate-Collections.Tests.ps1 from scripts/tests/plugins/ to scripts/tests/collections/ and removed the superseded Resolve-ItemMaturity test block. Removed ~270 lines of tests from PluginHelpers.Tests.ps1 for functions that moved to CollectionHelpers.

Created Validate-Marketplace.Tests.ps1 (354 lines, 15 Describe blocks) covering marketplace manifest validation: format checks, required fields, version consistency, duplicate detection, and source directory verification.

Added 'collections' to coverage directories in pester.config.ps1 and introduced a defensive CollectionHelpers.psm1 re-import in Generate-Plugins.Tests.ps1 to handle PowerShell module scope invalidation from nested -Force imports. Overall test coverage improved from 82.70% to 84.12% across 1,500 tests with zero failures.

Documentation

Updated the Scripts Organization section in .github/copilot-instructions.md with the new scripts/collections/ entry. Revised scripts/README.md directory tree, scripts table, and tests table. Narrowed scripts/plugins/README.md to plugin-only content. Created scripts/collections/README.md with directory documentation, scripts table, and prerequisites.

Related Issue(s)

Related to #521

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)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
• See Agents Not Accepted and Model Version Requirements.

Other:

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

Sample Prompts (for AI Artifact Contributions)

Testing

All 11 extracted functions have dedicated test coverage in CollectionHelpers.Tests.ps1. The new Validate-Marketplace.Tests.ps1 provides 15 Describe blocks covering format validation, required fields, version consistency, duplicate detection, and source directory verification. Existing Validate-Collections.Tests.ps1 was relocated and updated to match the new module structure. Coverage configuration in pester.config.ps1 was updated to include the scripts/collections/ directory.

Full suite: 1,500 tests, 0 failures, 84.12% code coverage (up from 82.70%).

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)

AI Artifact Contributions

• Used /prompt-analyze to review contribution
• Addressed all feedback from prompt-builder review
• Verified contribution follows common standards and type-specific requirements

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
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps
• Plugin freshness: npm run plugin:generate

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

The backward-compatible re-import in PluginHelpers.psm1 (Import-Module CollectionHelpers) ensures existing callers continue to resolve collection functions during transition. This bridge can be removed once all downstream consumers reference CollectionHelpers.psm1 directly.

[github-actions]

Dependency Review

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

Scanned Files

None

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@0a600ba). Learn more about missing BASE report.
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #728   +/-   ##
=======================================
  Coverage        ?   86.59%           
=======================================
  Files           ?       25           
  Lines           ?     4893           
  Branches        ?        0           
=======================================
  Hits            ?     4237           
  Misses          ?      656           
  Partials        ?        0           

Flag	Coverage Δ
pester	86.59% <100.00%> (?)

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

Files with missing lines	Coverage Δ
scripts/collections/Modules/CollectionHelpers.psm1	100.00% <100.00%> (ø)
scripts/collections/Validate-Collections.ps1	91.36% <100.00%> (ø)
scripts/extension/Package-Extension.ps1	96.02% <100.00%> (ø)
scripts/extension/Prepare-Extension.ps1	94.45% <100.00%> (ø)
scripts/plugins/Generate-Plugins.ps1	96.11% <100.00%> (ø)
scripts/plugins/Modules/PluginHelpers.psm1	78.44% <100.00%> (ø)

🚀 New features to boost your workflow:

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