mandrel-platform 1.11.0 → 1.12.0

package/scripts/audit-check.test.mjs

@@ -46,6 +46,9 @@ import {
   isBoundedOverride,
   findUnboundedOverrides,
   lintOverrides,
+  detectPackageManager,
+  ghsaIdFromUrl,
+  recognizeReport,
 } from "./audit-check.mjs";
 
 const TODAY = "2026-07-02";
@@ -319,10 +322,29 @@ test("evaluateReport: uninterpretable report + non-zero pnpm exit → exit 1 (fa
   assert.equal(result.reason, "uninterpretable-failclosed");
 });
 
-test("evaluateReport: uninterpretable report + zero exit → exit 0 (clean, nothing to report)", () => {
+test("evaluateReport: unrecognized report + ZERO exit → exit 1 (fail closed)", () => {
+  // This assertion is the inverse of the one it replaces (Story #475), and the
+  // inversion is the point. The old contract read "no advisories key" as "no
+  // advisories" and passed on a zero exit. That is safe only while every report
+  // this gate can meet is the legacy shape — and it is not: `npm audit --json`
+  // reports v7+ advisories under `vulnerabilities` and exits 0 when clean, so
+  // the old branch would have reported an npm graph clean without reading one
+  // advisory, and would have kept doing so as highs landed.
+  //
+  // A report is clean only when a schema was RECOGNIZED and found nothing.
   const result = evaluateReport({ metadata: {} }, 0, new Set());
-  assert.equal(result.exitCode, 0);
-  assert.equal(result.reason, "clean-no-advisories");
+  assert.equal(result.exitCode, 1);
+  assert.equal(result.reason, "uninterpretable-failclosed");
+  assert.equal(result.schema, null);
+});
+
+test("evaluateReport: an unrecognized report fails closed on EVERY exit code", () => {
+  // Exit code must not be able to rescue an unreadable report from either side.
+  for (const exitCode of [0, 1, 2, 127]) {
+    const result = evaluateReport({ nonsense: true }, exitCode, new Set());
+    assert.equal(result.exitCode, 1, `exit ${exitCode}`);
+    assert.equal(result.reason, "uninterpretable-failclosed", `exit ${exitCode}`);
+  }
 });
 
 test("evaluateReport: validly-suppressed high (GHSA) → exit 0", () => {
@@ -837,3 +859,186 @@ test("parseArgs defaults the package.json path alongside the allowlist path", ()
   assert.equal(allowlistPath, "/tmp/proj/audit-allowlist.json");
   assert.equal(packageJsonPath, "/tmp/proj/package.json");
 });
+
+// ---------------------------------------------------------------------------
+// Package-manager detection (Story #475)
+//
+// The lockfile is the discriminator, not `packageManager` / `engines`: it is
+// what the audit actually reads, and this very repo declares one manager in
+// metadata while committing the other's lockfile.
+// ---------------------------------------------------------------------------
+
+/** existsSync stub answering true for exactly the named basenames. */
+function lockfilesPresent(...names) {
+  return (path) => names.some((name) => path.endsWith(`/${name}`));
+}
+
+test("detectPackageManager: a pnpm lockfile selects pnpm", () => {
+  const result = detectPackageManager("/proj", {
+    existsSyncImpl: lockfilesPresent("pnpm-lock.yaml"),
+  });
+  assert.equal(result.manager, "pnpm");
+  assert.equal(result.error, undefined);
+});
+
+test("detectPackageManager: an npm lockfile selects npm", () => {
+  const result = detectPackageManager("/proj", {
+    existsSyncImpl: lockfilesPresent("package-lock.json"),
+  });
+  assert.equal(result.manager, "npm");
+  assert.equal(result.error, undefined);
+});
+
+test("detectPackageManager: no lockfile is a loud error, never a default", () => {
+  // Defaulting to either manager would make the gate's verdict a claim about a
+  // graph nobody chose.
+  const result = detectPackageManager("/proj", { existsSyncImpl: () => false });
+  assert.equal(result.manager, undefined);
+  assert.match(result.error, /No lockfile found/);
+});
+
+test("detectPackageManager: two lockfiles are a loud error, never a guess", () => {
+  const result = detectPackageManager("/proj", {
+    existsSyncImpl: lockfilesPresent("pnpm-lock.yaml", "package-lock.json"),
+  });
+  assert.equal(result.manager, undefined);
+  assert.match(result.error, /Ambiguous lockfiles/);
+});
+
+// ---------------------------------------------------------------------------
+// GHSA id extraction — npm exposes the id ONLY inside the advisory url
+// ---------------------------------------------------------------------------
+
+test("ghsaIdFromUrl: reads the id from a GitHub advisory url", () => {
+  assert.equal(
+    ghsaIdFromUrl("https://github.com/advisories/GHSA-aaaa-bbbb-cccc"),
+    "GHSA-AAAA-BBBB-CCCC",
+  );
+});
+
+test("ghsaIdFromUrl: only the last path segment counts, never the host", () => {
+  // Matching a GHSA-shaped substring anywhere in a caller-controlled URL would
+  // let a hostile host or query string mint an id that silences an allowlist
+  // lookup. Only the final path segment is tested.
+  assert.equal(ghsaIdFromUrl("https://GHSA-aaaa-bbbb-cccc.example.com/x"), null);
+  assert.equal(
+    ghsaIdFromUrl("https://example.com/p?id=GHSA-aaaa-bbbb-cccc"),
+    null,
+  );
+});
+
+test("ghsaIdFromUrl: rejects non-urls, empty values and non-GHSA segments", () => {
+  for (const value of ["", "not a url", null, undefined, 42, "https://example.com/x"]) {
+    assert.equal(ghsaIdFromUrl(value), null, String(value));
+  }
+});
+
+// ---------------------------------------------------------------------------
+// The npm v7+ (`auditReportVersion` 2) report shape
+//
+// Fixture-driven of necessity: this repo has zero vulnerabilities tree-wide,
+// so no live npm sample carrying an advisory can be captured from it.
+// ---------------------------------------------------------------------------
+
+const NPM_HIGH_URL = "https://github.com/advisories/GHSA-dddd-eeee-ffff";
+
+/** An npm v2 report with one high advisory reached through `pkg`. */
+function npmReportWithHigh({ severity = "high", cve = [] } = {}) {
+  return {
+    auditReportVersion: 2,
+    vulnerabilities: {
+      pkg: {
+        name: "pkg",
+        severity,
+        via: [
+          {
+            source: 123456,
+            name: "pkg",
+            title: "Prototype pollution in pkg",
+            url: NPM_HIGH_URL,
+            severity,
+            cve,
+          },
+        ],
+      },
+    },
+    metadata: { vulnerabilities: { high: 1, total: 1 } },
+  };
+}
+
+test("recognizeReport: identifies each schema and normalizes its advisories", () => {
+  assert.equal(recognizeReport(reportWith({ 1: HIGH_GHSA })).schema, "legacy");
+
+  const npm = recognizeReport(npmReportWithHigh());
+  assert.equal(npm.schema, "npm");
+  assert.equal(npm.advisories.length, 1);
+  assert.deepEqual(npm.advisories[0].ids, ["GHSA-DDDD-EEEE-FFFF"]);
+  assert.equal(npm.advisories[0].severity, "high");
+});
+
+test("recognizeReport: an empty npm report is RECOGNIZED, not unreadable", () => {
+  // The real shape this repo produces today. It must read as a genuine clean —
+  // reached by inspecting `vulnerabilities`, not by failing to find
+  // `advisories`.
+  const result = recognizeReport({
+    auditReportVersion: 2,
+    vulnerabilities: {},
+    metadata: { vulnerabilities: { total: 0 } },
+  });
+  assert.equal(result.schema, "npm");
+  assert.deepEqual(result.advisories, []);
+});
+
+test("evaluateReport: an unsuppressed high in the NPM shape blocks", () => {
+  const result = evaluateReport(npmReportWithHigh(), 1, new Set());
+  assert.equal(result.exitCode, 1);
+  assert.equal(result.reason, "unsuppressed");
+  assert.equal(result.schema, "npm");
+  assert.equal(result.blocking.length, 1);
+  assert.equal(result.blocking[0].id, "GHSA-DDDD-EEEE-FFFF");
+});
+
+test("evaluateReport: an allowlisted GHSA id suppresses in the NPM shape", () => {
+  // The id exists only inside `via[].url` here, so this is the assertion that
+  // the allowlist still means something once the schema changes.
+  const result = evaluateReport(
+    npmReportWithHigh(),
+    1,
+    new Set(["GHSA-DDDD-EEEE-FFFF"]),
+  );
+  assert.equal(result.exitCode, 0);
+  assert.equal(result.reason, "clean");
+});
+
+test("evaluateReport: a CVE id suppresses in the NPM shape too", () => {
+  const report = npmReportWithHigh({ cve: ["CVE-2026-9999"] });
+  assert.equal(
+    evaluateReport(report, 1, new Set(["CVE-2026-9999"])).exitCode,
+    0,
+  );
+  assert.equal(evaluateReport(report, 1, new Set()).exitCode, 1);
+});
+
+test("evaluateReport: below-gate npm severities never block", () => {
+  for (const severity of ["moderate", "low", "info"]) {
+    const result = evaluateReport(npmReportWithHigh({ severity }), 0, new Set());
+    assert.equal(result.exitCode, 0, severity);
+    assert.equal(result.reason, "clean", severity);
+  }
+});
+
+test("recognizeReport: a transitive npm chain counts its advisory once", () => {
+  // `via` carries STRING edges for transitive chains alongside advisory
+  // objects. Counting an edge as an advisory would inflate the finding set;
+  // counting the same advisory once per reaching package would duplicate it.
+  const report = {
+    auditReportVersion: 2,
+    vulnerabilities: {
+      pkg: npmReportWithHigh().vulnerabilities.pkg,
+      dependent: { name: "dependent", severity: "high", via: ["pkg"] },
+      other: npmReportWithHigh().vulnerabilities.pkg,
+    },
+    metadata: {},
+  };
+  assert.equal(recognizeReport(report).advisories.length, 1);
+});

package/scripts/check-advisory-scan-setup.test.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * check-advisory-scan-setup.test.mjs — regression guard for advisory-scan.yml's
+ * `setup` input (Story #471).
+ *
+ * The bug this pins: `advisory-scan.yml` provisioned Node one way only — the
+ * `setup-toolchain` composite, which is pnpm-only (`actions/setup-node` with
+ * `cache: pnpm`, then `pnpm install --frozen-lockfile`). This repo is npm
+ * (`package-lock.json`, `npm ci` in ci.yml, no `pnpm-lock.yaml`), so the
+ * scheduled dogfood caller died at setup-node — "Dependencies lock file is not
+ * found ... Supported file patterns: pnpm-lock.yaml" — on EVERY run from the
+ * day it shipped. The job never reached the scan, so a workflow whose whole
+ * job is to notice things silently noticed nothing for seven weeks.
+ *
+ * That failure mode is why the assertions below are behavioural rather than
+ * textual wherever they can be: the `if:` expressions are EXTRACTED and RUN
+ * under GitHub's own truthiness rules (`scripts/lib/actions-expression.mjs`),
+ * because the defect class here is an expression that reads correctly and
+ * evaluates wrong.
+ *
+ * Run: node --test scripts/check-advisory-scan-setup.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readFileSync } from "node:fs";
+import { evaluate } from "./lib/actions-expression.mjs";
+
+const ADVISORY = ".github/workflows/advisory-scan.yml";
+const SCHEDULE = ".github/workflows/advisory-scan-schedule.yml";
+const DOCS = "docs/reusable-workflows.md";
+const ARCHITECTURE = "docs/architecture.md";
+
+const advisory = readFileSync(ADVISORY, "utf8");
+const schedule = readFileSync(SCHEDULE, "utf8");
+
+// ---------------------------------------------------------------------------
+// Extraction — the same read-then-execute approach as
+// check-toolchain-cache-default.test.mjs, so a guarded expression is never
+// asserted by its spelling.
+// ---------------------------------------------------------------------------
+
+/**
+ * The block of one `- name: <name>` step, up to the next step at the same
+ * indent. Scans lines rather than building a `new RegExp` around `name`: a
+ * dynamically-constructed regex is a SAST finding and buys nothing here.
+ */
+function stepByName(text, name) {
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => l.trim() === `- name: ${name}`);
+  assert.notEqual(start, -1, `${ADVISORY}: step "${name}" not found`);
+  const indent = lines[start].match(/^(\s*)/)[1].length;
+  const out = [lines[start]];
+  for (let i = start + 1; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed.startsWith("- ") && lines[i].match(/^(\s*)/)[1].length <= indent) break;
+    out.push(lines[i]);
+  }
+  return out.join("\n");
+}
+
+/** The `${{ … }}`-free body of a step's `if:` condition. */
+function ifExpression(step, name) {
+  const m = step.match(/^\s*if:\s*(.+)$/m);
+  assert.ok(m, `step "${name}" has no \`if:\` guard`);
+  return m[1].trim().replace(/^\$\{\{/, "").replace(/\}\}$/, "").trim();
+}
+
+/** The literal `default:` of the named workflow_call input. */
+function inputDefault(text, name) {
+  const lines = text.split("\n");
+  const start = lines.indexOf(`      ${name}:`);
+  assert.notEqual(start, -1, `${ADVISORY}: workflow_call input \`${name}\` not found`);
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].trim() === "") continue;
+    if (lines[i].match(/^(\s*)/)[1].length <= 6) break;
+    const d = lines[i].match(/^\s*default:\s*(.+)$/);
+    if (d) return d[1].trim();
+  }
+  return assert.fail(`${ADVISORY}: input \`${name}\` has no default`);
+}
+
+const TOOLCHAIN_STEP = "Setup toolchain";
+const NODE_STEP = "Setup Node.js (install-free)";
+const GUARD_STEP = "Validate setup input";
+
+// ---------------------------------------------------------------------------
+// AC-1 — the default is a literal, so no consumer moves.
+// ---------------------------------------------------------------------------
+
+test("the `setup` default is a literal 'toolchain', not an expression", () => {
+  // An expression here is what portability lint Rule 2 rejects and what GitHub
+  // silently fails to evaluate at interface-validation time. The value itself
+  // matters just as much: every consumer on today's pinned SHA passes no
+  // `setup` at all, so the default IS their behaviour.
+  const value = inputDefault(advisory, "setup");
+  assert.equal(value, "'toolchain'");
+  assert.doesNotMatch(value, /\$\{\{/, "a workflow_call default may not hold an expression");
+});
+
+// ---------------------------------------------------------------------------
+// AC-3 — one cache site, and none on the install-free path.
+// ---------------------------------------------------------------------------
+
+test("exactly one cache expression exists, and it is the toolchain step's", () => {
+  // check-toolchain-cache-default.test.mjs extracts the FIRST `cache: ${{ … }}`
+  // in this file and asserts it against pr-quality.yml's. A second site would
+  // silently pin the wrong expression while that whole suite stayed green — so
+  // the count, not just the value, is the invariant.
+  const sites = advisory.split("\n").filter((l) => /^\s*cache:\s*\$\{\{.+\}\}\s*$/.test(l));
+  assert.equal(sites.length, 1, "expected exactly one cache: call site");
+  assert.ok(
+    stepByName(advisory, TOOLCHAIN_STEP).includes(sites[0]),
+    "the surviving cache site must belong to the setup-toolchain step",
+  );
+});
+
+test("the install-free step declares no cache key at all", () => {
+  // Not even `cache: ''` — an empty value is still a second site for a reader,
+  // and there is nothing to cache on a path that installs nothing.
+  assert.doesNotMatch(stepByName(advisory, NODE_STEP), /^\s*cache:/m);
+});
+
+// ---------------------------------------------------------------------------
+// AC-4 — the install-free path provisions a pinned Node and installs nothing.
+// ---------------------------------------------------------------------------
+
+test("the install-free step pins Node from .nvmrc via a SHA-pinned setup-node", () => {
+  const step = stepByName(advisory, NODE_STEP);
+  assert.match(step, /node-version-file:\s*\.nvmrc/, "Node must come from .nvmrc, not a literal");
+  assert.match(
+    step,
+    /uses:\s*actions\/setup-node@[0-9a-f]{40}/,
+    "setup-node must be SHA-pinned",
+  );
+});
+
+test("no dependency install runs on the install-free path", () => {
+  // The whole point of the path: osv-scanner reads lockfiles off disk, and both
+  // composites' gate scripts import only node builtins and relative siblings.
+  const step = stepByName(advisory, NODE_STEP);
+  assert.doesNotMatch(step, /pnpm install/, "the install-free path must not install");
+  assert.doesNotMatch(step, /npm ci|npm install/, "the install-free path must not install");
+});
+
+// ---------------------------------------------------------------------------
+// AC-5 — exhaustive selection, and a loud failure on anything else.
+// ---------------------------------------------------------------------------
+
+test("each recognized `setup` value selects exactly one provisioning step", () => {
+  // Evaluated, not grepped: `&&`/`||` in an Actions expression yield OPERANDS
+  // and every non-empty string is truthy, so a guard can read right and select
+  // both branches — or neither.
+  const guards = [
+    { name: TOOLCHAIN_STEP, expr: ifExpression(stepByName(advisory, TOOLCHAIN_STEP), TOOLCHAIN_STEP) },
+    { name: NODE_STEP, expr: ifExpression(stepByName(advisory, NODE_STEP), NODE_STEP) },
+  ];
+  for (const setup of ["toolchain", "node"]) {
+    const selected = guards.filter(({ expr }) => evaluate(expr, { setup }) === true);
+    assert.equal(
+      selected.length,
+      1,
+      `setup '${setup}' selected ${selected.length} step(s): ${selected.map((s) => s.name).join(", ")}`,
+    );
+  }
+});
+
+test("an unrecognized `setup` value selects NO provisioning step — so a guard must reject it first", () => {
+  // This is the fail-closed half. With both branches skipped and no guard, the
+  // job would run the composites' gate scripts against whatever ambient Node
+  // the runner image carries: green, unpinned, and wrong.
+  const guards = [TOOLCHAIN_STEP, NODE_STEP].map((name) =>
+    ifExpression(stepByName(advisory, name), name),
+  );
+  for (const setup of ["", "nodejs", "Toolchain ", "true"]) {
+    assert.equal(
+      guards.filter((expr) => evaluate(expr, { setup }) === true).length,
+      0,
+      `setup '${setup}' must not select a provisioning step`,
+    );
+  }
+
+  const guard = stepByName(advisory, GUARD_STEP);
+  assert.match(guard, /toolchain\|node\)/, "the guard must accept exactly the two known values");
+  assert.match(guard, /::error::/, "the guard must fail loudly, not warn");
+  assert.match(guard, /exit 1/, "the guard must fail the job");
+});
+
+test("the guard runs before either provisioning step", () => {
+  // A guard that ran after the branches would report the typo only once the
+  // damage — a scan on ambient Node — had already been done.
+  const order = [GUARD_STEP, TOOLCHAIN_STEP, NODE_STEP].map((name) =>
+    advisory.indexOf(`- name: ${name}`),
+  );
+  assert.ok(order.every((i) => i !== -1), "every named step must exist");
+  assert.ok(order[0] < order[1] && order[0] < order[2], "the guard must come first");
+});
+
+// ---------------------------------------------------------------------------
+// AC-6 — the dogfood caller is on the new path.
+// ---------------------------------------------------------------------------
+
+test("the scheduled dogfood caller passes setup: node", () => {
+  // This repo commits package-lock.json and has no pnpm-lock.yaml, so the
+  // pnpm default cannot survive its own setup step here.
+  assert.match(schedule, /^\s*setup:\s*node\s*$/m, `${SCHEDULE} must pass setup: node`);
+});
+
+test("this repo really is the npm case the caller claims", () => {
+  // The assertion above is only correct while the premise holds. If this repo
+  // ever adopts pnpm, this test fails and the caller gets revisited — rather
+  // than silently keeping an install-free path it no longer needs.
+  const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+  assert.ok(pkg, "package.json must parse");
+  assert.doesNotThrow(
+    () => readFileSync("package-lock.json", "utf8"),
+    "package-lock.json must exist for the npm premise to hold",
+  );
+  assert.throws(
+    () => readFileSync("pnpm-lock.yaml", "utf8"),
+    "a pnpm-lock.yaml would mean setup: node is no longer the right call here",
+  );
+});
+
+// ---------------------------------------------------------------------------
+// AC-8 / AC-9 — the documented contract.
+// ---------------------------------------------------------------------------
+
+test("the advisory-scan Inputs table documents the `setup` input", () => {
+  // The table is the consumer-facing contract; an input absent from it is one
+  // no consumer can be expected to find.
+  const docs = readFileSync(DOCS, "utf8");
+  const rows = docs.split("\n").filter((l) => /^\|\s*`setup`\s*\|\s*string\s*\|/.test(l));
+  assert.equal(rows.length, 1, "expected exactly one documented `setup` row");
+  assert.match(rows[0], /`'toolchain'`/, "row does not state the 'toolchain' default");
+  assert.match(rows[0], /\.nvmrc/, "row does not state the node path's .nvmrc requirement");
+});
+
+test("the Tech Stack row names this repo's real package manager", () => {
+  // The row claiming pnpm is what made the pnpm-only setup look correct when
+  // advisory-scan.yml was pointed at this repo.
+  const arch = readFileSync(ARCHITECTURE, "utf8");
+  const rows = arch.split("\n").filter((l) => /^\|\s*Package manager\s*\|/.test(l));
+  assert.equal(rows.length, 1, "expected exactly one Package manager row");
+  assert.match(rows[0], /npm/, "row must name npm");
+  assert.match(rows[0], /package-lock\.json/, "row must name the committed lockfile");
+});

package/scripts/check-semgrep-lockfile.test.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * check-semgrep-lockfile.test.mjs — guards the SAST toolchain lockfile
+ * (Story #477).
+ *
+ * What this pins, and why each part earned a test:
+ *
+ * 1. **The advisories stay gone.** The lockfile carried protobuf 4.25.9
+ *    (CVE-2026-0994, CVSS 8.2) and setuptools 80.9.0 (GHSA-h35f-9h28-mq5c).
+ *    Neither could be fixed in place: every protobuf 4.x is affected, and
+ *    semgrep 1.97.0's `opentelemetry-*~=1.25.0` pin capped protobuf below
+ *    every patched release. A future bump that lands back inside an affected
+ *    range would reintroduce a high with no other signal until the next
+ *    scheduled OSV scan.
+ *
+ * 2. **The pin sites cannot drift.** The semgrep version lives in THREE
+ *    places — this lockfile, `SEMGREP_PIN` in pr-quality.yml, and
+ *    `DEFAULT_SEMGREP_PIN` in update-semgrep-rules.mjs — plus the
+ *    `SEMGREP_HASHES` map that must carry digests for whatever the default is.
+ *    Nothing detected disagreement between them before this file.
+ *
+ * 3. **`--require-hashes` stays satisfiable.** Every entry must be `==`-pinned
+ *    with a sha256, or the install fails at CI time rather than here.
+ *
+ * The end-to-end proof (a real `pip install --require-hashes` on linux/cp312)
+ * cannot run in this suite — it needs that platform and a network. It is a
+ * `verify[]` step on the Story instead; these are the invariants checkable
+ * from the tree.
+ *
+ * Run: node --test scripts/check-semgrep-lockfile.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readFileSync } from "node:fs";
+
+const LOCKFILE = "scripts/semgrep-requirements.txt";
+const WORKFLOW = ".github/workflows/pr-quality.yml";
+const UPDATER = "scripts/update-semgrep-rules.mjs";
+
+const lockfile = readFileSync(LOCKFILE, "utf8");
+
+/**
+ * Parse `name==version` requirement lines, ignoring comments and hash
+ * continuations. Keyed by lowercased name.
+ */
+function requirements(text) {
+  /** @type {Map<string, string>} */
+  const out = new Map();
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#") || trimmed.startsWith("--hash")) {
+      continue;
+    }
+    const m = trimmed.match(/^([A-Za-z0-9._-]+)==([^\s\\]+)/);
+    if (m) {
+      out.set(m[1].toLowerCase(), m[2]);
+    }
+  }
+  return out;
+}
+
+const REQS = requirements(lockfile);
+
+/** Compare dotted release segments numerically. Returns -1 / 0 / 1. */
+function compareVersions(a, b) {
+  const pa = a.split(".").map((n) => Number.parseInt(n, 10));
+  const pb = b.split(".").map((n) => Number.parseInt(n, 10));
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = Number.isNaN(pa[i]) || pa[i] === undefined ? 0 : pa[i];
+    const y = Number.isNaN(pb[i]) || pb[i] === undefined ? 0 : pb[i];
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// 1. The advisories that put this Story on the board
+// ---------------------------------------------------------------------------
+
+test("protobuf is outside every CVE-2026-0994 affected range", () => {
+  // Affected: `< 5.29.6` and `>= 6.30.0rc1, <= 6.33.4`. Patched: 5.29.6, 6.33.5.
+  // A DoS in google.protobuf.json_format.ParseDict — 8.2, and the finding that
+  // opened tracking issue #472.
+  const version = REQS.get("protobuf");
+  assert.ok(version, `${LOCKFILE}: protobuf must be pinned`);
+  assert.doesNotMatch(version, /[a-zA-Z]/, "expected a final release, not a pre-release");
+
+  assert.ok(
+    compareVersions(version, "5.29.6") >= 0,
+    `protobuf ${version} is below the 5.29.6 patch — inside the "< 5.29.6" affected range`,
+  );
+  const inSixLine = compareVersions(version, "6.0.0") >= 0;
+  if (inSixLine) {
+    assert.ok(
+      compareVersions(version, "6.33.5") >= 0,
+      `protobuf ${version} is inside the ">= 6.30.0rc1, <= 6.33.4" affected range`,
+    );
+  }
+});
+
+test("setuptools is absent from the closure", () => {
+  // It was pinned to 80.9.0 only because semgrep 1.97.0's transitive
+  // opentelemetry-instrumentation imported pkg_resources at load. 0.58b0 does
+  // not, so the package — and its own advisory — leaves the graph entirely.
+  assert.equal(
+    REQS.has("setuptools"),
+    false,
+    "setuptools carries its own advisories and is no longer needed; do not re-add it without a stated reason",
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 2. Drift between the three pin sites
+// ---------------------------------------------------------------------------
+
+test("the lockfile, the workflow, and the rules updater pin the same semgrep", () => {
+  const lockVersion = REQS.get("semgrep");
+  assert.ok(lockVersion, `${LOCKFILE}: semgrep must be pinned`);
+
+  const workflow = readFileSync(WORKFLOW, "utf8");
+  const wf = workflow.match(/SEMGREP_PIN='semgrep==([^']+)'/);
+  assert.ok(wf, `${WORKFLOW}: SEMGREP_PIN not found`);
+  assert.equal(wf[1], lockVersion, "workflow SEMGREP_PIN disagrees with the lockfile");
+
+  const updater = readFileSync(UPDATER, "utf8");
+  const up = updater.match(/const DEFAULT_SEMGREP_PIN = "semgrep==([^"]+)";/);
+  assert.ok(up, `${UPDATER}: DEFAULT_SEMGREP_PIN not found`);
+  assert.equal(up[1], lockVersion, "updater DEFAULT_SEMGREP_PIN disagrees with the lockfile");
+});
+
+test("the rules updater carries artifact hashes for the version it defaults to", () => {
+  // SEMGREP_HASHES is a fail-fast supply-chain guard: a version with no entry
+  // is rejected rather than installed unverified. A bump that moved the default
+  // without adding digests would turn that guard into a hard stop.
+  const updater = readFileSync(UPDATER, "utf8");
+  const version = REQS.get("semgrep");
+  const map = updater.slice(updater.indexOf("const SEMGREP_HASHES = {"));
+  const block = map.slice(0, map.indexOf("\n};"));
+  assert.ok(
+    block.includes(`"${version}": [`),
+    `${UPDATER}: SEMGREP_HASHES has no entry for ${version}`,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 3. --require-hashes remains satisfiable
+// ---------------------------------------------------------------------------
+
+test("every requirement is == pinned and carries a sha256 hash", () => {
+  const pins = lockfile
+    .split("\n")
+    .filter((l) => /^[A-Za-z0-9._-]+==/.test(l.trim())).length;
+  const hashes = lockfile.split("\n").filter((l) => l.trim().startsWith("--hash=sha256:")).length;
+
+  assert.ok(pins > 0, "expected at least one pinned requirement");
+  assert.equal(REQS.size, pins, "every pinned line must parse to a requirement");
+  assert.ok(
+    hashes >= pins,
+    `${hashes} hash line(s) for ${pins} requirement(s) — --require-hashes needs at least one each`,
+  );
+});
+
+test("no requirement is pinned with a loose operator", () => {
+  // `--require-hashes` rejects these at install time; catching it here names
+  // the offending line instead of failing inside CI's pip.
+  //
+  // The operator is matched by string comparison, NOT by a regex alternating
+  // `<` and `>`. CodeQL reads such a pattern as an attempted HTML-tag filter
+  // and raises js/bad-tag-filter at HIGH — which blocks the merge, since
+  // code-scanning gates on high. Comparing prefixes says the same thing with
+  // nothing for that query to match on.
+  const LOOSE_OPERATORS = [">=", "<=", "~=", "!=", ">", "<"];
+  for (const line of lockfile.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#") || trimmed.startsWith("--hash")) continue;
+    const name = trimmed.match(/^[A-Za-z0-9._-]+/);
+    if (!name) continue;
+    const operator = trimmed.slice(name[0].length).trimStart();
+    for (const loose of LOOSE_OPERATORS) {
+      assert.ok(
+        !operator.startsWith(loose),
+        `loose pin (${loose}) — --require-hashes needs an exact ==: ${trimmed}`,
+      );
+    }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 4. The regeneration trap
+// ---------------------------------------------------------------------------
+
+test("the header warns about the manylinux_2_34 wheel tag", () => {
+  // semgrep moved its Linux wheel tag after 1.157.0. A `pip download` whose
+  // --platform list omits the new tag resolves NOTHING newer and reports only
+  // "No matching distribution found", never naming the tag as the cause.
+  const header = lockfile.slice(0, lockfile.indexOf("\n\n\n") + 1 || 4000);
+  assert.match(header, /manylinux_2_34_x86_64/, "the header must name the current wheel tag");
+  assert.match(header, /1\.157\.0/, "the header must say which version the tag changed after");
+  assert.match(
+    lockfile,
+    /pip download semgrep/,
+    "the header must carry a regeneration command",
+  );
+});