From cebfdc530c439adae105040b8c5d8e8ef027822c Mon Sep 17 00:00:00 2001
From: "goodolclint-claude[bot]"
 <323206664+goodolclint-claude[bot]@users.noreply.github.com>
Date: Thu, 3 Sep 2026 01:07:36 +0000
Subject: [PATCH] ci: fail the PR when the generated help is out of date (#206)

* ci: fail the PR when the generated help is out of date

docs/cmdlets/ and the MAML are outputs of generate-help.ps1, but no
workflow ran it, so the help drifted 25 cmdlets behind the source (#153)
and the stale MAML shipped in every PSGallery release. A help-current job
regenerates and fails on a dirty tree, comparing content rather than the
CRLF platyPS writes.

Depends on #205, which commits the regenerated help; before that merges
this job fails on its first run.

* ci: normalize untracked help stubs too, and quote the pathspecs

---------

Co-authored-by: goodolclint-claude[bot] <323206664+goodolclint-claude[bot]@users.noreply.github.com>
---
 .github/workflows/unit-tests.yml | 37 ++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml
index f3fd04f..c6ca3f7 100644
--- a/.github/workflows/unit-tests.yml
+++ b/.github/workflows/unit-tests.yml
@@ -169,6 +169,43 @@ jobs:
           name: pester-results-${{ matrix.os }}-ps${{ matrix.ps_version }}
           path: TestResults/
 
+  # ── Generated help matches the source ───────────────────────────────
+  # docs/cmdlets/ and the MAML are outputs of generate-help.ps1, but no
+  # workflow ran it, so cmdlets shipped undocumented until someone noticed:
+  # at #153 the module had 194 cmdlets and 169 help entries, and the stale
+  # MAML went out in every PSGallery release.
+  help-current:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Regenerate help
+        shell: pwsh
+        run: ./generate-help.ps1
+
+      # platyPS writes CRLF into every file it produces, so compare content,
+      # not line endings. Untracked files count: a new cmdlet's stub is
+      # exactly the miss this job exists to catch.
+      - name: Fail if the generated help is out of date
+        shell: bash
+        run: |
+          paths=(docs/cmdlets src/PSProxmoxVE/PSProxmoxVE.dll-Help.xml)
+          find "${paths[@]}" -type f -print0 | xargs -0 -r perl -pi -e 's/\r\n/\n/g'
+          if [ -n "$(git status --porcelain -- "${paths[@]}")" ]; then
+            echo "::error::generated help is out of date - run ./generate-help.ps1 and commit the result"
+            git status --porcelain -- "${paths[@]}"
+            git diff --stat -- "${paths[@]}"
+            exit 1
+          fi
+
   # ── CI infrastructure shell self-checks ─────────────────────────────
   # These guard the provisioning and reporting scripts, whose real exercise is
   # a ~45-minute nested-PVE run. They stub ssh/gh/git and finish in seconds, so