Summary

Refactor 7 linting scripts to use the shared CIHelpers.psm1 module, removing approximately 15 inline CI annotation patterns across all scripts. These scripts all follow the same simple pattern (catch block annotations), making them suitable for batch refactoring.

Prerequisites

• Create CIHelpers.psm1 shared module for CI platform detection and output #287 - Create CIHelpers.psm1 shared module (must be completed first)

Problem

All linting scripts contain similar inline CI patterns in their catch blocks:

catch {
    if ($env:GITHUB_ACTIONS -eq 'true') {
        Write-Output "::error::$($_.Exception.Message)"
    }
    throw
}

Scripts and pattern counts

Total: ~15 patterns across 7 scripts

Common patterns to replace

Pattern 1: Catch block error annotation

# Before
catch {
    if ($env:GITHUB_ACTIONS -eq 'true') {
        Write-Output "::error::$($_.Exception.Message)"
    }
    throw
}

# After  
catch {
    Write-CIAnnotation -Type error -Message $_.Exception.Message
    throw
}

Pattern 2: Warning annotations with file location

# Before
if ($env:GITHUB_ACTIONS -eq 'true') {
    Write-Output "::warning file=$file,line=$line::$message"
}

# After
Write-CIAnnotation -Type warning -Message $message -File $file -Line $line

Pattern 3: Environment detection conditionals

# Before
if ($env:GITHUB_ACTIONS -eq 'true') {
    # CI-specific logic
}

# After
if (Test-CIEnvironment) {
    # CI-specific logic
}

Solution

Step 1: Add module import to all scripts

Add after the param() block in each script:

# Import shared CI helpers module
$ciHelpersPath = Join-Path $PSScriptRoot "../lib/Modules/CIHelpers.psm1"
Import-Module $ciHelpersPath -Force

Note: Adjust relative path based on script location (../lib/ for scripts in linting/).

Step 2: Replace patterns in each script

Validate-MarkdownFrontmatter.ps1

This script has 3 patterns including validation result annotations:

# Replace error output in validation results
foreach ($result in $failures) {
    Write-CIAnnotation -Type error -Message $result.Message -File $result.File -Line $result.Line
}

Invoke-LinkLanguageCheck.ps1, Invoke-PSScriptAnalyzer.ps1, Invoke-YamlLint.ps1

Standard catch block replacement:

catch {
    Write-CIAnnotation -Type error -Message $_.Exception.Message
    throw
}

Link-Lang-Check.ps1, Markdown-Link-Check.ps1

Standard catch block plus any result annotations:

# For link check failures
foreach ($broken in $brokenLinks) {
    Write-CIAnnotation -Type warning -Message "Broken link: $($broken.Url)" -File $broken.File -Line $broken.Line
}

Testing Requirements

Update test files

Each script has a corresponding test file in scripts/tests/linting/:

Standard test pattern for all scripts

Add to each test file's BeforeAll block:

BeforeAll {
    # Mock CIHelpers functions
    Mock Write-CIAnnotation { }
    Mock Test-CIEnvironment { return $false }
    Mock Get-CIPlatform { return 'Local' }
}

Add CI annotation tests

Describe 'CI Integration' {
    Context 'Error handling' {
        It 'Writes error annotation on exception' {
            # Trigger error condition
            { ./Script.ps1 -InvalidParam } | Should -Throw
            Should -Invoke Write-CIAnnotation -ParameterFilter { $Type -eq 'error' }
        }
    }

    Context 'Validation results' {
        It 'Writes annotations for failures' {
            # Run with files that will fail validation
            Should -Invoke Write-CIAnnotation -ParameterFilter { $Type -eq 'warning' -or $Type -eq 'error' }
        }
    }
}

Coverage targets

All scripts must reach 80%+ test coverage.

Run validation

# Run all linting tests with coverage
Invoke-Pester -Path scripts/tests/linting/ -Output Detailed -CodeCoverage @(
    'scripts/linting/Validate-MarkdownFrontmatter.ps1',
    'scripts/linting/Invoke-LinkLanguageCheck.ps1',
    'scripts/linting/Invoke-PSScriptAnalyzer.ps1',
    'scripts/linting/Invoke-YamlLint.ps1',
    'scripts/linting/Link-Lang-Check.ps1',
    'scripts/linting/Markdown-Link-Check.ps1'
)

# Verify no inline CI patterns remain
$patterns = '::error|::warning|::notice|##vso\[|GITHUB_ACTIONS|TF_BUILD'
Select-String -Path scripts/linting/*.ps1 -Pattern $patterns -Exclude '*.Tests.ps1' | Should -BeNullOrEmpty

Acceptance Criteria

• All 7 scripts import CIHelpers.psm1 module
• All ~15 inline CI patterns replaced with CIHelpers function calls
• No $env:GITHUB_ACTIONS, $env:TF_BUILD checks remain in script files
• No ::error::, ::warning::, ##vso[ string patterns remain
• All 6 test files updated with CIHelpers mocks
• CI annotation tests added to all test files
• Test coverage reaches 80%+ for all 7 scripts
• All linting npm scripts remain functional:
  • npm run lint:frontmatter
  • npm run lint:links
  • npm run psscriptanalyzer
  • npm run lint:yaml
• PSScriptAnalyzer passes with no errors

Files Changed

Scripts (7)

• scripts/linting/Validate-MarkdownFrontmatter.ps1
• scripts/linting/Invoke-LinkLanguageCheck.ps1
• scripts/linting/Invoke-PSScriptAnalyzer.ps1
• scripts/linting/Invoke-YamlLint.ps1
• scripts/linting/Link-Lang-Check.ps1
• scripts/linting/Markdown-Link-Check.ps1

Tests (6)

• scripts/tests/linting/Validate-MarkdownFrontmatter.Tests.ps1
• scripts/tests/linting/Invoke-LinkLanguageCheck.Tests.ps1
• scripts/tests/linting/Invoke-PSScriptAnalyzer.Tests.ps1
• scripts/tests/linting/Invoke-YamlLint.Tests.ps1
• scripts/tests/linting/Link-Lang-Check.Tests.ps1
• scripts/tests/linting/Markdown-Link-Check.Tests.ps1

Related Issues

• Create CIHelpers.psm1 shared module for CI platform detection and output #287 - CIHelpers module creation (prerequisite)
• refactor: Remove duplicate git diff logic in Validate-MarkdownFrontmatter.ps1 #322 - Validate-MarkdownFrontmatter duplicate removal (can be combined or sequenced)
• refactor(scripts): refactor Test-DependencyPinning.ps1 to use CIHelpers module #349 - Test-DependencyPinning refactoring (related)
• [Issue]: Refactor extension scripts to use CIHelpers module #350 - Extension scripts refactoring (related)