fix(scripts): add FooterExcludePaths parameter to frontmatter validation (#334)

# Pull Request

## Description

Add `FooterExcludePaths` parameter to frontmatter validation, enabling
per-file exclusion from footer validation without skipping footer checks
entirely.

**Changes:**

- Add `FooterExcludePaths` parameter to `Test-SingleFileFrontmatter`
with wildcard pattern support
- Thread parameter through `Invoke-FrontmatterValidation` and
`Validate-MarkdownFrontmatter.ps1`
- Add `footer-exclude-paths` workflow input with `CHANGELOG.md` default
(comma-separated list support)
- Normalize path separators for cross-platform pattern matching (forward
slashes)
- Add 6 unit tests covering exclusion logic, non-excluded files,
wildcard patterns, and parameter threading

## Related Issue(s)

Closes #333

## Type of Change

Select all that apply:

**Code & Documentation:**

- [x] 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:**

- [x] 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`)

**Other:**

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

## Testing

- **Unit tests**: 4 new tests in `FrontmatterValidation.Tests.ps1`
covering `Test-SingleFileFrontmatter` footer exclusion behavior
- **Integration tests**: 2 new tests in
`Validate-MarkdownFrontmatter.Tests.ps1` verifying parameter threading
to module
- **All tests pass**: 237 total Pester tests execute successfully
- **PSScriptAnalyzer**: Clean analysis with no issues

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

### 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] Link validation: `npm run lint:md-links`
- [x] PowerShell analysis: `npm run lint:ps`

## Security Considerations

- [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 `FooterExcludePaths` parameter uses PowerShell's `-like` operator
for pattern matching, supporting wildcards (`*`, `?`). Path separators
are normalized to forward slashes for consistent cross-platform
behavior.

Default workflow configuration excludes `CHANGELOG.md` from footer
validation since changelog files follow their own formatting
conventions.

Author: WilliamBerryiii

.github/workflows/frontmatter-validation.yml

@@ -23,6 +23,11 @@ on:
         required: false
         type: boolean
         default: true
+      footer-exclude-paths:
+        description: 'Comma-separated list of file patterns to exclude from footer validation'
+        required: false
+        type: string
+        default: 'CHANGELOG.md'
 
 permissions:
   contents: read
@@ -65,6 +70,12 @@ jobs:
             $params['WarningsAsErrors'] = $true
           }
           
+          # Parse footer exclude paths from comma-separated input
+          $footerExcludeInput = '${{ inputs.footer-exclude-paths }}'
+          if ($footerExcludeInput -and $footerExcludeInput -ne '') {
+            $params['FooterExcludePaths'] = $footerExcludeInput -split ',' | ForEach-Object { $_.Trim() }
+          }
+          
           # Exclude test fixture files (intentionally invalid frontmatter for testing)
           $params['ExcludePaths'] = @('scripts/tests/Fixtures/**')
           

scripts/linting/Modules/FrontmatterValidation.psm1

@@ -783,6 +783,10 @@ function Test-SingleFileFrontmatter {
         Repository root path for relative path computation and file classification.
     .PARAMETER FileReader
         Optional scriptblock for reading file content. Enables testing.
+    .PARAMETER FooterExcludePaths
+        Array of wildcard patterns for files to exclude from footer validation.
+        Uses PowerShell -like operator for matching against relative paths.
+        Path separators are normalized to forward slashes for cross-platform support.
     .OUTPUTS
         FileValidationResult
     #>
@@ -799,6 +803,8 @@ function Test-SingleFileFrontmatter {
 
         [scriptblock]$FileReader = { param($p) Get-Content -Path $p -Raw -ErrorAction Stop },
 
+        [string[]]$FooterExcludePaths = @(),
+
         [switch]$SkipFooterValidation
     )
 
@@ -891,8 +897,20 @@ function Test-SingleFileFrontmatter {
         }
     }
 
+    # Check if file matches footer exclusion pattern
+    # Normalize path separators for cross-platform pattern matching
+    $skipFooterForFile = $false
+    $normalizedRelativePath = $relativePath -replace '\\', '/'
+    foreach ($pattern in $FooterExcludePaths) {
+        $normalizedPattern = $pattern -replace '\\', '/'
+        if ($normalizedRelativePath -like $normalizedPattern) {
+            $skipFooterForFile = $true
+            break
+        }
+    }
+
     # Footer validation for all markdown EXCEPT AI artifacts (prompts, instructions, agents, chatmodes)
-    if (-not $isAiArtifact -and -not $SkipFooterValidation) {
+    if (-not $isAiArtifact -and -not $SkipFooterValidation -and -not $skipFooterForFile) {
         # Determine severity based on file type
         $footerSeverity = 'Warning'
         if ($fileTypeInfo.IsRootCommunityFile -or $fileTypeInfo.IsDevContainer -or $fileTypeInfo.IsVSCodeReadme) {
@@ -924,6 +942,11 @@ function Invoke-FrontmatterValidation {
     .PARAMETER RepoRoot
         Repository root path for relative path computation and file classification.
 
+    .PARAMETER FooterExcludePaths
+        Array of wildcard patterns for files to exclude from footer validation.
+        Uses PowerShell -like operator for matching against relative paths.
+        Path separators are normalized to forward slashes for cross-platform support.
+
     .OUTPUTS
         ValidationSummary
     #>
@@ -937,13 +960,15 @@ function Invoke-FrontmatterValidation {
         [ValidateNotNullOrEmpty()]
         [string]$RepoRoot,
 
+        [string[]]$FooterExcludePaths = @(),
+
         [switch]$SkipFooterValidation
     )
 
     $summary = [ValidationSummary]::new()
 
     foreach ($file in $Files) {
-        $result = Test-SingleFileFrontmatter -FilePath $file -RepoRoot $RepoRoot -SkipFooterValidation:$SkipFooterValidation
+        $result = Test-SingleFileFrontmatter -FilePath $file -RepoRoot $RepoRoot -FooterExcludePaths $FooterExcludePaths -SkipFooterValidation:$SkipFooterValidation
         $summary.AddResult($result)
     }
 

scripts/linting/Validate-MarkdownFrontmatter.ps1

@@ -39,6 +39,9 @@ param(
     [Parameter(Mandatory = $false)]
     [switch]$EnableSchemaValidation,
 
+    [Parameter(Mandatory = $false)]
+    [string[]]$FooterExcludePaths = @(),
+
     [Parameter(Mandatory = $false)]
     [switch]$SkipFooterValidation
 )
@@ -464,6 +467,11 @@ function Test-FrontmatterValidation {
     .PARAMETER EnableSchemaValidation
     Enable JSON Schema validation (advisory only).
 
+    .PARAMETER FooterExcludePaths
+    Array of wildcard patterns for files to exclude from footer validation only.
+    Uses PowerShell -like operator for matching against relative paths.
+    Path separators are normalized to forward slashes for cross-platform support.
+
     .OUTPUTS
     ValidationSummary from FrontmatterValidation module.
     #>
@@ -476,6 +484,7 @@ function Test-FrontmatterValidation {
         [switch]$ChangedFilesOnly,
         [string]$BaseBranch = "origin/main",
         [switch]$EnableSchemaValidation,
+        [string[]]$FooterExcludePaths = @(),
         [switch]$SkipFooterValidation
     )
 
@@ -550,7 +559,7 @@ function Test-FrontmatterValidation {
     Write-Host "Found $($resolvedFiles.Count) total markdown files to validate" -ForegroundColor Cyan
 
     # Use module's orchestration function for core validation
-    $summary = Invoke-FrontmatterValidation -Files $resolvedFiles -RepoRoot $repoRoot -SkipFooterValidation:$SkipFooterValidation
+    $summary = Invoke-FrontmatterValidation -Files $resolvedFiles -RepoRoot $repoRoot -FooterExcludePaths $FooterExcludePaths -SkipFooterValidation:$SkipFooterValidation
 
     # Optional schema validation overlay (advisory only)
     # Uses frontmatter already parsed by Invoke-FrontmatterValidation
@@ -726,13 +735,13 @@ function Get-ChangedMarkdownFileGroup {
 try {
     if ($MyInvocation.InvocationName -ne '.') {
         if ($ChangedFilesOnly) {
-            $result = Test-FrontmatterValidation -ChangedFilesOnly -BaseBranch $BaseBranch -ExcludePaths $ExcludePaths -WarningsAsErrors:$WarningsAsErrors -EnableSchemaValidation:$EnableSchemaValidation -SkipFooterValidation:$SkipFooterValidation
+            $result = Test-FrontmatterValidation -ChangedFilesOnly -BaseBranch $BaseBranch -ExcludePaths $ExcludePaths -WarningsAsErrors:$WarningsAsErrors -EnableSchemaValidation:$EnableSchemaValidation -FooterExcludePaths $FooterExcludePaths -SkipFooterValidation:$SkipFooterValidation
         }
         elseif ($Files.Count -gt 0) {
-            $result = Test-FrontmatterValidation -Files $Files -ExcludePaths $ExcludePaths -WarningsAsErrors:$WarningsAsErrors -EnableSchemaValidation:$EnableSchemaValidation -SkipFooterValidation:$SkipFooterValidation
+            $result = Test-FrontmatterValidation -Files $Files -ExcludePaths $ExcludePaths -WarningsAsErrors:$WarningsAsErrors -EnableSchemaValidation:$EnableSchemaValidation -FooterExcludePaths $FooterExcludePaths -SkipFooterValidation:$SkipFooterValidation
         }
         else {
-            $result = Test-FrontmatterValidation -Paths $Paths -ExcludePaths $ExcludePaths -WarningsAsErrors:$WarningsAsErrors -EnableSchemaValidation:$EnableSchemaValidation -SkipFooterValidation:$SkipFooterValidation
+            $result = Test-FrontmatterValidation -Paths $Paths -ExcludePaths $ExcludePaths -WarningsAsErrors:$WarningsAsErrors -EnableSchemaValidation:$EnableSchemaValidation -FooterExcludePaths $FooterExcludePaths -SkipFooterValidation:$SkipFooterValidation
         }
 
         # Normalize result: if pipeline output produced an array, extract the ValidationSummary object

scripts/tests/linting/FrontmatterValidation.Tests.ps1

@@ -1310,6 +1310,74 @@ description: Test
             $result.RelativePath | Should -Be $expectedPath
         }
     }
+
+    Context 'Footer exclude paths' {
+        It 'Skips footer validation for file matching exclusion pattern' {
+            $mockContent = @"
+---
+title: Changelog
+description: Release history
+---
+
+# Changelog
+
+No Copilot footer here
+"@
+            $testFile = Join-Path $script:TestRepoRoot 'CHANGELOG.md'
+            $result = Test-SingleFileFrontmatter `
+                -FilePath $testFile `
+                -RepoRoot $script:TestRepoRoot `
+                -FooterExcludePaths @('CHANGELOG.md') `
+                -FileReader { $mockContent }.GetNewClosure()
+
+            # File without footer should NOT have footer error when excluded
+            $footerIssues = $result.Issues | Where-Object { $_.Field -eq 'footer' }
+            $footerIssues | Should -BeNullOrEmpty
+        }
+
+        It 'Applies footer validation for non-excluded files' {
+            $mockContent = @"
+---
+title: Test Doc
+description: Test description
+---
+
+# Content
+
+No Copilot footer here
+"@
+            $testFile = Join-Path $script:TestRepoRoot 'docs' 'guide.md'
+            $result = Test-SingleFileFrontmatter `
+                -FilePath $testFile `
+                -RepoRoot $script:TestRepoRoot `
+                -FooterExcludePaths @('CHANGELOG.md') `
+                -FileReader { $mockContent }.GetNewClosure()
+
+            # Non-excluded file without footer should have footer error
+            $footerIssues = $result.Issues | Where-Object { $_.Field -eq 'footer' }
+            $footerIssues | Should -Not -BeNullOrEmpty
+        }
+
+        It 'Supports wildcard patterns in exclusions' {
+            $mockContent = @"
+---
+title: Test
+description: Test
+---
+
+No footer
+"@
+            $testFile = Join-Path $script:TestRepoRoot 'logs' 'output.md'
+            $result = Test-SingleFileFrontmatter `
+                -FilePath $testFile `
+                -RepoRoot $script:TestRepoRoot `
+                -FooterExcludePaths @('logs/*.md') `
+                -FileReader { $mockContent }.GetNewClosure()
+
+            $footerIssues = $result.Issues | Where-Object { $_.Field -eq 'footer' }
+            $footerIssues | Should -BeNullOrEmpty
+        }
+    }
 }
 
 Describe 'Invoke-FrontmatterValidation' -Tag 'Unit' {
@@ -1437,6 +1505,29 @@ Describe 'Invoke-FrontmatterValidation' -Tag 'Unit' {
             $summary.TotalFiles | Should -Be 1
         }
     }
+
+    Context 'FooterExcludePaths threading' {
+        It 'Passes FooterExcludePaths to Test-SingleFileFrontmatter' {
+            $capturedParams = @{}
+
+            Mock Test-SingleFileFrontmatter -ModuleName FrontmatterValidation {
+                $capturedParams.FooterExcludePaths = $FooterExcludePaths
+                & (Get-Module FrontmatterValidation) {
+                    param($path)
+                    $r = [FileValidationResult]::new($path)
+                    $r.HasFrontmatter = $true
+                    return $r
+                } $FilePath
+            }
+
+            $null = Invoke-FrontmatterValidation `
+                -Files @("$script:TestRepoRoot\file.md") `
+                -RepoRoot $script:TestRepoRoot `
+                -FooterExcludePaths @('CHANGELOG.md', 'logs/*.md')
+
+            $capturedParams.FooterExcludePaths | Should -Be @('CHANGELOG.md', 'logs/*.md')
+        }
+    }
 }
 
 #endregion

scripts/tests/linting/Validate-MarkdownFrontmatter.Tests.ps1

@@ -1055,6 +1055,29 @@ Content
             $relativePath -like $pattern | Should -BeTrue
         }
     }
+
+    Context 'FooterExcludePaths integration' {
+        It 'Passes FooterExcludePaths to Invoke-FrontmatterValidation' {
+            $testFile = Join-Path $TestDrive 'CHANGELOG.md'
+            Set-Content $testFile "---`ndescription: Release history`n---`n# Changelog`n`nNo footer here"
+
+            # File should not have footer error when excluded (use wildcard to match filename in any path)
+            $result = Test-FrontmatterValidation -Files @($testFile) -FooterExcludePaths @('*CHANGELOG.md')
+            $footerErrors = $result.Results | ForEach-Object { $_.Issues } | Where-Object { $_.Field -eq 'footer' }
+            $footerErrors | Should -BeNullOrEmpty
+        }
+
+        It 'Applies footer validation to non-excluded files' {
+            $testFile = Join-Path $TestDrive 'docs' 'guide.md'
+            New-Item -ItemType Directory -Path (Join-Path $TestDrive 'docs') -Force | Out-Null
+            Set-Content $testFile "---`ndescription: Test guide`n---`n# Guide`n`nNo footer here"
+
+            # Non-excluded file should have footer error
+            $result = Test-FrontmatterValidation -Files @($testFile) -FooterExcludePaths @('*CHANGELOG.md')
+            $footerErrors = $result.Results | ForEach-Object { $_.Issues } | Where-Object { $_.Field -eq 'footer' }
+            $footerErrors | Should -Not -BeNullOrEmpty
+        }
+    }
 }
 
 #endregion