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

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)
- [x] 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](../docs/contributing/skills.md).
> - **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](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).

**Other:**

- [x] Script/automation (`.ps1`, `.sh`, `.py`)
- [ ] Other (please describe):

## Sample Prompts (for AI Artifact Contributions)

<!-- Not applicable: no AI artifact contributions in this PR -->

## 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

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

### AI Artifact Contributions

<!-- Not applicable: no AI artifact contributions in this PR -->
- [ ] 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:

- [x] Markdown linting: `npm run lint:md`
- [x] Spell checking: `npm run spell-check`
- [x] Frontmatter validation: `npm run lint:frontmatter`
- [x] Skill structure validation: `npm run validate:skills`
- [x] Link validation: `npm run lint:md-links`
- [x] PowerShell analysis: `npm run lint:ps`
- [x] Plugin freshness: `npm run plugin:generate`

## Security Considerations

<!-- ⚠️ WARNING: Do not commit sensitive information such as API keys,
passwords, or personal data -->
- [x] This PR does not contain any sensitive or NDA information
- [x] Any new dependencies have been reviewed for security issues
- [x] 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.

Author: WilliamBerryiii

.github/copilot-instructions.md

@@ -50,6 +50,7 @@ The project is organized into these main areas:
 
 Scripts are organized by function:
 
+* Collections (`scripts/collections/`) - Collection validation and shared helper modules.
 * Extension (`scripts/extension/`) - Extension packaging and preparation.
 * Linting (`scripts/linting/`) - Markdown validation, link checking, frontmatter validation, and PowerShell analysis.
 * Security (`scripts/security/`) - Dependency pinning validation and SHA staleness checks.

package.json

@@ -14,7 +14,7 @@
     "lint:links": "pwsh -NoProfile -Command \"& scripts/linting/Invoke-LinkLanguageCheck.ps1 -ExcludePaths 'scripts/tests/**'\"",
     "lint:md-links": "pwsh -File scripts/linting/Markdown-Link-Check.ps1",
     "lint:frontmatter": "pwsh -NoProfile -Command \"& './scripts/linting/Validate-MarkdownFrontmatter.ps1' -WarningsAsErrors -EnableSchemaValidation\"",
-    "lint:collections-metadata": "pwsh -File scripts/plugins/Validate-Collections.ps1",
+    "lint:collections-metadata": "pwsh -File scripts/collections/Validate-Collections.ps1",
     "lint:marketplace": "pwsh -File scripts/plugins/Validate-Marketplace.ps1",
     "lint:version-consistency": "pwsh -NoProfile -Command \"./scripts/security/Test-ActionVersionConsistency.ps1 -FailOnMismatch\"",
     "lint:all": "npm run format:tables && npm run lint:md && npm run lint:ps && npm run lint:yaml && npm run lint:links && npm run lint:frontmatter && npm run lint:collections-metadata && npm run lint:marketplace && npm run lint:version-consistency && npm run validate:skills",

scripts/README.md

@@ -19,10 +19,11 @@ This directory contains PowerShell scripts for automating linting, validation, a
 
 ```text
 scripts/
+├── collections/     Collection validation and shared helpers
 ├── extension/       VS Code extension packaging utilities
 ├── lib/             Shared utility modules
 ├── linting/         PowerShell linting and validation scripts
-├── plugins/         Copilot CLI plugin generation and validation
+├── plugins/         Copilot CLI plugin generation
 ├── security/        Security scanning and SHA pinning scripts
 └── tests/           Pester test organization
 ```
@@ -69,12 +70,13 @@ The `security/` directory contains scripts for security scanning and dependency
 
 Pester test organization matching the scripts structure.
 
-| Directory    | Tests For                 |
-|--------------|---------------------------|
-| `extension/` | Extension packaging tests |
-| `lib/`       | Library utility tests     |
-| `linting/`   | Linting script tests      |
-| `security/`  | Security validation tests |
+| Directory      | Tests For                 |
+|----------------|---------------------------|
+| `collections/` | Collection helpers tests  |
+| `extension/`   | Extension packaging tests |
+| `lib/`         | Library utility tests     |
+| `linting/`     | Linting script tests      |
+| `security/`    | Security validation tests |
 
 Run all tests: