From 23254828f8d47b48b6479ec31daa87912d116e7c Mon Sep 17 00:00:00 2001
From: Trent Blackburn <trent.blackburn@gmail.com>
Date: Fri, 29 May 2026 15:17:30 -0400
Subject: [PATCH] fix: retry the in-build Lint task on PSScriptAnalyzer's
 transient null reference

PSScriptAnalyzer 1.25.0 intermittently throws "Object reference not set to
an instance of an object." from inside the analyzer engine, failing the
Lint task on otherwise-green builds. It has struck both Linux (#65) and
Windows (#66) CI runners at random, so it is not platform-specific and a
non-Windows disable would not cover it.

Retry the analysis up to three times on that specific null reference, while
letting any genuine analysis error surface immediately.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 build.psake.ps1 | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/build.psake.ps1 b/build.psake.ps1
index b827204..16f9b65 100644
--- a/build.psake.ps1
+++ b/build.psake.ps1
@@ -128,7 +128,32 @@ Task -Name 'Lint' -Depends 'Build' -Description 'Run PSScriptAnalyzer against th
         Settings = $PSBPreference.Test.ScriptAnalysis.SettingsPath
         Recurse  = $true
     }
-    $analysisResult = Invoke-ScriptAnalyzer @analyzeParameters
+    # PSScriptAnalyzer 1.25.0 intermittently throws a NullReferenceException
+    # ("Object reference not set to an instance of an object.") from inside the
+    # analyzer engine - a transient failure that has struck both Linux and Windows
+    # CI runners (PRs #65 and #66) on otherwise-passing builds. It is not a code
+    # defect and clears on a retry, so attempt the analysis a few times, retrying
+    # only that specific null reference and letting any genuine error surface
+    # immediately.
+    $maxAnalysisAttempts = 3
+    $analysisResult = $null
+    for ($analysisAttempt = 1; $analysisAttempt -le $maxAnalysisAttempts; $analysisAttempt++) {
+        try {
+            $analysisResult = Invoke-ScriptAnalyzer @analyzeParameters
+            break
+        }
+        catch {
+            $isTransientNullReference =
+                $_.Exception -is [NullReferenceException] -or
+                $_.Exception.InnerException -is [NullReferenceException] -or
+                $_.Exception.Message -like '*Object reference not set to an instance of an object*'
+            if (-not $isTransientNullReference -or $analysisAttempt -eq $maxAnalysisAttempts) {
+                throw
+            }
+            Write-Warning "PSScriptAnalyzer threw a transient null reference on attempt $analysisAttempt of $maxAnalysisAttempts; retrying. ($($_.Exception.Message))"
+            Start-Sleep -Seconds 1
+        }
+    }
     if ($analysisResult) {
         $analysisResult | Format-Table -AutoSize | Out-String | Write-Host
     }