@mmerterden/multi-agent-pipeline 17.3.0 → 17.4.0

package/pipeline/schemas/review-file-exclusions.json

@@ -0,0 +1,137 @@
+{
+  "$comment": "Not a JSON Schema: the data the review file filter reads. Lives beside token-budget.json for the same reason - it is a budget-shaped decision the pipeline owns, versioned with the code that consumes it.",
+  "version": 1,
+  "patterns": [
+    {
+      "glob": "**/*.generated.*",
+      "reason": "generated file - review the generator, not its output"
+    },
+    {
+      "glob": "**/Generated/**",
+      "reason": "generated tree - review the generator, not its output"
+    },
+    {
+      "glob": "**/generated/**",
+      "reason": "generated tree - review the generator, not its output"
+    },
+    { "glob": "**/*.pb.go", "reason": "generated file - review the generator, not its output" },
+    { "glob": "**/*_pb2.py", "reason": "generated file - review the generator, not its output" },
+
+    {
+      "glob": "**/package-lock.json",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/yarn.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/pnpm-lock.yaml",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Package.resolved",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Podfile.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Gemfile.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/poetry.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/Cargo.lock",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+    {
+      "glob": "**/gradle.lockfile",
+      "reason": "lockfile - resolved by the package manager, not written by hand"
+    },
+
+    {
+      "glob": "**/__snapshots__/**",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+    {
+      "glob": "**/*.snap",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+    {
+      "glob": "**/__Snapshots__/**",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+    {
+      "glob": "**/ReferenceImages/**",
+      "reason": "recorded snapshot - the assertion is the test that records it"
+    },
+
+    {
+      "glob": "vendor/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+    {
+      "glob": "**/node_modules/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+    {
+      "glob": "Pods/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+    {
+      "glob": "**/third_party/**",
+      "reason": "vendored third-party source - not ours to change in this diff"
+    },
+
+    {
+      "glob": "**/*.min.js",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "**/*.min.css",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "**/*.map",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "dist/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "build/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": ".build/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+    {
+      "glob": "**/DerivedData/**",
+      "reason": "build output - unreadable by design, and the source is elsewhere in the diff"
+    },
+
+    { "glob": "**/*.png", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.jpg", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.jpeg", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.gif", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.webp", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.pdf", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.zip", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.ipa", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.apk", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.aab", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.mp4", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.mov", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.ttf", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.otf", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.woff", "reason": "binary asset - a text reviewer cannot read it" },
+    { "glob": "**/*.woff2", "reason": "binary asset - a text reviewer cannot read it" }
+  ]
+}

package/pipeline/schemas/reviewer-output.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/reviewer-output.schema.json",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "title": "Multi-Agent Pipeline  -  Phase 4 reviewer output",
   "description": "Contract for a single code-reviewer subagent's JSON output in Phase 4 Step 2. Every host dispatches 3 parallel reviewers; the middle slot is CLI-aware: Claude Code (Fable, Opus, Sonnet); Copilot CLI (Opus, GPT-5.4, Sonnet); Codex CLI dispatches 3 (gpt-5.6 at xhigh, gpt-5.4, gpt-5.6 at medium). Every reviewer must return an object matching this shape before Opus triage merges them. v1.1.0 adds the rule-ID conformance checklist: when the orchestrator supplies a ${CRITERIA} block (Phase 4 Step 1.78), the reviewer must return one conformance row per selected rule ID. Findings alone cannot answer 'was this applied completely' - a reviewer that opened nothing returns the same empty findings array as one that checked everything. v1.2.0 adds the optional per-finding fingerprint (Phase 4 Step 2.1): the stable id a finding keeps across review rounds.",
   "type": "object",
@@ -55,6 +55,32 @@
           }
         }
       }
+    },
+    "fileCoverage": {
+      "type": "array",
+      "description": "One row per file in the supplied review denominator, and none outside it. Required whenever a denominator was supplied. The set is computed by review-file-filter.mjs and written to disk BEFORE the reviewer runs, for the same reason selectedRules[] is: after seeing the diff, 'I did not look at that one' and 'there was nothing there' become the same sentence. An empty findings[] from a reviewer that skipped nine of ten files is not a clean review.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "verdict"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Must appear in the supplied denominator, byte for byte."
+          },
+          "verdict": {
+            "type": "string",
+            "enum": ["reviewed", "skipped"],
+            "description": "reviewed = read in full. skipped = not read, and the reason says why. There is deliberately no 'partial': a file read in part is read, and what was not understood belongs in a finding."
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 4,
+            "description": "Required when verdict is 'skipped'. Names why the file was not read (too large for the budget, truncated by the diff cap, binary content). 'Not relevant' is a review decision, not a skip reason."
+          }
+        }
+      }
     }
   },
   "$defs": {

package/pipeline/scripts/diff-risk-score.mjs

@@ -40,6 +40,7 @@
 
 import { readFileSync, existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
+import { unquoteGitPath, unquotePathIfNeeded } from "./git-path.mjs";
 
 const argv = process.argv.slice(2);
 const flags = {};
@@ -171,42 +172,6 @@ const TEST_PATH_GLOBS = [
 const DIFF_GIT_QUOTED_RE = /^diff --git "a\/((?:[^"\\]|\\.)*)" "b\/((?:[^"\\]|\\.)*)"$/;
 const DIFF_GIT_UNQUOTED_RE = /^diff --git a\/(.+?) b\/(.+)$/;
 
-// Reverse git's C-style quoting: octal byte escapes (\NNN, one per raw byte -
-// a multi-byte UTF-8 character is several consecutive \NNN triplets) plus
-// the standard \\ \" \t \n \r escapes.
-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");
-}
-
-// `git diff --numstat` quotes a non-ASCII/unusual path the same C-style way
-// as the `diff --git` header line (e.g. `"\303\226deme.swift"`), just
-// without the surrounding "diff --git a/...b/..." context to detect it by.
-function unquotePathIfNeeded(s) {
-  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
-    return unquoteGitPath(s.slice(1, -1));
-  }
-  return s;
-}
-
 // Returns the b/-side path from a `diff --git` header line, or null if the
 // line isn't one. Handles both the quoted and unquoted forms.
 function matchDiffGitHeader(line) {

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();
+}