@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/symbol-existence-gate.mjs

@@ -0,0 +1,450 @@
+#!/usr/bin/env node
+/**
+ * symbol-existence-gate.mjs  -  every key, identifier and endpoint a change
+ * starts referencing has to exist somewhere the stack declares such things.
+ *
+ * A localization key, a string resource or an endpoint path is a reference to a
+ * declaration the model did not write and often cannot see. Invented ones
+ * compile (a string is a string) and fail at run time, on a screen nobody in an
+ * unattended run looks at. This reads the stack adapter's `referencePatterns`
+ * over the ADDED lines of the diff and looks each captured `ref` up in the
+ * adapter's `truthSources` for the same kind: generated key enums, strings.xml,
+ * i18n JSON, OpenAPI documents, generated endpoint files.
+ *
+ * Rules:
+ *   - Only added lines are read. An old reference is not this change's claim.
+ *   - A file that is itself a truth source of that kind holds declarations, not
+ *     references, and is skipped. So is a test file (adapter testFilePatterns).
+ *   - Truth sources are read at the head of the change, so a key added to
+ *     strings.xml in the same change exists.
+ *   - A kind with no truth-source file in the repo is not checked; when no kind
+ *     can be checked the verdict is not-applicable, never a failure. A gate that
+ *     fails for want of a file to read would fail every repo it does not know.
+ *
+ * Runs only while the quality gates are active (lib/unattended.mjs,
+ * gatesActive: MULTI_AGENT_UNATTENDED=1, or the run's state says autopilot).
+ * Otherwise it prints a not-applicable verdict and exits 0 without reading the
+ * repository.
+ *
+ * Usage:
+ *   node symbol-existence-gate.mjs --repo <dir> [--base <ref>] [--head <ref>]
+ *        [--stack <id>] [--state <agent-state.json>] [--json]
+ *
+ *   --base defaults to HEAD; without --head the working tree is the head, and
+ *   untracked files count as added.
+ *
+ * Exit: 0 pass or not-applicable · 1 a referenced symbol is missing · 2 usage
+ *
+ * @module pipeline/scripts/symbol-existence-gate
+ */
+
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { attendedVerdict } from "../lib/unattended.mjs";
+import { getAdapter, resolveStack, AdapterError } from "./_stack-adapter.mjs";
+import { globToRegExp } from "./glob-match.mjs";
+import { gateContext, recordQuietly } from "./gate-ledger.mjs";
+
+const GATE = "symbol-existence";
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+class UsageError extends Error {}
+
+function git(dir, args) {
+  const r = spawnSync("git", ["-C", dir, ...args], {
+    encoding: "utf8",
+    timeout: 60000,
+    maxBuffer: MAX_BUFFER,
+  });
+  return { ok: r.status === 0, out: r.stdout || "", err: (r.stderr || "").trim() };
+}
+
+// ---------------------------------------------------------------------------
+// Globs
+
+/** `a/{b,c}.x` -> [`a/b.x`, `a/c.x`]; glob-match.mjs has no brace expansion. */
+export function expandBraces(glob) {
+  const m = /\{([^{}]*)\}/.exec(glob);
+  if (!m) return [glob];
+  const head = glob.slice(0, m.index);
+  const tail = glob.slice(m.index + m[0].length);
+  return m[1].split(",").flatMap((alt) => expandBraces(`${head}${alt}${tail}`));
+}
+
+function globMatcher(globs) {
+  const res = (globs || []).flatMap(expandBraces).map(globToRegExp);
+  return (path) => res.some((re) => re.test(path));
+}
+
+// ---------------------------------------------------------------------------
+// Truth sources: what each file format declares
+
+function flattenJson(value, prefix, out) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return;
+  for (const [k, v] of Object.entries(value)) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    out.add(key);
+    flattenJson(v, key, out);
+  }
+}
+
+const IDENT_DECL =
+  /\b(?:case|let|var|func|enum|struct|class|protocol|typealias|val|fun|object|const|def|fn)\s+([A-Za-z_][A-Za-z0-9_]*)/g;
+const STRING_LITERAL = /"((?:[^"\\\n]|\\.)*)"|'((?:[^'\\\n]|\\.)*)'/g;
+
+/**
+ * What one truth-source file declares, split by how a reference may match it.
+ *
+ * `keys` are whole keys: a JSON / `.xcstrings` key by its full dotted path (a
+ * nested leaf is only reachable through its parents, so `title` under `login`
+ * is `login.title` and never `title`), and the flat keys of `strings.xml`,
+ * `.strings`, `.stringsdict`, `.properties`, `.po` and `.ftl`. A reference
+ * matches a key exactly.
+ *
+ * `idents` are the declared identifiers and string literals of any other file
+ * (a generated Swift key enum, an endpoints file) and YAML / TOML keys, which
+ * are read without their nesting. A dotted reference such as
+ * `L10n.Profile.header` exists when every segment is an identifier.
+ *
+ * @param {string} path
+ * @param {string} text
+ * @returns {{keys: Set<string>, idents: Set<string>}}
+ */
+export function declarationsIn(path, text) {
+  const keys = new Set();
+  const idents = new Set();
+  let out = keys;
+  const add = (re, group = 1) => {
+    for (const m of text.matchAll(re)) if (m[group]) out.add(m[group]);
+  };
+  const lower = path.toLowerCase();
+  if (lower.endsWith(".json") || lower.endsWith(".xcstrings")) {
+    try {
+      const doc = JSON.parse(text);
+      if (lower.endsWith(".xcstrings") && doc && typeof doc.strings === "object") {
+        for (const k of Object.keys(doc.strings)) keys.add(k);
+      } else {
+        flattenJson(doc, "", keys);
+        if (doc && typeof doc.paths === "object") {
+          for (const k of Object.keys(doc.paths)) keys.add(k);
+        }
+      }
+      return { keys, idents };
+    } catch {
+      /* not JSON after all: fall through to the generic reading */
+    }
+  }
+  if (lower.endsWith(".xml")) add(/\bname\s*=\s*"([^"]+)"/g);
+  else if (lower.endsWith(".strings")) add(/^\s*"((?:[^"\\]|\\.)*)"\s*=/gm);
+  else if (lower.endsWith(".stringsdict")) add(/<key>([^<]+)<\/key>/g);
+  else if (lower.endsWith(".properties")) add(/^\s*([^#!\s][^=:\s]*)\s*[=:]/gm);
+  else if (lower.endsWith(".po")) add(/^\s*msgid\s+"((?:[^"\\]|\\.)*)"/gm);
+  else if (lower.endsWith(".ftl")) add(/^([A-Za-z][A-Za-z0-9_-]*)\s*=/gm);
+  else if (/\.(ya?ml|toml)$/.test(lower)) {
+    out = idents;
+    add(/^\s*["']?([^\s"':#][^"':]*?)["']?\s*[:=]/gm);
+  } else {
+    out = idents;
+    add(IDENT_DECL);
+    for (const m of text.matchAll(STRING_LITERAL)) {
+      const v = m[1] ?? m[2];
+      if (v) idents.add(v);
+    }
+  }
+  return { keys, idents };
+}
+
+/**
+ * Every key and identifier one truth-source file declares, as one set.
+ *
+ * @param {string} path
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+export function declaredIn(path, text) {
+  const { keys, idents } = declarationsIn(path, text);
+  return new Set([...keys, ...idents]);
+}
+
+/** `/users/{id}`, `/users/:id`, `/users/${id}`, `/users/<id>` all read the same. */
+export function normalizeEndpoint(p) {
+  return String(p)
+    .split(/[?#]/)[0]
+    .replace(/\$\{[^}]*\}|\{[^}]*\}|<[^>]*>|:[A-Za-z_][A-Za-z0-9_]*/g, "{}")
+    .replace(/\/+$/, "")
+    .toLowerCase();
+}
+
+function endpointExists(ref, declared) {
+  const want = normalizeEndpoint(ref);
+  if (!want) return true;
+  for (const d of declared) {
+    if (!d.includes("/")) continue;
+    const have = normalizeEndpoint(d);
+    if (!have) continue;
+    if (have === want) return true;
+    // A client path is often relative to a base URL the contract spells out,
+    // and a contract path is often mounted under a prefix the client carries.
+    if (have.endsWith(want) && have[have.length - want.length - 1] === "/") return true;
+    if (want.endsWith(have) && want[want.length - have.length - 1] === "/") return true;
+  }
+  return false;
+}
+
+function keyExists(ref, { keys, idents }) {
+  const whole = (r) => keys.has(r) || idents.has(r);
+  if (whole(ref)) return true;
+  const colon = ref.indexOf(":");
+  if (colon > 0 && whole(ref.slice(colon + 1))) return true;
+  if (ref.includes(".")) return ref.split(".").every((seg) => seg && idents.has(seg));
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// The change
+
+function listFiles(dir, head) {
+  if (head) {
+    const r = git(dir, ["ls-tree", "-r", "--name-only", head]);
+    if (!r.ok) throw new UsageError(`cannot list ${head}: ${r.err}`);
+    return r.out.split("\n").filter(Boolean);
+  }
+  const tracked = git(dir, ["ls-files", "--cached"]);
+  const untracked = git(dir, ["ls-files", "--others", "--exclude-standard"]);
+  return [...new Set([...tracked.out.split("\n"), ...untracked.out.split("\n")].filter(Boolean))];
+}
+
+function readAt(dir, head, file) {
+  if (head) {
+    const r = git(dir, ["show", `${head}:${file}`]);
+    return r.ok ? r.out : null;
+  }
+  try {
+    return readFileSync(join(dir, file), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Added lines of base..head (or base..working tree), with their new line numbers.
+ *
+ * @returns {{file: string, line: number, text: string}[]}
+ */
+export function addedLines(dir, base, head) {
+  const range = head ? [base, head] : [base];
+  const d = git(dir, ["diff", "-U0", "--no-color", "--no-ext-diff", "--diff-filter=AMR", ...range]);
+  if (!d.ok) throw new UsageError(`git diff failed: ${d.err}`);
+  const out = [];
+  let file = null;
+  let line = 0;
+  for (const raw of d.out.split("\n")) {
+    if (raw.startsWith("+++ ")) {
+      file = raw === "+++ /dev/null" ? null : raw.slice(4).replace(/^b\//, "");
+      continue;
+    }
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
+    if (hunk) {
+      line = Number(hunk[1]);
+      continue;
+    }
+    if (!file || raw.startsWith("--- ")) continue;
+    if (raw.startsWith("+")) {
+      out.push({ file, line, text: raw.slice(1) });
+      line++;
+    }
+  }
+  if (!head) {
+    const untracked = git(dir, ["ls-files", "--others", "--exclude-standard"]);
+    for (const f of untracked.out.split("\n").filter(Boolean)) {
+      const text = readAt(dir, null, f);
+      if (text === null || text.includes("\u0000")) continue;
+      text.split("\n").forEach((t, i) => out.push({ file: f, line: i + 1, text: t }));
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The gate
+
+/**
+ * @param {{repo: string, base: string, head?: string|null, stack?: string|null}} opts
+ */
+export function checkSymbols({ repo, base, head = null, stack = null }) {
+  const ids = stack
+    ? [getAdapter(stack, { strict: true }).id]
+    : resolveStack(repo).adapters.map((a) => a.id);
+  const adapters = ids.map((id) => getAdapter(id)).filter((a) => a.applicable);
+  const result = {
+    gate: GATE,
+    verdict: "not-applicable",
+    stacks: adapters.map((a) => a.id),
+    base,
+    head: head || "worktree",
+    kinds: {},
+    checked: 0,
+    missing: [],
+  };
+  if (adapters.length === 0) {
+    result.reason = "no stack adapter describes this repository";
+    return result;
+  }
+
+  const files = listFiles(repo, head);
+  const kinds = new Map();
+  for (const a of adapters) {
+    const isTest = (p) => a.testFilePatterns.some((re) => new RegExp(re).test(p));
+    for (const [kind, patterns] of Object.entries(a.referencePatterns || {})) {
+      if (!patterns?.length) continue;
+      const globs = a.truthSources?.[kind] || [];
+      const k = kinds.get(kind) || { patterns: [], globs: [], tests: [] };
+      k.patterns.push(...patterns.map((p) => new RegExp(p, "g")));
+      k.globs.push(...globs);
+      k.tests.push(isTest);
+      kinds.set(kind, k);
+    }
+  }
+
+  const lines = addedLines(repo, base, head);
+  for (const [kind, k] of kinds) {
+    const isTruth = globMatcher(k.globs);
+    const truthFiles = files.filter(isTruth);
+    if (truthFiles.length === 0) {
+      result.kinds[kind] = {
+        truthFiles: 0,
+        checked: 0,
+        reason: "no truth source in the repository",
+      };
+      continue;
+    }
+    const split = { keys: new Set(), idents: new Set() };
+    for (const f of truthFiles) {
+      const text = readAt(repo, head, f);
+      if (text === null) continue;
+      const d = declarationsIn(f, text);
+      for (const k of d.keys) split.keys.add(k);
+      for (const k of d.idents) split.idents.add(k);
+    }
+    const declared = new Set([...split.keys, ...split.idents]);
+    let checked = 0;
+    const seen = new Set();
+    for (const l of lines) {
+      if (isTruth(l.file) || k.tests.some((t) => t(l.file))) continue;
+      for (const re of k.patterns) {
+        re.lastIndex = 0;
+        for (const m of l.text.matchAll(re)) {
+          const ref = m.groups?.ref;
+          if (!ref) continue;
+          const at = `${l.file}:${l.line}:${ref}`;
+          if (seen.has(at)) continue;
+          seen.add(at);
+          checked++;
+          const ok = kind === "endpoints" ? endpointExists(ref, declared) : keyExists(ref, split);
+          if (!ok) result.missing.push({ kind, ref, file: l.file, line: l.line });
+        }
+      }
+    }
+    result.kinds[kind] = { truthFiles: truthFiles.length, checked };
+    result.checked += checked;
+  }
+
+  const checkable = Object.values(result.kinds).some((k) => k.truthFiles > 0);
+  if (!checkable) {
+    result.reason = `no truth source for ${[...kinds.keys()].join(", ") || "any reference kind"} in the repository`;
+    return result;
+  }
+  result.verdict = result.missing.length ? "fail" : "pass";
+  return result;
+}
+
+function parseArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") {
+      opts.json = true;
+      continue;
+    }
+    if (!["--repo", "--base", "--head", "--stack", "--state"].includes(a)) {
+      throw new UsageError(`unexpected argument ${a}`);
+    }
+    const v = argv[++i];
+    if (v === undefined) throw new UsageError(`${a} needs a value`);
+    opts[a.slice(2)] = v;
+  }
+  return opts;
+}
+
+function print(opts, result) {
+  if (opts.json) {
+    writeFileSync(1, `${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  if (result.verdict === "fail") {
+    const lines = [
+      `symbol-existence: ${result.missing.length} of ${result.checked} reference(s) name nothing the truth sources declare:`,
+      ...result.missing.map((m) => `  ${m.file}:${m.line}  ${m.kind} ${m.ref}`),
+    ];
+    writeFileSync(1, `${lines.join("\n")}\n`);
+  } else {
+    writeFileSync(
+      1,
+      `symbol-existence: ${result.verdict}${result.reason ? ` (${result.reason})` : ` (${result.checked} reference(s) checked)`}\n`,
+    );
+  }
+}
+
+async function main(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    process.stderr.write(`symbol-existence-gate: ${err.message}\n`);
+    return 2;
+  }
+  const repo = opts.repo || process.cwd();
+  const ctx = gateContext({ statePath: opts.state || null, repo });
+  if (!ctx.active) {
+    print(opts, attendedVerdict(GATE));
+    return 0;
+  }
+  let result;
+  try {
+    result = checkSymbols({
+      repo,
+      base: opts.base || "HEAD",
+      head: opts.head || null,
+      stack: opts.stack || null,
+    });
+  } catch (err) {
+    if (err instanceof UsageError || err instanceof AdapterError) {
+      process.stderr.write(`symbol-existence-gate: ${err.message}\n`);
+      return 2;
+    }
+    throw err;
+  }
+  await recordQuietly(
+    GATE,
+    result.verdict,
+    {
+      checked: result.checked,
+      missing: result.missing.length,
+      stacks: result.stacks,
+      ...(result.reason ? { reason: result.reason } : {}),
+      ...(result.missing.length
+        ? { first: result.missing.slice(0, 5).map((m) => `${m.file}:${m.line} ${m.ref}`) }
+        : {}),
+    },
+    { repo, statePath: ctx.statePath },
+  );
+  print(opts, result);
+  return result.verdict === "fail" ? 1 : 0;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/pipeline/scripts/test-gap-scan.mjs

@@ -18,7 +18,14 @@
  *   --head <ref>       Head ref. Default: HEAD
  *   --diff <path>      Pre-computed diff file (skip git invocation)
  *   --root <path>      Repo root for git -C and tree scan. Default: cwd
- *   --stack <id>       ios | android | python | node. Required.
+ *   --stack <id>       ios | android | python | node. Required unless
+ *                      --stack-from is given.
+ *   --stack-from <agent-state.json>
+ *                      Take the stack from state.analysis.stack.primary:
+ *                      ios|swift -> ios, android|kotlin -> android, python,
+ *                      node|typescript|js -> node. Any other value has no gap
+ *                      rules: nothing is printed and the exit is 3. Phase 3
+ *                      uses it so the mapping is not a shell `case` in the doc.
  *   --scan-tree        When set, also scan repo for existing tests by symbol
  *                      name (slower; default off  -  diff-only is sufficient
  *                      for the common case).
@@ -33,6 +40,7 @@
  *   0  -  success (gap report rendered, possibly empty)
  *   1  -  git invocation or rule-load error
  *   2  -  empty diff (no changed sources for this stack)
+ *   3  -  --stack-from: the analysed stack has no gap rules (not applicable)
  *  64  -  usage error
  *
  * @module pipeline/scripts/test-gap-scan
@@ -66,7 +74,37 @@ const ROOT = flags.root || process.cwd();
 const HEAD = flags.head || "HEAD";
 let BASE = flags.base || null;
 const DIFF_FILE = flags.diff || null;
-const STACK = flags.stack;
+const STACK_ALIASES = {
+  ios: "ios",
+  swift: "ios",
+  android: "android",
+  kotlin: "android",
+  python: "python",
+  node: "node",
+  typescript: "node",
+  js: "node",
+};
+
+function stackFromState(path) {
+  let primary = null;
+  try {
+    primary = JSON.parse(readFileSync(path, "utf8"))?.analysis?.stack?.primary ?? null;
+  } catch (e) {
+    process.stderr.write(`test-gap-scan: cannot read ${path}: ${e.message}\n`);
+    process.exit(64);
+  }
+  const stack = STACK_ALIASES[String(primary ?? "").toLowerCase()];
+  if (!stack) {
+    process.stderr.write(
+      `test-gap-scan: not applicable - analysed stack '${primary ?? "unknown"}' has no gap rules\n`,
+    );
+    process.exit(3);
+  }
+  return stack;
+}
+
+const STACK =
+  typeof flags["stack-from"] === "string" ? stackFromState(flags["stack-from"]) : flags.stack;
 const SCAN_TREE = flags["scan-tree"] === true;
 const PRETTY = flags.json === true;
 const PROMOTE = flags["severity-promote"] === true;

package/pipeline/scripts/test-integrity-gate.mjs

@@ -22,18 +22,34 @@
  *
  * Usage:
  *   node diff-risk-score.mjs --base B --head H | node test-integrity-gate.mjs
- *   node test-integrity-gate.mjs --file risk.json [--json]
+ *   node test-integrity-gate.mjs --file risk.json [--json] [--out <path>]
+ *
+ * --out writes the JSON to <path> (parent directories created) instead of
+ * stdout, the empty result included, so Phase 3 always has a file to merge and
+ * the step needs no shell fallback.
  *
  * Output (stdout, JSON): { schemaVersion, count, findings: [ ... ] }
  * Exit 0 always (detection tool; severity is adjudicated downstream). Exit 1
  * only on a setup error (unreadable/invalid input is treated as "no findings").
  */
-import { readFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { runMain } from "../lib/fatal.mjs";
 
 const args = process.argv.slice(2);
 const fileFlag = args.indexOf("--file");
 const PRETTY = args.includes("--json");
+const outFlag = args.indexOf("--out");
+const OUT = outFlag !== -1 ? args[outFlag + 1] : null;
+
+function emit(text) {
+  if (!OUT) {
+    process.stdout.write(text);
+    return;
+  }
+  mkdirSync(dirname(OUT), { recursive: true });
+  writeFileSync(OUT, text);
+}
 
 function readInput() {
   try {
@@ -53,7 +69,7 @@ function main() {
     report = JSON.parse(raw);
   } catch {
     // No/invalid input -> fail OPEN (no findings). A gate bug must not wedge Phase 4.
-    process.stdout.write(JSON.stringify({ schemaVersion: "1.0.0", count: 0, findings: [] }));
+    emit(JSON.stringify({ schemaVersion: "1.0.0", count: 0, findings: [] }));
     return;
   }
 
@@ -84,7 +100,7 @@ function main() {
     });
   }
 
-  process.stdout.write(
+  emit(
     JSON.stringify(
       { schemaVersion: "1.0.0", count: findings.length, findings },
       null,