mandrel-platform 1.2.0 → 1.3.0

package/scripts/check-setup-toolchain-store.test.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * check-setup-toolchain-store.test.mjs — regression guard for where the pnpm
+ * store lives (setup-toolchain).
+ *
+ * The bug this pins: pnpm derives its default store from PNPM_HOME, which
+ * `pnpm/action-setup` sets to `dest` — so the store lands inside the shim dir
+ * that the action's own "Clean stale pnpm install dir" step removes at the top
+ * of every job. With `cache: 'false'` that left a self-hosted runner with no
+ * cache at all (none from GitHub by design, none on disk in fact), re-fetching
+ * the whole dependency graph every time. It looks like a warm store right up
+ * until a registry blip fails the install (Beestera/swarm-os#1174).
+ *
+ * Reading the YAML is not enough: what decides the outcome is a shell branch,
+ * and the failure mode is silent — a resolution bug just hands pnpm no flag and
+ * quietly restores the old behaviour. So this extracts the real `run:` body and
+ * executes it against a stub `pnpm` that echoes its argv, the same
+ * read-then-execute approach as `check-osv-scan-mode.test.mjs`.
+ *
+ * Run: node --test scripts/check-setup-toolchain-store.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { execFileSync } from "node:child_process";
+import { readFileSync, mkdtempSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { stepByName, runScript } from "./lib/yaml-step.mjs";
+
+const ACTION = ".github/actions/setup-toolchain/action.yml";
+const WORKFLOW = ".github/workflows/pr-quality.yml";
+
+const actionText = readFileSync(ACTION, "utf8");
+const installScript = runScript(stepByName(actionText, "Install dependencies"));
+
+/**
+ * Run the extracted install body with a stub `pnpm` on PATH and return what the
+ * stub saw. `TRUST_LOCKFILE` defaults to the action's own default so a case only
+ * states the variables it is about.
+ */
+function runInstall(env) {
+  const dir = mkdtempSync(path.join(tmpdir(), "setup-toolchain-store-"));
+  try {
+    const stub = path.join(dir, "pnpm");
+    writeFileSync(stub, '#!/bin/sh\necho "PNPM_ARGV: $*"\n');
+    chmodSync(stub, 0o755);
+    const script = path.join(dir, "install.sh");
+    writeFileSync(script, installScript);
+    return execFileSync("bash", [script], {
+      cwd: dir,
+      encoding: "utf8",
+      env: {
+        PATH: `${dir}${path.delimiter}${process.env.PATH}`,
+        TRUST_LOCKFILE: "false",
+        STORE_DIR_INPUT: "",
+        ...env,
+      },
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("cache 'false' puts the store in the tool cache, outside the pre-cleaned shim dir", () => {
+  const out = runInstall({ CACHE_ENABLED: "false", TOOL_CACHE: "/opt/hostedtoolcache" });
+  assert.match(out, /--store-dir \/opt\/hostedtoolcache\/pnpm-store/);
+  assert.match(out, /--frozen-lockfile/);
+});
+
+test("cache 'true' leaves the store alone — setup-node resolves it to decide what to cache", () => {
+  const out = runInstall({ CACHE_ENABLED: "true", TOOL_CACHE: "/opt/hostedtoolcache" });
+  assert.doesNotMatch(out, /--store-dir/);
+});
+
+test("an explicit store-dir input wins, whether caching is on or off", () => {
+  for (const CACHE_ENABLED of ["false", "true"]) {
+    const out = runInstall({
+      CACHE_ENABLED,
+      STORE_DIR_INPUT: "/mnt/fast/store",
+      TOOL_CACHE: "/opt/hostedtoolcache",
+    });
+    assert.match(out, /--store-dir \/mnt\/fast\/store/, `cache: '${CACHE_ENABLED}'`);
+  }
+});
+
+test("no tool cache resolved falls back to pnpm's default rather than passing an empty path", () => {
+  const out = runInstall({ CACHE_ENABLED: "false", TOOL_CACHE: "" });
+  assert.doesNotMatch(out, /--store-dir/);
+});
+
+test("trust-lockfile composes with the store flag instead of replacing it", () => {
+  const out = runInstall({
+    CACHE_ENABLED: "false",
+    TOOL_CACHE: "/opt/hostedtoolcache",
+    TRUST_LOCKFILE: "true",
+  });
+  assert.match(out, /--trust-lockfile/);
+  assert.match(out, /--store-dir \/opt\/hostedtoolcache\/pnpm-store/);
+});
+
+test("a store path containing a space stays one argument", () => {
+  // The reason the script uses positional parameters rather than string
+  // concatenation. Also why it cannot use a bash array: this runs on macOS
+  // bash 3.2, where "${arr[@]}" under `set -u` errors on an empty array.
+  const out = runInstall({ CACHE_ENABLED: "false", STORE_DIR_INPUT: "/mnt/my store" });
+  assert.match(out, /--store-dir \/mnt\/my store/);
+});
+
+test("the store never resolves inside the directory the pre-clean removes", () => {
+  // The whole point. PNPM_DEST is what "Clean stale pnpm install dir" deletes;
+  // a store under it is a store that cannot survive a job.
+  const out = runInstall({ CACHE_ENABLED: "false", TOOL_CACHE: "/opt/hostedtoolcache" });
+  const argv = out.match(/PNPM_ARGV: (.*)/)?.[1] ?? "";
+  const storeDir = argv.match(/--store-dir (\S+)/)?.[1] ?? "";
+  assert.notEqual(storeDir, "", "expected a --store-dir with caching disabled");
+  assert.ok(
+    !storeDir.includes("/pnpm/store") && !storeDir.includes("_temp"),
+    `store must not live under the pnpm shim dest; got ${storeDir}`,
+  );
+});
+
+test("pr-quality threads toolchain-store-dir to the shared setup-toolchain anchor", () => {
+  const workflow = readFileSync(WORKFLOW, "utf8");
+  assert.match(
+    workflow,
+    /^ {6}toolchain-store-dir:$/m,
+    "workflow_call input toolchain-store-dir is missing",
+  );
+  assert.match(
+    workflow,
+    /store-dir: \$\{\{ inputs\.toolchain-store-dir \}\}/,
+    "the setup-toolchain anchor does not pass store-dir through",
+  );
+  // One anchor, aliased by the other jobs: threading it once must reach them all.
+  const aliases = workflow.match(/^ {6}- \*setup-toolchain$/gm) ?? [];
+  assert.ok(aliases.length > 0, "expected the setup-toolchain anchor to be aliased");
+});

package/scripts/check-toolchain-cache-default.test.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+/**
+ * check-toolchain-cache-default.test.mjs — regression guard for the derived
+ * `toolchain-cache` default (Story #364).
+ *
+ * The bug this pins: `toolchain-cache` defaulted to `'true'`, which is only
+ * correct for a GitHub-hosted caller. On a self-hosted runner with a warm pnpm
+ * store the cache adds a POST-JOB save — a step that runs after every work step
+ * has already reported success, billed against the same `timeout-minutes` those
+ * steps spent. A slow save exhausts the ceiling, GitHub kills the job, and the
+ * kill is recorded as `cancelled` rather than `failure`, which `ci-required`
+ * maps to a red gate with every step green.
+ *
+ * The fix cannot live in the input's `default:` — a `workflow_call` default may
+ * not hold a `${{ }}` expression (check-workflow-portability.mjs Rule 2), and
+ * GitHub resolves defaults during interface validation, before `inputs.runner`
+ * exists. So the default is the LITERAL `'auto'` and the derivation happens at
+ * the use site.
+ *
+ * Asserting that by string-matching the expression would pin the spelling, not
+ * the behaviour: the failure mode here is a subtly wrong ternary that still
+ * looks right (Actions `&&`/`||` return OPERANDS, not booleans, and every
+ * non-empty string — including `'false'` — is truthy). So this extracts the real
+ * expression from each workflow and EVALUATES it under GitHub's own truthiness
+ * rules, the same read-then-execute approach as
+ * check-setup-toolchain-store.test.mjs.
+ *
+ * Run: node --test scripts/check-toolchain-cache-default.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readFileSync } from "node:fs";
+
+const QUALITY = ".github/workflows/pr-quality.yml";
+const ADVISORY = ".github/workflows/advisory-scan.yml";
+
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+
+/** The `${{ … }}` body of the `cache:` value passed to setup-toolchain. */
+function cacheExpression(text, file) {
+  const m = text.match(/^\s*cache:\s*\$\{\{(.+)\}\}\s*$/m);
+  assert.ok(m, `${file}: no \`cache: \${{ … }}\` value found at the setup-toolchain call site`);
+  return m[1].trim();
+}
+
+/**
+ * The literal `default:` of the named workflow_call input.
+ *
+ * Scans lines rather than building a `new RegExp` around `name`: a
+ * dynamically-constructed regex is a SAST finding (ReDoS surface) and buys
+ * nothing here, since the block boundary is just indentation.
+ */
+function inputDefault(text, name, file) {
+  const lines = text.split("\n");
+  const start = lines.indexOf(`      ${name}:`);
+  assert.notEqual(start, -1, `${file}: workflow_call input \`${name}\` not found`);
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].trim() === "") continue;
+    // Dedent to the input-name level or beyond → the block ended.
+    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(`${file}: input \`${name}\` has no default`);
+}
+
+// ---------------------------------------------------------------------------
+// A minimal GitHub Actions expression evaluator
+//
+// Only the surface this expression uses: string literals, `inputs.<name>` /
+// `inputs['<name>']` context reads, `==`/`!=`, `&&`/`||`, parentheses, and
+// `contains()`. The semantics that matter and that a hand-read gets wrong:
+//
+//   - `a && b` yields `b` when `a` is truthy, else `a`.
+//   - `a || b` yields `a` when `a` is truthy, else `b`.
+//   - EVERY non-empty string is truthy — including the string `'false'`.
+//   - String comparison is case-insensitive.
+// ---------------------------------------------------------------------------
+
+function truthy(v) {
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") return v !== 0;
+  if (typeof v === "string") return v !== "";
+  return v !== null && v !== undefined;
+}
+
+function looseEqual(a, b) {
+  if (typeof a === "string" && typeof b === "string") {
+    return a.toLowerCase() === b.toLowerCase();
+  }
+  return a === b;
+}
+
+function evaluate(expr, inputs) {
+  let i = 0;
+
+  const ws = () => {
+    while (i < expr.length && /\s/.test(expr[i])) i++;
+  };
+  const eat = (token) => {
+    ws();
+    if (expr.startsWith(token, i)) {
+      i += token.length;
+      return true;
+    }
+    return false;
+  };
+
+  function parseOr() {
+    let left = parseAnd();
+    for (;;) {
+      ws();
+      if (!eat("||")) return left;
+      const right = parseAnd();
+      left = truthy(left) ? left : right;
+    }
+  }
+
+  function parseAnd() {
+    let left = parseCompare();
+    for (;;) {
+      ws();
+      if (!eat("&&")) return left;
+      const right = parseCompare();
+      left = truthy(left) ? right : left;
+    }
+  }
+
+  function parseCompare() {
+    const left = parsePrimary();
+    ws();
+    if (eat("!=")) return !looseEqual(left, parsePrimary());
+    if (eat("==")) return looseEqual(left, parsePrimary());
+    return left;
+  }
+
+  function parsePrimary() {
+    ws();
+    if (eat("(")) {
+      const v = parseOr();
+      ws();
+      assert.ok(eat(")"), `unbalanced parenthesis at ${i} in: ${expr}`);
+      return v;
+    }
+    if (expr[i] === "'") {
+      i++;
+      let out = "";
+      while (i < expr.length) {
+        if (expr[i] === "'" && expr[i + 1] === "'") {
+          out += "'";
+          i += 2;
+          continue;
+        }
+        if (expr[i] === "'") {
+          i++;
+          return out;
+        }
+        out += expr[i++];
+      }
+      assert.fail(`unterminated string literal in: ${expr}`);
+    }
+    if (expr.startsWith("contains(", i)) {
+      i += "contains(".length;
+      const hay = parseOr();
+      ws();
+      assert.ok(eat(","), `contains() expects two arguments in: ${expr}`);
+      const needle = parseOr();
+      ws();
+      assert.ok(eat(")"), `unclosed contains() in: ${expr}`);
+      return String(hay).toLowerCase().includes(String(needle).toLowerCase());
+    }
+    const ident = expr.slice(i).match(/^[A-Za-z_][A-Za-z0-9_.\-]*(\['[^']*'\])?/);
+    assert.ok(ident, `unparseable token at ${i} in: ${expr}`);
+    i += ident[0].length;
+    const raw = ident[0];
+    if (raw === "true") return true;
+    if (raw === "false") return false;
+    const bracket = raw.match(/^inputs\['([^']*)'\]$/);
+    const dotted = raw.match(/^inputs\.(.+)$/);
+    const key = bracket ? bracket[1] : dotted ? dotted[1] : null;
+    assert.ok(key !== null, `unsupported context read \`${raw}\` in: ${expr}`);
+    assert.ok(key in inputs, `expression reads \`inputs.${key}\`, not provided by the test case`);
+    return inputs[key];
+  }
+
+  const value = parseOr();
+  ws();
+  assert.equal(i, expr.length, `trailing tokens at ${i} in: ${expr}`);
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// The evaluator itself must be trustworthy before it can judge the workflow.
+// ---------------------------------------------------------------------------
+
+test("the expression evaluator models Actions truthiness, not JavaScript's", () => {
+  // The trap the real expression depends on: the STRING 'false' is truthy, so
+  // an explicitly-pinned 'false' survives the first arm of the ternary.
+  assert.equal(evaluate("'false' && 'yes' || 'no'", {}), "yes");
+  // `&&`/`||` yield operands, not booleans.
+  assert.equal(evaluate("true && 'kept'", {}), "kept");
+  assert.equal(evaluate("'' || 'fallback'", {}), "fallback");
+  // Comparison is case-insensitive.
+  assert.equal(evaluate("'AUTO' == 'auto'", {}), true);
+  assert.equal(evaluate("contains('[\"self-hosted\",\"x\"]', 'self-hosted')", {}), true);
+});
+
+// ---------------------------------------------------------------------------
+// The contract
+// ---------------------------------------------------------------------------
+
+const workflows = [
+  { file: QUALITY, text: readFileSync(QUALITY, "utf8") },
+  { file: ADVISORY, text: readFileSync(ADVISORY, "utf8") },
+];
+
+for (const { file, text } of workflows) {
+  test(`${file}: the toolchain-cache default is a literal 'auto', not an expression`, () => {
+    // AC-1. An expression here is what the portability lint (Rule 2) rejects
+    // and what GitHub silently fails to evaluate at interface-validation time.
+    const value = inputDefault(text, "toolchain-cache", file);
+    assert.equal(value, "'auto'");
+    assert.doesNotMatch(value, /\$\{\{/, "a workflow_call default may not hold an expression");
+  });
+
+  test(`${file}: an unset toolchain-cache disables caching on a self-hosted runner`, () => {
+    // AC-2 — the whole point: no post-job store save, so no teardown eating the
+    // job's timeout and reporting as `cancelled` with every step green.
+    const expr = cacheExpression(text, file);
+    for (const runner of ["self-hosted", '["self-hosted","domio-runner"]', '["self-hosted"]']) {
+      assert.equal(
+        evaluate(expr, { "toolchain-cache": "auto", runner }),
+        "false",
+        `runner ${runner}`,
+      );
+    }
+  });
+
+  test(`${file}: an unset toolchain-cache keeps caching on for a hosted runner`, () => {
+    // AC-3 — hosted behaviour must not move. Detection is self-hosted-side
+    // precisely so a larger-runner custom label is not mistaken for one.
+    const expr = cacheExpression(text, file);
+    for (const runner of [
+      "ubuntu-latest",
+      "ubuntu-24.04",
+      "macos-14",
+      "windows-latest",
+      "ubuntu-latest-8-cores",
+      '["ubuntu-latest"]',
+    ]) {
+      assert.equal(evaluate(expr, { "toolchain-cache": "auto", runner }), "true", `runner ${runner}`);
+    }
+  });
+
+  test(`${file}: an explicit toolchain-cache is passed through on either runner class`, () => {
+    // AC-4. 'false' is the one that breaks under a naive ternary — it is a
+    // non-empty string and therefore truthy, which is what makes it survive.
+    const expr = cacheExpression(text, file);
+    for (const runner of ["ubuntu-latest", '["self-hosted","domio-runner"]']) {
+      for (const pinned of ["true", "false"]) {
+        assert.equal(
+          evaluate(expr, { "toolchain-cache": pinned, runner }),
+          pinned,
+          `${pinned} on ${runner}`,
+        );
+      }
+    }
+  });
+}
+
+test("both workflows derive the default identically", () => {
+  // AC-5. Two documented rows describing one behaviour must not drift apart —
+  // the reason this Story moves both workflows rather than only the quality one.
+  const [quality, advisory] = workflows.map(({ file, text }) => cacheExpression(text, file));
+  assert.equal(advisory, quality);
+});
+
+test("pr-quality resolves the default at the shared setup-toolchain anchor", () => {
+  // One anchor, aliased by every other tier: deriving it once must reach them
+  // all, or a tier silently keeps the old always-on default.
+  const text = readFileSync(QUALITY, "utf8");
+  assert.match(text, /^ {6}- &setup-toolchain$/m, "the setup-toolchain anchor is missing");
+  const aliases = text.match(/^ {6}- \*setup-toolchain$/gm) ?? [];
+  assert.ok(aliases.length > 0, "expected the setup-toolchain anchor to be aliased");
+  assert.equal(
+    (text.match(/^\s*cache:\s*\$\{\{/gm) ?? []).length,
+    1,
+    "expected exactly one cache: call site — a second one would bypass the anchor",
+  );
+});
+
+test("both documented input rows state the derived default and the self-hosted reason", () => {
+  // AC-6. The rows are the consumer-facing contract; a fix documented in only
+  // one of the two tables leaves them contradicting each other.
+  const docs = readFileSync("docs/reusable-workflows.md", "utf8");
+  // Scoped to the two `Inputs` tables (`| name | type | default | …`) so the
+  // explainer section's own table is not counted as a third row.
+  const rows = docs.split("\n").filter((l) => /^\|\s*`toolchain-cache`\s*\|\s*string\s*\|/.test(l));
+  assert.equal(rows.length, 2, "expected one documented row per workflow");
+  for (const row of rows) {
+    assert.match(row, /`'auto'`/, "row does not state the 'auto' default");
+    assert.match(row, /self-hosted/i, "row does not explain the self-hosted derivation");
+    assert.doesNotMatch(row, /\|\s*`'true'`\s*\|/, "row still documents the old 'true' default");
+  }
+});

package/scripts/lib/yaml-step.mjs

@@ -0,0 +1,109 @@
+/**
+ * scripts/lib/yaml-step.mjs
+ *
+ * The single indentation-based YAML step extractor shared by the workflow and
+ * composite-action test suites under `scripts/` (Story #377).
+ *
+ * ## Why this is a shared module and not five copies
+ *
+ * Several suites in this repository do not merely READ a workflow — they pull
+ * the real `run:` body out of a named step and execute it against a stubbed
+ * binary, because what decides the outcome is a shell branch rather than the
+ * YAML around it. That read-then-execute pattern needs exactly two helpers,
+ * and they had been copy-pasted verbatim into five test files
+ * (check-affected-mode, check-environments-isolation-audit,
+ * check-gitleaks-allowlist, check-osv-scan-mode, check-setup-toolchain-store).
+ *
+ * The duplication was not cosmetic. These helpers decide WHICH BYTES each
+ * suite executes, so a copy that drifts and silently extracts the wrong block
+ * asserts against different text and still reports green — the same
+ * runs-but-verifies-nothing failure the suites themselves exist to prevent.
+ * One definition means a drift is a change to one file that every caller sees.
+ *
+ * ## Deliberately dependency-free, and deliberately test-only
+ *
+ * There is no YAML parser in this repository's dependency graph, by design:
+ * the guardrail scripts consumers copy into their CI must run on a bare Node
+ * runtime with no package install. So this is a line-oriented indentation
+ * reader, not a parser. It handles the two shapes the suites actually use — a
+ * `- name:`-keyed step block, and a `run: |` block scalar — and nothing else.
+ *
+ * Both helpers `assert` internally rather than returning a sentinel: a step
+ * name that no longer resolves is a test-authoring fault that must fail loudly
+ * at the point of extraction, not silently degrade into an empty script that
+ * passes every downstream assertion. That is why this module imports
+ * `node:assert/strict`, which is acceptable here because this is a TEST-ONLY
+ * lib module — nothing under `scripts/*.mjs` that runs in CI imports it.
+ */
+
+import assert from "node:assert/strict";
+
+/**
+ * Extract the text of a single step, keyed by a substring of its `name:`.
+ *
+ * A step spans from its `- ` bullet to the next sibling bullet at the same
+ * indent (or to the first dedent below it), so nested `with:` / `env:` mappings
+ * come along and a following step never does.
+ *
+ * @param {string} text  Workflow or composite-action YAML.
+ * @param {string} name  A substring of the target step's `name:` value.
+ * @returns {string} The step block, newline-joined, including its `- ` bullet.
+ * @throws {assert.AssertionError} When no step name contains `name`.
+ */
+export function stepByName(text, name) {
+  const lines = text.split("\n");
+  const nameIdx = lines.findIndex((l) => /^\s+(- )?name:\s/.test(l) && l.includes(name));
+  assert.notEqual(nameIdx, -1, `step "${name}" not found`);
+  let start = -1;
+  for (let i = nameIdx; i >= 0; i--) {
+    if (/^\s*-\s/.test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+  assert.notEqual(start, -1, `opening bullet for step "${name}" not found`);
+  const bulletIndent = lines[start].match(/^(\s*)/)[1].length;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) continue;
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent < bulletIndent) {
+      end = i;
+      break;
+    }
+    if (indent === bulletIndent && /^\s*-\s/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+/**
+ * The dedented body of a step's `run: |` block scalar.
+ *
+ * Blank lines are preserved as empty lines rather than skipped, so line numbers
+ * inside the extracted script still line up with the workflow — which is what
+ * makes a `bash -x` trace of the executed body readable against the source.
+ *
+ * @param {string} stepBlock  A step block, typically from {@link stepByName}.
+ * @returns {string} The `run:` body with the block-scalar indent removed.
+ * @throws {assert.AssertionError} When the step has no `run: |` block scalar.
+ */
+export function runScript(stepBlock) {
+  const lines = stepBlock.split("\n");
+  const start = lines.findIndex((l) => /^\s+run:\s*\|\s*$/.test(l));
+  assert.notEqual(start, -1, "`run: |` block not found");
+  const runIndent = lines[start].match(/^(\s*)/)[1].length;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) {
+      body.push("");
+      continue;
+    }
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent <= runIndent) break;
+    body.push(lines[i].slice(runIndent + 2));
+  }
+  return body.join("\n");
+}