fix: restore Windows PowerShell 5.1 import compatibility

Get-PSBuildCertificate used the PowerShell 7+-only ternary operator, which
fails to parse under Windows PowerShell 5.1. The module loader dot-sources
every Public/*.ps1 at import, so this file broke import of the entire module
on 5.1 (Desktop) even though the manifest still declares support for it.

- Replace the ternary with an if/else expression (5.1-safe).
- Make the $IsWindows platform guard 5.1-safe using the repo's existing
  idiom ($null -ne $IsWindows -and -not $IsWindows); on Desktop edition the
  automatic variable is absent and the platform is always Windows. PS7
  behavior is unchanged.

Add guardrails so this cannot silently regress:
- Enable PSUseCompatibleSyntax/Commands/Types (targeting 5.1 and 7.0) in
  ScriptAnalyzerSettings.psd1, with justified suppressions for two
  documented false positives (Get-ChildItem -CodeSigningCert provider
  dynamic parameter; Invoke-Pester -Configuration from required Pester 5+).
- Fail the Analyze build task on any compatibility violation.
- Add an import-smoke CI job that parses and imports the module on the real
  Windows PowerShell 5.1 engine.

The manifest support contract (PowerShellVersion/CompatiblePSEditions) is
intentionally left unchanged here; formalizing the real floor is tracked for
the v1.0.0 roadmap (#120).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tablackburn

.github/workflows/test.yml

@@ -25,3 +25,46 @@ jobs:
           $DebugPreference = 'Continue'
         }
         ./build.ps1 -Task Test -Bootstrap
+
+  # Smoke test on the lowest supported engine. The manifest declares support for Windows
+  # PowerShell (Desktop), so the module must parse and import there. This job caught the 0.8.0
+  # regression where a PowerShell 7+-only ternary operator broke module import on 5.1.
+  # The root .psm1 is imported directly (rather than the .psd1) so the real dot-source loader runs
+  # without the manifest's RequiredModules bootstrap, keeping the smoke test fast and dependency-free.
+  import-smoke:
+    name: Import smoke (Windows PowerShell 5.1)
+    runs-on: windows-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Parse and import module under Windows PowerShell 5.1
+      shell: powershell
+      run: |
+        $ErrorActionPreference = 'Stop'
+        "Engine: $($PSVersionTable.PSEdition) $($PSVersionTable.PSVersion)"
+
+        $moduleRoot = Join-Path $PWD 'PowerShellBuild'
+
+        # 1. Parse every module file with the 5.1 language parser to catch syntax the lowest
+        #    supported engine cannot load (for example the PowerShell 7+ ternary operator).
+        $files = Get-ChildItem -Path $moduleRoot -Recurse -Include *.ps1, *.psm1, *.psd1
+        $parseFailed = $false
+        foreach ($file in $files) {
+            $tokens = $parseErrors = $null
+            [System.Management.Automation.Language.Parser]::ParseFile($file.FullName, [ref]$tokens, [ref]$parseErrors) > $null
+            if ($parseErrors) {
+                $parseFailed = $true
+                Write-Host "Parse errors in $($file.FullName):"
+                $parseErrors | ForEach-Object { Write-Host "  line $($_.Extent.StartLineNumber): $($_.Message)" }
+            }
+        }
+        if ($parseFailed) {
+            throw 'One or more module files failed to parse under Windows PowerShell 5.1.'
+        }
+        "Parsed $($files.Count) module files with no errors."
+
+        # 2. Import the root module to run the real dot-source loader and confirm it loads on 5.1.
+        Import-Module (Join-Path $moduleRoot 'PowerShellBuild.psm1') -Force -ErrorAction Stop
+        if (-not (Get-Command Get-PSBuildCertificate -ErrorAction SilentlyContinue)) {
+            throw 'PowerShellBuild imported but expected functions are missing.'
+        }
+        'PowerShellBuild imported successfully under Windows PowerShell 5.1.'

CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+### Fixed
+
+- Restore Windows PowerShell 5.1 (Desktop edition) compatibility, which regressed
+  in 0.8.0. `Get-PSBuildCertificate` used the PowerShell 7+-only ternary operator,
+  causing the file to fail to parse and the whole module to fail to import under
+  Windows PowerShell 5.1 — even though the manifest still declares support for it.
+  The ternary is replaced with an `if`/`else` expression, and the `$IsWindows`
+  platform guard now treats the absent automatic variable on Desktop edition as
+  Windows (matching the existing pattern in `Build-PSBuildUpdatableHelp`). Behavior
+  on PowerShell 7+ is unchanged.
+
+### Added
+
+- Cross-version compatibility guardrails so a PowerShell 7+-only construct cannot
+  silently break the lowest supported engine again:
+  - The `PSUseCompatibleSyntax`, `PSUseCompatibleCommands`, and
+    `PSUseCompatibleTypes` rules are enabled in
+    `PowerShellBuild/ScriptAnalyzerSettings.psd1` (targeting Windows PowerShell 5.1
+    and PowerShell 7), and the `Analyze` build task now fails on any compatibility
+    violation.
+  - A new `Import smoke (Windows PowerShell 5.1)` CI job parses and imports the
+    module on the real lowest-supported engine.
+
 ## [0.8.0] 2026-02-20
 
 ### Added

PowerShellBuild/Public/Get-PSBuildCertificate.ps1

@@ -88,6 +88,11 @@ function Get-PSBuildCertificate {
         'CertificatePasswordEnvVar',
         Justification = 'This is not a password in plain text. It is the name of an environment variable that contains the password, which is a common pattern for CI/CD pipelines and secrets management.'
     )]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSUseCompatibleCommands',
+        '',
+        Justification = 'Get-ChildItem -CodeSigningCert is a dynamic parameter supplied by the Certificate (Cert:) provider, not a static parameter of Get-ChildItem, so the static command data used by PSUseCompatibleCommands cannot see it. It is available on both Windows PowerShell 5.1 and PowerShell 7+.'
+    )]
     param(
         [ValidateSet('Auto', 'Store', 'Thumbprint', 'EnvVar', 'PfxFile')]
         [string]$CertificateSource = 'Auto',
@@ -122,8 +127,11 @@ function Get-PSBuildCertificate {
 
     switch ($resolvedSource) {
         'Store' {
-            # Throw if running on a non-Windows platform since the certificate store is not supported
-            if (-not $IsWindows) {
+            # Throw if running on a non-Windows platform since the certificate store is not supported.
+            # $IsWindows does not exist on Windows PowerShell 5.1 (Desktop edition), where it is $null
+            # and the platform is always Windows; only treat the platform as non-Windows when $IsWindows
+            # is explicitly $false (PowerShell 7+ on Linux/macOS).
+            if ($null -ne $IsWindows -and -not $IsWindows) {
                 throw $LocalizedData.CertificateSourceStoreNotSupported
             }
             $cert = Get-ChildItem -Path $CertStoreLocation -CodeSigningCert |
@@ -195,6 +203,7 @@ function Get-PSBuildCertificate {
         Write-Verbose "Certificate validation passed: HasPrivateKey=$($cert.HasPrivateKey), NotAfter=$($cert.NotAfter), CodeSigningEKU=Present"
     }
 
-    Write-Verbose ('Certificate resolution complete: ' + ($cert ? $cert.Subject : 'No certificate found'))
+    $certSubject = if ($cert) { $cert.Subject } else { 'No certificate found' }
+    Write-Verbose ('Certificate resolution complete: ' + $certSubject)
     $cert
 }

PowerShellBuild/Public/Test-PSBuildPester.ps1

@@ -36,6 +36,11 @@ function Test-PSBuildPester {
         Run Pester tests in ./tests and save results to ./out/testResults.xml
     #>
     [CmdletBinding()]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSUseCompatibleCommands',
+        '',
+        Justification = 'Invoke-Pester -Configuration is a Pester 5+ parameter. This module requires Pester >= 5.6.1 (see RequiredModules in the manifest) and imports Pester with -MinimumVersion 5.0.0 before use, so the parameter is always available at runtime. The bundled PSUseCompatibleCommands profiles captured an older Pester, producing a false positive on both Windows PowerShell 5.1 and PowerShell 7.'
+    )]
     param(
         [parameter(Mandatory)]
         [string]$Path,

PowerShellBuild/ScriptAnalyzerSettings.psd1

@@ -9,5 +9,30 @@
         PSAvoidUsingCmdletAliases = @{
             Whitelist = @('task')
         }
+
+        # Cross-version compatibility guardrails. PowerShellBuild still supports
+        # Windows PowerShell 5.1 (Desktop) per the manifest, so these rules flag any
+        # syntax, command, or type that would not work on the lowest supported engine.
+        # PSUseCompatibleSyntax checks against the target language versions regardless
+        # of the engine the analyzer runs under, so a PowerShell 7+-only construct (for
+        # example the ternary operator) is caught even when the analyzer runs from pwsh.
+        PSUseCompatibleSyntax = @{
+            Enable         = $true
+            TargetVersions = @('5.1', '7.0')
+        }
+        PSUseCompatibleCommands = @{
+            Enable         = $true
+            TargetProfiles = @(
+                'win-8_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework'
+                'win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core'
+            )
+        }
+        PSUseCompatibleTypes = @{
+            Enable         = $true
+            TargetProfiles = @(
+                'win-8_x64_10.0.17763.0_5.1.17763.316_x64_4.0.30319.42000_framework'
+                'win-8_x64_10.0.17763.0_7.0.0_x64_3.1.2_core'
+            )
+        }
     }
 }

psakeFile.ps1

@@ -16,12 +16,29 @@ task Init {
 task Test -Depends Init, Analyze, Pester -description 'Run test suite'
 
 task Analyze -depends Build {
-    $analysis = Invoke-ScriptAnalyzer -Path $settings.ModuleOutDir -Recurse -Verbose:$false -Settings ([IO.Path]::Combine($env:BHModulePath, 'ScriptAnalyzerSettings.psd1'))
-    $errors   = $analysis | Where-Object {$_.Severity -eq 'Error'}
-    $warnings = $analysis | Where-Object {$_.Severity -eq 'Warning'}
+    $analyzerSettings = [IO.Path]::Combine($env:BHModulePath, 'ScriptAnalyzerSettings.psd1')
+    $analysis = Invoke-ScriptAnalyzer -Path $settings.ModuleOutDir -Recurse -Verbose:$false -Settings $analyzerSettings
+    $errors   = $analysis | Where-Object { $_.Severity -eq 'Error' }
+
+    # Cross-version compatibility violations (PSUseCompatibleSyntax/Commands/Types) are reported at
+    # Warning severity, but must always fail the build. A PowerShell 7+-only construct such as the
+    # ternary operator parses fine under pwsh yet breaks module import on Windows PowerShell 5.1,
+    # which the manifest still supports. PSUseCompatibleSyntax checks the target language versions
+    # regardless of the engine the analyzer runs under, so this gate catches such a regression even
+    # though CI runs the analysis from pwsh.
+    $compatibilityIssues = $analysis | Where-Object { $_.RuleName -like 'PSUseCompatible*' }
+
+    # Remaining warnings are reported but, per project policy, do not fail the build.
+    $warnings = $analysis | Where-Object { $_.Severity -eq 'Warning' -and $_.RuleName -notlike 'PSUseCompatible*' }
+
+    if (@($compatibilityIssues).Count -gt 0) {
+        $compatibilityIssues | Format-Table RuleName, ScriptName, Line, Message -AutoSize -Wrap
+        Write-Error -Message 'One or more cross-version compatibility issues were found. Build cannot continue!'
+    }
+
     if (@($errors).Count -gt 0) {
-        Write-Error -Message 'One or more Script Analyzer errors were found. Build cannot continue!'
         $errors | Format-Table -AutoSize
+        Write-Error -Message 'One or more Script Analyzer errors were found. Build cannot continue!'
     }
 
     if (@($warnings).Count -gt 0) {