refactor(scripts): refactor dev-tools and lib scripts to use CIHelpers module #352
Description
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 -ForceGet-VerifiedDownload.ps1
# Import shared CI helpers module
$ciHelpersPath = Join-Path $PSScriptRoot "Modules/CIHelpers.psm1"
Import-Module $ciHelpersPath -ForceStep 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 -BeNullOrEmptyAcceptance Criteria
- Both scripts import
CIHelpers.psm1module - All 4 inline CI patterns replaced with CIHelpers function calls
- No
$env:GITHUB_ACTIONS,$env:TF_BUILDchecks 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.ps1scripts/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)
- 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)
- refactor(scripts): refactor linting scripts to use CIHelpers module #351 - Linting scripts refactoring (related)