Pull Request

Description

Validate-Collections.ps1 was the only collections-facing linting script that did not write structured results to logs/. All other pipeline scripts persist JSON reports after each run; this gap meant collection validation results were lost at terminal close, blocking any tooling or CI step that reads from logs/.

Changes made:

• Added -OutputPath parameter to Validate-Collections.ps1 (default: logs/collection-validation-results.json).
• Refactored $fileErrors from plain strings to typed hashtables (ErrorType + Message), enabling specific error codes in JSON output: MissingRequiredField, InvalidIdFormat, DuplicateCollectionId, InvalidCollectionMaturity, RepoSpecificPath, PathNotFound, MissingSuffix, MissingItemKind, InvalidMaturity, IntraCollectionDuplicate.
• Introduced inner helper Add-ValidationResult that accumulates a typed results list alongside every existing Write-Host call (console output unchanged).
• Added Export-CollectionValidationReport function for path resolution, directory creation, and JSON serialization.
• Moved Create logs directory step in plugin-validation.yml to before Validate collection metadata to make workflow intent explicit.
• Expanded Pester test coverage: updated ErrorType assertion to specific type, added severity differentiation, directory creation, multiple distinct ErrorType values in one run, and clean-run Results key presence tests.

Output schema:

{
  "Timestamp": "2026-04-23T17:00:00.000Z",
  "TotalCollections": 14,
  "ErrorCount": 0,
  "Results": [
    {
      "Collection": "hve-core",
      "Severity": "Warning",
      "ErrorType": "MissingCompanionCollectionMd",
      "Message": "missing companion 'hve-core.collection.md'"
    }
  ]
}

Related Issue(s)

Closes #992.

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

Baseline runs confirmed pre-existing test suite intact; post-change runs confirmed new tests pass and JSON file is created with correct schema.

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
• Docusaurus tests: npm run docs:test

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 PR was rebased on top of the main branch which includes #1430 (structured JSON output for Validate-Marketplace.ps1). The merge conflict in package.json was resolved by combining both -OutputPath flags: lint:collections-metadata and lint:marketplace both now pass their respective output paths.