@mmerterden/multi-agent-pipeline 17.1.0 → 17.4.0

package/pipeline/scripts/gen-ref-toc.mjs

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+// gen-ref-toc.mjs  -  a table of contents on every long reference file.
+//
+// Anthropic's published Agent Skills guidance: "For reference files longer than
+// 100 lines, include a table of contents". The reason is the same one behind
+// the one-level-deep rule - an agent that reads a long file partially needs to
+// know from the top what is further down, and without that it answers from the
+// first screen and stops.
+//
+// Generated, never hand-written. Fifty-six files' worth of hand-maintained
+// contents lists would be wrong by the second edit, and a wrong ToC is worse
+// than none: it tells a reader a section exists where it does not.
+//
+// Section level is DERIVED, not assumed. These files are not consistent: some
+// open at `##` and section at `###` (keychain.md), others open at `###` and
+// section at `##` (phases/phase-3-dev.md). The rule is the shallowest heading
+// depth that occurs more than once - a depth used exactly once is a title, not
+// a section level.
+//
+// Not every long file is eligible, and the exclusion is measured rather than
+// preferred. A contents list helps a file that is OPENED AND SKIMMED. It is
+// pure cost on a file that is loaded whole by contract, because there is no
+// partial read for it to rescue - and those files are already at their limit:
+//
+//   the 8 phase docs   a ToC each puts 5 of 8 over their per-phase max and the
+//                      aggregate 1,533 tokens over 62,700
+//   rules.md           always loaded; 59,908 of a 60,000 byte ceiling, and a
+//                      ToC takes it to 60,997
+//   the analysis refs  mounted as one set per analysis run; 158,500 byte
+//                      ceiling, and the ToCs put them 2,298 over
+//
+// So the two published rules genuinely conflict there, and the ToC is the one
+// that loses: raising either ceiling to buy navigation nobody navigates is the
+// move this repo spent a release removing.
+//
+// The exclusion is DERIVED from those two budgets, never hand-listed. A
+// document entering or leaving a budget changes its ToC status by itself, which
+// is the difference between a rule and a list somebody has to remember.
+//
+// Usage:
+//   node gen-ref-toc.mjs            write/refresh every eligible file
+//   node gen-ref-toc.mjs --check    report drift, write nothing, exit 1 if any
+//   node gen-ref-toc.mjs --stats    byte cost, write nothing
+//   node gen-ref-toc.mjs --verify   every generated anchor resolves to a heading
+
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const REFS = join(ROOT, "pipeline", "multi-agent-refs");
+const MIN_LINES = 100;
+const MARK_OPEN = "<!-- toc -->";
+const MARK_CLOSE = "<!-- /toc -->";
+
+// Every file that some other gate already holds to a byte or token ceiling.
+function budgeted() {
+  const out = new Set();
+  const budget = JSON.parse(readFileSync(join(ROOT, "pipeline/schemas/token-budget.json"), "utf8"));
+  for (const phase of Object.keys(budget.phases)) {
+    out.add(join(REFS, "phases", `${phase}.md`));
+  }
+  // The always-loaded set, read out of the gate that owns it rather than copied.
+  const ctx = readFileSync(join(ROOT, "pipeline/scripts/smoke-context-budget.sh"), "utf8");
+  const block = ctx.match(/TRACKED="\n([\s\S]*?)"/);
+  if (block) {
+    for (const line of block[1].split("\n")) {
+      const t = line.trim();
+      if (t) out.add(join(ROOT, t));
+    }
+  }
+
+  // The analysis set, mounted whole per analysis run under its own ceiling. Same
+  // two globs that gate uses - `analysis/<name>.md` named by the analysis
+  // command, plus every analysis-template*.md.
+  const cmd = readFileSync(join(ROOT, "pipeline/commands/multi-agent/analysis/SKILL.md"), "utf8");
+  for (const m of cmd.matchAll(/analysis\/[a-z-]+\.md/g)) out.add(join(REFS, m[0]));
+  for (const e of readdirSync(REFS, { withFileTypes: true })) {
+    if (e.isFile() && /^analysis-template.*\.md$/.test(e.name)) out.add(join(REFS, e.name));
+  }
+  return out;
+}
+
+function walk(dir, out = []) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walk(p, out);
+    else if (e.name.endsWith(".md")) out.push(p);
+  }
+  return out;
+}
+
+// GitHub's anchor rule, which is what a `](#...)` link resolves against.
+function slug(text) {
+  return text
+    .toLowerCase()
+    .replace(/`/g, "")
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/[^\w\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-");
+}
+
+function sections(lines) {
+  const heads = [];
+  let fenced = false;
+  lines.forEach((l, i) => {
+    if (/^\s*```/.test(l)) fenced = !fenced;
+    if (fenced) return;
+    const m = l.match(/^(#{1,6})\s+(.*\S)\s*$/);
+    if (m) heads.push({ depth: m[1].length, text: m[2], line: i });
+  });
+  if (!heads.length) return { level: 0, heads: [] };
+  const counts = {};
+  for (const h of heads) counts[h.depth] = (counts[h.depth] || 0) + 1;
+  const depths = Object.keys(counts)
+    .map(Number)
+    .sort((a, b) => a - b);
+  // The shallowest depth used more than once. A depth used exactly once is the
+  // document's title and listing it as the only entry is a ToC of one.
+  const level = depths.find((d) => counts[d] > 1) ?? depths[depths.length - 1];
+  return { level, heads: heads.filter((h) => h.depth === level) };
+}
+
+function render(heads) {
+  const seen = new Map();
+  const rows = heads.map((h) => {
+    let a = slug(h.text);
+    const n = (seen.get(a) || 0) + 1;
+    seen.set(a, n);
+    if (n > 1) a = `${a}-${n - 1}`;
+    return `- [${h.text.replace(/\|/g, "\\|")}](#${a})`;
+  });
+  return [MARK_OPEN, ...rows, MARK_CLOSE].join("\n");
+}
+
+// After the frontmatter and after the first heading, so the reader sees what the
+// file IS before a list of what is in it.
+function insertionPoint(lines) {
+  let i = 0;
+  if (lines[0] === "---") {
+    i = 1;
+    while (i < lines.length && lines[i] !== "---") i += 1;
+    i += 1;
+  }
+  for (let j = i; j < lines.length; j += 1) {
+    if (/^#{1,6}\s/.test(lines[j])) return j + 1;
+  }
+  return i;
+}
+
+const BUDGETED = budgeted();
+const excluded = [];
+const files = walk(REFS)
+  .filter((f) => readFileSync(f, "utf8").split("\n").length - 1 > MIN_LINES)
+  .filter((f) => {
+    if (!BUDGETED.has(f)) return true;
+    excluded.push(relative(ROOT, f));
+    return false;
+  })
+  .sort();
+
+// Does every `](#anchor)` in a generated block name a heading that exists in the
+// same file? --check cannot answer that: it compares the file against THIS
+// script's output, so a wrong slug rule agrees with itself. This validates the
+// rule against the real headings instead, and it lives here so there is one
+// definition of `slug`, not a second copy inside a gate.
+if (process.argv.includes("--verify")) {
+  let total = 0;
+  const bad = [];
+  for (const f of walk(REFS)) {
+    const raw = readFileSync(f, "utf8");
+    if (!raw.includes(MARK_OPEN)) continue;
+    const lines = raw.split("\n");
+    const seen = new Map();
+    const anchors = new Set();
+    let fenced = false;
+    for (const l of lines) {
+      if (/^\s*```/.test(l)) fenced = !fenced;
+      if (fenced) continue;
+      const m = l.match(/^#{1,6}\s+(.*\S)\s*$/);
+      if (!m) continue;
+      let a = slug(m[1]);
+      const n = (seen.get(a) || 0) + 1;
+      seen.set(a, n);
+      if (n > 1) a = `${a}-${n - 1}`;
+      anchors.add(a);
+    }
+    const s0 = lines.indexOf(MARK_OPEN);
+    const e0 = lines.indexOf(MARK_CLOSE, s0);
+    for (const l of lines.slice(s0 + 1, e0)) {
+      const m = l.match(/\]\(#(.+)\)\s*$/);
+      if (!m) continue;
+      total += 1;
+      if (!anchors.has(m[1])) bad.push(`${relative(ROOT, f)} -> #${m[1]}`);
+    }
+  }
+  if (total === 0) {
+    console.log("gen-ref-toc: no anchors found at all - the generator produced nothing");
+    process.exit(1);
+  }
+  if (bad.length) {
+    console.log(`gen-ref-toc: ${bad.length} of ${total} anchor(s) point at no heading:`);
+    for (const b of bad.slice(0, 10)) console.log(`  ${b}`);
+    process.exit(1);
+  }
+  console.log(`gen-ref-toc: ${total} anchors, all resolve to a heading in their own file`);
+  process.exit(0);
+}
+
+const mode = process.argv.includes("--check")
+  ? "check"
+  : process.argv.includes("--stats")
+    ? "stats"
+    : "write";
+
+const drifted = [];
+const skipped = [];
+let added = 0;
+
+for (const f of files) {
+  const raw = readFileSync(f, "utf8");
+  const rel = relative(ROOT, f);
+  const lines = raw.split("\n");
+  const { heads } = sections(lines);
+  // Fewer than three sections is a file that does not need a map of itself.
+  if (heads.length < 3) {
+    skipped.push(`${rel} (${heads.length} section(s))`);
+    continue;
+  }
+  const block = render(heads);
+
+  const start = lines.indexOf(MARK_OPEN);
+  let next;
+  if (start !== -1) {
+    const end = lines.indexOf(MARK_CLOSE, start);
+    if (end === -1) {
+      drifted.push(`${rel}: ${MARK_OPEN} with no ${MARK_CLOSE}`);
+      continue;
+    }
+    const current = lines.slice(start, end + 1).join("\n");
+    if (current === block) continue;
+    next = [...lines.slice(0, start), ...block.split("\n"), ...lines.slice(end + 1)];
+    drifted.push(`${rel}: contents no longer match the headings`);
+  } else {
+    const at = insertionPoint(lines);
+    next = [...lines.slice(0, at), "", ...block.split("\n"), ...lines.slice(at)];
+    drifted.push(`${rel}: no table of contents`);
+  }
+  const out = next.join("\n");
+  added += out.length - raw.length;
+  if (mode === "write") writeFileSync(f, out);
+}
+
+if (mode === "stats") {
+  console.log(`eligible: ${files.length} ref files over ${MIN_LINES} lines`);
+  console.log(`excluded as loaded-whole-by-contract: ${excluded.length}`);
+  console.log(`skipped (under 3 sections): ${skipped.length}`);
+  console.log(
+    `would add: ${added} bytes total, ~${Math.round(added / 4)} tokens if every one were read`,
+  );
+  process.exit(0);
+}
+
+if (mode === "check") {
+  if (drifted.length === 0) {
+    console.log(`gen-ref-toc: ${files.length} long ref(s) carry a current table of contents`);
+    process.exit(0);
+  }
+  console.log(
+    `gen-ref-toc: ${drifted.length} file(s) need \`node pipeline/scripts/gen-ref-toc.mjs\`:`,
+  );
+  for (const d of drifted) console.log(`  ${d}`);
+  process.exit(1);
+}
+
+console.log(
+  `gen-ref-toc: ${drifted.length} file(s) updated, ${skipped.length} skipped, ${added} bytes added`,
+);

package/pipeline/scripts/git-path.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+/**
+ * @file git-path.mjs  -  undo git's C-style path quoting, in one place.
+ *
+ * With `core.quotePath` on (the default), git quotes any path containing a
+ * non-ASCII byte or an unusual character: a Turkish filename comes out of
+ * `diff --name-only` as `"G\303\266r\303\274n\303\274m.swift"`, quotes and all.
+ * A consumer that treats that string as a path sees a name that matches no
+ * glob, resolves to no file, and simply DISAPPEARS from whatever it was
+ * feeding - which is how every non-ASCII-named file was once silently dropped
+ * from risk scoring.
+ *
+ * Shared rather than copied because the failure is silent on every axis that
+ * uses it: a dropped file is not an error anywhere, it is an absence.
+ *
+ * @module pipeline/scripts/git-path
+ */
+
+/**
+ * Reverse git's C-style quoting: octal byte escapes (`\NNN`, one per raw byte,
+ * so a multi-byte UTF-8 character is several consecutive triplets) plus the
+ * standard `\\ \" \t \n \r` escapes.
+ *
+ * @param {string} s the INNER text, without the surrounding quotes
+ * @returns {string}
+ */
+export function unquoteGitPath(s) {
+  const bytes = [];
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "\\") {
+      const octal = s.slice(i + 1, i + 4);
+      if (/^[0-7]{3}$/.test(octal)) {
+        bytes.push(parseInt(octal, 8));
+        i += 3;
+        continue;
+      }
+      const simple = { "\\": 92, '"': 34, t: 9, n: 10, r: 13 };
+      const next = s[i + 1];
+      if (next in simple) {
+        bytes.push(simple[next]);
+        i += 1;
+        continue;
+      }
+    }
+    bytes.push(s.charCodeAt(i));
+  }
+  return Buffer.from(bytes).toString("utf-8");
+}
+
+/**
+ * Unquote a path only if git actually quoted it. An unquoted path is returned
+ * untouched, so this is safe to run over every line of any git path listing.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function unquotePathIfNeeded(s) {
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
+    return unquoteGitPath(s.slice(1, -1));
+  }
+  return s;
+}

package/pipeline/scripts/glob-match.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * @file glob-match.mjs  -  the one glob matcher, so two denominators cannot drift.
+ *
+ * `skill-conformance.mjs` matches a changed file against a rule's declared
+ * scope; `review-file-filter.mjs` matches the same file against the exclusion
+ * list. Those two answers decide what is reviewed and what it was measured
+ * against, so a second implementation is not a duplication of code but a
+ * duplication of MEANING: the day they disagree, a file is excluded from the
+ * review and still counted in the conformance denominator, and nothing says so.
+ *
+ * Deliberately minimal - the `**\/x`, `*.ext`, `dir/**` shapes the pattern
+ * lists actually use. No brace expansion, no extglob, no character classes: a
+ * pattern that needs them belongs in a list nobody can read either.
+ *
+ * @module pipeline/scripts/glob-match
+ */
+
+/**
+ * Compile a glob to an anchored RegExp.
+ *
+ * `**` followed by `/` matches zero or more path segments, so `**\/x` matches
+ * a bare `x` at the root as well as `a/b/x`. A bare `*` never crosses `/`.
+ *
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+export function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        if (glob[i + 2] === "/") {
+          re += "(?:.*/)?";
+          i += 2;
+        } else {
+          re += ".*";
+          i += 1;
+        }
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") re += "[^/]";
+    else re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * True when `file` matches any glob, or when the list is empty - an unscoped
+ * rule applies everywhere.
+ *
+ * @param {string} file
+ * @param {string[]} globs
+ * @returns {boolean}
+ */
+export function matchesAnyGlob(file, globs) {
+  if (!globs || globs.length === 0) return true;
+  return globs.some((g) => globToRegExp(g).test(file));
+}

package/pipeline/scripts/graph-mermaid.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+/**
+ * @file graph-mermaid.mjs  -  draw the blast radius that was already measured.
+ *
+ * The PR body's Impact Analysis asks, in part 3, which symbols and files a
+ * change reaches. `graph-affected.mjs` answers exactly that question
+ * deterministically, from a graph pinned to a commit - and until now the answer
+ * was re-typed as prose by a model while the measurement sat unused on disk.
+ *
+ * This emits the same answer as a mermaid `flowchart`. Mermaid because GitHub
+ * renders it natively in pull requests, issues and markdown files, so the
+ * diagram costs no renderer, no plugin and no dependency: the output is text.
+ * Jira is deliberately NOT a target - its wiki renderer turns a mermaid fence
+ * into a literal `{code:mermaid}` block, so a diagram there is worse than the
+ * prose it replaced.
+ *
+ * Traversal is not reimplemented here. `findByName` and `affected` come from
+ * graph-affected.mjs, so the diagram and the text report can never disagree
+ * about what is affected - they are the same call.
+ *
+ * Inputs:
+ *   "<symbol>"          Symbol name; comma-separate for several seeds. Required.
+ *   --graph <path>      Graph file. Default: the same default graph-query uses
+ *   --depth N           Reverse traversal depth. Default: 2
+ *   --kind K[,K]        Restrict to these edge kinds
+ *   --max-nodes N       Node ceiling. Default: 25
+ *   --direction LR|TD   Flowchart direction. Default: LR
+ *   --json              Emit {mermaid, nodes, edges, truncated, baseCommit}
+ *
+ * Exit codes (same family as graph-affected.mjs, on purpose):
+ *   0   -  drawn, possibly with nothing affected
+ *   1   -  graph missing or unreadable; the reason goes to stderr and the
+ *          caller records it as a gap rather than inventing a diagram
+ *   64  -  usage error
+ *
+ * @module pipeline/scripts/graph-mermaid
+ */
+
+import { resolve } from "node:path";
+import { parseFlags } from "./graph-build.mjs";
+import { loadGraph, defaultGraphPath } from "./graph-query.mjs";
+import { findByName, affected } from "./graph-affected.mjs";
+
+const DEFAULT_MAX_NODES = 25;
+
+/**
+ * A mermaid-safe identifier for a graph node id.
+ *
+ * Graph ids carry `:`, `/`, `#` and `.`, all of which mermaid reads as syntax.
+ * Rather than escaping them, ids are positional (`n0`, `n1`) and the real name
+ * travels in the quoted label, where mermaid only needs `"` handled.
+ *
+ * @param {number} i
+ * @returns {string}
+ */
+export function nodeKey(i) {
+  return `n${i}`;
+}
+
+/**
+ * The label a reader sees. Paths are shown basename-first because a column of
+ * identical directory prefixes is the fastest way to make a diagram unreadable,
+ * and the full path is already in the text report beside it.
+ *
+ * @param {object} node
+ * @returns {string}
+ */
+export function label(node) {
+  // A symbol is known by its name; a file by its basename. Using the path for
+  // both printed the DEFINING FILE as the label of every symbol, which drew a
+  // diagram where the thing that changed appeared to be something else.
+  const base =
+    node.kind === "file" || node.kind === "module"
+      ? (node.path || node.name || node.id).split("/").pop()
+      : node.name || node.id;
+  const where = node.kind !== "file" && node.path ? ` - ${node.path.split("/").pop()}` : "";
+  return `${base}${where}`.replace(/"/g, "'");
+}
+
+/**
+ * Build the diagram model: which nodes survive the ceiling, which edges connect
+ * them, and how many were left out.
+ *
+ * Over the ceiling the highest-degree nodes are kept, because they are the ones
+ * a reviewer most needs to see, and the count of the rest is REPORTED. Silently
+ * dropping them would draw a small blast radius for a large change, which is
+ * the one failure a diagram must not have.
+ *
+ * @param {object} graph
+ * @param {{id: string, dist: number}[]} hits
+ * @param {string[]} seedIds
+ * @param {number} maxNodes
+ * @returns {{nodes: object[], edges: object[], truncated: number}}
+ */
+export function buildModel(graph, hits, seedIds, maxNodes) {
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const wanted = new Map();
+
+  for (const id of seedIds) {
+    const n = byId.get(id);
+    if (n) wanted.set(id, { node: n, dist: 0 });
+  }
+  for (const h of hits) {
+    if (wanted.has(h.id)) continue;
+    const n = byId.get(h.id);
+    if (n) wanted.set(h.id, { node: n, dist: h.dist });
+  }
+
+  // Seeds are never dropped - a diagram without the thing that changed is not a
+  // smaller diagram, it is a different question. Order the rest by distance
+  // first (near blast radius before far), then by degree, then by id so the
+  // output is byte-stable across runs.
+  const seeds = [...wanted.values()].filter((e) => e.dist === 0);
+  const rest = [...wanted.values()]
+    .filter((e) => e.dist !== 0)
+    .sort(
+      (a, b) =>
+        a.dist - b.dist ||
+        (b.node.degree || 0) - (a.node.degree || 0) ||
+        a.node.id.localeCompare(b.node.id),
+    );
+
+  const room = Math.max(0, maxNodes - seeds.length);
+  const kept = [...seeds, ...rest.slice(0, room)];
+  const truncated = rest.length - Math.min(rest.length, room);
+
+  const keptIds = new Set(kept.map((e) => e.node.id));
+  const edges = graph.edges
+    .filter((e) => keptIds.has(e.from) && keptIds.has(e.to))
+    .sort(
+      (a, b) =>
+        a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.kind.localeCompare(b.kind),
+    );
+
+  return { nodes: kept.map((e) => ({ ...e.node, dist: e.dist })), edges, truncated };
+}
+
+/**
+ * Render the model as mermaid text.
+ *
+ * @param {{nodes: object[], edges: object[], truncated: number}} model
+ * @param {{direction?: string, baseCommit?: string}} [opts]
+ * @returns {string}
+ */
+export function render(model, opts = {}) {
+  const dir = opts.direction || "LR";
+  const idx = new Map(model.nodes.map((n, i) => [n.id, nodeKey(i)]));
+  const L = [`flowchart ${dir}`];
+
+  for (const n of model.nodes) {
+    const key = idx.get(n.id);
+    // Seeds are the thing that changed; everything else is downstream of it.
+    L.push(n.dist === 0 ? `  ${key}["${label(n)}"]` : `  ${key}("${label(n)}")`);
+  }
+  for (const e of model.edges) {
+    L.push(`  ${idx.get(e.from)} -->|${e.kind}| ${idx.get(e.to)}`);
+  }
+  if (model.truncated > 0) {
+    L.push(`  more["+${model.truncated} more, not drawn"]`);
+  }
+  return L.join("\n");
+}
+
+function main() {
+  // Same argument contract as graph-affected.mjs, deliberately: positional parts
+  // are one name. Several seeds are comma-separated inside that name, so a PR
+  // touching three symbols draws one diagram rather than three.
+  const { flags, positional } = parseFlags(process.argv.slice(2));
+  const name = positional.join(" ").trim();
+  if (!name) {
+    console.error('graph-mermaid: a symbol name is required, e.g. graph-mermaid "Flight"');
+    process.exit(64);
+  }
+  const symbols = name
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  const graphPath = flags.graph && flags.graph !== true ? resolve(flags.graph) : defaultGraphPath();
+  let graph;
+  try {
+    graph = loadGraph(graphPath);
+  } catch {
+    // Not an error to shout about: a repo with no graph yet simply has no
+    // diagram, and the caller records the reason instead of drawing nothing and
+    // calling it empty.
+    console.error(`graph-mermaid: no code graph at ${graphPath} - run /multi-agent:graph first`);
+    process.exit(1);
+  }
+
+  const depth = Number(flags.depth && flags.depth !== true ? flags.depth : 2);
+  // A Set, not an array: `affected` calls `kinds.has(...)`, and an array there
+  // silently matches nothing rather than failing.
+  const kinds = flags.kind && flags.kind !== true ? new Set(String(flags.kind).split(",")) : null;
+  const maxNodes = Number(
+    flags["max-nodes"] && flags["max-nodes"] !== true ? flags["max-nodes"] : DEFAULT_MAX_NODES,
+  );
+  const direction = flags.direction === "TD" ? "TD" : "LR";
+
+  const seedNodes = symbols.flatMap((s) => findByName(graph, s));
+  if (seedNodes.length === 0) {
+    console.error(`graph-mermaid: no node named ${symbols.join(", ")} in ${graphPath}`);
+    process.exit(1);
+  }
+  // `affected` takes node OBJECTS, not ids - it reads `n.id` off each seed.
+  // Passing ids made every traversal start from `undefined` and return nothing,
+  // which looks exactly like "nothing depends on this".
+  const seen = new Set();
+  const seeds = seedNodes.filter((n) => !seen.has(n.id) && seen.add(n.id));
+  const hits = affected({ graph, seeds, depth, kinds });
+  const model = buildModel(
+    graph,
+    hits,
+    seeds.map((n) => n.id),
+    maxNodes,
+  );
+  const mermaid = render(model, { direction });
+
+  if (flags.json) {
+    console.log(
+      JSON.stringify(
+        {
+          mermaid,
+          nodes: model.nodes.map((n) => n.id),
+          edges: model.edges.map((e) => ({ from: e.from, to: e.to, kind: e.kind })),
+          truncated: model.truncated,
+          baseCommit: graph.baseCommit || null,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  console.log("```mermaid");
+  console.log(mermaid);
+  console.log("```");
+  // The pin, printed beside the diagram rather than inside it: a graph built at
+  // an older commit draws an older blast radius, and a reader who cannot see
+  // which commit it came from has no way to notice.
+  if (graph.baseCommit) {
+    console.log("");
+    console.log(`_Graph at \`${String(graph.baseCommit).slice(0, 12)}\`._`);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}