fix: retry the in-build Lint task on PSScriptAnalyzer's transient null reference

[tablackburn]

Summary

• PSScriptAnalyzer 1.25.0 intermittently throws Object reference not set to an instance of an object. from inside the analyzer engine, failing the in-build Lint task (build.psake.ps1) on otherwise-green builds.
• This flake hit both Linux (chore: bump psake to 5.0.4 #65) and Windows (ci: queue integration tests so they don't race on the shared Plex server #66) CI runners at random — it is not platform-specific, so the previously-removed non-Windows disable would not have covered it.
• The Lint task now retries Invoke-ScriptAnalyzer up to three times on that specific null reference (matched by exception type, inner exception, or message), while letting any genuine analysis error surface immediately and still failing after the final attempt.

Test Plan

• build.psake.ps1 parses clean; no new PSScriptAnalyzer findings introduced
• pwsh -File ./build.ps1 -Task Lint passes locally (errors: 0)
• Retry semantics simulated:
  • null reference on attempts 1–2, success on 3 → task succeeds
  • a genuine (non-null-ref) error → rethrown immediately, no retry
  • null reference on every attempt → rethrown after 3 attempts (build fails)
• CI green across all OS matrices

Breaking Changes

None — build/CI tooling only; no module behavior changes.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores
  • Improved build reliability by implementing automatic recovery for intermittent linting failures. The linting process now handles transient issues gracefully, reducing build failures and enabling smoother development workflows.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6d72ac47-19c5-4b95-8156-6eade73dee46

📥 Commits

Reviewing files that changed from the base of the PR and between bb93bca and 2325482.

📒 Files selected for processing (1)

• build.psake.ps1

---

📝 Walkthrough

Walkthrough

The Lint task in build.psake.ps1 now wraps Invoke-ScriptAnalyzer in a retry loop to mitigate intermittent NullReferenceException failures from PSScriptAnalyzer 1.25.0. The task attempts up to three invocations, retrying only on that specific exception type or its known message pattern, and rethrows immediately on other failures.

Changes

Lint task with NullReferenceException retry

Layer / File(s)	Summary
Lint task with NullReferenceException retry build.psake.ps1	The Lint task wraps Invoke-ScriptAnalyzer invocation in a retry loop (max 3 attempts). It detects transient NullReferenceException failures or the specific "Object reference not set…" message pattern, sleeps briefly on match, and rethrows immediately on non-transient failures or after exhausting retries.

Possibly related PRs

• tablackburn/PlexAutomationToolkit#64: Modifies build.psake.ps1's Lint task around Invoke-ScriptAnalyzer execution; directly related as it configures the task that this PR now wraps with retry logic.
• tablackburn/PlexAutomationToolkit#30: Also addresses Invoke-ScriptAnalyzer failures in the Lint task workflow, using platform-conditional logic to disable ScriptAnalyzer on non-Windows systems instead of retry.
• tablackburn/PlexAutomationToolkit#35: Modifies CI workflow to conditionally skip module installation on cache hits to prevent PSScriptAnalyzer initialization failures during linting.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 When PSScript doth stumble with references lost,
A retry loop rises to pay the small cost!
Three chances to parse, then admit defeat true,
Build stage now waits patient for science anew. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and specifically describes the main change: adding retry logic to the Lint task to handle PSScriptAnalyzer's transient null reference exceptions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/lint-retry-transient-pssa-nullref

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds a small retry loop around Invoke-ScriptAnalyzer in the custom Lint psake task to mitigate a transient NullReferenceException ("Object reference not set to an instance of an object.") thrown intermittently by PSScriptAnalyzer 1.25.0 on otherwise-green CI builds. Genuine analysis errors still surface immediately, and exhausting all attempts still fails the build.

Changes:

• Wrap Invoke-ScriptAnalyzer in a 3-attempt retry loop with a 1-second backoff.
• Detect transient null-reference failures via exception type, inner exception type, or message substring.
• Rethrow non-matching exceptions and rethrow on the final attempt.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.