mandrel-platform 1.5.0 → 1.6.0

package/scripts/check-workflow-portability.mjs

@@ -39,6 +39,20 @@
  *      job". Requires git history (run CI checkout with fetch-depth: 0); the
  *      check degrades to a skipped NOTE when the pinned blob is unreachable.
  *
+ *   4. `runs-on: ${{ inputs.runner }}` — consuming a `runner` input RAW is
+ *      PROHIBITED. GitHub does not parse a JSON-array *string* in that
+ *      position: it takes the entire text as ONE label name, so the
+ *      documented `'["self-hosted","my-runner"]'` form matches no runner and
+ *      every job sits `queued` until the 24-hour timeout. This one is worse
+ *      than the others because it is not even loud — no job starts, so there
+ *      are no logs, and `gh pr checks` reports `pending 0`, indistinguishable
+ *      from a busy fleet. Normalize to
+ *      `fromJSON(startsWith(inputs.runner, '[') && inputs.runner ||
+ *      format('"{0}"', inputs.runner))`, which accepts both documented
+ *      shapes. (Caused #419 / v1.5.0; behaviour is covered by
+ *      check-runner-runs-on.test.mjs, which evaluates the real expression
+ *      rather than matching its spelling.)
+ *
  * What this lint deliberately does NOT flag: `${{ }}` in `runs.steps[].with`
  * (e.g. `dest: ${{ inputs['pnpm-dest'] || format('{0}/pnpm', runner.temp) }}`)
  * is a VALID runtime expression. The lint only inspects `description` and
@@ -266,6 +280,31 @@ export function checkWorkflowContent(content) {
     }
   }
 
+
+  // Rule 4: no `runs-on` that consumes a `runner` input raw. GitHub does not
+  // parse a JSON-array STRING in that position — it takes the whole text as one
+  // label name — so the documented `'["self-hosted","my-runner"]'` form matches
+  // no runner and every job sits `queued` until the 24-hour timeout. The failure
+  // is silent (no job starts, so no logs, and `gh pr checks` shows `pending 0`),
+  // which is why it needs a static tripwire as well as the behavioural guard in
+  // check-runner-runs-on.test.mjs.
+  content.split("\n").forEach((raw, idx) => {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("runs-on:")) return;
+    const m = trimmed.match(/^runs-on:\s*\$\{\{(.+)\}\}\s*$/);
+    if (!m) return;
+    if (m[1].trim() !== "inputs.runner") return;
+    violations.push({
+      line: idx + 1,
+      message:
+        `\`runs-on: \${{ inputs.runner }}\` consumes the input raw — a ` +
+        `JSON-encoded label-array string resolves to ONE unmatchable label ` +
+        `name and the job queues until the 24-hour timeout, silently. ` +
+        `Normalize it: \`fromJSON(startsWith(inputs.runner, '[') && ` +
+        `inputs.runner || format('"{0}"', inputs.runner))\`.`,
+    });
+  });
+
   return violations;
 }
 

package/scripts/check-workflow-portability.test.mjs

@@ -197,3 +197,69 @@ test("parseArgs: --no-pin-check, dir overrides, and --help are parsed", () => {
     help: true,
   });
 });
+
+// ---------------------------------------------------------------------------
+// Rule 4 — `runs-on` must not consume a `runner` input raw (Story #421)
+// ---------------------------------------------------------------------------
+
+/** A minimal reusable workflow whose single job's `runs-on` is `value`. */
+function runnerWorkflow(value) {
+  return [
+    "on:",
+    "  workflow_call:",
+    "    inputs:",
+    "      runner:",
+    "        required: false",
+    "        type: string",
+    "        default: 'ubuntu-latest'",
+    "jobs:",
+    "  build:",
+    `    runs-on: ${value}`,
+    "    steps:",
+    "      - run: echo hi",
+    "",
+  ].join("\n");
+}
+
+const NORMALIZED =
+  "${{ fromJSON(startsWith(inputs.runner, '[') && inputs.runner " +
+  "|| format('\"{0}\"', inputs.runner)) }}";
+
+test("Rule 4: a raw `runs-on: ${{ inputs.runner }}` is a violation", () => {
+  const violations = checkWorkflowContent(runnerWorkflow("${{ inputs.runner }}"));
+  assert.equal(violations.length, 1);
+  assert.equal(violations[0].line, 10);
+  assert.match(violations[0].message, /consumes the input raw/);
+  // The message must name the failure mode, not just the rule — a silent
+  // 24-hour queue is not something a reader infers from "normalize this".
+  assert.match(violations[0].message, /queues until the 24-hour timeout/);
+});
+
+test("Rule 4: the normalized form is clean", () => {
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow(NORMALIZED)), []);
+});
+
+test("Rule 4: a hardcoded `runs-on` is untouched", () => {
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow("ubuntu-latest")), []);
+});
+
+test("Rule 4: an unrelated expression in `runs-on` is untouched", () => {
+  // Only the exact raw-input read is flagged; a caller doing its own
+  // normalization or reading a different context is none of this rule's business.
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow("${{ fromJSON(vars.CI_RUNNER) }}")), []);
+  assert.deepEqual(checkWorkflowContent(runnerWorkflow("${{ inputs.runner-label }}")), []);
+});
+
+test("Rule 4: only reusable workflows are checked", () => {
+  // A `push`-triggered workflow has no workflow_call interface to break.
+  const plain = [
+    "on:",
+    "  push:",
+    "    branches: [main]",
+    "jobs:",
+    "  build:",
+    "    runs-on: ${{ inputs.runner }}",
+    "",
+  ].join("\n");
+  assert.deepEqual(checkWorkflowContent(plain), []);
+});

package/scripts/lib/actions-expression.mjs

@@ -0,0 +1,271 @@
+/**
+ * actions-expression.mjs — a minimal GitHub Actions expression evaluator.
+ *
+ * Extracted from check-toolchain-cache-default.test.mjs (Story #364) when a
+ * second guard needed it (Story #421). It exists because **a `grep` is not an
+ * acceptance criterion for a workflow expression**: string-matching pins the
+ * spelling, not the behaviour, and both expression defects this repo has
+ * shipped read correctly and evaluated wrong. Extract the real expression from
+ * the YAML and RUN it.
+ *
+ * Supported surface — only what the guarded expressions use: string literals,
+ * `inputs.<name>` / `inputs['<name>']` reads, `==`/`!=`, `&&`/`||`,
+ * parentheses, and `contains()`, `startsWith()`, `format()`, `fromJSON()`.
+ *
+ * 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`.
+ *     Both yield OPERANDS, not booleans.
+ *   - EVERY non-empty string is truthy — including the string `'false'`.
+ *   - Arrays and objects are truthy. GitHub documents the falsy set as exactly
+ *     `false`, `0`, `-0`, `''`, `null`; an array is not in it.
+ *   - String comparison is case-insensitive.
+ *
+ * ## On short-circuiting
+ *
+ * This evaluator parses to an AST first and evaluates `&&`/`||` lazily, which
+ * is the standard semantic. GitHub does NOT document whether its own evaluator
+ * short-circuits, so a guarded expression **must not depend on it** — never
+ * place a throwing call (`fromJSON` on caller-controlled text) in a branch that
+ * is only conditionally reached. Wrap the conditional instead:
+ *
+ *     fromJSON(cond && '<json>' || '<json>')     ← safe under either semantic
+ *     cond && fromJSON(x) || x                   ← safe ONLY if lazy
+ *
+ * Evaluating lazily here while requiring the safe shape in the workflows means
+ * the guard cannot bless an expression whose correctness rests on an
+ * unverified assumption about GitHub's evaluator.
+ *
+ * Errors are thrown as plain `Error`s; nothing here depends on a test framework.
+ */
+
+/** Actions truthiness — NOT JavaScript's. */
+export 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;
+}
+
+/** Actions comparison: case-insensitive for strings. */
+export function looseEqual(a, b) {
+  if (typeof a === "string" && typeof b === "string") {
+    return a.toLowerCase() === b.toLowerCase();
+  }
+  return a === b;
+}
+
+function fail(message) {
+  throw new Error(`[actions-expression] ${message}`);
+}
+
+const FUNCTIONS = new Map([
+  ["contains", 2],
+  ["startsWith", 2],
+  ["endsWith", 2],
+  ["fromJSON", 1],
+]);
+
+/** Parse `expr` into an AST. Exported for tests that assert on shape. */
+export function parse(expr) {
+  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;
+      left = { kind: "or", left, right: parseAnd() };
+    }
+  }
+
+  function parseAnd() {
+    let left = parseCompare();
+    for (;;) {
+      ws();
+      if (!eat("&&")) return left;
+      left = { kind: "and", left, right: parseCompare() };
+    }
+  }
+
+  function parseCompare() {
+    const left = parsePrimary();
+    ws();
+    if (eat("!=")) return { kind: "ne", left, right: parsePrimary() };
+    if (eat("==")) return { kind: "eq", left, right: parsePrimary() };
+    return left;
+  }
+
+  function parsePrimary() {
+    ws();
+    if (eat("(")) {
+      const node = parseOr();
+      ws();
+      if (!eat(")")) fail(`unbalanced parenthesis at ${i} in: ${expr}`);
+      return node;
+    }
+    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 { kind: "literal", value: out };
+        }
+        out += expr[i++];
+      }
+      fail(`unterminated string literal in: ${expr}`);
+    }
+    for (const [name, arity] of FUNCTIONS) {
+      if (!expr.startsWith(`${name}(`, i)) continue;
+      i += `${name}(`.length;
+      const args = [parseOr()];
+      while (args.length < arity) {
+        ws();
+        if (!eat(",")) fail(`${name}() expects ${arity} arguments in: ${expr}`);
+        args.push(parseOr());
+      }
+      ws();
+      if (!eat(")")) fail(`unclosed ${name}() in: ${expr}`);
+      return { kind: "call", name, args };
+    }
+    // `format()` is variadic, so it is parsed separately from the fixed-arity table.
+    if (expr.startsWith("format(", i)) {
+      i += "format(".length;
+      const args = [parseOr()];
+      for (;;) {
+        ws();
+        if (!eat(",")) break;
+        args.push(parseOr());
+      }
+      ws();
+      if (!eat(")")) fail(`unclosed format() in: ${expr}`);
+      return { kind: "call", name: "format", args };
+    }
+    const ident = expr.slice(i).match(/^[A-Za-z_][A-Za-z0-9_.\-]*(\['[^']*'\])?/);
+    if (!ident) fail(`unparseable token at ${i} in: ${expr}`);
+    i += ident[0].length;
+    const raw = ident[0];
+    if (raw === "true") return { kind: "literal", value: true };
+    if (raw === "false") return { kind: "literal", value: false };
+    const bracket = raw.match(/^inputs\['([^']*)'\]$/);
+    const dotted = raw.match(/^inputs\.(.+)$/);
+    const key = bracket ? bracket[1] : dotted ? dotted[1] : null;
+    if (key === null) fail(`unsupported context read \`${raw}\` in: ${expr}`);
+    return { kind: "input", key };
+  }
+
+  const ast = parseOr();
+  ws();
+  if (i !== expr.length) fail(`trailing tokens at ${i} in: ${expr}`);
+  return ast;
+}
+
+function applyFormat(args) {
+  const template = String(args[0]);
+  const rest = args.slice(1);
+  let out = "";
+  for (let k = 0; k < template.length; k++) {
+    const ch = template[k];
+    if (ch === "{" && template[k + 1] === "{") {
+      out += "{";
+      k++;
+    } else if (ch === "}" && template[k + 1] === "}") {
+      out += "}";
+      k++;
+    } else if (ch === "{") {
+      const close = template.indexOf("}", k);
+      if (close === -1) fail(`unclosed format placeholder in: ${template}`);
+      const idx = Number(template.slice(k + 1, close));
+      if (!Number.isInteger(idx)) fail(`non-numeric format placeholder in: ${template}`);
+      out += rest[idx] === undefined ? "" : String(rest[idx]);
+      k = close;
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+function evalNode(node, inputs) {
+  switch (node.kind) {
+    case "literal":
+      return node.value;
+    case "input":
+      if (!(node.key in inputs)) {
+        fail(`expression reads \`inputs.${node.key}\`, not provided by the caller`);
+      }
+      return inputs[node.key];
+    case "and": {
+      // Lazy on purpose — see the module header's note on short-circuiting.
+      const left = evalNode(node.left, inputs);
+      return truthy(left) ? evalNode(node.right, inputs) : left;
+    }
+    case "or": {
+      const left = evalNode(node.left, inputs);
+      return truthy(left) ? left : evalNode(node.right, inputs);
+    }
+    case "eq":
+      return looseEqual(evalNode(node.left, inputs), evalNode(node.right, inputs));
+    case "ne":
+      return !looseEqual(evalNode(node.left, inputs), evalNode(node.right, inputs));
+    case "call": {
+      const args = node.args.map((a) => evalNode(a, inputs));
+      if (node.name === "format") return applyFormat(args);
+      const [a, b] = args;
+      if (node.name === "contains") {
+        // Substring on a string haystack; exact-item match on an array one.
+        if (Array.isArray(a)) return a.some((item) => looseEqual(item, b));
+        return String(a).toLowerCase().includes(String(b).toLowerCase());
+      }
+      if (node.name === "startsWith") {
+        return String(a).toLowerCase().startsWith(String(b).toLowerCase());
+      }
+      if (node.name === "endsWith") {
+        return String(a).toLowerCase().endsWith(String(b).toLowerCase());
+      }
+      if (node.name === "fromJSON") {
+        try {
+          return JSON.parse(String(a));
+        } catch {
+          // A parse failure is a HARD expression error in Actions — the run
+          // fails rather than yielding null, which is what makes a malformed
+          // `runner` value loud instead of silently unmatchable.
+          fail(`fromJSON() could not parse ${JSON.stringify(String(a))} in this expression`);
+        }
+      }
+      return fail(`unsupported function \`${node.name}\``);
+    }
+    default:
+      return fail(`unsupported node kind \`${node.kind}\``);
+  }
+}
+
+/**
+ * Evaluate `expr` (the body BETWEEN `${{` and `}}`) against `inputs`.
+ *
+ * @param {string} expr
+ * @param {Record<string, unknown>} inputs values for `inputs.*` reads
+ * @returns {unknown} the resulting operand — a string, boolean, or array
+ */
+export function evaluate(expr, inputs) {
+  return evalNode(parse(expr), inputs);
+}

package/scripts/lib/actions-expression.test.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * actions-expression.test.mjs — the evaluator must be trustworthy before it
+ * can judge a workflow (Story #421).
+ *
+ * These assertions are the reason the evaluator exists: every one of them is a
+ * place where Actions semantics diverge from JavaScript's, and where a
+ * hand-read of an expression gets the wrong answer.
+ *
+ * Run: node --test scripts/lib/actions-expression.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { evaluate, truthy } from "./actions-expression.mjs";
+
+test("`&&` and `||` yield OPERANDS, not booleans", () => {
+  assert.equal(evaluate("true && 'kept'", {}), "kept");
+  assert.equal(evaluate("'' || 'fallback'", {}), "fallback");
+  assert.equal(evaluate("'a' || 'b'", {}), "a");
+});
+
+test("every non-empty string is truthy — including the string 'false'", () => {
+  // The trap the toolchain-cache expression depends on: an explicitly-pinned
+  // 'false' must survive the first arm of the ternary rather than falling
+  // through to the derivation.
+  assert.equal(evaluate("'false' && 'yes' || 'no'", {}), "yes");
+  assert.equal(truthy("false"), true);
+  assert.equal(truthy(""), false);
+});
+
+test("arrays are truthy — the property the runs-on normalization rests on", () => {
+  // GitHub documents the falsy set as exactly false, 0, -0, '', null. An array
+  // is not in it, so a parsed label array carries through `&&` / `||`.
+  assert.equal(truthy([]), true);
+  assert.equal(truthy(["self-hosted"]), true);
+});
+
+test("comparison is case-insensitive", () => {
+  assert.equal(evaluate("'AUTO' == 'auto'", {}), true);
+  assert.equal(evaluate("'AUTO' != 'auto'", {}), false);
+});
+
+test("contains() is substring on a string and exact-item on an array", () => {
+  assert.equal(evaluate("contains('[\"self-hosted\",\"x\"]', 'self-hosted')", {}), true);
+  assert.equal(evaluate("contains(inputs.r, 'self-hosted')", { r: ["self-hosted", "x"] }), true);
+  // Exact-item, NOT substring, once the haystack is an array.
+  assert.equal(evaluate("contains(inputs.r, 'self')", { r: ["self-hosted"] }), false);
+});
+
+test("startsWith() casts to string and is case-insensitive", () => {
+  assert.equal(evaluate("startsWith('[\"a\"]', '[')", {}), true);
+  assert.equal(evaluate("startsWith('ubuntu-latest', '[')", {}), false);
+  assert.equal(evaluate("startsWith('UBUNTU', 'ub')", {}), true);
+});
+
+test("format() substitutes positionally and unescapes doubled braces", () => {
+  assert.equal(evaluate("format('\"{0}\"', inputs.r)", { r: "my-runner" }), '"my-runner"');
+  assert.equal(evaluate("format('{{{0}}}', inputs.r)", { r: "x" }), "{x}");
+});
+
+test("fromJSON() parses arrays and scalars", () => {
+  assert.deepEqual(evaluate("fromJSON('[\"self-hosted\",\"x\"]')", {}), ["self-hosted", "x"]);
+  assert.equal(evaluate("fromJSON('\"bare-label\"')", {}), "bare-label");
+});
+
+test("fromJSON() on malformed input THROWS — it does not yield null", () => {
+  // Load-bearing: in Actions a fromJSON parse failure fails the run. If it
+  // degraded to null here, a malformed `runner` would look like a clean
+  // fallback in the guard while hanging forever in production.
+  assert.throws(() => evaluate("fromJSON('[\"unterminated')", {}), /could not parse/);
+});
+
+test("`&&` / `||` short-circuit, so an unreached branch is never evaluated", () => {
+  // The evaluator is lazy. Guarded workflow expressions must NOT rely on that
+  // (GitHub does not document its own behaviour here) — but modelling it
+  // faithfully keeps the guard honest about what it is asserting.
+  assert.equal(evaluate("false && fromJSON('nonsense') || 'safe'", {}), "safe");
+});
+
+test("an unknown input read is an error, not a silent undefined", () => {
+  assert.throws(() => evaluate("inputs.missing", {}), /not provided by the caller/);
+});