mandrel-platform 1.12.0 → 1.13.1

package/scripts/check-husky-hook-modes.test.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * check-husky-hook-modes.test.mjs — regression guard for the mode bit that
+ * decides whether this repository's git hooks run at all.
+ *
+ * The bug this pins: `.husky/pre-commit` was tracked at mode 100644. Git
+ * 2.36+ refuses to execute a hook that is not marked executable, and the way
+ * it refuses is the problem — it prints
+ *
+ *     hint: The '.../.husky/pre-commit' hook was ignored because it's not
+ *           set as executable.
+ *
+ * to stderr and then lets the commit SUCCEED with exit 0. So the quality gate
+ * the hook exists to run (`quality-preview.js`, which blocks MI/CRAP drift at
+ * commit time) never ran for anybody, in any clone, from the day it was
+ * added — and nothing anywhere went red to say so. An inert gate and a
+ * passing gate are indistinguishable from the outside.
+ *
+ * Why the mode is asserted against the INDEX and not the filesystem. `chmod`
+ * on the working copy is not the fix and would not be caught here: git stores
+ * only two file modes, 100644 and 100755, and it is the tracked one that
+ * every fresh clone and every `git checkout` materializes. A working tree can
+ * be executable while the committed mode is not (and vice versa), so a
+ * `statSync` check would go green on the maintainer's machine and ship the
+ * defect to everyone else. `git ls-files -s` reads the index, which is the
+ * mode that actually propagates.
+ *
+ * Why this is not a one-line assertion on one path. The upstream cause is
+ * still live: the hook is installed by the vendored bootstrap
+ * (`.agents/scripts/lib/bootstrap/quality-bootstrap.js`) with a bare
+ * `fs.writeFileSync` and no `chmod`, so a hook file CREATED by a fresh
+ * bootstrap run is born 0644. (An existing file survives — `writeFileSync`
+ * truncates in place and preserves the mode — which is why fixing the tracked
+ * mode holds.) `.agents/**` is vendored payload re-materialized from the
+ * mandrel package, so that cause cannot be fixed here; this guard is the
+ * compensating control, and it therefore covers every hook the directory may
+ * grow, not just the one that was broken.
+ *
+ * Run: node --test scripts/check-husky-hook-modes.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { execFileSync } from "node:child_process";
+
+const HOOKS_DIR = ".husky";
+const EXECUTABLE = "100755";
+
+/**
+ * Every client-side hook name git will invoke. A file in `.husky/` whose name
+ * is not on this list is never run by git no matter what its mode is, so a
+ * typo (`pre_commit`, `precommit`) is the same silent no-op as a missing
+ * executable bit and is asserted against below.
+ *
+ * Source: `githooks(5)`, client-side hooks only — server-side hooks
+ * (`pre-receive`, `update`, `post-receive`) cannot fire from a clone.
+ */
+const GIT_CLIENT_HOOKS = new Set([
+  "applypatch-msg",
+  "pre-applypatch",
+  "post-applypatch",
+  "pre-commit",
+  "pre-merge-commit",
+  "prepare-commit-msg",
+  "commit-msg",
+  "post-commit",
+  "pre-rebase",
+  "post-checkout",
+  "post-merge",
+  "pre-push",
+  "pre-auto-gc",
+  "post-rewrite",
+  "sendemail-validate",
+  "post-index-change",
+  "reference-transaction",
+  "push-to-checkout",
+]);
+
+/**
+ * Tracked entries directly under `.husky/`, as `{ mode, path, name }`.
+ *
+ * `git ls-files -s` emits `<mode> <object> <stage>\t<path>`. Husky's own
+ * `_/` shim directory and dotfiles (`.gitignore`) are not hooks and are
+ * excluded; everything else in the directory is one by convention.
+ */
+function trackedHooks() {
+  const out = execFileSync("git", ["ls-files", "-s", "--", HOOKS_DIR], {
+    encoding: "utf8",
+  });
+
+  return out
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .map((line) => {
+      const [meta, path] = line.split("\t");
+      return { mode: meta.split(" ")[0], path, name: path.slice(HOOKS_DIR.length + 1) };
+    })
+    .filter(({ name }) => !name.startsWith(".") && !name.startsWith("_/"));
+}
+
+test("the quality-gate pre-commit hook is still tracked", () => {
+  // Without this the mode assertion below passes vacuously the moment the
+  // hook is deleted — which is the same outcome (no gate) by another route.
+  const names = trackedHooks().map((h) => h.name);
+  assert.ok(
+    names.includes("pre-commit"),
+    `${HOOKS_DIR}/pre-commit is not tracked; the commit-time quality gate would not run. Tracked: ${names.join(", ") || "(none)"}`,
+  );
+});
+
+test("every tracked hook under .husky/ is executable in the index", () => {
+  const hooks = trackedHooks();
+  assert.ok(hooks.length > 0, `no tracked hooks found under ${HOOKS_DIR}/`);
+
+  const nonExecutable = hooks.filter((h) => h.mode !== EXECUTABLE);
+  assert.deepEqual(
+    nonExecutable.map((h) => `${h.path} (${h.mode})`),
+    [],
+    `git 2.36+ silently IGNORES a non-executable hook and lets the commit succeed with exit 0. ` +
+      `Fix the tracked mode with: git update-index --chmod=+x <path>  (a bare chmod does not change it).`,
+  );
+});
+
+test("every tracked hook under .husky/ has a name git will actually invoke", () => {
+  const unknown = trackedHooks()
+    .map((h) => h.name)
+    .filter((name) => !GIT_CLIENT_HOOKS.has(name));
+
+  assert.deepEqual(
+    unknown,
+    [],
+    `git invokes hooks by exact filename; a name outside githooks(5) never runs, as silently as a non-executable one.`,
+  );
+});

package/scripts/check-runner-runs-on.test.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * check-runner-runs-on.test.mjs — regression guard for the `runner` input's
- * two documented shapes (Story #421).
+ * check-runner-runs-on.test.mjs — regression guard for every shape the
+ * `runner` input can arrive in (Stories #421, #493).
  *
  * The bug this pins: every `runs-on:` site consumed the input raw as
  * `${{ inputs.runner }}`. GitHub does not parse a JSON-array *string* in that
@@ -21,6 +21,25 @@
  * expression from the workflow and EVALUATES it under Actions semantics, the
  * same read-then-execute approach as check-toolchain-cache-default.test.mjs.
  *
+ * The same failure had a second door, closed by #493: `runner: ''`. A
+ * workflow_call `default:` fires only when the key is ABSENT, so a caller
+ * who passes the key with an empty value — threading an unset input or a
+ * matrix value through — got the label `""` rather than `ubuntu-latest`, and
+ * with it the identical never-scheduled job. The fallback therefore lives at
+ * the `runs-on` site, and the byte-identical assertion below is what stops a
+ * fix that reaches six of the seven workflows from shipping as if it reached
+ * all seven.
+ *
+ * Story #493 also left a downstream door open, closed here: `runs-on` was not
+ * the only site reading `inputs.runner`. `pr-quality.yml`'s harden-runner
+ * egress-audit step gates on `startsWith(inputs.runner, 'ubuntu-')`, which was
+ * unreachable-but-consistent while `runner: ''` never scheduled a job. Once the
+ * empty value resolved to the hosted default, the job ran on ubuntu-latest
+ * while the gate read the raw `''` and skipped — a SECURITY step opting itself
+ * out with nothing red to show for it. So the gate is asserted the same way:
+ * extracted and EVALUATED, and required to AGREE with what `runs-on` resolves
+ * to for the same input.
+ *
  * Run: node --test scripts/check-runner-runs-on.test.mjs
  */
 
@@ -28,6 +47,7 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 import { readFileSync, readdirSync } from "node:fs";
 import { evaluate } from "./lib/actions-expression.mjs";
+import { stepByName } from "./lib/yaml-step.mjs";
 
 const WORKFLOW_DIR = ".github/workflows";
 
@@ -58,6 +78,28 @@ function runsOnExpressions(text) {
   return out;
 }
 
+/**
+ * The `default:` this workflow declares for its `runner` workflow_call input.
+ *
+ * Read from the YAML rather than hardcoded so the empty-input assertion below
+ * pins the real contract: whatever label a caller gets by omitting `runner`
+ * is the label an explicitly-empty `runner` must get too. Scanned line by
+ * line — the block boundary is indentation, and a dynamically-constructed
+ * regex is a SAST finding that buys nothing here.
+ */
+function declaredRunnerDefault(text) {
+  const lines = text.split("\n");
+  const start = lines.indexOf("      runner:");
+  assert.notEqual(start, -1, "no `runner:` workflow_call input found");
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() !== "" && !line.startsWith("        ")) break;
+    const m = line.match(/^\s+default:\s*'([^']*)'\s*$/);
+    if (m) return m[1];
+  }
+  return assert.fail("the `runner` input declares no `default:` to fall back to");
+}
+
 const WORKFLOWS = runnerWorkflows();
 
 test("every workflow taking a `runner` input is covered by this guard", () => {
@@ -127,6 +169,38 @@ for (const { file, text } of WORKFLOWS) {
     }
   });
 
+  test(`${file}: an empty runner resolves to this workflow's documented default`, () => {
+    // The silent-queue shape #421 left behind. `runner: ''` is not exotic — a
+    // caller threading `runner: ${{ inputs.runner }}` or a matrix value that
+    // resolves to nothing passes it without meaning to, and `format('"{0}"',
+    // '')` yielded the label `""`. An empty label matches no runner, so the
+    // job sat `queued` with no logs and no red, exactly as the JSON-array
+    // string did. The fallback belongs at the `runs-on` site because the
+    // input `default:` only fires when the key is ABSENT, never when it is
+    // present and empty.
+    const fallback = declaredRunnerDefault(text);
+    assert.notEqual(fallback, "", `${file}: the declared default is itself empty`);
+    for (const { line, expr } of sites) {
+      const resolved = evaluate(expr, { runner: "" });
+      assert.equal(
+        typeof resolved,
+        "string",
+        `${file}:${line}: an empty runner must resolve to a single label, not ${JSON.stringify(resolved)}`,
+      );
+      assert.notEqual(
+        resolved,
+        "",
+        `${file}:${line}: an empty runner resolves to an empty label — no runner ` +
+          `carries it, so the job queues until the 24-hour timeout with nothing to read`,
+      );
+      assert.equal(
+        resolved,
+        fallback,
+        `${file}:${line}: an empty runner must land on the input's documented default`,
+      );
+    }
+  });
+
   test(`${file}: every runs-on site resolves identically`, () => {
     // One workflow must not drift into two dialects of the same decision.
     const rendered = sites.map(({ expr }) =>
@@ -136,6 +210,25 @@ for (const { file, text } of WORKFLOWS) {
   });
 }
 
+
+test("every runs-on expression across the seven workflows is byte-identical", () => {
+  // The per-workflow tests above each score one file, so a fix applied to six
+  // of the seven passes every one of them and ships the seventh still broken.
+  // This is the assertion a partial edit cannot survive: one decision, spelled
+  // one way, everywhere it is made.
+  const distinct = new Map();
+  for (const { file, text } of WORKFLOWS) {
+    for (const { line, expr } of runsOnExpressions(text)) {
+      if (!distinct.has(expr)) distinct.set(expr, []);
+      distinct.get(expr).push(`${file}:${line}`);
+    }
+  }
+  const report = [...distinct.entries()]
+    .map(([expr, at]) => `${expr}  @ ${at.join(", ")}`)
+    .join("\n  ");
+  assert.equal(distinct.size, 1, `runs-on expressions have drifted apart:\n  ${report}`);
+});
+
 test("the documented array form resolves AND derives toolchain-cache 'false'", () => {
   // The coupling the gap report found: before this fix the only `runner` value
   // that derived the correct cache posture was the one that never reached a
@@ -152,3 +245,131 @@ test("the documented array form resolves AND derives toolchain-cache 'false'", (
   assert.ok(cache, "no `cache: ${{ … }}` value found at the setup-toolchain call site");
   assert.equal(evaluate(cache[1].trim(), { runner, "toolchain-cache": "auto" }), "false");
 });
+
+// ---------------------------------------------------------------------------
+// The harden-runner egress-audit gate (`pr-quality.yml`)
+//
+// `runs-on` was not the only expression reading `inputs.runner`. Anything that
+// branches on the runner class has to resolve the input the SAME way, or the
+// job and the step disagree about which machine they are on. This section
+// pins that agreement behaviourally — extract the real `if:` and run it.
+// ---------------------------------------------------------------------------
+
+/**
+ * The `${{ … }}` body of the harden-runner step's `if:` gate.
+ *
+ * Keyed off the step, not off a line pattern that happens to contain
+ * `startsWith` — the point is to score whatever expression actually guards
+ * that step, including one a future edit spells differently.
+ */
+function hardenRunnerGate(text) {
+  const block = stepByName(text, "Harden runner (egress audit)");
+  assert.match(
+    block,
+    /uses: step-security\/harden-runner@/,
+    "the extracted block is not the harden-runner step",
+  );
+  const m = block.match(/^\s*if:\s*\$\{\{(.+)\}\}\s*$/m);
+  assert.ok(m, "the harden-runner step has no single-expression `if:` gate to score");
+  return m[1].trim();
+}
+
+/**
+ * What `runs-on` resolves to for `runner`, as a hosted-ubuntu predicate.
+ *
+ * A single string label starting with `ubuntu-` is a GitHub-hosted ubuntu
+ * image — the one environment where harden-runner installs its own monitor.
+ * An ARRAY (the documented self-hosted form) is not, regardless of the labels
+ * inside it: harden-runner ships its agent in a self-hosted runner image, so
+ * the step is correctly a no-op there.
+ */
+function resolvesToHostedUbuntu(runsOnExpr, runner) {
+  const resolved = evaluate(runsOnExpr, { runner });
+  return typeof resolved === "string" && resolved.startsWith("ubuntu-");
+}
+
+const QUALITY_FILE = `${WORKFLOW_DIR}/pr-quality.yml`;
+const QUALITY_TEXT = readFileSync(QUALITY_FILE, "utf8");
+
+test("pr-quality.yml: the harden-runner gate reaches every tier through one anchor", () => {
+  // The gate is written once (`&harden-runner`) and aliased into the other
+  // tiers. A second literal copy could carry a stale expression that every
+  // behavioural assertion below would miss, because they score the anchor.
+  assert.match(QUALITY_TEXT, /^ {6}- &harden-runner$/m, "the harden-runner anchor is missing");
+  assert.ok(
+    (QUALITY_TEXT.match(/^ {6}- \*harden-runner$/gm) ?? []).length > 0,
+    "expected the harden-runner anchor to be aliased into the other tiers",
+  );
+  assert.equal(
+    (QUALITY_TEXT.match(/uses: step-security\/harden-runner@/g) ?? []).length,
+    1,
+    "expected exactly one harden-runner step — a second one would bypass the anchor",
+  );
+});
+
+test("pr-quality.yml: an empty runner keeps the egress audit ON", () => {
+  // The regression. `runner: ''` resolves to the hosted ubuntu-latest default
+  // at `runs-on` (#493), so the job DOES run on a GitHub-hosted machine — but
+  // a gate reading the raw input saw `startsWith('', 'ubuntu-')` → false and
+  // skipped. Nothing goes red when a step is skipped, so the egress baseline
+  // silently disappears for exactly the callers who never asked to opt out.
+  const gate = hardenRunnerGate(QUALITY_TEXT);
+  assert.equal(
+    evaluate(gate, { runner: "", "enable-harden-runner": true }),
+    true,
+    "an empty runner lands on hosted ubuntu-latest, so the egress audit must run there",
+  );
+});
+
+test("pr-quality.yml: the gate agrees with what runs-on resolves to", () => {
+  // The real contract, and the one that survives a respelling of either
+  // expression: the step runs precisely when the job is on a hosted ubuntu
+  // image. Scoring both sides against the same input is what makes a future
+  // change to one of them fail here instead of shipping a silent divergence.
+  const gate = hardenRunnerGate(QUALITY_TEXT);
+  const [runsOn] = runsOnExpressions(QUALITY_TEXT);
+  for (const runner of [
+    "",
+    "ubuntu-latest",
+    "ubuntu-24.04",
+    "ubuntu-22.04",
+    "ubuntu-latest-8-cores",
+    "macos-14",
+    "windows-latest",
+    '["self-hosted","beestera-runner"]',
+    '["ubuntu-latest"]',
+  ]) {
+    assert.equal(
+      evaluate(gate, { runner, "enable-harden-runner": true }),
+      resolvesToHostedUbuntu(runsOn.expr, runner),
+      `runner ${JSON.stringify(runner)}: the gate and the resolved runs-on disagree ` +
+        `about whether this job is on a GitHub-hosted ubuntu image`,
+    );
+  }
+});
+
+test("pr-quality.yml: `enable-harden-runner: false` still opts out everywhere", () => {
+  // The documented escape hatch. A fallback added to the runner half of the
+  // gate must not make the boolean half unreachable — `false && …` yields
+  // `false`, but only if the operands stayed in that order.
+  const gate = hardenRunnerGate(QUALITY_TEXT);
+  for (const runner of ["", "ubuntu-latest", "ubuntu-24.04", '["self-hosted","x"]']) {
+    assert.equal(
+      evaluate(gate, { runner, "enable-harden-runner": false }),
+      false,
+      `runner ${JSON.stringify(runner)}: opting out must win regardless of the runner`,
+    );
+  }
+});
+
+test("pr-quality.yml: the toolchain-cache derivation reads an empty runner as hosted", () => {
+  // The sibling `inputs.runner` reader, checked rather than assumed. It is
+  // correct as written for `runner: ''` — but only incidentally, because
+  // `contains('', 'self-hosted')` is false and the derivation is
+  // self-hosted-side. Pinning it here means a future inversion to a
+  // hosted-side test (`contains(runner, 'ubuntu')`) trips instead of quietly
+  // disabling the cache for every empty-runner caller.
+  const cache = QUALITY_TEXT.match(/^\s*cache:\s*\$\{\{(.+)\}\}\s*$/m);
+  assert.ok(cache, "no `cache: ${{ … }}` value found at the setup-toolchain call site");
+  assert.equal(evaluate(cache[1].trim(), { runner: "", "toolchain-cache": "auto" }), "true");
+});