mandrel-platform 1.1.0 → 1.3.0

package/scripts/audit-check.test.mjs

@@ -30,7 +30,7 @@
 
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -43,6 +43,9 @@ import {
   parseArgs,
   loadAllowlist,
   runCli,
+  isBoundedOverride,
+  findUnboundedOverrides,
+  lintOverrides,
 } from "./audit-check.mjs";
 
 const TODAY = "2026-07-02";
@@ -456,3 +459,381 @@ test("loadAllowlist: non-array throws", () => {
     rmSync(dir, { recursive: true, force: true });
   }
 });
+
+// ---------------------------------------------------------------------------
+// Unbounded dependency overrides (Story #365)
+//
+// The failure these close: nothing lints for an unbounded override. Written as
+// a bare lower bound it rewrites a dependent's range open-endedly, leaving the
+// committed lockfile as the only pin — so any fresh resolution re-picks the
+// newest release and can cross a major. Two consumers derived this rule
+// independently after a major jump silently emptied a test suite, and both
+// then found further already-escaped overrides.
+// ---------------------------------------------------------------------------
+
+test("isBoundedOverride: a bare lower bound is unbounded; a capped range is not", () => {
+  for (const unbounded of [">=1.2.3", "> 1.2.3", ">=0", "*", "x", "latest", "", "   "]) {
+    assert.equal(isBoundedOverride(unbounded), false, `${JSON.stringify(unbounded)} is unbounded`);
+  }
+  for (const bounded of ["1.2.3", "^1.2.3", "~1.2.3", "1.2.x", ">=1.2.3 <2.0.0", "<2.0.0"]) {
+    assert.equal(isBoundedOverride(bounded), true, `${JSON.stringify(bounded)} is bounded`);
+  }
+});
+
+// The wildcard truth table (Story #375).
+//
+// The shipped regex enumerated only some wildcard spellings, so `x.x.x` and
+// `x.x` — the exact shape the lint exists to catch, and what npm reads as
+// plain `*` — fell through the catch-all and were reported bounded. The
+// deciding question is the MAJOR position: a wildcard there is open to every
+// future release, while a wildcard below it (`1.2.x`, `1.*`) stays inside its
+// major and is genuinely bounded. Every spelling is enumerated so the next
+// regex tweak has to keep answering all of them.
+const WILDCARD_TRUTH_TABLE = [
+  ["*", false],
+  ["x", false],
+  ["X", false],
+  ["*.*", false],
+  ["x.x", false],
+  ["X.X", false],
+  ["*.*.*", false],
+  ["x.x.x", false],
+  ["X.X.X", false],
+  ["x.*", false],
+  ["*.x.x", false],
+  ["x.2.3", false],
+  ["*.x", false],
+  ["latest", false],
+  ["next", false],
+  ["LATEST", false],
+  ["NEXT", false],
+  ["1.x", true],
+  ["1.X", true],
+  ["1.*", true],
+  ["1.2.x", true],
+  ["1.2.*", true],
+];
+
+test("AC-1/AC-4: every wildcard spelling is judged on its major position", () => {
+  for (const [spec, expected] of WILDCARD_TRUTH_TABLE) {
+    assert.equal(
+      isBoundedOverride(spec),
+      expected,
+      `${JSON.stringify(spec)} should be bounded=${expected}`,
+    );
+  }
+});
+
+test("AC-2: a non-registry specifier expresses no upper bound", () => {
+  // Each of these re-resolves to whatever the source holds at install time —
+  // a branch head, a workspace sibling, a path — so none of them is a range
+  // the lint can call bounded.
+  for (const spec of [
+    "github:owner/repo",
+    "github:owner/repo#v1.2.3",
+    "git+https://github.com/owner/repo.git",
+    "git+ssh://git@github.com/owner/repo.git#main",
+    "git://github.com/owner/repo.git",
+    "workspace:*",
+    "workspace:^",
+    "file:../local-pkg",
+    "link:../local-pkg",
+    "https://example.com/pkg-1.2.3.tgz",
+  ]) {
+    assert.equal(
+      isBoundedOverride(spec),
+      false,
+      `${JSON.stringify(spec)} pins nothing`,
+    );
+  }
+});
+
+test("AC-2: a git specifier carrying #semver: is judged on that range", () => {
+  assert.equal(
+    isBoundedOverride("git+https://github.com/owner/repo.git#semver:^1.2.3"),
+    true,
+  );
+  assert.equal(isBoundedOverride("github:owner/repo#semver:>=1.2.3"), false);
+});
+
+test("AC-3: a range carrying an explicit upper bound stays bounded", () => {
+  for (const bounded of [
+    "1.2.3",
+    "=1.2.3",
+    "^1.2.3",
+    "~1.2.3",
+    ">=1.2.3 <2.0.0",
+    "<2.0.0",
+    "1.2.3 - 2.0.0",
+  ]) {
+    assert.equal(
+      isBoundedOverride(bounded),
+      true,
+      `${JSON.stringify(bounded)} is bounded`,
+    );
+  }
+});
+
+test("AC-3: a wildcard LOWER end still counts as bounded when the range caps it", () => {
+  // The wildcard test asks about the major position, so it may only be applied
+  // to a single bare token. Applied to a compound range it read the first
+  // dot-segment of the whole string and called `x.x <2.0.0` unbounded — a
+  // range that plainly carries an upper bound — while the equivalent
+  // `* <2.0.0` passed, because its first segment is `* <2`. That
+  // self-inconsistency is the tell: it was an artifact of check ordering.
+  for (const bounded of [
+    "x.x <2.0.0",
+    "x.x.x <2.0.0",
+    "* <2.0.0",
+    "x.x.x - 2.0.0",
+    "x - 2.0.0",
+    "* - 2.0.0",
+  ]) {
+    assert.equal(
+      isBoundedOverride(bounded),
+      true,
+      `${JSON.stringify(bounded)} is bounded`,
+    );
+  }
+});
+
+// Residual fail-opens left open by the dotted-wildcard fix. Both classes reach
+// the catch-all `return true` and so read as bounded while pinning nothing.
+//
+// Class 1 — an operator in front of the wildcard. The wildcard test is gated on
+// a single BARE token, so any leading range operator defeats it: `^x.x.x` is
+// `^` applied to "any version", which is still any version.
+const OPERATOR_PREFIXED_WILDCARDS = [
+  ["^x.x.x", false],
+  ["^x.x", false],
+  ["^x", false],
+  ["^*", false],
+  ["~*", false],
+  ["~x.x.x", false],
+  ["=x.x.x", false],
+  ["=*", false],
+  ["=X.X", false],
+  ["^latest", false],
+  // The same operators over a real version are untouched — this is the
+  // near-miss the fix must not break.
+  ["^1.2.3", true],
+  ["~1.2.3", true],
+  ["=1.2.3", true],
+  ["^1.x", true],
+  ["~1.2.x", true],
+];
+
+test("operator-prefixed wildcards are unbounded, real versions unaffected", () => {
+  for (const [spec, expected] of OPERATOR_PREFIXED_WILDCARDS) {
+    assert.equal(
+      isBoundedOverride(spec),
+      expected,
+      `${JSON.stringify(spec)} should be bounded=${expected}`,
+    );
+  }
+});
+
+test("a compound whose every term is a wildcard or bare lower bound is unbounded", () => {
+  // Class 2 — a wildcard lower with no upper bound anywhere. `x.x >=1.0.0`
+  // reads as a range only because it is spelled like one; both terms are open
+  // above, so the resolved set is still "every future release".
+  for (const unbounded of [
+    "x.x >=1.0.0",
+    "x.x.x >=1.0.0",
+    "* >=1.0.0",
+    "x.x >1.0.0",
+    ">=1.0.0 x.x",
+    "x.x - x.x",
+    "x.x.x - *",
+    "* - x",
+    "1.0.0 - x.x.x",
+  ]) {
+    assert.equal(
+      isBoundedOverride(unbounded),
+      false,
+      `${JSON.stringify(unbounded)} carries no upper bound`,
+    );
+  }
+});
+
+test("a malformed hyphen range carrying a comparator still fails closed", () => {
+  // A real hyphen range takes plain versions on both sides. Reading the
+  // right-hand side of `>=1.0.0 - 2.0.0` as the cap answers a range npm never
+  // agreed to parse, and turns a spec that failed closed into one that passes
+  // — the exact fail-open direction this lint exists to prevent.
+  for (const unbounded of [">=1.0.0 - 2.0.0", ">=1.0.0 - ^2.0.0", ">1.0.0 - 2.0.0"]) {
+    assert.equal(
+      isBoundedOverride(unbounded),
+      false,
+      `${JSON.stringify(unbounded)} is not a hyphen range and must fail closed`,
+    );
+  }
+});
+
+test("a real upper bound still closes a range with a wildcard lower", () => {
+  // The regression guard for the trap the dotted-wildcard fix already hit once:
+  // testing the wildcard against the whole specifier called these unbounded.
+  // An upper bound is an upper bound regardless of how loose the lower end is.
+  for (const bounded of [
+    "x.x <2.0.0",
+    "x.x.x - 2.0.0",
+    "* <=2.0.0",
+    "x.x >=1.0.0 <2.0.0",
+    "^x.x.x - 2.0.0",
+  ]) {
+    assert.equal(
+      isBoundedOverride(bounded),
+      true,
+      `${JSON.stringify(bounded)} carries a real upper bound`,
+    );
+  }
+});
+
+test("isBoundedOverride: a || union is only as bounded as its loosest arm", () => {
+  assert.equal(isBoundedOverride("^1.0.0 || ^2.0.0"), true);
+  assert.equal(isBoundedOverride("^1.0.0 || >=2.0.0"), false);
+});
+
+test("isBoundedOverride: an npm: alias is judged on the range it carries", () => {
+  assert.equal(isBoundedOverride("npm:other-pkg@^1.2.3"), true);
+  assert.equal(isBoundedOverride("npm:@scope/other@^1.2.3"), true);
+  assert.equal(isBoundedOverride("npm:other-pkg@>=1.2.3"), false);
+  // An alias with no range at all pins nothing.
+  assert.equal(isBoundedOverride("npm:other-pkg"), false);
+});
+
+test("AC-5: findUnboundedOverrides names the package and the bound", () => {
+  const findings = findUnboundedOverrides({
+    pnpm: { overrides: { "left-pad": ">=1.3.0", semver: "^7.5.2" } },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].package, "left-pad");
+  assert.equal(findings[0].bound, ">=1.3.0");
+  assert.equal(findings[0].field, "pnpm.overrides");
+});
+
+test("AC-5: every override field is checked, npm and pnpm and yarn alike", () => {
+  const findings = findUnboundedOverrides({
+    overrides: { a: ">=1.0.0" },
+    resolutions: { b: "*" },
+    pnpm: { overrides: { c: ">2" } },
+  });
+  assert.deepEqual(
+    findings.map((f) => `${f.field}.${f.package}`).sort(),
+    ["overrides.a", "pnpm.overrides.c", "resolutions.b"],
+  );
+});
+
+test("AC-5: a nested (dependent-scoped) override is named by its full path", () => {
+  const findings = findUnboundedOverrides({
+    overrides: { "some-dep": { "left-pad": ">=1.3.0" } },
+  });
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].package, "some-dep.left-pad");
+  assert.equal(findings[0].bound, ">=1.3.0");
+});
+
+test("AC-6: an override that pins a bounded range passes", () => {
+  assert.deepEqual(
+    findUnboundedOverrides({
+      overrides: { a: "^1.2.3", b: "~2.0.0", c: "3.1.4", d: ">=1.0.0 <2.0.0" },
+      pnpm: { overrides: { e: "1.2.x" } },
+    }),
+    [],
+  );
+});
+
+test("findUnboundedOverrides: a package.json with no overrides at all is clean", () => {
+  assert.deepEqual(findUnboundedOverrides({ name: "x", dependencies: { a: ">=1.0.0" } }), []);
+  assert.deepEqual(findUnboundedOverrides(null), []);
+  assert.deepEqual(findUnboundedOverrides("not-an-object"), []);
+});
+
+test("AC-5: runCli fails on an unbounded override before pnpm ever runs", () => {
+  const dir = mkdtempSync(join(tmpdir(), "audit-check-override-"));
+  try {
+    const packageJsonPath = join(dir, "package.json");
+    writeFileSync(
+      packageJsonPath,
+      JSON.stringify({ name: "fixture", pnpm: { overrides: { "left-pad": ">=1.3.0" } } }),
+    );
+    // An absent allowlist keeps this case about the override and nothing else.
+    const exit = runCli([
+      "--package-json",
+      packageJsonPath,
+      "--allowlist",
+      join(dir, "no-such-allowlist.json"),
+    ]);
+    assert.equal(exit, 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("AC-6: the override gate passes a bounded override, reaching the audit", () => {
+  // Executes the clean path rather than asserting around it. lintOverrides is
+  // the gate runCli delegates to, split out precisely so a PASS is provable
+  // without `pnpm audit` (which needs a real lockfile and a network).
+  const dir = mkdtempSync(join(tmpdir(), "audit-check-bounded-"));
+  try {
+    const packageJsonPath = join(dir, "package.json");
+    writeFileSync(
+      packageJsonPath,
+      JSON.stringify({
+        name: "fixture",
+        overrides: { a: "^1.3.0", b: ">=1.0.0 <2.0.0" },
+        pnpm: { overrides: { "left-pad": "~1.3.0" } },
+      }),
+    );
+    assert.equal(lintOverrides(packageJsonPath), 0);
+    assert.equal(parseArgs(["--package-json", packageJsonPath]).packageJsonPath, packageJsonPath);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("AC-5: the override gate blocks an unbounded override", () => {
+  const dir = mkdtempSync(join(tmpdir(), "audit-check-lint-"));
+  try {
+    const packageJsonPath = join(dir, "package.json");
+    writeFileSync(packageJsonPath, JSON.stringify({ overrides: { "left-pad": ">=1.3.0" } }));
+    assert.equal(lintOverrides(packageJsonPath), 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("the override gate is a no-op when there is no package.json to read", () => {
+  assert.equal(lintOverrides(join(tmpdir(), "audit-check-absent-xyz", "package.json")), 0);
+});
+
+test("this repo's own package.json passes the override gate", () => {
+  // The lint ships enabled by default; a false positive here would red the
+  // platform's own required check on every PR.
+  assert.deepEqual(findUnboundedOverrides(JSON.parse(readFileSync("package.json", "utf8"))), []);
+});
+
+test("runCli: an unparseable package.json is a hard error, not a skipped check", () => {
+  const dir = mkdtempSync(join(tmpdir(), "audit-check-badpkg-"));
+  try {
+    const packageJsonPath = join(dir, "package.json");
+    writeFileSync(packageJsonPath, "{ not json");
+    assert.equal(
+      runCli([
+        "--package-json",
+        packageJsonPath,
+        "--allowlist",
+        join(dir, "no-such-allowlist.json"),
+      ]),
+      1,
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("parseArgs defaults the package.json path alongside the allowlist path", () => {
+  const { allowlistPath, packageJsonPath } = parseArgs([], "/tmp/proj");
+  assert.equal(allowlistPath, "/tmp/proj/audit-allowlist.json");
+  assert.equal(packageJsonPath, "/tmp/proj/package.json");
+});

package/scripts/check-action-pins.mjs

@@ -27,13 +27,29 @@
  *     `pnpm/action-setup`.) A non-SHA ref (a tag like `v4`, a branch, a short
  *     SHA) FAILS the lint.
  *
- *   • FIRST-PARTY self-references — `dsj1984/mandrel-platform/...@<ref>` — are
- *     EXEMPT from this ratchet. They are this repo's OWN reusable workflows /
- *     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. They ARE, however, subject to the
- *     single-pin invariant below.
+ *   • FIRST-PARTY self-references — `dsj1984/mandrel-platform/...@<ref>` — MUST
+ *     ALSO be a 40-char hex SHA, and are reported as their own violation class.
+ *     They were exempt until Story #354's audit: the exemption's stated
+ *     justification was that `check-workflow-portability.mjs` Rule 3 governs
+ *     them, but Rule 3's `collectInternalPins` skips any ref that is not
+ *     already a 40-hex SHA (`if (!isSha40(cls.ref)) return`), so a
+ *     branch-pinned self-reference was validated by NOTHING. The two other
+ *     first-party guards had the same hole — the single-pin invariant below
+ *     compares whatever refs it finds without requiring a SHA, and
+ *     `check-first-party-pin-freshness.mjs` files a non-SHA ref under an
+ *     informational `unpinnedRefs` note that never fails. So
+ *     `…/gitleaks-scan@main` was green on all three.
+ *
+ *     A moving self-ref is the same supply-chain risk the third-party ratchet
+ *     exists to close, with a wider blast radius: `pr-quality.yml` is inherited
+ *     by every consumer. It is also invisible to `platform-sync.mjs`, whose
+ *     rewrite regex matches `@[0-9a-fA-F]{40}` only — a branch-pinned consumer
+ *     workflow is silently skipped on every platform bump.
+ *
+ *     The land-then-bump flow is unaffected: it always pins full SHAs (see
+ *     docs/reusable-workflows.md § First-party self-pin freshness). The
+ *     first-party owner is overridable via `--first-party-owner` for a fork,
+ *     and first-party refs remain 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
@@ -125,10 +141,18 @@ export function parseArgs(argv) {
 // ---------------------------------------------------------------------------
 
 /**
- * Scan a single file's TEXT for `uses:` step keys and evaluate each third-party
- * reference. Returns { violations: [...], scanned: <count> }. A violation is
- * `{ file, line, ref, owner, reason }`. `file` is left as passed-in (the
- * caller supplies a display path).
+ * Scan a single file's TEXT for `uses:` step keys and evaluate every REMOTE
+ * reference against the 40-hex SHA ratchet. Returns
+ * `{ violations, scanned, firstPartyViolations, firstPartyScanned }` — the two
+ * owner classes are counted and reported separately because their remediation
+ * differs (bump a vendored third-party pin vs. re-pin one of this repo's own
+ * call sites, which must move at every call site together to keep the
+ * single-pin invariant). A violation is `{ file, line, ref, owner, reason }`;
+ * `file` is left as passed-in (the caller supplies a display path).
+ *
+ * LOCAL (`./path`) and `docker://` references stay exempt: a local path has no
+ * upstream ref that can move, and a docker ref carries its own digest
+ * convention.
  *
  * Only lines whose first non-space token is `uses:` (a YAML mapping key) are
  * inspected — `uses:` appearing inside a comment or a `run:` heredoc never
@@ -138,13 +162,33 @@ export function parseArgs(argv) {
  */
 export function scanContent(content, displayFile, firstPartyOwner = DEFAULT_FIRST_PARTY_OWNER) {
   const violations = [];
+  const firstPartyViolations = [];
   let scanned = 0;
+  let firstPartyScanned = 0;
   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 !== "third-party") continue; // local/docker/first-party/unparseable → exempt
+
+    // First-party self-references (Story #354 audit). A bare `owner/repo@ref`
+    // carrying no subpath is ratcheted too: the hazard is the MOVING REF, and
+    // it moves whether or not the reference names a subpath.
+    if (cls.kind === "first-party") {
+      firstPartyScanned++;
+      if (!isSha40(cls.ref)) {
+        firstPartyViolations.push({
+          file: displayFile,
+          line: i + 1,
+          ref: bareRef,
+          owner: cls.owner,
+          reason: `first-party self-reference "${cls.owner}" is pinned to "${cls.ref}", not a full 40-char commit SHA`,
+        });
+      }
+      continue;
+    }
+
+    if (cls.kind !== "third-party") continue; // local/docker/unparseable → exempt
     scanned++;
     if (!isSha40(cls.ref)) {
       violations.push({
@@ -156,7 +200,7 @@ export function scanContent(content, displayFile, firstPartyOwner = DEFAULT_FIRS
       });
     }
   }
-  return { violations, scanned };
+  return { violations, scanned, firstPartyViolations, firstPartyScanned };
 }
 
 // ---------------------------------------------------------------------------
@@ -178,7 +222,9 @@ export function runLint(opts) {
   const files = [...workflowFiles, ...listActionFiles(acDir)];
 
   const violations = [];
+  const firstPartyViolations = [];
   let scanned = 0;
+  let firstPartyScanned = 0;
   // Keep the raw workflow-file contents for the single-pin pass so we read
   // each file from disk once.
   const workflowRecords = [];
@@ -192,7 +238,9 @@ export function runLint(opts) {
     const display = relative(cwd, file) || file;
     const res = scanContent(content, display, opts.firstPartyOwner);
     violations.push(...res.violations);
+    firstPartyViolations.push(...res.firstPartyViolations);
     scanned += res.scanned;
+    firstPartyScanned += res.firstPartyScanned;
     if (workflowFiles.includes(file)) {
       workflowRecords.push({ file: display, content });
     }
@@ -204,9 +252,14 @@ export function runLint(opts) {
     : [];
 
   return {
-    ok: violations.length === 0 && singlePinViolations.length === 0,
+    ok:
+      violations.length === 0 &&
+      firstPartyViolations.length === 0 &&
+      singlePinViolations.length === 0,
     violations,
+    firstPartyViolations,
     scanned,
+    firstPartyScanned,
     files,
     singlePinViolations,
   };
@@ -242,6 +295,24 @@ export function runCli(argv, { log = console.log, err = console.error } = {}) {
     );
   }
 
+  if (result.firstPartyViolations.length > 0) {
+    failed = true;
+    err(
+      `[action-pins] ❌ ${result.firstPartyViolations.length} first-party self-reference(s) pinned to a moving ref:`
+    );
+    for (const v of result.firstPartyViolations) {
+      err(`  • ${v.file}:${v.line} — ${v.reason}`);
+    }
+    err(
+      "[action-pins] Pin every first-party `uses:` to a full 40-char commit SHA " +
+        "too (keep the `# vX.Y.Z` tag note as a comment). A branch or tag ref " +
+        "means the revision that runs can change with no diff here — and " +
+        "`pr-quality.yml` is inherited by every consumer. It is also invisible " +
+        "to platform-sync.mjs, whose rewrite matches 40-hex SHAs only, so it " +
+        "would be skipped on every platform bump."
+    );
+  }
+
   if (result.singlePinViolations.length > 0) {
     failed = true;
     err(
@@ -263,7 +334,8 @@ export function runCli(argv, { log = console.log, err = console.error } = {}) {
   if (failed) return 1;
 
   log(
-    `[action-pins] ✅ all ${result.scanned} third-party action reference(s) are SHA-pinned ` +
+    `[action-pins] ✅ all ${result.scanned} third-party and ${result.firstPartyScanned} ` +
+      `first-party action reference(s) are SHA-pinned ` +
       `(${result.files.length} file(s) scanned); first-party single-pin invariant holds.`
   );
   return 0;