@mmerterden/multi-agent-pipeline 20.21.0 → 20.23.0

package/pipeline/scripts/graph-affected.mjs

@@ -9,7 +9,14 @@
  * radius of a change rather than its neighbourhood.
  *
  * Inputs:
- *   "<symbol>"       Symbol name, exact or case-insensitive. Required.
+ *   "<symbol>"       Symbol name, exact or case-insensitive. Required unless
+ *                    --diff or --diff-file is given.
+ *   --diff <spec>    Seed from a change instead: `<base>` (working tree against
+ *                    base) or `<base>..<head>`. Hunks map onto the innermost
+ *                    declarations they touch, read on the side of the diff
+ *                    the graph was built from (_diff-impact.mjs graphSide).
+ *   --diff-file <p>  The same, from a saved unified diff.
+ *   --root <path>    Repo for --diff. Default: the root recorded in the graph
  *   --graph <path>   Graph file. Default: ~/.claude/knowledge/<cwd name>/code-graph.json
  *   --depth N        Reverse traversal depth. Default: 2
  *   --kind K         Restrict to one edge kind (repeatable via comma)
@@ -24,8 +31,16 @@
  */
 
 import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
 import { parseFlags } from "./graph-build.mjs";
 import { loadGraph, defaultGraphPath } from "./graph-query.mjs";
+import {
+  parseHunkRanges,
+  changedSymbols,
+  graphFreshness,
+  graphSide,
+  diffFor,
+} from "./_diff-impact.mjs";
 
 /**
  * Nodes whose name matches, preferring an exact hit.
@@ -62,37 +77,156 @@ export function incoming(graph, kinds = null) {
 }
 
 /**
- * Walk backwards from each seed.
+ * Walk backwards from each seed, over files.
+ *
+ * Dependents are files: a file depends on a target when it references a
+ * symbol or imports a file. The walk continues through what a dependent file
+ * itself declares, because the next ring depends on those declarations, not on
+ * the file node - references point from files to symbols, so a walk that only
+ * followed a file's own incoming edges would stop after one ring. `defines`
+ * is never a dependency, and the files that define the seeds are never
+ * reported as their own dependents.
  *
  * @param {object} params
+ * @param {object} params.graph
+ * @param {object[]} params.seeds - symbol or file nodes
+ * @param {number} params.depth
+ * @param {Set<string>|null} [params.kinds] - dependency edge kinds to follow
  * @returns {Array<{id: string, dist: number, kind: string, node: object}>}
  */
-export function affected({ graph, seeds, depth, kinds }) {
+export function affected({ graph, seeds, depth, kinds = null }) {
   const byId = new Map(graph.nodes.map((n) => [n.id, n]));
   const adj = incoming(graph, kinds);
-  const seen = new Set(seeds.map((n) => n.id));
+  const declares = new Map();
+  const definer = new Map();
+  for (const e of graph.edges) {
+    if (e.kind !== "defines") continue;
+    if (!declares.has(e.from)) declares.set(e.from, []);
+    declares.get(e.from).push(e.to);
+    definer.set(e.to, e.from);
+  }
+  const expand = (node) =>
+    node.kind === "file"
+      ? [node.id, ...(declares.get(node.id) || [])]
+      : [node.id, ...(definer.has(node.id) ? [definer.get(node.id)] : [])];
+
+  const seedFiles = new Set(
+    seeds.map((n) => (n.kind === "file" ? n.id : definer.get(n.id))).filter(Boolean),
+  );
+  const walked = new Set();
+  let frontier = [];
+  for (const seed of seeds)
+    for (const id of expand(seed)) if (!walked.has(id)) walked.add(id) && frontier.push(id);
+
+  const reported = new Set();
   const out = [];
-  const queue = seeds.map((n) => ({ id: n.id, dist: 0, kind: "seed" }));
-
-  while (queue.length) {
-    const cur = queue.shift();
-    if (cur.dist > 0) out.push({ ...cur, node: byId.get(cur.id) });
-    if (cur.dist >= depth) continue;
-    for (const dep of adj.get(cur.id) || []) {
-      if (seen.has(dep.id)) continue;
-      seen.add(dep.id);
-      queue.push({ id: dep.id, dist: cur.dist + 1, kind: dep.kind });
+  for (let dist = 1; dist <= depth && frontier.length; dist++) {
+    const next = [];
+    for (const target of frontier) {
+      for (const dep of adj.get(target) || []) {
+        if (dep.kind === "defines" || seedFiles.has(dep.id) || reported.has(dep.id)) continue;
+        const node = byId.get(dep.id);
+        if (!node) continue;
+        reported.add(dep.id);
+        out.push({ id: dep.id, dist, kind: dep.kind, node });
+        for (const id of expand(node)) if (!walked.has(id)) walked.add(id) && next.push(id);
+      }
     }
+    frontier = next;
   }
   return out;
 }
 
+function printJson(obj) {
+  process.stdout.write(JSON.stringify(obj, null, 2) + "\n");
+}
+
+function hitRows(hits) {
+  return hits.map((h) => ({
+    id: h.id,
+    dist: h.dist,
+    edgeKind: h.kind,
+    path: h.node?.path || null,
+  }));
+}
+
+function freshnessLine(f) {
+  if (!f.stale) return "graph: current";
+  const parts = [];
+  if (f.commitMoved)
+    parts.push(
+      `built at ${String(f.baseCommit).slice(0, 12)}, HEAD is ${String(f.head).slice(0, 12)}`,
+    );
+  if (f.changedFiles.length) parts.push(`${f.changedFiles.length} file(s) edited since the build`);
+  if (f.removedFiles.length) parts.push(`${f.removedFiles.length} file(s) removed`);
+  return `graph: STALE (${parts.join("; ")}) - rebuild with graph-build.mjs for a current answer`;
+}
+
+function runDiff(flags, graph, depth, kinds) {
+  const root = flags.root && flags.root !== true ? resolve(flags.root) : graph.root;
+  let text;
+  if (flags["diff-file"] && flags["diff-file"] !== true) {
+    text = readFileSync(resolve(flags["diff-file"]), "utf8");
+  } else {
+    text = diffFor(root, flags.diff);
+  }
+  const freshness = graphFreshness(graph, { root });
+  const range = flags["diff-file"] && flags["diff-file"] !== true ? undefined : flags.diff;
+  const side = graphSide(graph, { root, range });
+  const mapped = changedSymbols(graph, parseHunkRanges(text, side));
+  const hits = affected({ graph, seeds: mapped.seeds, depth, kinds });
+  const result = {
+    mode: "diff",
+    diff: flags["diff-file"] && flags["diff-file"] !== true ? flags["diff-file"] : flags.diff,
+    changedSymbols: mapped.changed.map((c) => ({
+      name: c.name,
+      path: c.path,
+      line: c.line,
+      endLine: c.endLine,
+    })),
+    seeds: mapped.seeds.map((s) => s.id),
+    fileLevel: mapped.fileLevel,
+    notIndexed: mapped.notIndexed,
+    affected: hitRows(hits),
+    side,
+    freshness,
+  };
+  if (flags.json === true) return printJson(result);
+
+  process.stdout.write(`# affected by diff ${result.diff}\n\n`);
+  for (const c of result.changedSymbols)
+    process.stdout.write(`* ${c.name} ${c.path}:${c.line}-${c.endLine}\n`);
+  for (const p of result.fileLevel)
+    process.stdout.write(`* ${p} (whole file: graph has no spans, rebuild for symbol level)\n`);
+  const files = new Set();
+  process.stdout.write("\n");
+  for (const hit of hits) {
+    if (hit.node?.path) files.add(hit.node.path);
+    process.stdout.write(
+      `${" ".repeat(hit.dist)}- ${hit.node?.name || hit.id} [${hit.kind}] ${hit.node?.path || "-"}\n`,
+    );
+  }
+  process.stdout.write(`\n${hits.length} dependents across ${files.size} files\n`);
+  if (result.notIndexed.length)
+    process.stdout.write(`not in the graph: ${result.notIndexed.join(", ")}\n`);
+  process.stdout.write(`${freshnessLine(freshness)}\n`);
+}
+
 function main() {
   const { flags, positional } = parseFlags(process.argv.slice(2));
   const name = positional.join(" ").trim();
-  if (!name) {
+  const diffMode = flags.diff !== undefined || flags["diff-file"] !== undefined;
+  if (diffMode) {
+    const spec = flags["diff-file"] !== undefined ? flags["diff-file"] : flags.diff;
+    if (spec === true || String(spec).startsWith("-")) {
+      process.stderr.write(
+        "graph-affected: --diff takes <base> or <base>..<head>; --diff-file takes a path\n",
+      );
+      process.exit(64);
+    }
+  } else if (!name) {
     process.stderr.write(
-      'graph-affected: a symbol name is required, e.g. graph-affected "Flight"\n',
+      'graph-affected: a symbol name is required, e.g. graph-affected "Flight", or --diff <base>\n',
     );
     process.exit(64);
   }
@@ -109,12 +243,20 @@ function main() {
   const depth = Number(flags.depth) > 0 ? Number(flags.depth) : 2;
   const kinds = flags.kind && flags.kind !== true ? new Set(String(flags.kind).split(",")) : null;
 
+  if (diffMode) {
+    try {
+      return runDiff(flags, graph, depth, kinds);
+    } catch (e) {
+      process.stderr.write(`graph-affected: ${e.message}\n`);
+      process.exit(1);
+    }
+  }
+
   const seeds = findByName(graph, name);
+  const freshness = graphFreshness(graph);
   if (seeds.length === 0) {
     if (flags.json === true) {
-      process.stdout.write(
-        JSON.stringify({ symbol: name, seeds: [], affected: [] }, null, 2) + "\n",
-      );
+      printJson({ symbol: name, seeds: [], affected: [], freshness });
     } else {
       process.stdout.write(`no node named '${name}'\n`);
     }
@@ -124,23 +266,12 @@ function main() {
   const hits = affected({ graph, seeds, depth, kinds });
 
   if (flags.json === true) {
-    process.stdout.write(
-      JSON.stringify(
-        {
-          symbol: name,
-          seeds: seeds.map((s) => s.id),
-          affected: hits.map((h) => ({
-            id: h.id,
-            dist: h.dist,
-            edgeKind: h.kind,
-            path: h.node?.path || null,
-          })),
-        },
-        null,
-        2,
-      ) + "\n",
-    );
-    return;
+    return printJson({
+      symbol: name,
+      seeds: seeds.map((s) => s.id),
+      affected: hitRows(hits),
+      freshness,
+    });
   }
 
   process.stdout.write(`# affected by ${name}\n\n`);
@@ -156,6 +287,7 @@ function main() {
     );
   }
   process.stdout.write(`\n${hits.length} dependents across ${files.size} files\n`);
+  process.stdout.write(`${freshnessLine(freshness)}\n`);
 }
 
 if (process.argv[1] && process.argv[1].endsWith("graph-affected.mjs")) main();

package/pipeline/scripts/graph-confirm.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+/**
+ * @file graph-confirm.mjs  -  a name-based blast radius, checked by a language server.
+ *
+ * The code graph joins files to declarations by name, so a dependent it lists
+ * may only share a name with the changed type, and a dependent behind an
+ * ambiguous name is missing. The toolkit's `code_references` answers the same
+ * question semantically when the project has an index. This merges the two
+ * without trusting either blindly:
+ *
+ *   confirmed  a direct dependent the server also found
+ *   name-only  a direct dependent a ready semantic index did not find
+ *   unchecked  a deeper ring the server did not name (it depends on an
+ *              intermediate declaration), or no answer could check it
+ *
+ * A deeper ring the server names directly is confirmed too.
+ *
+ * `lspOnly` lists files the server found that the graph did not. Only a result
+ * with `semantic: true` and `indexReady: true` confirms or demotes anything; a
+ * fallback answer or an index still building leaves every file unchecked,
+ * because "not found" from an unready index is not evidence.
+ *
+ * Inputs:
+ *   --affected <path>    graph-affected --json output
+ *   --references <path>  JSON array of code_references results, one per changed type
+ *   --root <path>        repository root the server's absolute paths are under
+ *
+ * Exit codes: 0 answered, 64 usage error.
+ *
+ * Zero runtime dependencies (ADR-0004).
+ *
+ * @module pipeline/scripts/graph-confirm
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+/**
+ * @param {{affected: Array<{path: string|null, dist: number}>}} affectedDoc
+ * @param {Array<{semantic?: boolean, indexReady?: boolean, results?: Array<{file: string}>}>} references
+ * @param {{root: string}} opts
+ */
+export function confirmImpact(affectedDoc, references, { root }) {
+  const usable = (references || []).filter(
+    (r) => r && r.semantic === true && r.indexReady === true,
+  );
+  const checked = usable.length > 0 && usable.length === (references || []).length;
+  const real = (p) => {
+    const abs = resolve(p);
+    try {
+      return realpathSync(abs);
+    } catch {
+      const parent = dirname(abs);
+      return parent === abs ? abs : join(real(parent), basename(abs));
+    }
+  };
+  const repo = real(root);
+  // A server answers with paths relative to its own workspace root (the
+  // nearest package), absolute ones through whatever spelling of a symlinked
+  // directory it was given, and files outside the repository (SDKs).
+  const rel = (file, serverRoot) => {
+    const abs = isAbsolute(file) ? file : resolve(serverRoot || root, file);
+    const r = relative(repo, real(abs));
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r : null;
+  };
+  const found = new Set();
+  for (const r of usable)
+    for (const loc of r.results || []) {
+      const f = loc?.file ? rel(loc.file, r.root) : null;
+      if (f) found.add(f);
+    }
+
+  const seedPaths = new Set((affectedDoc.changedSymbols || []).map((c) => c.path).filter(Boolean));
+  for (const id of affectedDoc.seeds || []) {
+    const s = String(id);
+    if (s.startsWith("sym:")) seedPaths.add(s.slice(4, s.lastIndexOf("#")));
+    else if (s.startsWith("file:")) seedPaths.add(s.slice(5));
+  }
+  const graphPaths = new Set();
+  const affected = (affectedDoc.affected || []).map((row) => {
+    if (row.path) graphPaths.add(row.path);
+    let confirmation = "unchecked";
+    if (checked && row.path && found.has(row.path)) confirmation = "confirmed";
+    else if (checked && row.dist === 1 && row.path) confirmation = "name-only";
+    return { ...row, confirmation };
+  });
+
+  const lspOnly = checked
+    ? [...found].filter((f) => !graphPaths.has(f) && !seedPaths.has(f)).sort()
+    : [];
+  const byPath = new Map();
+  for (const a of affected) if (a.path && !byPath.has(a.path)) byPath.set(a.path, a.confirmation);
+  const count = (c) => [...byPath.values()].filter((v) => v === c).length;
+  return {
+    affected,
+    lspOnly,
+    summary: {
+      confirmed: count("confirmed"),
+      nameOnly: count("name-only"),
+      unchecked: count("unchecked"),
+      lspOnly: lspOnly.length,
+      checked,
+    },
+  };
+}
+
+function flag(argv, name) {
+  const i = argv.indexOf(name);
+  const v = i >= 0 ? argv[i + 1] : undefined;
+  return v && !v.startsWith("--") ? v : null;
+}
+
+function main(argv) {
+  const affectedPath = flag(argv, "--affected");
+  const referencesPath = flag(argv, "--references");
+  const root = flag(argv, "--root");
+  if (!affectedPath || !referencesPath || !root) {
+    process.stderr.write(
+      "usage: graph-confirm.mjs --affected <json> --references <json> --root <path>\n",
+    );
+    process.exitCode = 64;
+    return;
+  }
+  let affectedDoc;
+  let references;
+  try {
+    affectedDoc = JSON.parse(readFileSync(affectedPath, "utf8"));
+    references = JSON.parse(readFileSync(referencesPath, "utf8"));
+  } catch (e) {
+    process.stderr.write(`graph-confirm: ${e.message}\n`);
+    process.exitCode = 64;
+    return;
+  }
+  if (!Array.isArray(references)) references = [references];
+  process.stdout.write(`${JSON.stringify(confirmImpact(affectedDoc, references, { root }))}\n`);
+}
+
+if (invokedDirectly(import.meta.url)) main(process.argv.slice(2));

package/pipeline/scripts/graph-query.mjs

@@ -99,6 +99,20 @@ function renderNode(node) {
   return `${node.name} (${kind}) ${where}`;
 }
 
+/**
+ * The line main() prints for a hit. The budget is charged for this, not for
+ * the bare node text, so the token count it reports is the one the caller pays.
+ *
+ * @param {number} dist
+ * @param {string} line
+ * @param {string|null} via
+ * @returns {string}
+ */
+export function printedLine(dist, line, via) {
+  const prefix = dist === 0 ? "*" : " ".repeat(dist) + "-";
+  return `${prefix} ${line}${via ? ` [${via}]` : ""}`;
+}
+
 /**
  * Seed, then breadth-first expand until the budget is spent.
  *
@@ -119,7 +133,7 @@ export function traverse({ graph, question, budget, depth, seedCount }) {
   const queue = seeds.map((n) => ({ node: n, dist: 0, via: null }));
   while (queue.length) {
     const { node, dist, via } = queue.shift();
-    const cost = Math.ceil(renderNode(node).length / CHARS_PER_TOKEN);
+    const cost = Math.ceil(printedLine(dist, renderNode(node), via).length / CHARS_PER_TOKEN);
     if (tokens + cost > budget) {
       truncated = true;
       break;
@@ -177,9 +191,7 @@ function main() {
     return;
   }
   for (const hit of result.hits) {
-    const prefix = hit.dist === 0 ? "*" : " ".repeat(hit.dist) + "-";
-    const via = hit.via ? ` [${hit.via}]` : "";
-    process.stdout.write(`${prefix} ${hit.line}${via}\n`);
+    process.stdout.write(`${printedLine(hit.dist, hit.line, hit.via)}\n`);
   }
   process.stdout.write(
     `\n${result.hits.length} nodes, ~${result.tokens} tokens` +

package/pipeline/scripts/learnings-ledger.mjs

@@ -41,7 +41,8 @@
  *                 Distill the triage's rejected[] findings into rejected-preference
  *                 entries so reviewers stop re-raising them. SAFETY: blocking-
  *                 severity rejections are NOT distilled - a wrong rejection of a
- *                 blocking issue must never permanently suppress that class.
+ *                 blocking issue must never permanently suppress that class. Exit 2
+ *                 when nothing new was distilled (a repeat of the same triage).
  *   forget     [--statement "..."] [--kind <kind>] [--repo-slug <slug>]
  *                 Remove ledger entries matching the statement substring and/or
  *                 kind (rewrites the file). Use to clear a bad/stale learning.
@@ -311,7 +312,7 @@ function cmdFromTriage() {
     }
   }
   process.stdout.write(JSON.stringify({ ok: true, slug, added: written, skippedBlocking }) + "\n");
-  process.exitCode = 0;
+  process.exitCode = written ? 0 : 2;
   return;
 }