fix(scripts): add CI annotations and step summary to copyright header check

[WilliamBerryiii]

Added per-file Write-CIAnnotation calls and a Write-CIStepSummary block to Test-CopyrightHeaders.ps1, aligning its GitHub Actions output with the existing pattern in Invoke-PSScriptAnalyzer.ps1. Added 9 Pester tests covering the new CI output behavior.

Description

• Emitted Write-CIAnnotation per failing file with missing header type details, warning level, file path, and line number.
• Appended a Write-CIStepSummary markdown block with a pass/fail status, compliance metrics table, and per-file failure details.
• Added 9 Pester tests across two Describe blocks (CI Annotations and Step Summary) validating annotation invocation counts, parameter filters, and summary content.

Related Issue(s)

Fixes #630

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 24 Pester tests pass, including 9 new tests covering CI annotation and step summary output.
• PSScriptAnalyzer reports zero warnings with project settings (scripts/linting/PSScriptAnalyzer.psd1).

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

The implementation follows the CI output pattern established by Invoke-PSScriptAnalyzer.ps1, using the shared CIHelpers module functions (Write-CIAnnotation, Write-CIStepSummary) that are already imported by the script.

🔧 - Generated by Copilot

[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.
✅ Project coverage is 85.13%. Comparing base (9d3b71d) to head (9bb6f98).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #638      +/-   ##
==========================================
+ Coverage   85.10%   85.13%   +0.02%     
==========================================
  Files          23       23              
  Lines        4491     4506      +15     
==========================================
+ Hits         3822     3836      +14     
- Misses        669      670       +1     

Flag	Coverage Δ
pester	85.13% <100.00%> (+0.02%)	⬆️

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

Files with missing lines	Coverage Δ
scripts/linting/Test-CopyrightHeaders.ps1	88.99% <100.00%> (+1.75%)	⬆️

... 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 improves the CI ergonomics of the copyright-header lint by emitting GitHub Actions/AzDO annotations per failing file and adding a Markdown step summary, mirroring the CI output pattern used by other linting scripts.

Changes:

• Emit Write-CIAnnotation warnings per file that is missing required headers.
• Add a Write-CIStepSummary block with pass/fail status and a failure details table.
• Add new Pester tests validating annotation and step summary behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
scripts/linting/Test-CopyrightHeaders.ps1	Adds per-file CI annotations and a CI step summary for copyright header validation results.
scripts/tests/linting/Test-CopyrightHeaders.Tests.ps1	Adds unit tests to validate the new annotation and step summary CI output behavior.

[WilliamBerryiii]

Review Comment Responses

Thanks for the review. Addressed the path issues in dd65682, declining the others based on codebase conventions.

✅ Fixed: Annotation file path is scan-relative (Comment 4)

Changed Write-CIAnnotation -File $fileResult.file to -File $file.FullName, matching the pattern in Invoke-PSScriptAnalyzer.ps1 which passes the absolute path and lets GitHub Actions strip the workspace root.

✅ Fixed: Step summary table paths are scan-relative (Comment 5)

Added fullPath property to the result hashtable and use it in the failure table. Paths now resolve correctly regardless of the -Path argument.

🚫 Declined: Success path missing metrics table (Comment 1)

The success-path step summary intentionally uses a simple status line without a metrics table. This matches every peer script in scripts/linting/:

• Invoke-PSScriptAnalyzer.ps1 → "✅ Status: Passed — All N files passed linting checks."
• Invoke-YamlLint.ps1 → "✅ Status: Passed — All N files passed validation."
• Invoke-LinkLanguageCheck.ps1 → "✅ Status: Passed — No URLs detected."

Metrics tables appear only on the failure path across all linting scripts.

🚫 Declined: Brittle -Exactly assertions (Comments 2 & 3)

-Exactly is the exclusive convention in this test suite:

• 19 occurrences of -Exactly across 4 test files
• 0 occurrences of -AtLeast anywhere in the repo
• Invoke-YamlLint.Tests.ps1 uses -Times N without a modifier, which Pester defaults to -Exactly behavior

Switching to -AtLeast would be inconsistent with the codebase and reduce test precision.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

The new step summary is only written after scanning at least one file. If $filesToCheck.Count -eq 0, the function returns earlier (no step summary), which can still leave the GitHub Actions job summary empty in some configurations (e.g., restrictive -FileExtensions / -ExcludePaths). Consider emitting a minimal Write-CIStepSummary before returning in the "no files found" branch so CI output is consistent.

Suggested change

	if ($output.filesMissingHeaders -eq 0) {
	if ($output.totalFiles -eq 0) {
	Write-CIStepSummary -Content @"
	ℹ️ **Status**: No files were checked
	No files matched the configured filters. Ensure this is expected for this run.
	"@
	}
	elseif ($output.filesMissingHeaders -eq 0) {

[Copilot]

The step-summary table later rebuilds the same missing-header label list that’s used to form this annotation message. To avoid drift (e.g., if required headers change), consider centralizing the missing-header computation (e.g., store missingHeaders on $fileResult or extract a helper).