[Issue]: Refactor dev-tools and lib scripts to use CIHelpers module

[WilliamBerryiii]

Summary

Refactor Generate-PrReference.ps1 and Get-VerifiedDownload.ps1 to use the shared CIHelpers.psm1 module, removing 4 inline CI annotation patterns across both utility scripts.

Prerequisites

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

Problem

The dev-tools and lib utility scripts contain inline CI patterns in their catch blocks:

Generate-PrReference.ps1 (2 patterns)

Location: scripts/dev-tools/Generate-PrReference.ps1

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

Get-VerifiedDownload.ps1 (2 patterns)

Location: scripts/lib/Get-VerifiedDownload.ps1

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

Pattern inventory (4 total)

Script	Pattern	CIHelpers Function
Generate-PrReference.ps1	Environment detection	Test-CIEnvironment
Generate-PrReference.ps1	Error annotation	Write-CIAnnotation
Get-VerifiedDownload.ps1	Environment detection	Test-CIEnvironment
Get-VerifiedDownload.ps1	Error annotation	Write-CIAnnotation

Solution

Step 1: Add module imports

Generate-PrReference.ps1

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

Get-VerifiedDownload.ps1

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

Step 2: Replace catch block patterns

Both scripts use the same pattern:

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

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

Step 3: Additional refactoring opportunities

Get-VerifiedDownload.ps1

If the script has checksum verification warnings:

# Before
if ($env:GITHUB_ACTIONS -eq 'true') {
    Write-Output "::warning::Checksum mismatch for $FileName"
}

# After
Write-CIAnnotation -Type warning -Message "Checksum mismatch for $FileName"

Testing Requirements

Create/update test files

Script	Test File
Generate-PrReference.ps1	scripts/tests/dev-tools/Generate-PrReference.Tests.ps1
Get-VerifiedDownload.ps1	scripts/tests/lib/Get-VerifiedDownload.Tests.ps1

Note: Create test directory scripts/tests/dev-tools/ if it doesn't exist.

Test file template

BeforeAll {
    $scriptPath = "$PSScriptRoot/../../dev-tools/Generate-PrReference.ps1"  # Adjust path
    
    # Mock CIHelpers functions
    Mock Write-CIAnnotation { }
    Mock Test-CIEnvironment { return $false }
    Mock Get-CIPlatform { return 'Local' }
}

Describe 'Generate-PrReference' {
    Context 'Normal operation' {
        It 'Generates PR reference without errors' {
            # Test normal execution
        }
    }

    Context 'Error handling' {
        It 'Writes error annotation on failure' {
            # Trigger error condition
            { & $scriptPath -InvalidInput } | Should -Throw
            Should -Invoke Write-CIAnnotation -ParameterFilter { $Type -eq 'error' }
        }
    }

    Context 'CI environment' {
        BeforeEach {
            Mock Test-CIEnvironment { return $true }
            Mock Get-CIPlatform { return 'GitHub' }
        }

        It 'Uses CIHelpers for annotations in CI' {
            # Trigger warning or error
            Should -Invoke Write-CIAnnotation
        }
    }
}

Coverage targets

Script	Target Coverage
Generate-PrReference.ps1	80%+
Get-VerifiedDownload.ps1	80%+

Run validation

# Create test directory if needed
New-Item -ItemType Directory -Path scripts/tests/dev-tools -Force

# Run tests with coverage
Invoke-Pester -Path @(
    'scripts/tests/dev-tools/',
    'scripts/tests/lib/Get-VerifiedDownload.Tests.ps1'
) -Output Detailed -CodeCoverage @(
    'scripts/dev-tools/Generate-PrReference.ps1',
    'scripts/lib/Get-VerifiedDownload.ps1'
)

# Verify no inline CI patterns remain
$patterns = '::error|::warning|##vso\[|GITHUB_ACTIONS|TF_BUILD'
Select-String -Path scripts/dev-tools/Generate-PrReference.ps1 -Pattern $patterns | Should -BeNullOrEmpty
Select-String -Path scripts/lib/Get-VerifiedDownload.ps1 -Pattern $patterns | Should -BeNullOrEmpty

Acceptance Criteria

• Both scripts import CIHelpers.psm1 module
• All 4 inline CI patterns replaced with CIHelpers function calls
• No $env:GITHUB_ACTIONS, $env:TF_BUILD checks remain
• No ::error::, ::warning:: string patterns remain
• Test file created for Generate-PrReference.ps1
• Get-VerifiedDownload.Tests.ps1 updated with CI annotation tests
• Test coverage reaches 80%+ for both scripts
• PR reference generation workflow remains functional
• Verified download functionality remains intact
• PSScriptAnalyzer passes with no errors

Files Changed

Scripts (2)

• scripts/dev-tools/Generate-PrReference.ps1
• scripts/lib/Get-VerifiedDownload.ps1

Tests (2)

• scripts/tests/dev-tools/Generate-PrReference.Tests.ps1 (create)
• scripts/tests/lib/Get-VerifiedDownload.Tests.ps1 (update)

Directories

• scripts/tests/dev-tools/ (create if needed)

Related Issues

• Create CIHelpers.psm1 shared module for CI platform detection and output #287 - CIHelpers module creation (prerequisite)
• [Issue]: 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)
• [Issue]: Refactor linting scripts to use CIHelpers module #351 - Linting scripts refactoring (related)