test: guard consumer documentation freshness

docs/getting-started.md

@@ -1,7 +1,8 @@
 # Getting started
 
 PatchGate is a public pre-release. The npm package is unpublished
-(`private: true`, `0.1.0-dev`). The current Action release is `v0.1.0-beta.5`,
+(`private: true`, `0.1.0-dev`). The current Action release is
+[`v0.1.0-beta.5`](https://github.com/daichunghy/patchgate/releases/tag/v0.1.0-beta.5),
 which is for shadow evaluation only — not production, not a `v0.1` claim, and
 not evidence of external pilots. Pin commit
 the immutable commit SHA shown on its release page.

docs/github-action-usage.md

@@ -57,7 +57,7 @@ jobs:
       # github.token cannot read Administration, so native Rulesets /
       # branch-protection snapshots fail closed (correct). A PAT/App token
       # with administration:read is required for a complete native-control
-      # snapshot. beta.2 posts a Check Run for successful evaluations;
+      # snapshot. beta.5 posts a Check Run for successful evaluations;
       # snapshot-rejection Check Runs are included in beta.5.
       - name: Run PatchGate Shadow Gate
         uses: daichunghy/patchgate@v0.1.0-beta.5

docs/releases/beta-release-and-rollback.md

@@ -20,8 +20,9 @@ Before publishing a beta, the maintainer must have independently recorded:
   no-go decision;
 - support, security-reporting, compatibility and unsupported-behavior wording.
 
-The current repository has public pre-release `v0.1.0-beta.5` and a private
-development package. The two external shadow installations and production
+The current repository has public pre-release
+[`v0.1.0-beta.5`](https://github.com/daichunghy/patchgate/releases/tag/v0.1.0-beta.5)
+and a private development package. The two external shadow installations and production
 gates remain open.
 
 ## Release procedure

package.json

@@ -58,6 +58,7 @@
     "check:workflow-pins": "node scripts/check-workflow-pins.mjs",
     "check:workflow-events": "node scripts/check-workflow-events.mjs",
     "check:doc-links": "node scripts/check-doc-links.mjs",
+    "check:consumer-docs": "node scripts/check-consumer-docs.mjs",
     "check:community-schedule": "node scripts/check-community-schedule.mjs",
     "check:application-dossier": "node scripts/check-application-dossier.mjs",
     "test:consumer-fixture": "node scripts/test-consumer-fixture.mjs",
@@ -66,7 +67,7 @@
     "usability:session": "npm run build && node dist/scripts/run-usability-session.js",
     "lint": "node scripts/lint.mjs",
     "verify:dist": "node scripts/verify-dist.mjs",
-    "verify": "npm run lint && npm run typecheck && npm run check:fixture-budgets && npm run check:workflow-pins && npm run check:workflow-events && npm run check:doc-links && npm run check:community-schedule && npm run check:application-dossier && npm run audit && npm test && npm run test:security && npm run test:github && npm run build && npm run bundle:action && npm run test:consumer-fixture && npm run check:release-candidate && npm run test:cli && npm run verify:dist"
+    "verify": "npm run lint && npm run typecheck && npm run check:fixture-budgets && npm run check:workflow-pins && npm run check:workflow-events && npm run check:doc-links && npm run check:consumer-docs && npm run check:community-schedule && npm run check:application-dossier && npm run audit && npm test && npm run test:security && npm run test:github && npm run build && npm run bundle:action && npm run test:consumer-fixture && npm run check:release-candidate && npm run test:cli && npm run verify:dist"
   },
   "dependencies": {
     "ajv": "^8.20.0",

scripts/check-consumer-docs.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const currentTag = "v0.1.0-beta.5";
+const currentReleaseUrl = `https://github.com/daichunghy/patchgate/releases/tag/${currentTag}`;
+const surfaces = [
+  "README.md",
+  "docs/github-action-usage.md",
+  "docs/getting-started.md",
+  "docs/releases/beta-release-and-rollback.md",
+];
+const failures = [];
+
+for (const relativePath of surfaces) {
+  const text = readFileSync(join(root, relativePath), "utf8");
+  if (!text.includes(currentTag)) failures.push(`${relativePath} must name ${currentTag}`);
+  if (!text.includes(currentReleaseUrl)) failures.push(`${relativePath} must link the ${currentTag} release`);
+}
+
+const usage = readFileSync(join(root, "docs/github-action-usage.md"), "utf8");
+if (!usage.includes(`uses: daichunghy/patchgate@${currentTag}`)) {
+  failures.push("docs/github-action-usage.md must pin the current beta in consumer examples");
+}
+if (usage.includes("beta.2 posts a Check Run")) {
+  failures.push("docs/github-action-usage.md contains the stale beta.2 Check Run claim");
+}
+if (!usage.includes("snapshot-rejection Check Runs are included in beta.5")) {
+  failures.push("docs/github-action-usage.md must state the current snapshot-rejection Check Run behavior");
+}
+
+const readme = readFileSync(join(root, "README.md"), "utf8");
+if (readme.includes("uses: daichunghy/patchgate@v0.1.0-beta.2")) {
+  failures.push("README.md must not teach the superseded beta.2 Action reference");
+}
+
+if (failures.length > 0) {
+  process.stderr.write(`consumer documentation check failed:\n${failures.join("\n")}\n`);
+  process.exit(1);
+}
+
+process.stdout.write(`consumer documentation check passed: ${surfaces.length} public surfaces reference ${currentTag}\n`);