From ff409668324b730c5831f4fe88ec2590bec3da32 Mon Sep 17 00:00:00 2001
From: Johnathan Corgan <johnathan@corganlabs.com>
Date: Sun, 3 May 2026 18:20:50 +0000
Subject: [PATCH] Add PowerShell lint job for packaging/windows scripts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add windows-lint job to .github/workflows/ci.yml running
PSScriptAnalyzer against the three operator-facing PowerShell scripts
(build-zip.ps1, install-service.ps1, uninstall-service.ps1) on the
windows-latest runner. Job runs in parallel with build/test, no
needs:, no tag gating.

Also add packaging/windows/PSScriptAnalyzerSettings.psd1 with two
project-appropriate suppressions:

  PSAvoidUsingWriteHost — operator-facing progress in all three
    scripts is intentional; Write-Output would conflate progress
    with return value.
  PSAvoidUsingPositionalParameters — Copy-Item src dst / New-Item
    -Path style positional usage is widespread for cp/mv-like
    readability.

Severity = @('Error', 'Warning') gates CI on Warnings+ only,
skipping Information-only findings.

The lint job lives in ci.yml rather than package-windows.yml: keeps
the packaging workflow focused, avoids interleaving with the
structural-verification steps in package-windows.yml, and the lint
runs on every push (not just tags).
---
 .github/workflows/ci.yml                      | 29 +++++++++++++++++++
 .../windows/PSScriptAnalyzerSettings.psd1     | 25 ++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 packaging/windows/PSScriptAnalyzerSettings.psd1

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2d27397..a797fdd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -250,6 +250,35 @@ jobs:
       - name: Run unit tests
         run: cargo nextest run --all --profile ci
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Job 2d – PowerShell lint (Windows packaging scripts)
+#
+# Runs PSScriptAnalyzer against the operator-facing installer/build
+# scripts shipped in the Windows ZIP package. Settings live in
+# packaging/windows/PSScriptAnalyzerSettings.psd1 (each suppressed rule
+# is documented there). Pre-installed on windows-latest runners; no
+# Install-Module step needed.
+# ─────────────────────────────────────────────────────────────────────────────
+  windows-lint:
+    name: PowerShell lint (Windows packaging)
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run PSScriptAnalyzer
+        shell: pwsh
+        run: |
+          $results = Invoke-ScriptAnalyzer `
+            -Path packaging/windows/*.ps1 `
+            -Settings packaging/windows/PSScriptAnalyzerSettings.psd1
+          if ($results) {
+            $results | Format-Table -AutoSize
+            Write-Error "PSScriptAnalyzer found $($results.Count) issue(s)"
+            exit 1
+          } else {
+            Write-Host "PSScriptAnalyzer: no issues"
+          }
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Job 3 – Integration tests (static mesh + chaos simulation)
 #
diff --git a/packaging/windows/PSScriptAnalyzerSettings.psd1 b/packaging/windows/PSScriptAnalyzerSettings.psd1
new file mode 100644
index 0000000..a26f49d
--- /dev/null
+++ b/packaging/windows/PSScriptAnalyzerSettings.psd1
@@ -0,0 +1,25 @@
+# PSScriptAnalyzer settings for FIPS Windows packaging scripts.
+#
+# Starts from the default ruleset and excludes a small set of rules that
+# do not apply to operator-facing installer scripts. Each exclusion lists
+# why it was suppressed and which scripts justify it.
+
+@{
+    # Skip Information-level findings; gate CI on Warning and Error only.
+    Severity = @('Error', 'Warning')
+
+    ExcludeRules = @(
+        # Console output to the operator is intentional in build-zip.ps1,
+        # install-service.ps1, and uninstall-service.ps1. These scripts
+        # are run interactively by humans installing/packaging FIPS, and
+        # Write-Host gives them feedback at the terminal. Switching to
+        # Write-Output would conflate progress text with the (non-existent)
+        # script return value.
+        'PSAvoidUsingWriteHost',
+
+        # Copy-Item, New-Item, and similar cmdlet calls in the installer
+        # use positional parameters (source, destination) for readability
+        # and to mirror cp/mv conventions Unix-familiar operators expect.
+        'PSAvoidUsingPositionalParameters'
+    )
+}