mandrel-platform 0.17.2 → 0.19.0

package/scripts/audit-check.test.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+/**
+ * audit-check.test.mjs — node:test suite for the CVE-gate core in
+ * audit-check.mjs (Story #195).
+ *
+ * Covers the fail-closed contract and the pure decision core:
+ *   - an uninterpretable report + non-zero pnpm exit fails closed (exit 1)
+ *   - a validly-suppressed high advisory (by GHSA id and by CVE id) passes
+ *   - an expired allowlist entry fails closed (exit 1)
+ *   - an unsuppressed critical fails closed (exit 1)
+ *
+ * The suppression/expiry/interpretation logic is exercised through the pure
+ * functions (`partitionAllowlist`, `isInterpretableReport`,
+ * `extractBlockingAdvisories`, `evaluateReport`) — no pnpm spawn, no
+ * filesystem — plus the CLI-level allowlist paths (`runCli` with a fixture
+ * allowlist) that decide the exit code before pnpm ever runs.
+ *
+ * Run: node --test scripts/audit-check.test.mjs  (or `node --test scripts/`)
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  partitionAllowlist,
+  isInterpretableReport,
+  extractBlockingAdvisories,
+  evaluateReport,
+  parseArgs,
+  loadAllowlist,
+  runCli,
+} from "./audit-check.mjs";
+
+const TODAY = "2026-07-02";
+
+// A far-future expiry so "valid" fixtures never age out as the clock moves.
+const FUTURE = "2999-12-31";
+// A date safely in the past.
+const PAST = "2000-01-01";
+
+/** Build a pnpm-audit-shaped report from a list of advisories. */
+function reportWith(advisories) {
+  const map = {};
+  for (const [key, adv] of Object.entries(advisories)) {
+    map[key] = adv;
+  }
+  return { advisories: map, metadata: {} };
+}
+
+const HIGH_GHSA = {
+  ghsa_id: "GHSA-aaaa-bbbb-cccc",
+  cve: ["CVE-2026-1111"],
+  severity: "high",
+  title: "High severity in transitive dep",
+  url: "https://example.test/GHSA-aaaa-bbbb-cccc",
+};
+
+const CRITICAL_ADV = {
+  ghsa_id: "GHSA-dddd-eeee-ffff",
+  cve: ["CVE-2026-2222"],
+  severity: "critical",
+  title: "Critical RCE",
+  url: "https://example.test/GHSA-dddd-eeee-ffff",
+};
+
+// ── partitionAllowlist ──────────────────────────────────────────────────────
+
+test("partitionAllowlist: active entry lands in suppressed set", () => {
+  const { suppressed, expired, invalid } = partitionAllowlist(
+    [{ id: "GHSA-aaaa-bbbb-cccc", reason: "accepted", expires: FUTURE }],
+    TODAY,
+  );
+  assert.ok(suppressed.has("GHSA-aaaa-bbbb-cccc"));
+  assert.equal(expired.length, 0);
+  assert.equal(invalid.length, 0);
+});
+
+test("partitionAllowlist: expired entry lands in expired, not suppressed", () => {
+  const { suppressed, expired } = partitionAllowlist(
+    [{ id: "GHSA-aaaa-bbbb-cccc", reason: "accepted", expires: PAST }],
+    TODAY,
+  );
+  assert.equal(suppressed.size, 0);
+  assert.equal(expired.length, 1);
+  assert.equal(expired[0].id, "GHSA-aaaa-bbbb-cccc");
+});
+
+test("partitionAllowlist: entry missing id or expires is invalid", () => {
+  const { invalid } = partitionAllowlist(
+    [
+      { reason: "no id", expires: FUTURE },
+      { id: "GHSA-x", reason: "no expires" },
+    ],
+    TODAY,
+  );
+  assert.equal(invalid.length, 2);
+});
+
+// ── isInterpretableReport ───────────────────────────────────────────────────
+
+test("isInterpretableReport: true for a report with an advisories object", () => {
+  assert.equal(isInterpretableReport(reportWith({})), true);
+});
+
+test("isInterpretableReport: false for an error envelope without advisories", () => {
+  assert.equal(
+    isInterpretableReport({ error: { code: "ERR", summary: "boom" } }),
+    false,
+  );
+  assert.equal(isInterpretableReport(null), false);
+  assert.equal(isInterpretableReport("not-json-object"), false);
+  assert.equal(isInterpretableReport({ advisories: null }), false);
+});
+
+// ── extractBlockingAdvisories: suppression matching ─────────────────────────
+
+test("extractBlockingAdvisories: high advisory suppressed by GHSA id → no blocking", () => {
+  const report = reportWith({ 1: HIGH_GHSA });
+  const suppressed = new Set(["GHSA-aaaa-bbbb-cccc"]);
+  assert.deepEqual(extractBlockingAdvisories(report, suppressed), []);
+});
+
+test("extractBlockingAdvisories: high advisory suppressed by CVE id → no blocking", () => {
+  const report = reportWith({ 1: HIGH_GHSA });
+  const suppressed = new Set(["CVE-2026-1111"]);
+  assert.deepEqual(extractBlockingAdvisories(report, suppressed), []);
+});
+
+test("extractBlockingAdvisories: unsuppressed critical is blocking", () => {
+  const report = reportWith({ 1: CRITICAL_ADV });
+  const blocking = extractBlockingAdvisories(report, new Set());
+  assert.equal(blocking.length, 1);
+  assert.equal(blocking[0].severity, "critical");
+  assert.equal(blocking[0].id, "GHSA-dddd-eeee-ffff");
+});
+
+test("extractBlockingAdvisories: moderate/low severities are ignored", () => {
+  const report = reportWith({
+    1: { ghsa_id: "GHSA-mod", severity: "moderate", title: "meh" },
+    2: { ghsa_id: "GHSA-low", severity: "low", title: "meh" },
+  });
+  assert.deepEqual(extractBlockingAdvisories(report, new Set()), []);
+});
+
+test("extractBlockingAdvisories: uninterpretable report yields empty (guarded by caller)", () => {
+  assert.deepEqual(extractBlockingAdvisories({ error: "boom" }, new Set()), []);
+});
+
+// ── evaluateReport: the fail-closed decision core ───────────────────────────
+
+test("evaluateReport: uninterpretable report + non-zero pnpm exit → exit 1 (fail closed)", () => {
+  const result = evaluateReport({ error: "boom" }, 1, new Set());
+  assert.equal(result.exitCode, 1);
+  assert.equal(result.reason, "uninterpretable-failclosed");
+});
+
+test("evaluateReport: uninterpretable report + zero exit → exit 0 (clean, nothing to report)", () => {
+  const result = evaluateReport({ metadata: {} }, 0, new Set());
+  assert.equal(result.exitCode, 0);
+  assert.equal(result.reason, "clean-no-advisories");
+});
+
+test("evaluateReport: validly-suppressed high (GHSA) → exit 0", () => {
+  const report = reportWith({ 1: HIGH_GHSA });
+  const result = evaluateReport(report, 1, new Set(["GHSA-aaaa-bbbb-cccc"]));
+  assert.equal(result.exitCode, 0);
+  assert.equal(result.reason, "clean");
+});
+
+test("evaluateReport: validly-suppressed high (CVE) → exit 0", () => {
+  const report = reportWith({ 1: HIGH_GHSA });
+  const result = evaluateReport(report, 1, new Set(["CVE-2026-1111"]));
+  assert.equal(result.exitCode, 0);
+  assert.equal(result.reason, "clean");
+});
+
+test("evaluateReport: unsuppressed critical → exit 1", () => {
+  const report = reportWith({ 1: CRITICAL_ADV });
+  const result = evaluateReport(report, 1, new Set());
+  assert.equal(result.exitCode, 1);
+  assert.equal(result.reason, "unsuppressed");
+  assert.equal(result.blocking.length, 1);
+});
+
+// ── CLI-level: expired allowlist short-circuits before pnpm ─────────────────
+
+test("runCli: expired allowlist entry → exit non-zero (before pnpm runs)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "audit-check-expired-"));
+  try {
+    const allowlistPath = join(dir, "audit-allowlist.json");
+    writeFileSync(
+      allowlistPath,
+      JSON.stringify([
+        { id: "GHSA-aaaa-bbbb-cccc", reason: "was accepted", expires: PAST },
+      ]),
+    );
+    const exit = runCli(["--allowlist", allowlistPath]);
+    assert.equal(exit, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("runCli: malformed allowlist entry (missing expires) → exit non-zero", () => {
+  const dir = mkdtempSync(join(tmpdir(), "audit-check-malformed-"));
+  try {
+    const allowlistPath = join(dir, "audit-allowlist.json");
+    writeFileSync(
+      allowlistPath,
+      JSON.stringify([{ id: "GHSA-aaaa-bbbb-cccc", reason: "no expiry" }]),
+    );
+    const exit = runCli(["--allowlist", allowlistPath]);
+    assert.equal(exit, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("runCli: non-array allowlist → exit non-zero", () => {
+  const dir = mkdtempSync(join(tmpdir(), "audit-check-nonarray-"));
+  try {
+    const allowlistPath = join(dir, "audit-allowlist.json");
+    writeFileSync(allowlistPath, JSON.stringify({ not: "an array" }));
+    const exit = runCli(["--allowlist", allowlistPath]);
+    assert.equal(exit, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ── parseArgs / loadAllowlist ───────────────────────────────────────────────
+
+test("parseArgs: --allowlist resolves against cwd; default is audit-allowlist.json", () => {
+  assert.equal(
+    parseArgs(["--allowlist", "custom.json"], "/repo").allowlistPath,
+    "/repo/custom.json",
+  );
+  assert.equal(
+    parseArgs([], "/repo").allowlistPath,
+    "/repo/audit-allowlist.json",
+  );
+});
+
+test("loadAllowlist: absent file returns empty array", () => {
+  assert.deepEqual(
+    loadAllowlist(join(tmpdir(), "does-not-exist-xyz.json")),
+    [],
+  );
+});
+
+test("loadAllowlist: non-array throws", () => {
+  const dir = mkdtempSync(join(tmpdir(), "audit-check-load-"));
+  try {
+    const p = join(dir, "a.json");
+    writeFileSync(p, JSON.stringify({ nope: true }));
+    assert.throws(() => loadAllowlist(p), /must be a JSON array/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/scripts/check-action-pins.mjs

@@ -2,7 +2,7 @@
 /**
  * check-action-pins.mjs
  *
- * Action-pin ratchet (Story #112).
+ * Action-pin ratchet (Story #112) + intra-repo single-pin invariant (#203).
  *
  * Third-party GitHub Actions referenced by `uses:` in this repo's workflows
  * and composite actions are SHA-pinned by convention — but until now NOTHING
@@ -32,12 +32,20 @@
  *     composite actions, governed by the cross-repo portability lint's pin-lag
  *     guard (`check-workflow-portability.mjs`, Rule 3), and they carry a
  *     release-tag shape at publish time. The first-party owner is overridable
- *     via `--first-party-owner` for a fork.
+ *     via `--first-party-owner` for a fork. They ARE, however, subject to the
+ *     single-pin invariant below.
  *
  *   • LOCAL `./path` references and `docker://image` references are EXEMPT —
  *     a local path has no upstream tag to move, and a docker ref is pinned by
  *     its own digest convention, out of scope for this action-tag ratchet.
  *
+ * Single-pin invariant (Story #203): across `.github/workflows/`, two
+ * first-party `uses:` refs to the SAME subpath MUST carry the SAME SHA. Two
+ * workflows pinning `owner/repo/.github/actions/foo` at different commits is a
+ * silent split-brain — one workflow runs the fixed action, the other the
+ * stale one. This lint fails when that drift is present. Disable with
+ * `--no-single-pin` (e.g. mid-migration).
+ *
  * The reference is read from the `uses:` value with any trailing `# comment`
  * (the conventional `# v4.2.2` tag annotation) stripped first, so the human
  * tag note alongside the SHA never confuses the parse.
@@ -47,11 +55,13 @@
  *   node scripts/check-action-pins.mjs --workflows-dir .github/workflows
  *   node scripts/check-action-pins.mjs --actions-dir .github/actions
  *   node scripts/check-action-pins.mjs --first-party-owner my-org/my-repo
+ *   node scripts/check-action-pins.mjs --no-single-pin
  *
  * Exit codes:
- *   0 — every third-party `uses:` is pinned to a full 40-char commit SHA.
- *   1 — one or more third-party actions are not SHA-pinned (each named in
- *       stderr with file:line).
+ *   0 — every third-party `uses:` is SHA-pinned and the single-pin invariant holds.
+ *   1 — one or more third-party actions are not SHA-pinned, or a first-party
+ *       subpath is pinned to two different SHAs (each named in stderr with
+ *       file:line).
  *
  * Consumer adoption:
  *   Copy this script into your project's `scripts/` directory and wire it into
@@ -60,20 +70,37 @@
  *     - name: Lint third-party action pins
  *       run: node scripts/check-action-pins.mjs --first-party-owner <owner/repo>
  *
- *   It is dependency-free (no YAML parser) so it copies cleanly into any repo.
+ *   It depends only on the sibling `scripts/lib/` helpers (no YAML parser), so
+ *   copy `scripts/lib/{args,uses-pins,walk}.mjs` alongside it.
  */
 
-import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
-import { resolve, join, relative } from "node:path";
+import { readFileSync } from "node:fs";
+import { resolve, relative } from "node:path";
 
-// ---------------------------------------------------------------------------
-// Pure helpers (exported for the sibling node:test suite)
-// ---------------------------------------------------------------------------
+import { parseFlags } from "./lib/args.mjs";
+import {
+  DEFAULT_FIRST_PARTY_OWNER,
+  stripUsesValue,
+  parseUsesLine,
+  classifyUses,
+  isSha40,
+  findSinglePinViolations,
+} from "./lib/uses-pins.mjs";
+import { listWorkflowFiles, listActionFiles } from "./lib/walk.mjs";
 
-const DEFAULT_FIRST_PARTY_OWNER = "dsj1984/mandrel-platform";
+// Re-export the shared primitives so the sibling test suite (and any external
+// consumer that imports from this script) keeps its existing import surface.
+export {
+  stripUsesValue,
+  classifyUses,
+  isSha40,
+  listWorkflowFiles,
+  listActionFiles,
+};
 
-/** A full git commit SHA is exactly 40 lowercase/uppercase hex characters. */
-const SHA40_RE = /^[0-9a-fA-F]{40}$/;
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
 
 /**
  * Parse the CLI argv (array AFTER `node script.mjs`) into an options object.
@@ -81,106 +108,21 @@ const SHA40_RE = /^[0-9a-fA-F]{40}$/;
  * loudly rather than silently mis-reading its own configuration.
  */
 export function parseArgs(argv) {
-  const opts = {
-    workflowsDir: ".github/workflows",
-    actionsDir: ".github/actions",
-    firstPartyOwner: DEFAULT_FIRST_PARTY_OWNER,
-    cwd: process.cwd(),
-  };
-  const takeValue = (i, flag) => {
-    const v = argv[i + 1];
-    if (v === undefined || v.startsWith("--")) {
-      throw new Error(`missing value for "${flag}"`);
-    }
-    return v;
-  };
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    switch (arg) {
-      case "--workflows-dir":
-        opts.workflowsDir = takeValue(i, arg);
-        i++;
-        break;
-      case "--actions-dir":
-        opts.actionsDir = takeValue(i, arg);
-        i++;
-        break;
-      case "--first-party-owner":
-        opts.firstPartyOwner = takeValue(i, arg);
-        i++;
-        break;
-      case "--cwd":
-        opts.cwd = takeValue(i, arg);
-        i++;
-        break;
-      default:
-        throw new Error(`unknown argument "${arg}"`);
-    }
-  }
-  return opts;
-}
-
-/**
- * Strip a trailing `# comment` (the conventional `# v4.2.2` tag note) and
- * surrounding whitespace/quotes from a raw `uses:` value, returning the bare
- * action reference. A `#` inside the ref itself is not valid GitHub syntax,
- * so splitting on the first ` #` is safe.
- */
-export function stripUsesValue(raw) {
-  let v = String(raw).trim();
-  // Drop a trailing comment: the first '#' that is preceded by whitespace (or
-  // at the start) begins a comment. GitHub action refs never contain '#'.
-  const hashIdx = v.search(/\s#/);
-  if (hashIdx !== -1) v = v.slice(0, hashIdx);
-  v = v.trim();
-  // Unwrap matched surrounding quotes.
-  if (
-    (v.startsWith('"') && v.endsWith('"')) ||
-    (v.startsWith("'") && v.endsWith("'"))
-  ) {
-    v = v.slice(1, -1).trim();
-  }
-  return v;
-}
-
-/**
- * Classify a bare `uses:` reference. Returns one of:
- *   { kind: 'local' }            — `./path` or `../path` (exempt)
- *   { kind: 'docker' }           — `docker://image` (exempt)
- *   { kind: 'first-party', owner, ref } — the configured first-party owner (exempt)
- *   { kind: 'third-party', owner, ref } — external action (MUST be SHA-pinned)
- *   { kind: 'unparseable' }      — not a recognizable `uses:` reference
- */
-export function classifyUses(bareRef, firstPartyOwner = DEFAULT_FIRST_PARTY_OWNER) {
-  const ref = String(bareRef).trim();
-  if (ref === "") return { kind: "unparseable" };
-  if (ref.startsWith("./") || ref.startsWith("../")) return { kind: "local" };
-  if (ref.startsWith("docker://")) return { kind: "docker" };
-
-  // owner/repo[/subpath]@gitref. The git ref is everything after the LAST '@'
-  // (an action subpath never contains '@'; the ref does not either).
-  const atIdx = ref.lastIndexOf("@");
-  if (atIdx === -1) {
-    // No `@ref` at all — not a pinnable external reference (e.g. a malformed
-    // entry). Treat as unparseable so the caller can flag it explicitly.
-    return { kind: "unparseable", ownerRepoPath: ref };
-  }
-  const ownerRepoPath = ref.slice(0, atIdx);
-  const gitRef = ref.slice(atIdx + 1);
-  const segments = ownerRepoPath.split("/");
-  if (segments.length < 2) return { kind: "unparseable", ownerRepoPath, ref: gitRef };
-
-  const ownerRepo = `${segments[0]}/${segments[1]}`;
-  if (ownerRepo.toLowerCase() === String(firstPartyOwner).toLowerCase()) {
-    return { kind: "first-party", owner: ownerRepo, ref: gitRef };
-  }
-  return { kind: "third-party", owner: ownerRepo, ref: gitRef };
+  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() },
+      "--no-single-pin": { type: "boolean", dest: "singlePin", value: false, default: true },
+    },
+    onUnknown: "throw",
+  });
 }
 
-/** True when a git ref is a full 40-character commit SHA. */
-export function isSha40(gitRef) {
-  return SHA40_RE.test(String(gitRef).trim());
-}
+// ---------------------------------------------------------------------------
+// Content scan
+// ---------------------------------------------------------------------------
 
 /**
  * Scan a single file's TEXT for `uses:` step keys and evaluate each third-party
@@ -198,17 +140,9 @@ export function scanContent(content, displayFile, firstPartyOwner = DEFAULT_FIRS
   const violations = [];
   let scanned = 0;
   const lines = String(content).split(/\r?\n/);
-  // Matches a YAML `uses:` mapping key: optional leading whitespace, an
-  // optional leading `- ` (sequence item), then `uses:` and the value.
-  const usesRe = /^\s*(?:-\s+)?uses:\s*(\S.*)$/;
   for (let i = 0; i < lines.length; i++) {
-    const raw = lines[i];
-    // Skip whole-line comments outright (defensive; the regex below also
-    // won't match a leading '#').
-    if (/^\s*#/.test(raw)) continue;
-    const m = raw.match(usesRe);
-    if (!m) continue;
-    const bareRef = stripUsesValue(m[1]);
+    const bareRef = parseUsesLine(lines[i]);
+    if (bareRef === null) continue;
     const cls = classifyUses(bareRef, firstPartyOwner);
     if (cls.kind !== "third-party") continue; // local/docker/first-party/unparseable → exempt
     scanned++;
@@ -225,67 +159,29 @@ export function scanContent(content, displayFile, firstPartyOwner = DEFAULT_FIRS
   return { violations, scanned };
 }
 
-// ---------------------------------------------------------------------------
-// Filesystem walking
-// ---------------------------------------------------------------------------
-
-/** List `*.yml` / `*.yaml` files directly under a workflows dir (non-recursive). */
-export function listWorkflowFiles(dir) {
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir)
-    .filter((f) => /\.ya?ml$/.test(f))
-    .map((f) => join(dir, f))
-    .filter((p) => {
-      try {
-        return statSync(p).isFile();
-      } catch {
-        return false;
-      }
-    })
-    .sort();
-}
-
-/** Recursively list composite `action.yml` / `action.yaml` files under a dir. */
-export function listActionFiles(dir) {
-  const out = [];
-  if (!existsSync(dir)) return out;
-  const walk = (d) => {
-    let entries;
-    try {
-      entries = readdirSync(d, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const e of entries) {
-      const full = join(d, e.name);
-      if (e.isDirectory()) {
-        walk(full);
-      } else if (/^action\.ya?ml$/.test(e.name)) {
-        out.push(full);
-      }
-    }
-  };
-  walk(dir);
-  return out.sort();
-}
-
 // ---------------------------------------------------------------------------
 // Orchestration
 // ---------------------------------------------------------------------------
 
 /**
  * Run the full lint against the resolved option set. Returns
- * `{ ok, violations, scanned, files }`. Pure with respect to stdout — the CLI
- * wrapper formats and prints.
+ * `{ ok, violations, scanned, files, singlePinViolations }`. Pure with respect
+ * to stdout — the CLI wrapper formats and prints. `singlePinViolations` is
+ * populated only when `opts.singlePin` is not `false`, and reflects the
+ * intra-repo single-pin invariant across the workflow files only.
  */
 export function runLint(opts) {
   const cwd = opts.cwd || process.cwd();
   const wfDir = resolve(cwd, opts.workflowsDir);
   const acDir = resolve(cwd, opts.actionsDir);
-  const files = [...listWorkflowFiles(wfDir), ...listActionFiles(acDir)];
+  const workflowFiles = listWorkflowFiles(wfDir);
+  const files = [...workflowFiles, ...listActionFiles(acDir)];
 
   const violations = [];
   let scanned = 0;
+  // Keep the raw workflow-file contents for the single-pin pass so we read
+  // each file from disk once.
+  const workflowRecords = [];
   for (const file of files) {
     let content;
     try {
@@ -297,8 +193,23 @@ export function runLint(opts) {
     const res = scanContent(content, display, opts.firstPartyOwner);
     violations.push(...res.violations);
     scanned += res.scanned;
+    if (workflowFiles.includes(file)) {
+      workflowRecords.push({ file: display, content });
+    }
   }
-  return { ok: violations.length === 0, violations, scanned, files };
+
+  const singlePin = opts.singlePin !== false;
+  const singlePinViolations = singlePin
+    ? findSinglePinViolations(workflowRecords, opts.firstPartyOwner)
+    : [];
+
+  return {
+    ok: violations.length === 0 && singlePinViolations.length === 0,
+    violations,
+    scanned,
+    files,
+    singlePinViolations,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -316,7 +227,10 @@ export function runCli(argv, { log = console.log, err = console.error } = {}) {
 
   const result = runLint(opts);
 
-  if (!result.ok) {
+  let failed = false;
+
+  if (result.violations.length > 0) {
+    failed = true;
     err(`[action-pins] ❌ ${result.violations.length} unpinned third-party action(s):`);
     for (const v of result.violations) {
       err(`  • ${v.file}:${v.line} — ${v.reason}`);
@@ -326,12 +240,31 @@ export function runCli(argv, { log = console.log, err = console.error } = {}) {
         "(keep the `# vX.Y.Z` tag note as a comment). A mutable tag can be " +
         "force-moved to a malicious commit after review."
     );
-    return 1;
   }
 
+  if (result.singlePinViolations.length > 0) {
+    failed = true;
+    err(
+      `[action-pins] ❌ ${result.singlePinViolations.length} first-party subpath(s) pinned to different SHAs (single-pin invariant):`
+    );
+    for (const v of result.singlePinViolations) {
+      err(`  • ${v.target} is pinned to ${v.shas.length} distinct refs:`);
+      for (const occ of v.occurrences) {
+        err(`      ${occ.file}:${occ.line} — @${occ.ref}`);
+      }
+    }
+    err(
+      "[action-pins] Every first-party `uses:` to the same subpath across " +
+        ".github/workflows/ must carry the SAME SHA — otherwise one workflow " +
+        "runs the fixed action and another the stale one."
+    );
+  }
+
+  if (failed) return 1;
+
   log(
     `[action-pins] ✅ all ${result.scanned} third-party action reference(s) are SHA-pinned ` +
-      `(${result.files.length} file(s) scanned).`
+      `(${result.files.length} file(s) scanned); first-party single-pin invariant holds.`
   );
   return 0;
 }