mandrel-platform 1.0.0 → 1.1.0

package/scripts/check-ci-required-aggregator.test.mjs

@@ -17,20 +17,34 @@
  *   1. STRUCTURE — each aggregator's `steps:` derive results from
  *      `toJSON(needs)` and contain NO hardcoded reference to any job named in
  *      its own `needs:` array (the "no hardcoded tier-name list" AC).
- *   2. PARITY — the two aggregators' `steps:` blocks are textually identical,
- *      so a fix to one cannot drift from the other.
+ *   2. PARITY — the two aggregators' `run:` scripts are byte-identical and both
+ *      declare the same `env:` keys, so a fix to one cannot drift from the
+ *      other. (Story #333 loosened this from "the whole `steps:` blocks are
+ *      identical": ci.yml has no `workflow_call` inputs, so it must source
+ *      `CANCELLED_POLICY` as a literal where pr-quality.yml sources it from
+ *      `inputs.cancelled-policy`. The shared script reads it from the
+ *      environment, which is what keeps the logic itself byte-identical.)
  *   3. SEMANTICS — the shared run script passes on `success`/`skipped` and
  *      fails on anything else, INCLUDING `cancelled` (load-bearing for #223's
  *      fail-fast design), while naming the failing jobs and their results.
  *      Executed against real bash+jq; skipped when jq is unavailable locally
- *      (CI's ubuntu runner always has it).
+ *      (CI's ubuntu runner always has it). `gh` is stubbed to fail so these
+ *      tests stay hermetic — provenance classification (Story #333) has its
+ *      own suite in scripts/check-cancelled-provenance.test.mjs.
  *
  * Run: node --test scripts/check-ci-required-aggregator.test.mjs
  */
 
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { readFileSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import {
+  readFileSync,
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  chmodSync,
+  rmSync,
+} from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -155,14 +169,61 @@ for (const { rel, needs, steps } of blocks) {
 // 2. PARITY — the two implementations are textually identical
 // ---------------------------------------------------------------------------
 
-test("pr-quality.yml and ci.yml aggregator steps are textually identical", () => {
+// Story #333 re-shaped this from "the whole `steps:` blocks are byte-identical"
+// to "the `run:` scripts are byte-identical AND both declare the same `env:`
+// keys". ci.yml has no `workflow_call` inputs, so it cannot source
+// `CANCELLED_POLICY` from `inputs.cancelled-policy` the way pr-quality.yml
+// does — but the LOGIC is what must not drift, and the script reads the policy
+// from the environment precisely so the two can share it verbatim.
+
+/** The `KEY:` names declared under a steps block's `env:` mapping. */
+function extractEnvKeys(steps) {
+  const stepLines = steps.split("\n");
+  const start = stepLines.findIndex((l) => /^\s+env:\s*$/.test(l));
+  assert.notEqual(start, -1, "`env:` block not found");
+  const envIndent = stepLines[start].match(/^(\s*)/)[1].length;
+  const keys = [];
+  for (let i = start + 1; i < stepLines.length; i++) {
+    if (/^\s*$/.test(stepLines[i])) continue;
+    if (/^\s*#/.test(stepLines[i])) continue;
+    const indent = stepLines[i].match(/^(\s*)/)[1].length;
+    if (indent <= envIndent) break;
+    const key = stepLines[i].match(/^\s+([A-Za-z_][A-Za-z0-9_]*):/);
+    if (key) keys.push(key[1]);
+  }
+  assert.ok(keys.length > 0, "`env:` block declared no keys");
+  return keys.sort();
+}
+
+test("pr-quality.yml and ci.yml aggregator run scripts are byte-identical", () => {
   assert.equal(
-    blocks[0].steps,
-    blocks[1].steps,
-    "the two `ci-required` steps blocks must not drift — apply every change to both"
+    extractRunScript(blocks[0].steps),
+    extractRunScript(blocks[1].steps),
+    "the two `ci-required` run scripts must not drift — apply every logic change to both"
+  );
+});
+
+test("pr-quality.yml and ci.yml aggregators declare the same env keys", () => {
+  assert.deepEqual(
+    extractEnvKeys(blocks[0].steps),
+    extractEnvKeys(blocks[1].steps),
+    "the shared run script reads its inputs from the environment — a key present " +
+      "in only one workflow would leave the other running the same script unconfigured"
   );
 });
 
+test("the shared aggregator script never references workflow_call inputs", () => {
+  // ci.yml has none, so an `inputs.*` reference could not be mirrored and
+  // would break the byte-identical run-script guarantee above.
+  for (const { rel, steps } of blocks) {
+    assert.doesNotMatch(
+      extractRunScript(steps),
+      /inputs\./,
+      `${rel}: the run script must read configuration from \`env:\`, not \`inputs.*\``
+    );
+  }
+});
+
 // ---------------------------------------------------------------------------
 // 3. SEMANTICS — pass on success/skipped, fail (naming jobs) on anything else
 // ---------------------------------------------------------------------------
@@ -176,7 +237,7 @@ function jqAvailable() {
   }
 }
 
-function runAggregator(needsResults) {
+function runAggregator(needsResults, { captureSummary = false } = {}) {
   const script = extractRunScript(blocks[0].steps);
   const dir = mkdtempSync(join(tmpdir(), "ci-required-"));
   try {
@@ -185,10 +246,36 @@ function runAggregator(needsResults) {
     const needsJson = Object.fromEntries(
       Object.entries(needsResults).map(([k, result]) => [k, { result, outputs: {} }])
     );
-    return spawnSync("bash", [file], {
-      encoding: "utf8",
-      env: { ...process.env, NEEDS_JSON: JSON.stringify(needsJson) },
-    });
+    // Neutralize the provenance lookup (Story #333): shadow `gh` with a stub
+    // that always fails, so these tests stay hermetic and exercise the
+    // `unknown`-provenance path. Provenance classification itself is covered
+    // by scripts/check-cancelled-provenance.test.mjs.
+    const bin = join(dir, "bin");
+    mkdirSync(bin);
+    const ghStub = join(bin, "gh");
+    writeFileSync(ghStub, "#!/usr/bin/env bash\nexit 1\n");
+    chmodSync(ghStub, 0o755);
+
+    const env = {
+      ...process.env,
+      PATH: `${bin}:${process.env.PATH}`,
+      NEEDS_JSON: JSON.stringify(needsJson),
+    };
+    // The step-summary write must degrade when GITHUB_STEP_SUMMARY is unset
+    // (this harness, and any `act`-style local runner), so only define it when
+    // a test is actually asserting on the summary body.
+    const summaryPath = join(dir, "summary.md");
+    if (captureSummary) {
+      writeFileSync(summaryPath, "");
+      env.GITHUB_STEP_SUMMARY = summaryPath;
+    } else {
+      delete env.GITHUB_STEP_SUMMARY;
+    }
+    const r = spawnSync("bash", [file], { encoding: "utf8", env });
+    return {
+      ...r,
+      summary: captureSummary ? readFileSync(summaryPath, "utf8") : "",
+    };
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }
@@ -225,3 +312,72 @@ test("run script: every non-passing job is named", semantics, () => {
   assert.match(r.stderr, /unit\(cancelled\)/);
   assert.doesNotMatch(r.stderr, /e2e/);
 });
+
+// ---------------------------------------------------------------------------
+// 4. TRIAGE PARTITION (Story #331) — a fail-fast run reds N jobs but only one
+//    of them actually failed. The aggregate must say WHICH, so triage does not
+//    land on a collateral cancel.
+// ---------------------------------------------------------------------------
+
+test("run script: partitions own-failures from collateral cancels", semantics, () => {
+  const r = runAggregator({
+    lint: "success",
+    security: "failure",
+    unit: "cancelled",
+    e2e: "cancelled",
+  });
+  assert.equal(r.status, 1);
+
+  const own = r.stderr
+    .split("\n")
+    .find((l) => l.includes("Failed on their own"));
+  const collateral = r.stderr
+    .split("\n")
+    .find((l) => l.includes("do not triage"));
+
+  assert.ok(own, `no own-failure line in stderr:\n${r.stderr}`);
+  assert.ok(collateral, `no collateral line in stderr:\n${r.stderr}`);
+
+  // The tier that actually failed is named ONLY on the triage line, and the
+  // cancelled siblings ONLY on the collateral line — a partition, not two
+  // copies of the same flat list.
+  assert.match(own, /security\(failure\)/);
+  assert.doesNotMatch(own, /unit|e2e/);
+  assert.match(collateral, /unit\(cancelled\)/);
+  assert.match(collateral, /e2e\(cancelled\)/);
+  assert.doesNotMatch(collateral, /security/);
+});
+
+test("run script: an all-cancelled aggregate says no job failed on its own", semantics, () => {
+  const r = runAggregator({ lint: "success", unit: "cancelled" }, { captureSummary: true });
+  assert.equal(r.status, 1);
+  assert.doesNotMatch(r.stderr, /Failed on their own/);
+  assert.match(r.summary, /No job reported its own failure/);
+});
+
+test("run script: writes the triage partition to the job summary", semantics, () => {
+  const r = runAggregator(
+    { security: "failure", unit: "cancelled" },
+    { captureSummary: true }
+  );
+  assert.equal(r.status, 1);
+  assert.match(r.summary, /ci-required failed/);
+  assert.match(r.summary, /Failed on their own[^\n]*security\(failure\)/);
+  assert.match(r.summary, /Cancelled[^\n]*do not triage:[^\n]*unit\(cancelled\)/);
+});
+
+test("run script: a green aggregate writes no summary", semantics, () => {
+  const r = runAggregator({ lint: "success", unit: "success" }, { captureSummary: true });
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.summary, "");
+});
+
+test("run script: survives an unset GITHUB_STEP_SUMMARY", semantics, () => {
+  // The failure path writes a summary; with the variable unset (local runners,
+  // `act`, this harness) the redirect must degrade rather than error out and
+  // swallow the exit-1 verdict.
+  const r = runAggregator({ unit: "failure" });
+  assert.equal(r.status, 1);
+  assert.match(r.stderr, /unit\(failure\)/);
+  assert.doesNotMatch(r.stderr, /ambiguous redirect|No such file or directory/);
+});

package/scripts/check-destructive-migration.test.mjs

@@ -56,6 +56,43 @@ test("globToRegExp: `**` crosses path separators, `*` does not", () => {
   assert.ok(globToRegExp("*.sql").test("x.sql"));
 });
 
+// The glob set reaches this function from a CLI argument, so CodeQL reports
+// `js/regex-injection` (high) on the `new RegExp` it builds. That alert is a
+// false positive ONLY for as long as the translator escapes every regex
+// metacharacter — the input must be able to control `*` / `**` semantics and
+// nothing else. These two tests are the evidence that claim rests on; if a
+// future edit drops a character from the escape set, they fail rather than
+// letting a stale dismissal stand.
+test("globToRegExp: escapes every regex metacharacter to a literal", () => {
+  // `*` is excluded deliberately — it is the one character the glob syntax
+  // gives meaning to. `/` is not a metacharacter in the RegExp *constructor*
+  // (only in literal notation), but is asserted anyway.
+  const METACHARS = [".", "+", "?", "^", "$", "{", "}", "(", ")", "|", "[", "]", "\\", "/"];
+  for (const meta of METACHARS) {
+    const glob = `a${meta}b`;
+    const re = globToRegExp(glob);
+    assert.ok(re.test(glob), `\`${meta}\` must match itself literally (got ${re})`);
+    assert.ok(
+      !re.test("aXb"),
+      `\`${meta}\` leaked regex meaning — it matched an arbitrary character (got ${re})`
+    );
+  }
+});
+
+test("globToRegExp: a regex-injection payload translates to a literal pattern", () => {
+  // The classic catastrophic-backtracking payload. If any of it survived
+  // unescaped, this pattern would carry regex semantics into the matcher.
+  const re = globToRegExp("(a+)+$");
+  // Compared as a STRING, not against a regex literal: writing the expected
+  // pattern as `/^\(a\+\)\+\$$/` puts a (wholly escaped, quantifier-free)
+  // regex literal in the file that CodeQL's js/redos analysis reads as a live
+  // backtracking hazard. The assertion is identical in strength — this test
+  // has always been about the produced source text.
+  assert.equal(String(re), "/^\\(a\\+\\)\\+\\$$/");
+  assert.ok(re.test("(a+)+$"), "the payload matches only its literal self");
+  assert.ok(!re.test("aaaaaaaa"), "the payload carries no quantifier semantics");
+});
+
 test("isMigrationFile: matches migration globs and any .sql tail", () => {
   assert.ok(isMigrationFile("apps/api/migrations/0007_drop.ts"));
   assert.ok(isMigrationFile("drizzle/0001_init.sql"));

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)}`);
+  }
+});