@mmerterden/multi-agent-pipeline 16.12.0 → 16.14.0

package/pipeline/scripts/graph-affected.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+/**
+ * @file graph-affected.mjs  -  reverse traversal: what breaks if this changes.
+ *
+ * Phase 1's impact surface, feeding `analysis.touchedAreas[]`. Where
+ * graph-query.mjs answers "where does this live", this answers "who depends on
+ * it": it walks edges backwards from a named symbol, so the result is the blast
+ * radius of a change rather than its neighbourhood.
+ *
+ * Inputs:
+ *   "<symbol>"       Symbol name, exact or case-insensitive. Required.
+ *   --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)
+ *   --json           Emit JSON instead of text
+ *
+ * Exit codes:
+ *   0  -  answered (possibly empty)
+ *   1  -  graph missing or unreadable
+ *   64 -  usage error
+ *
+ * @module pipeline/scripts/graph-affected
+ */
+
+import { resolve } from "node:path";
+import { parseFlags } from "./graph-build.mjs";
+import { loadGraph, defaultGraphPath } from "./graph-query.mjs";
+
+/**
+ * Nodes whose name matches, preferring an exact hit.
+ *
+ * A case-insensitive fallback keeps the command usable from a task description,
+ * where the symbol is often typed in prose casing.
+ *
+ * @param {object} graph
+ * @param {string} name
+ * @returns {object[]}
+ */
+export function findByName(graph, name) {
+  const exact = graph.nodes.filter((n) => n.name === name);
+  if (exact.length) return exact;
+  const lower = name.toLowerCase();
+  return graph.nodes.filter((n) => (n.name || "").toLowerCase() === lower);
+}
+
+/**
+ * Incoming adjacency only.
+ *
+ * @param {object} graph
+ * @param {Set<string>|null} kinds
+ * @returns {Map<string, Array<{id: string, kind: string}>>}
+ */
+export function incoming(graph, kinds = null) {
+  const adj = new Map();
+  for (const e of graph.edges) {
+    if (kinds && !kinds.has(e.kind)) continue;
+    if (!adj.has(e.to)) adj.set(e.to, []);
+    adj.get(e.to).push({ id: e.from, kind: e.kind });
+  }
+  return adj;
+}
+
+/**
+ * Walk backwards from each seed.
+ *
+ * @param {object} params
+ * @returns {Array<{id: string, dist: number, kind: string, node: object}>}
+ */
+export function affected({ graph, seeds, depth, kinds }) {
+  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 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 });
+    }
+  }
+  return out;
+}
+
+function main() {
+  const { flags, positional } = parseFlags(process.argv.slice(2));
+  const name = positional.join(" ").trim();
+  if (!name) {
+    process.stderr.write(
+      'graph-affected: a symbol name is required, e.g. graph-affected "Flight"\n',
+    );
+    process.exit(64);
+  }
+
+  const path = flags.graph && flags.graph !== true ? resolve(flags.graph) : defaultGraphPath();
+  let graph;
+  try {
+    graph = loadGraph(path);
+  } catch (e) {
+    process.stderr.write(`graph-affected: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  const depth = Number(flags.depth) > 0 ? Number(flags.depth) : 2;
+  const kinds = flags.kind && flags.kind !== true ? new Set(String(flags.kind).split(",")) : null;
+
+  const seeds = findByName(graph, name);
+  if (seeds.length === 0) {
+    if (flags.json === true) {
+      process.stdout.write(
+        JSON.stringify({ symbol: name, seeds: [], affected: [] }, null, 2) + "\n",
+      );
+    } else {
+      process.stdout.write(`no node named '${name}'\n`);
+    }
+    return;
+  }
+
+  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;
+  }
+
+  process.stdout.write(`# affected by ${name}\n\n`);
+  for (const seed of seeds) {
+    process.stdout.write(`* ${seed.name} (${seed.symbolKind || seed.kind}) ${seed.path || "-"}\n`);
+  }
+  process.stdout.write("\n");
+  const files = new Set();
+  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 (process.argv[1] && process.argv[1].endsWith("graph-affected.mjs")) main();

package/pipeline/scripts/graph-build.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+
+/**
+ * @file graph-build.mjs  -  build the code graph for one repo.
+ *
+ * Full rebuild every time, by measurement rather than by principle: on the
+ * corporate iOS app (4,311 Swift sources, 14.3 MB) the whole pass takes under
+ * three seconds, so an incremental extraction path would add a cache file, a
+ * staleness bug surface and a second code path to test in exchange for nothing.
+ * The manifest is still written - Phase 1 uses it to report how far behind a
+ * graph is, not to rebuild a subset.
+ *
+ * Inputs:
+ *   --root <path>    Repo root. Default: cwd
+ *   --stack <id>     ios | android | node | python. Required.
+ *   --out <path>     Graph output. Default: ~/.claude/knowledge/<project>/code-graph.json
+ *   --max-nodes N    Refuse to write a graph larger than this. Default: 200000.
+ *                    Callers pass prefs.global.codeGraph.maxNodes. A tree that
+ *                    blows past it is vendored or generated source, and writing
+ *                    a several-hundred-megabyte file for it helps nobody, so
+ *                    the build fails loudly instead of succeeding quietly.
+ *   --json           Emit the summary as JSON instead of a line
+ *
+ * Output:
+ *   Writes the graph, prints a one-line summary.
+ *
+ * Exit codes:
+ *   0  -  built
+ *   1  -  rule load, walk, write error, or graph past --max-nodes
+ *   64 -  usage error
+ *
+ * @module pipeline/scripts/graph-build
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join, dirname, resolve, basename } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import {
+  loadRules,
+  listSourceFiles,
+  extractFile,
+  buildGraph,
+  diffManifest,
+} from "./_code-graph.mjs";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_MAX_NODES = 200000;
+
+export function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const k = a.slice(2);
+      const v = argv[i + 1];
+      if (v !== undefined && !v.startsWith("--")) {
+        flags[k] = v;
+        i++;
+      } else {
+        flags[k] = true;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { flags, positional };
+}
+
+export function defaultGraphPath(root) {
+  return join(homedir(), ".claude", "knowledge", basename(root), "code-graph.json");
+}
+
+function headCommit(root) {
+  try {
+    return execFileSync("git", ["-C", root, "rev-parse", "HEAD"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function main() {
+  const { flags } = parseFlags(process.argv.slice(2));
+  const stack = flags.stack;
+  if (!stack || stack === true) {
+    process.stderr.write("graph-build: --stack <ios|android|node|python> required\n");
+    process.exit(64);
+  }
+
+  const root = resolve(flags.root || process.cwd());
+  if (!existsSync(root)) {
+    process.stderr.write(`graph-build: root not found: ${root}\n`);
+    process.exit(1);
+  }
+  const out = flags.out && flags.out !== true ? resolve(flags.out) : defaultGraphPath(root);
+
+  let rules;
+  try {
+    rules = loadRules(stack, SCRIPT_DIR);
+  } catch (e) {
+    process.stderr.write(`graph-build: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  const startedAt = Date.now();
+  const files = listSourceFiles(root, rules);
+  const extracted = new Map();
+  for (const path of files) {
+    try {
+      extracted.set(path, extractFile(readFileSync(join(root, path), "utf8"), rules));
+    } catch {
+      /* unreadable file: skip, it simply does not reach the graph */
+    }
+  }
+
+  const { manifest } = diffManifest(root, [...extracted.keys()], {});
+  const graph = buildGraph({
+    root,
+    stack,
+    extracted,
+    rules,
+    manifest,
+    baseCommit: headCommit(root),
+    generatedAt: new Date().toISOString(),
+  });
+
+  const maxNodes = Number(flags["max-nodes"]) > 0 ? Number(flags["max-nodes"]) : DEFAULT_MAX_NODES;
+  if (graph.stats.nodes > maxNodes) {
+    process.stderr.write(
+      `graph-build: ${graph.stats.nodes} nodes exceeds --max-nodes ${maxNodes}; ` +
+        `nothing written. Narrow the tree with the stack rules' excludePathGlobs, ` +
+        `or raise prefs.global.codeGraph.maxNodes if this repo really is that large.\n`,
+    );
+    process.exit(1);
+  }
+
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, JSON.stringify(graph), "utf8");
+
+  const elapsedMs = Date.now() - startedAt;
+  const summary = { out, elapsedMs, ...graph.stats };
+  if (flags.json === true) {
+    process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+  } else {
+    process.stdout.write(
+      `graph-build: ${graph.stats.files} files, ${graph.stats.nodes} nodes, ` +
+        `${graph.stats.edges} edges in ${elapsedMs}ms -> ${out}\n`,
+    );
+  }
+}
+
+if (process.argv[1] && process.argv[1].endsWith("graph-build.mjs")) main();

package/pipeline/scripts/graph-query.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+/**
+ * @file graph-query.mjs  -  token-budgeted traversal of the code graph.
+ *
+ * Phase 1's read surface. Ranks graph nodes against the task text with the
+ * pipeline's own BM25 (`_retrieval.mjs`, already gated by eval-recall.mjs),
+ * takes the best seeds, then walks their edges breadth-first until the token
+ * budget is spent. The budget is the point: an unbounded neighbourhood dump is
+ * the context-stuffing anti-pattern this is supposed to replace, so the walk
+ * stops on budget rather than on depth alone.
+ *
+ * Inputs:
+ *   "<question>"     Free text. Required.
+ *   --graph <path>   Graph file. Default: ~/.claude/knowledge/<cwd name>/code-graph.json
+ *   --budget N       Output token cap. Default: 2000
+ *   --depth N        Max BFS depth from a seed. Default: 2
+ *   --seeds N        How many ranked seeds to expand. Default: 8
+ *   --json           Emit JSON instead of text
+ *
+ * Exit codes:
+ *   0  -  answered (possibly empty)
+ *   1  -  graph missing or unreadable
+ *   64 -  usage error
+ *
+ * @module pipeline/scripts/graph-query
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+import { homedir } from "node:os";
+import { bm25 } from "./_retrieval.mjs";
+import { parseFlags } from "./graph-build.mjs";
+
+const CHARS_PER_TOKEN = 4;
+
+export function defaultGraphPath(cwd = process.cwd()) {
+  return join(homedir(), ".claude", "knowledge", basename(resolve(cwd)), "code-graph.json");
+}
+
+export function loadGraph(path) {
+  if (!existsSync(path)) throw new Error(`graph not found: ${path}`);
+  const graph = JSON.parse(readFileSync(path, "utf8"));
+  if (!Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
+    throw new Error(`graph is malformed: ${path}`);
+  }
+  return graph;
+}
+
+/**
+ * Adjacency in both directions.
+ *
+ * Traversal has to cross an edge either way: a task naming a base class must
+ * reach its subclasses (incoming) as readily as its own file (outgoing).
+ *
+ * @param {object} graph
+ * @returns {Map<string, Array<{id: string, kind: string, dir: string}>>}
+ */
+export function adjacency(graph) {
+  const adj = new Map();
+  const push = (from, to, kind, dir) => {
+    if (!adj.has(from)) adj.set(from, []);
+    adj.get(from).push({ id: to, kind, dir });
+  };
+  for (const e of graph.edges) {
+    push(e.from, e.to, e.kind, "out");
+    push(e.to, e.from, e.kind, "in");
+  }
+  return adj;
+}
+
+/**
+ * Rank nodes against the question.
+ *
+ * `name` outweighs `path` because a task names symbols far more often than
+ * directories, and `symbolKind` carries a little signal ("the FlightList view
+ * model") without letting the kind word alone win a match.
+ *
+ * @param {object} graph
+ * @param {string} question
+ * @returns {Array<{node: object, score: number}>} descending, zero scores dropped
+ */
+export function rankNodes(graph, question) {
+  const docs = graph.nodes.map((n) => ({
+    name: n.name || "",
+    path: n.path || "",
+    symbolKind: n.symbolKind || "",
+  }));
+  const scored = bm25(question, docs, { fieldWeights: { name: 3, path: 1, symbolKind: 1 } });
+  return scored
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .map((s) => ({ node: graph.nodes[s.index], score: s.score }));
+}
+
+function renderNode(node) {
+  const where = node.path ? `${node.path}${node.line ? `:${node.line}` : ""}` : "-";
+  const kind = node.symbolKind || node.kind;
+  return `${node.name} (${kind}) ${where}`;
+}
+
+/**
+ * Seed, then breadth-first expand until the budget is spent.
+ *
+ * @param {object} params
+ * @returns {{seeds: object[], hits: object[], truncated: boolean, tokens: number}}
+ */
+export function traverse({ graph, question, budget, depth, seedCount }) {
+  const ranked = rankNodes(graph, question);
+  const seeds = ranked.slice(0, seedCount).map((r) => r.node);
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const adj = adjacency(graph);
+
+  const seen = new Set(seeds.map((n) => n.id));
+  const hits = [];
+  let tokens = 0;
+  let truncated = false;
+
+  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);
+    if (tokens + cost > budget) {
+      truncated = true;
+      break;
+    }
+    tokens += cost;
+    hits.push({ id: node.id, dist, via, line: renderNode(node), degree: node.degree });
+
+    if (dist >= depth) continue;
+    const neighbours = (adj.get(node.id) || [])
+      .slice()
+      .sort((a, b) => (byId.get(b.id)?.degree || 0) - (byId.get(a.id)?.degree || 0));
+    for (const n of neighbours) {
+      if (seen.has(n.id)) continue;
+      const target = byId.get(n.id);
+      if (!target) continue;
+      seen.add(n.id);
+      queue.push({ node: target, dist: dist + 1, via: `${n.kind}/${n.dir}` });
+    }
+  }
+
+  return { seeds, hits, truncated, tokens };
+}
+
+function main() {
+  const { flags, positional } = parseFlags(process.argv.slice(2));
+  const question = positional.join(" ").trim();
+  if (!question) {
+    process.stderr.write('graph-query: a question is required, e.g. graph-query "flight search"\n');
+    process.exit(64);
+  }
+
+  const path = flags.graph && flags.graph !== true ? resolve(flags.graph) : defaultGraphPath();
+  let graph;
+  try {
+    graph = loadGraph(path);
+  } catch (e) {
+    process.stderr.write(`graph-query: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  const budget = Number(flags.budget) > 0 ? Number(flags.budget) : 2000;
+  const depth = Number(flags.depth) > 0 ? Number(flags.depth) : 2;
+  const seedCount = Number(flags.seeds) > 0 ? Number(flags.seeds) : 8;
+
+  const result = traverse({ graph, question, budget, depth, seedCount });
+
+  if (flags.json === true) {
+    process.stdout.write(JSON.stringify({ question, budget, ...result }, null, 2) + "\n");
+    return;
+  }
+
+  process.stdout.write(`# ${question}\n\n`);
+  if (result.hits.length === 0) {
+    process.stdout.write("no matching nodes\n");
+    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(
+    `\n${result.hits.length} nodes, ~${result.tokens} tokens` +
+      (result.truncated ? " (budget reached)" : "") +
+      "\n",
+  );
+}
+
+if (process.argv[1] && process.argv[1].endsWith("graph-query.mjs")) main();