mandrel-platform 1.0.1 → 1.2.0

package/scripts/check-docs-staleness.mjs

@@ -90,7 +90,14 @@ export const RULES = [
   {
     id: 'quality-yml-ref',
     description: 'References `quality.yml` — verify this file exists in the project (swarm-os ships `ci.yml` instead)',
-    pattern: /quality\.yml/g,
+    // The bare filename only — the lookbehind stops the platform's OWN
+    // `pr-quality.yml` (and any other `<prefix>-quality.yml`) from matching as
+    // a substring. Without it this rule produced 58 findings against
+    // mandrel-platform's docs and 1 was a real bare reference, drowning a
+    // genuine `expired-placeholder` error in known-benign warnings. Guarding on
+    // `[-\w]` rather than spelling out `pr-` keeps it correct for a consumer
+    // that names its own caller `ci-quality.yml`.
+    pattern: /(?<![-\w])quality\.yml/g,
     severity: 'warning',
   },
   {
@@ -102,7 +109,13 @@ export const RULES = [
     // 4-digit 20xx year and defer the "is it actually in the past?" decision
     // to `matchFilter`, so the rule stays correct as the calendar advances and
     // never flags a still-valid FUTURE expiry.
-    pattern: /expires[:\s]+(20\d{2}-\d{2}-\d{2})/gi,
+    // The optional quotes either side of the separator are load-bearing: the
+    // CVE allowlist's own shape is JSON (`"expires": "2026-12-31"` — see
+    // audit-check.mjs), and `expires"` is neither `:` nor whitespace, so the
+    // unquoted-only form skipped every documented allowlist entry. That is the
+    // same fail-open class as the 202[0-4] year window this rule already fixed;
+    // it was hiding a second lapsed date in docs/runbooks/dependency-update.md.
+    pattern: /expires['"]?[:\s]+['"]?(20\d{2}-\d{2}-\d{2})/gi,
     severity: 'error',
     // Only flag when the captured date is strictly before today (UTC). Future
     // expiries are still valid and must not be reported.

package/scripts/check-docs-staleness.test.mjs

@@ -3,16 +3,23 @@
  * check-docs-staleness.test.mjs — node:test suite for the docs-staleness lint
  * (Story #197).
  *
- * Focus: the `expired-placeholder` rule. The rule previously hardcoded the
- * years 2020–2024 (`/expires[:\s]+202[0-4]-\d{2}-\d{2}/i`), so an expiry that
- * lapsed in 2025, 2026, or any later year sailed through the gate — a
- * fail-open. The fix broadens the pattern to any 20xx year and defers the
- * "is it actually in the past?" decision to `isExpiredDate`, so the rule stays
- * correct as the calendar advances and never flags a still-valid future date.
+ * Focus: rule PRECISION — the two ways a staleness rule stops being useful.
  *
- * These tests exercise the year fix directly (`isExpiredDate`) and end-to-end
- * (`lintFile` against a real fixture file), pinning "today" via a fixed clock
- * so they are deterministic.
+ * 1. Fail-open (`expired-placeholder` under-fires). The rule first hardcoded
+ *    the years 2020–2024 (`/expires[:\s]+202[0-4]-\d{2}-\d{2}/i`), so an expiry
+ *    that lapsed in 2025 or later sailed through. The fix broadens to any 20xx
+ *    year and defers "is it actually in the past?" to `isExpiredDate`, so the
+ *    rule stays correct as the calendar advances and never flags a still-valid
+ *    future date. A second instance of the same class: the separator required
+ *    `expires` to be followed directly by `:` or whitespace, which skipped the
+ *    CVE allowlist's own JSON shape (`"expires": "…"`).
+ * 2. Fail-noisy (`quality-yml-ref` over-fires). A plain substring match meant
+ *    the platform's own `pr-quality.yml` matched, so 58 of 59 findings were
+ *    false positives — enough to bury a real error in the same run.
+ *
+ * These tests exercise the date logic directly (`isExpiredDate`), the compiled
+ * patterns, and end-to-end behaviour (`lintFile` against a real fixture file),
+ * pinning "today" via a fixed clock so they are deterministic.
  *
  * Run: node --test scripts/check-docs-staleness.test.mjs
  */
@@ -128,3 +135,101 @@ test('lintFile honours the staleness-ignore suppression comment for the year rul
     },
   );
 });
+
+// ---------------------------------------------------------------------------
+// expired-placeholder — the JSON-quoted shape.
+//
+// Second fail-open of the same class as the 202[0-4] year window: the pattern
+// required `expires` to be followed directly by `:` or whitespace, so the CVE
+// allowlist's own JSON shape (`"expires": "2026-12-31"`, per audit-check.mjs)
+// never matched — `expires"` is neither. Every documented allowlist entry was
+// therefore invisible to the gate, including a lapsed one in
+// docs/runbooks/dependency-update.md.
+// ---------------------------------------------------------------------------
+
+test('expired-placeholder matches the JSON-quoted allowlist shape', () => {
+  const rule = RULES.find((r) => r.id === 'expired-placeholder');
+  for (const line of [
+    '  "expires": "2025-12-31",', // the CVE allowlist's real shape
+    "  'expires': '2025-12-31',", // single-quoted (YAML/JS)
+    '  expires: "2025-12-31"', // quoted value, bare key
+  ]) {
+    rule.pattern.lastIndex = 0;
+    assert.ok(rule.pattern.test(line), `pattern should match ${JSON.stringify(line)}`);
+  }
+});
+
+test('expired-placeholder still matches the unquoted shapes (no regression)', () => {
+  const rule = RULES.find((r) => r.id === 'expired-placeholder');
+  for (const line of [
+    'expires: 2025-01-01',
+    '# CVE-2022-3517 — expires 2025-06-01',
+  ]) {
+    rule.pattern.lastIndex = 0;
+    assert.ok(rule.pattern.test(line), `pattern should match ${JSON.stringify(line)}`);
+  }
+});
+
+test('lintFile flags a lapsed JSON-quoted expiry end-to-end', () => {
+  withTempDoc('Allowlist entry.\n  "expires": "2025-12-31",\nEnd.\n', (file) => {
+    const expired = lintFile(file).filter((f) => f.rule.id === 'expired-placeholder');
+    assert.equal(expired.length, 1);
+    assert.match(expired[0].match, /2025-12-31/);
+  });
+});
+
+test('lintFile does NOT flag a future JSON-quoted expiry', () => {
+  withTempDoc('Allowlist entry.\n  "expires": "2099-12-31",\nEnd.\n', (file) => {
+    const expired = lintFile(file).filter((f) => f.rule.id === 'expired-placeholder');
+    assert.equal(expired.length, 0);
+  });
+});
+
+test('lintFile does NOT flag a placeholder expiry token', () => {
+  // The runbooks intentionally use `<YYYY-MM-DD>` rather than a concrete date,
+  // precisely so an example can never lapse into a finding.
+  withTempDoc('Allowlist entry.\n  "expires": "<YYYY-MM-DD>",\nEnd.\n', (file) => {
+    const expired = lintFile(file).filter((f) => f.rule.id === 'expired-placeholder');
+    assert.equal(expired.length, 0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// quality-yml-ref — bare filename only.
+//
+// The pattern was a plain substring match, so the platform's own
+// `pr-quality.yml` matched: 58 of 59 findings against mandrel-platform's docs
+// were that false positive, burying a real `expired-placeholder` error. The
+// assertion below is on the invariant (a `<prefix>-quality.yml` is a different
+// file) rather than on the single `pr-` spelling that motivated it.
+// ---------------------------------------------------------------------------
+
+test('quality-yml-ref does NOT match a prefixed <prefix>-quality.yml', () => {
+  const rule = RULES.find((r) => r.id === 'quality-yml-ref');
+  assert.ok(rule, 'quality-yml-ref rule must exist');
+  for (const line of [
+    'uses: dsj1984/mandrel-platform/.github/workflows/pr-quality.yml@abc123',
+    'the `pr-quality.yml` reusable workflow',
+    'a consumer that names its caller `ci-quality.yml`',
+    'see my_quality.yml for details',
+  ]) {
+    rule.pattern.lastIndex = 0;
+    assert.equal(
+      rule.pattern.test(line),
+      false,
+      `pattern must not match ${JSON.stringify(line)}`,
+    );
+  }
+});
+
+test('quality-yml-ref still matches a bare quality.yml reference', () => {
+  const rule = RULES.find((r) => r.id === 'quality-yml-ref');
+  for (const line of [
+    "| athportal | `quality.yml` | `quality` |",
+    'the quality.yml workflow was renamed',
+    'quality.yml',
+  ]) {
+    rule.pattern.lastIndex = 0;
+    assert.ok(rule.pattern.test(line), `pattern should match ${JSON.stringify(line)}`);
+  }
+});

package/scripts/check-first-party-pin-freshness.mjs

@@ -0,0 +1,532 @@
+#!/usr/bin/env node
+/**
+ * check-first-party-pin-freshness.mjs
+ *
+ * First-party self-pin freshness guard (Story #354).
+ *
+ * This repo publishes its own composite actions and reusable workflows and
+ * then CALLS them by absolute `owner/repo/subpath@<sha>` reference — the same
+ * form a consumer uses. That self-pin is the ONLY thing that decides which
+ * revision of the action actually runs. Fixing an action file in the working
+ * tree therefore changes nothing at runtime until every call site is
+ * repointed, and nothing in the repo detected that gap:
+ *
+ *   • `check-action-pins.mjs` enforces only the single-pin invariant — that
+ *     every call site for a subpath agrees. A fleet of call sites agreeing on
+ *     ONE STALE sha is perfectly green. (At the time it also EXEMPTED
+ *     first-party refs from the SHA ratchet entirely; that exemption was
+ *     retired by the Story #354 audit — see the `unpinnedRefs` note below.)
+ *   • `check-workflow-portability.mjs` Rule 3 does read the manifest at the
+ *     pinned SHA, but re-runs only its own Rules 1–2 against it (relative
+ *     `uses:`, `${{ }}` in input descriptions/defaults). A BEHAVIOURAL lag —
+ *     e.g. `mktemp -d` → `${RUNNER_TEMP}` — is invisible to it.
+ *
+ * That blind spot shipped issue #352: PR #345 scoped the gitleaks/osv
+ * extraction dirs to `${RUNNER_TEMP}`, no call site was repointed, and every
+ * consumer on a self-hosted fleet kept leaking ~164 MB per run into the
+ * host-shared temp root on the latest release.
+ *
+ * This checker closes it by classifying every first-party SHA pin into one of
+ * two failure classes — deliberately kept distinct, because their remedies
+ * differ:
+ *
+ *   • `stale`       — the manifest AT THE PINNED SHA differs from the
+ *                     working-tree manifest at the same subpath. The fix is to
+ *                     BUMP the pin to a commit carrying the current manifest.
+ *   • `unreachable` — the pinned SHA is not an ancestor of the checked-out
+ *                     ref. Typically a pre-squash branch commit: content-
+ *                     identical to `main` today, resolvable only until GitHub
+ *                     garbage-collects it, after which every consumer fails at
+ *                     action-load time. The fix is to RE-PIN to the squashed
+ *                     commit on `main`.
+ *
+ * A first-party ref that is NOT a 40-hex SHA has no freshness answer at all —
+ * a branch or tag names a revision that can move after this check runs — so it
+ * is collected into `unpinnedRefs` and merely REPORTED. Enforcing the SHA
+ * shape belongs upstream of freshness, in `check-action-pins.mjs`, which
+ * ratchets first-party refs alongside third-party ones and runs in the
+ * PR-gating `ci.yml` where this check deliberately does not (see below). The
+ * note here is the backstop for a consumer that adopted only this script.
+ *
+ * Requires full git history — run the checkout with `fetch-depth: 0`. A
+ * shallow clone cannot answer either question and is refused loudly rather
+ * than reported as a wall of false `unreachable` findings.
+ *
+ * ## Where this runs, and why not on PRs
+ *
+ * Wired onto push-to-`main` and the `pin-drift.yml` schedule; deliberately
+ * ABSENT from the PR-gating `ci.yml`. A PR that edits a composite action
+ * cannot pin its own not-yet-existing merge commit, so a PR-time gate would
+ * be unsatisfiable on exactly the changes it exists to protect. A red `main`
+ * is instead the signal to open the follow-up bump PR — the land-then-bump
+ * sequence documented in docs/reusable-workflows.md.
+ *
+ * Usage:
+ *   node scripts/check-first-party-pin-freshness.mjs
+ *   node scripts/check-first-party-pin-freshness.mjs --cwd /path/to/repo
+ *   node scripts/check-first-party-pin-freshness.mjs --ref origin/main
+ *   node scripts/check-first-party-pin-freshness.mjs --first-party-owner my-org/my-repo
+ *
+ * Exit codes:
+ *   0 — every first-party pin resolves to a fresh, reachable manifest.
+ *   1 — one or more `stale` / `unreachable` pins (each named in stderr with
+ *       file, line, subpath and SHA), or the history needed to decide is
+ *       unavailable.
+ *
+ * Consumer adoption:
+ *   Copy this script into your project's `scripts/` directory alongside
+ *   `scripts/lib/{args,uses-pins,walk}.mjs` (its only dependencies — no YAML
+ *   parser), then run it on push to your default branch:
+ *
+ *     - uses: actions/checkout@<sha>
+ *       with: { fetch-depth: 0 }
+ *     - run: node scripts/check-first-party-pin-freshness.mjs --first-party-owner <owner/repo>
+ */
+
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { resolve, join, relative, basename } from "node:path";
+
+import { parseFlags } from "./lib/args.mjs";
+import {
+  DEFAULT_FIRST_PARTY_OWNER,
+  parseUsesLine,
+  classifyUses,
+  isSha40,
+} from "./lib/uses-pins.mjs";
+import { listWorkflowFiles, listActionFiles } from "./lib/walk.mjs";
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the CLI argv slice (everything AFTER `node script.mjs`) into an
+ * options object. Throws on an unknown flag so a typo fails loudly rather than
+ * silently disabling half the check.
+ *
+ * @param {string[]} argv
+ * @returns {{workflowsDir: string, actionsDir: string, firstPartyOwner: string, cwd: string, ref: string, help: boolean}}
+ */
+export function parseArgs(argv) {
+  return parseFlags(argv, {
+    flags: {
+      "--workflows-dir": { type: "string", dest: "workflowsDir", default: ".github/workflows" },
+      "--actions-dir": { type: "string", dest: "actionsDir", default: ".github/actions" },
+      "--first-party-owner": {
+        type: "string",
+        dest: "firstPartyOwner",
+        default: DEFAULT_FIRST_PARTY_OWNER,
+      },
+      "--cwd": { type: "string", dest: "cwd", default: process.cwd() },
+      "--ref": { type: "string", dest: "ref", default: "HEAD" },
+      "--help": { type: "boolean", dest: "help", value: true, default: false },
+    },
+    aliases: { "-h": "--help" },
+    onUnknown: "throw",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Pin collection (pure text)
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan a file's TEXT for first-party `uses:` references and split them into
+ * the SHA-pinned refs this checker classifies and the non-SHA refs it can only
+ * note. Third-party, local (`./path`) and `docker://` references are dropped
+ * here and can therefore never reach the report.
+ *
+ * A bare `owner/repo@ref` self-reference is skipped: with no subpath there is
+ * no manifest to resolve. Whole-line `#` comments never match (the doc-example
+ * `uses:` lines every action.yml carries in its header are comments).
+ *
+ * @param {string} content
+ * @param {string} displayFile Path as it should appear in the report.
+ * @param {string} [firstPartyOwner]
+ * @returns {{pins: Array<{file: string, line: number, subpath: string, sha: string}>, unpinnedRefs: Array<{file: string, line: number, subpath: string, ref: string}>}}
+ */
+export function collectPinnedRefs(
+  content,
+  displayFile,
+  firstPartyOwner = DEFAULT_FIRST_PARTY_OWNER
+) {
+  const pins = [];
+  const unpinnedRefs = [];
+  const lines = String(content).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const bareRef = parseUsesLine(lines[i]);
+    if (bareRef === null) continue;
+    const cls = classifyUses(bareRef, firstPartyOwner);
+    if (cls.kind !== "first-party") continue;
+    if (!cls.subpath) continue; // bare owner/repo self-ref — no manifest to resolve
+    const record = { file: displayFile, line: i + 1, subpath: cls.subpath };
+    if (isSha40(cls.ref)) pins.push({ ...record, sha: cls.ref });
+    else unpinnedRefs.push({ ...record, ref: cls.ref });
+  }
+  return { pins, unpinnedRefs };
+}
+
+/**
+ * Resolve the manifest a `uses:` subpath points at, relative to a repo root.
+ * A directory subpath resolves to its `action.yml` / `action.yaml`; a `.yml` /
+ * `.yaml` subpath resolves to itself. Returns null when the subpath does not
+ * exist in the working tree or holds no manifest.
+ *
+ * @param {string} repoRoot
+ * @param {string} subpath
+ * @returns {{path: string, kind: "action" | "workflow"} | null}
+ */
+export function resolveManifest(repoRoot, subpath) {
+  const local = join(repoRoot, subpath);
+  let st;
+  try {
+    st = statSync(local);
+  } catch {
+    return null;
+  }
+  if (st.isDirectory()) {
+    for (const name of ["action.yml", "action.yaml"]) {
+      if (existsSync(join(local, name))) return { path: `${subpath}/${name}`, kind: "action" };
+    }
+    return null;
+  }
+  if (/\.ya?ml$/.test(subpath)) {
+    return { path: subpath, kind: basename(subpath).startsWith("action.") ? "action" : "workflow" };
+  }
+  return null;
+}
+
+/**
+ * Compare two manifest bodies for equality, tolerating line-ending drift so a
+ * CRLF working tree on Windows does not report every pin as stale.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function manifestsMatch(a, b) {
+  const norm = (s) => String(s).replace(/\r\n/g, "\n");
+  return norm(a) === norm(b);
+}
+
+// ---------------------------------------------------------------------------
+// Git seam
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the narrow git interface `runCheck` needs, bound to a repo root. Every
+ * method is failure-tolerant: a missing object or an unreadable path answers
+ * "no" rather than throwing, so a broken pin is reported as a finding instead
+ * of crashing the lint.
+ *
+ * @param {string} repoRoot
+ */
+export function createGit(repoRoot) {
+  const run = (args) =>
+    execFileSync("git", args, {
+      cwd: repoRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 16 * 1024 * 1024,
+    });
+
+  return {
+    /** True when `repoRoot` sits inside a git work tree. */
+    isRepo() {
+      try {
+        run(["rev-parse", "--is-inside-work-tree"]);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    /** True when the clone is shallow (history truncated — cannot decide). */
+    isShallow() {
+      try {
+        return run(["rev-parse", "--is-shallow-repository"]).trim() === "true";
+      } catch {
+        return false;
+      }
+    },
+    /** Abbreviated SHA of a ref, or null when it does not resolve. */
+    resolveRef(ref) {
+      try {
+        return run(["rev-parse", ref]).trim();
+      } catch {
+        return null;
+      }
+    },
+    /** True when `sha` is an ancestor of (or equal to) `ref`. */
+    isAncestor(sha, ref) {
+      try {
+        execFileSync("git", ["merge-base", "--is-ancestor", sha, ref], {
+          cwd: repoRoot,
+          stdio: ["ignore", "ignore", "ignore"],
+        });
+        return true;
+      } catch {
+        // Exit 1 = not an ancestor; exit 128 = unknown object. Both mean the
+        // pin is not reachable from the checked-out ref.
+        return false;
+      }
+    },
+    /** `git show <sha>:<path>` → content, or null when unresolvable. */
+    show(sha, path) {
+      try {
+        return run(["show", `${sha}:${path}`]);
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Check
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify every first-party SHA pin under the repo's workflow and action
+ * trees. Returns a structured result; formatting and the exit code live in
+ * {@link runCli}.
+ *
+ * `git` is injectable so a caller can drive the classification against a
+ * substitute history; it defaults to the real git bound to `opts.cwd`.
+ *
+ * @param {{cwd?: string, workflowsDir?: string, actionsDir?: string, firstPartyOwner?: string, ref?: string}} opts
+ * @param {ReturnType<typeof createGit>} [git]
+ * @returns {{ok: boolean, fatal: string|null, stale: object[], unreachable: object[], unpinnedRefs: object[], scanned: number, files: string[], headSha: string|null}}
+ */
+export function runCheck(opts = {}, git = createGit(resolve(opts.cwd || process.cwd()))) {
+  const repoRoot = resolve(opts.cwd || process.cwd());
+  const ref = opts.ref || "HEAD";
+  const firstPartyOwner = opts.firstPartyOwner || DEFAULT_FIRST_PARTY_OWNER;
+  const wfDir = resolve(repoRoot, opts.workflowsDir || ".github/workflows");
+  const acDir = resolve(repoRoot, opts.actionsDir || ".github/actions");
+
+  const empty = {
+    ok: false,
+    fatal: null,
+    stale: [],
+    unreachable: [],
+    unpinnedRefs: [],
+    scanned: 0,
+    files: [],
+    headSha: null,
+  };
+
+  if (!git.isRepo()) {
+    return {
+      ...empty,
+      fatal:
+        "not a git repository — this check resolves each pinned manifest from " +
+        "git history and cannot run without it",
+    };
+  }
+  if (git.isShallow()) {
+    return {
+      ...empty,
+      fatal:
+        "shallow clone — pinned manifests and ancestry are unresolvable. Run " +
+        "the checkout with `fetch-depth: 0`",
+    };
+  }
+  const headSha = git.resolveRef(ref);
+  if (headSha === null) {
+    return { ...empty, fatal: `ref "${ref}" does not resolve in this repository` };
+  }
+
+  const files = [...listWorkflowFiles(wfDir), ...listActionFiles(acDir)];
+  const stale = [];
+  const unreachable = [];
+  const unpinnedRefs = [];
+  let scanned = 0;
+
+  for (const file of files) {
+    let content;
+    try {
+      content = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const display = relative(repoRoot, file) || file;
+    const collected = collectPinnedRefs(content, display, firstPartyOwner);
+    unpinnedRefs.push(...collected.unpinnedRefs);
+
+    for (const pin of collected.pins) {
+      scanned++;
+
+      // Reachability first: an unknown or off-branch object cannot be compared
+      // in the first place, and its remedy (re-pin to the squashed commit)
+      // differs from a bump.
+      if (!git.isAncestor(pin.sha, ref)) {
+        unreachable.push({
+          ...pin,
+          reason:
+            `pinned SHA is not an ancestor of ${ref} — a dangling or pre-squash ` +
+            `branch commit that breaks every consumer once it is garbage-collected`,
+        });
+        continue;
+      }
+
+      const manifest = resolveManifest(repoRoot, pin.subpath);
+      if (manifest === null) {
+        stale.push({
+          ...pin,
+          reason: `no manifest at ${pin.subpath} in the working tree — the pin references a path that no longer exists`,
+        });
+        continue;
+      }
+
+      const pinnedBody = git.show(pin.sha, manifest.path);
+      if (pinnedBody === null) {
+        stale.push({
+          ...pin,
+          reason: `${manifest.path} does not exist at the pinned SHA — the pin predates the manifest`,
+        });
+        continue;
+      }
+
+      let workingBody;
+      try {
+        workingBody = readFileSync(join(repoRoot, manifest.path), "utf8");
+      } catch {
+        stale.push({ ...pin, reason: `cannot read the working-tree ${manifest.path}` });
+        continue;
+      }
+
+      if (!manifestsMatch(pinnedBody, workingBody)) {
+        stale.push({
+          ...pin,
+          manifest: manifest.path,
+          reason: `the manifest at the pinned SHA differs from the working-tree ${manifest.path} — the pinned revision is what actually runs`,
+        });
+      }
+    }
+  }
+
+  return {
+    ok: stale.length === 0 && unreachable.length === 0,
+    fatal: null,
+    stale,
+    unreachable,
+    unpinnedRefs,
+    scanned,
+    files,
+    headSha,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const USAGE =
+  "Usage: node scripts/check-first-party-pin-freshness.mjs " +
+  "[--cwd <dir>] [--ref <git-ref>] [--workflows-dir <dir>] [--actions-dir <dir>] " +
+  "[--first-party-owner <owner/repo>]";
+
+/**
+ * Format one finding as a two-line report entry naming the referencing file,
+ * the line, the subpath and the full pinned SHA (the four facts needed to act
+ * on it without re-deriving anything).
+ */
+function formatFinding(f, cls) {
+  return (
+    `  • ${f.file}:${f.line} — ${f.subpath}@${f.sha} [${cls}]\n` +
+    `      ${f.reason}`
+  );
+}
+
+/**
+ * Run the check and return a POSIX exit code. `log` / `err` are injectable so
+ * the sibling node:test suite can capture output without touching the real
+ * streams.
+ *
+ * @param {string[]} argv
+ * @param {{log?: Function, err?: Function}} [io]
+ * @returns {number}
+ */
+export function runCli(argv, { log = console.log, err = console.error } = {}) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (e) {
+    err(`[pin-freshness] ❌ ${e.message}`);
+    err(USAGE);
+    return 1;
+  }
+  if (opts.help) {
+    log(USAGE);
+    return 0;
+  }
+
+  const result = runCheck(opts);
+
+  if (result.fatal !== null) {
+    err(`[pin-freshness] ❌ ${result.fatal}.`);
+    return 1;
+  }
+
+  if (result.unreachable.length > 0) {
+    err(
+      `[pin-freshness] ❌ ${result.unreachable.length} unreachable first-party pin(s) — ` +
+        `not an ancestor of ${opts.ref}:`
+    );
+    for (const f of result.unreachable) err(formatFinding(f, "unreachable"));
+    err(
+      "[pin-freshness] Re-pin each to the squashed commit on the default branch. " +
+        "These resolve today only because the pre-squash commit has not been " +
+        "garbage-collected yet."
+    );
+  }
+
+  if (result.stale.length > 0) {
+    err(
+      `[pin-freshness] ❌ ${result.stale.length} stale first-party pin(s) — ` +
+        `the pinned manifest lags the working tree:`
+    );
+    for (const f of result.stale) err(formatFinding(f, "stale"));
+    err(
+      "[pin-freshness] Bump each pin to a commit on the default branch whose " +
+        "manifest matches the working-tree copy. Every call site for a given " +
+        "subpath must move together (check-action-pins.mjs enforces the " +
+        "single-pin invariant per subpath)."
+    );
+  }
+
+  if (!result.ok) {
+    err(
+      "[pin-freshness] A first-party fix that no call site pins is inert: the " +
+        "pinned revision is what runs. See docs/reusable-workflows.md " +
+        "(First-party self-pin freshness) for the land-then-bump sequence."
+    );
+    return 1;
+  }
+
+  if (result.unpinnedRefs.length > 0) {
+    log(
+      `[pin-freshness] ℹ️  ${result.unpinnedRefs.length} first-party ref(s) are not SHA-pinned ` +
+        `(freshness undecidable — reported, not failed):`
+    );
+    for (const u of result.unpinnedRefs) {
+      log(`     ${u.file}:${u.line} — ${u.subpath}@${u.ref}`);
+    }
+  }
+
+  log(
+    `[pin-freshness] ✅ all ${result.scanned} first-party pin(s) resolve to a manifest ` +
+      `matching the working tree and reachable from ${opts.ref} (${result.headSha.slice(0, 7)}); ` +
+      `${result.files.length} file(s) scanned.`
+  );
+  return 0;
+}
+
+// Only run when executed directly, not when imported by the test suite.
+const invokedDirectly =
+  process.argv[1] &&
+  resolve(process.argv[1]).endsWith("check-first-party-pin-freshness.mjs");
+if (invokedDirectly) {
+  process.exit(runCli(process.argv.slice(2)));
+}