Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

22.4 KB
Raw Blame
/**
 * Blast radius of a diff: what else in the repo depends on the lines this change
 * touched.
 *
 * The whole command is a join between two things graft already has — git's changed
 * line ranges (`diff.ts`) and the wiring graph's incoming edges (`traverse.ts`) —
 * so there is no new graph logic here, only the seeding rule:
 *
 *   changed line → the innermost symbol whose span contains it → seed
 *
 * Seeding by SYMBOL rather than by file is what makes the answer worth reading: a
 * 400-line file with a one-line edit reports the dependents of that one function,
 * not of everything the file happens to define. The file node is seeded too, so
 * importers (whose edge targets the file, not the symbol) are still found.
 */
import { impactOfMany, type EdgeHit } from "../graph/traverse.js";
import type { GraphV1, NodeV1 } from "../graph/types.js";
import { dirLabel, moduleIndex, parentDir, shortLabel, type ModuleIndex } from "./modules.js";
import type { ChangedFile } from "./diff.js";
import type { Owner, Reviewer } from "./owners.js";

const SPAN_RE = /^L(\d+)-L(\d+)$/;

export interface BlastOptions {
  /** BFS depth over incoming edges; `Infinity` for the full closure. */
  depth: number;
  /** Concept/directory labels. Built from the context dir when omitted. */
  modules?: ModuleIndex;
}

/** A changed symbol the walk started from. */
export interface Seed {
  id: string;
  name: string;
  kind: string;
  path: string;
  span: string;
  /** True for a whole-file seed (an added file, or a change outside any symbol). */
  wholeFile: boolean;
}

/** One dependent symbol, and how the walk reached it. */
export interface Impacted {
  id: string;
  name: string;
  kind: string;
  path: string;
  span: string;
  relation: string;
  depth: number;
}

/**
 * Where a cluster's label came from — the rungs of the naming ladder.
 *
 * `concept` — a concept node from a `--deep` build claims every file in the cluster.
 * `named`   — `graft blast --name` asked a model to name this cluster (see name.ts).
 * `symbol`  — the deterministic backstop: the cluster's most significant symbol.
 *
 * A bare directory is never a label. The whole point of the picture is that a
 * reviewer reads what is affected, and `src/graph/` tells them nothing they could
 * not get from the diff — but it must never be replaced by a guess either, so the
 * backstop names a real symbol rather than inventing a feature name.
 */
export type LabelSource = "concept" | "named" | "symbol";

/** Dependents grouped for the diagram: the unit a reviewer actually thinks in. */
export interface ImpactedModule {
  label: string;
  labelSource: LabelSource;
  /** Stable identity for the cluster, independent of its label: the concept name
   * or the directory it was grouped by. Naming and its cache key hang off this. */
  key: string;
  files: string[];
  symbols: Impacted[];
  /** Changed files whose edges reached this module — the diagram's arrows. */
  from: string[];
  /** Who has worked on these files, best first. Filled in by `attachOwners`;
   * absent when the radius was taken outside a git repository. */
  owners?: Owner[];
}

/**
 * Whether the diff brought its tests along.
 *
 * `changed` — a test file that reaches this area was edited in this PR.
 * `stale`   — tests reach it and the diff left every one of them alone.
 * `none`    — nothing under `test/` reaches it at all.
 * `na`      — no function, method or class changed here, so there is nothing to
 *             ask the question of: a types-only file, or config and wiring.
 */
export type TestSignal = "changed" | "stale" | "none" | "na";

/** One area of the diff: the changed files a reviewer thinks of as one thing. */
export interface ChangedArea {
  label: string;
  labelSource: LabelSource;
  /** The directory the cluster was grouped by — see {@link ImpactedModule.key}. */
  key: string;
  /** Changed, indexed, non-test files grouped under this label. */
  files: string[];
  /** Changed symbols seeded from those files. */
  seeds: number;
  tests: TestSignal;
  /** Test files with an edge into this area, and those of them the diff changed. */
  testFiles: string[];
  changedTestFiles: string[];
  /** Test reach, over the area's exported functions/methods/classes only. */
  reached: number;
  behavioural: number;
  /** Names of the behavioural symbols no test reaches, for the collapsed detail. */
  unreached: string[];
  /** Changed symbol names, behaviour first — the backstop label and the naming
   * prompt both read from this. */
  seedNames: string[];
  /** Who has worked on these files, best first — see {@link ImpactedModule.owners}. */
  owners?: Owner[];
}

export interface BlastReport {
  basis: string;
  depth: number;
  changed: ChangedFile[];
  /** Changed paths the graph has no node for: unsupported language, or deleted. */
  unindexed: string[];
  /** Changed paths that were deleted, called out because their dependents are
   * unknowable from a graph built at the post-change commit. */
  deleted: string[];
  seeds: Seed[];
  impacted: Impacted[];
  modules: ImpactedModule[];
  /** The diff itself, grouped: the left-hand side of the diagram. */
  areas: ChangedArea[];
  /** Test-only dependents, kept out of `modules` so they cannot crowd it out. */
  testModules: ImpactedModule[];
  /** Who to tag, ranked across every area. Absent outside a git repository, and
   * empty when the author is the only person in the history. */
  reviewers?: Reviewer[];
}

function spanBounds(span: string): { start: number; end: number } | null {
  const m = SPAN_RE.exec(span);
  return m ? { start: Number(m[1]), end: Number(m[2]) } : null;
}

/**
 * The innermost symbols whose spans overlap any changed range in `path`.
 *
 * "Innermost" matters for a method: a changed line inside `Cache.get` overlaps both
 * the class span and the method span, and seeding the class would report everyone
 * who touches any part of `Cache`. Nesting is resolved by keeping, for each range,
 * only symbols that contain no other matched symbol.
 */
function seedsForFile(graph: GraphV1, path: string, ranges: { start: number; end: number }[]): NodeV1[] {
  const symbols: { node: NodeV1; start: number; end: number }[] = [];
  for (const n of graph.nodes) {
    if (n.kind === "file" || n.path !== path) continue;
    const b = spanBounds(n.span);
    if (b) symbols.push({ node: n, ...b });
  }
  if (symbols.length === 0) return [];

  const hit = new Map<string, NodeV1>();
  for (const r of ranges) {
    const overlapping = symbols.filter((s) => s.start <= r.end && s.end >= r.start);
    // Drop any symbol that strictly contains another overlapping one (the class
    // around a changed method), keeping the tightest description of the edit.
    for (const s of overlapping) {
      const containsAnother = overlapping.some(
        (o) => o !== s && o.start >= s.start && o.end <= s.end,
      );
      if (!containsAnother) hit.set(s.node.id, s.node);
    }
  }
  return [...hit.values()];
}

/** Compute the blast radius of `changed` against `graph`. */
export function blastRadius(
  graph: GraphV1,
  changed: ChangedFile[],
  basis: string,
  opts: BlastOptions,
): BlastReport {
  const fileNodes = new Map<string, NodeV1>();
  for (const n of graph.nodes) if (n.kind === "file") fileNodes.set(n.path, n);

  const seeds: Seed[] = [];
  const unindexed: string[] = [];
  const deleted: string[] = [];
  /** Seed nodes per changed file, kept for the area grouping and the test signal. */
  const seedNodes = new Map<string, NodeV1[]>();
  /** Merged dependents, keyed by node id, at the shallowest depth any file reached
   * them — plus which changed files did the reaching. */
  const merged = new Map<string, { hit: Impacted; from: Set<string> }>();

  for (const file of changed) {
    if (file.status === "deleted") {
      deleted.push(file.path);
      continue;
    }
    const fileNode = fileNodes.get(file.path);
    if (!fileNode) {
      unindexed.push(file.path);
      continue;
    }

    // No hunk ranges (a rename with no content change, a mode change) or an added
    // file: the unit of change is the file itself.
    const symbolSeeds = file.ranges.length > 0 ? seedsForFile(graph, file.path, file.ranges) : [];
    for (const node of symbolSeeds) {
      seeds.push({ id: node.id, name: node.name, kind: node.kind, path: node.path, span: node.span, wholeFile: false });
    }
    if (symbolSeeds.length === 0) {
      seeds.push({
        id: fileNode.id, name: fileNode.name, kind: fileNode.kind,
        path: fileNode.path, span: fileNode.span, wholeFile: true,
      });
    }

    // One walk PER CHANGED FILE, not one walk over every seed at once. A combined
    // walk records the depth a node was first reached at but not by which seed, so
    // the diagram could only draw "every changed file reaches every module" — a
    // cross-product that tells a reviewer nothing. Walking per file costs one
    // adjacency build each (cheap: the graph is already in memory) and buys arrows
    // that are true.
    //
    // The FILE node is a seed only when no symbol matched. `imports` edges target
    // the file id, so seeding it alongside symbols would pull in every importer of
    // the file — a one-line edit to one function would report every module that
    // imports the module, which is the noise this command exists to avoid. With no
    // symbol seeds (a change to a top-level constant, a new import, a file with no
    // extracted symbols) the file IS the unit of change, and its importers are the
    // only dependents there are.
    const walkSeeds = symbolSeeds.length > 0 ? symbolSeeds : [fileNode];
    seedNodes.set(file.path, walkSeeds);
    const hits = impactOfMany(graph, walkSeeds, opts.depth, "in");
    for (const h of hits) {
      if (!hasNode(h)) continue;
      const hit = toImpacted(h);
      const prev = merged.get(hit.id);
      if (!prev) merged.set(hit.id, { hit, from: new Set([file.path]) });
      else {
        prev.from.add(file.path);
        // Keep the shallowest reach: a symbol two hops from one changed file and one
        // hop from another is one hop away from this PR.
        if (hit.depth < prev.hit.depth) prev.hit = hit;
      }
    }
  }

  const impacted = [...merged.values()].map((m) => m.hit);
  const origins = new Map([...merged].map(([id, m]) => [id, m.from]));
  const index = opts.modules ?? emptyIndex();
  const grouped = groupByModule(impacted, changed, origins, index);

  return {
    basis,
    depth: opts.depth,
    changed,
    unindexed,
    deleted,
    seeds,
    impacted,
    modules: grouped.modules,
    testModules: grouped.testModules,
    areas: changedAreas(graph, changed, seedNodes, index, grouped.modules),
  };
}

/**
 * Group the changed files into areas, and work out whether each one's tests moved.
 *
 * The diff's own side of the diagram used to be one box per changed file, which can
 * never fit: a 24-file PR drew ten arbitrary paths. Grouped by the same concept
 * labels the dependents use, the same PR is three or four circles — and once the
 * files are grouped, "did a test that reaches this move too?" is one question per
 * circle instead of per file.
 */
function changedAreas(
  graph: GraphV1,
  changed: ChangedFile[],
  seedNodes: Map<string, NodeV1[]>,
  index: ModuleIndex,
  modules: ImpactedModule[],
): ChangedArea[] {
  const changedTests = new Set(changed.filter((c) => TEST_PATH.test(c.path)).map((c) => c.path));
  const nodeById = new Map(graph.nodes.map((n) => [n.id, n]));
  /** How many edges point AT each node — how central it is in the graph. */
  const inDegree = new Map<string, number>();
  for (const e of graph.edges) inDegree.set(e.target, (inDegree.get(e.target) ?? 0) + 1);
  /** Incoming edge sources per node id, resolved to the source's file path. */
  const incoming = new Map<string, Set<string>>();
  for (const e of graph.edges) {
    const path = nodeById.get(e.source)?.path;
    if (!path || !TEST_PATH.test(path)) continue;
    const at = incoming.get(e.target) ?? new Set<string>();
    at.add(path);
    incoming.set(e.target, at);
  }

  // Group by DIRECTORY, not by concept. Concepts in a well-summarised repo are
  // near-file-grained — graft's own PR produced nine of them, one file each — so
  // grouping the diff by concept groups nothing: the left side was nine circles
  // with near-identical truncated names. A directory is the coarser unit reviewers
  // already use, and a concept name is only worth borrowing when one concept
  // happens to claim the whole group.
  const groups = new Map<string, string[]>();
  for (const path of seedNodes.keys()) {
    // A changed test file is the signal, not the source of a blast radius. Drawing
    // it as an area would put "your tests changed" on both sides of the arrow.
    if (TEST_PATH.test(path)) continue;
    const dir = dirLabel(path);
    groups.set(dir, [...(groups.get(dir) ?? []), path]);
  }
  coarsen(groups, MAX_AREAS);

  const byKey = new Map<string, ChangedArea>();
  /** Hub candidates per area, ranked once every seed has been seen. */
  const candidates = new Map<ChangedArea, { name: string; behavioural: boolean; degree: number }[]>();
  for (const [dir, paths] of groups) {
    const area: ChangedArea = {
      label: dir, labelSource: "symbol", key: dir,
      files: [], seeds: 0, tests: "none", testFiles: [], changedTestFiles: [],
      reached: 0, behavioural: 0, unreached: [], seedNames: [],
    };
    byKey.set(dir, area);
    for (const path of paths) {
      const nodes = seedNodes.get(path) ?? [];
      area.files.push(path);
      area.seeds += nodes.length;

      for (const node of nodes) {
        // Reach is measured over behaviour only. Counting interfaces and type aliases
        // would sink every ratio: nothing "calls" a type, so a fully tested area of
        // typed code would report a third of its symbols as unreached.
        const behavioural = node.kind === "function" || node.kind === "method" || node.kind === "class";
        const from = incoming.get(node.id) ?? new Set<string>();
        for (const t of from) {
          if (!area.testFiles.includes(t)) area.testFiles.push(t);
          if (changedTests.has(t) && !area.changedTestFiles.includes(t)) area.changedTestFiles.push(t);
        }
        candidates.set(area, [
          ...(candidates.get(area) ?? []),
          { name: node.name, behavioural, degree: inDegree.get(node.id) ?? 0 },
        ]);
        if (!behavioural) continue;
        area.behavioural++;
        if (from.size > 0) area.reached++;
        else area.unreached.push(node.name);
      }
    }
  }

  for (const area of byKey.values()) {
    // The hub is the most-depended-on function in the area, not whichever symbol the
    // file walk happened to end on: `LlmFailureGate` rather than `transportRetries`.
    // Behaviour outranks types, since nothing calls an interface.
    area.seedNames = (candidates.get(area) ?? [])
      .sort((a, b) =>
        Number(b.behavioural) - Number(a.behavioural) || b.degree - a.degree || a.name.localeCompare(b.name))
      .map((c) => c.name);
    const concept = sharedConcept(area.files, index);
    area.label = concept ?? hubLabel(area.seedNames, area.key);
    area.labelSource = concept ? "concept" : "symbol";
    area.files.sort();
    area.testFiles.sort();
    area.changedTestFiles.sort();
    area.tests =
      area.behavioural === 0 ? "na"
      : area.changedTestFiles.length > 0 ? "changed"
      : area.testFiles.length > 0 ? "stale"
      : "none";
  }

  // Ordered by how much each area actually reaches, because the diagram caps this
  // list and folds the rest into one circle. Ordered by size instead, the fold ends
  // up holding the best-connected areas and the tail circle collects every arrow —
  // the same mistake, one level up, as capping changed FILES in diff order.
  const reach = (a: ChangedArea) =>
    modules.filter((m) => m.from.some((f) => a.files.includes(f))).length;
  return [...byKey.values()].sort(
    (a, b) => reach(b) - reach(a) || b.files.length - a.files.length || a.label.localeCompare(b.label),
  );
}

/** Convenience wrapper: build the module index from a context dir. */
export function blastRadiusIn(
  graph: GraphV1,
  contextDir: string,
  changed: ChangedFile[],
  basis: string,
  depth: number,
): BlastReport {
  return blastRadius(graph, changed, basis, { depth, modules: moduleIndex(contextDir) });
}

function hasNode(h: EdgeHit): h is EdgeHit & { node: NodeV1 } {
  // Unresolved endpoints (an import module string no node exists for) carry no
  // location, so they can neither be grouped nor opened — dropped rather than
  // rendered as a box with no file behind it.
  return h.node !== null;
}

function toImpacted(h: EdgeHit & { node: NodeV1 }): Impacted {
  return {
    id: h.node.id, name: h.node.name, kind: h.node.kind,
    path: h.node.path, span: h.node.span, relation: h.relation, depth: h.depth,
  };
}

function emptyIndex(): ModuleIndex {
  return { hasConcepts: false, labelOf: (p) => p, conceptOf: () => null };
}

/**
 * The concept claiming EVERY file in a cluster, or null when they disagree.
 *
 * Unanimity is the point: a concept that covers three of five files describes
 * something narrower than the cluster, and stamping its name on the whole thing is
 * how a diagram starts lying about what it drew.
 */
function sharedConcept(paths: string[], index: ModuleIndex): string | null {
  const concepts = new Set(paths.map((p) => index.conceptOf(p)));
  const [only] = concepts;
  return concepts.size === 1 && only ? shortLabel(only) : null;
}

/**
 * The deterministic backstop label: the cluster's most significant symbol.
 *
 * Reached with no concept, no cache and no API key, so this is what guarantees a
 * circle never carries a bare directory. It is a fact rather than a guess — the
 * reviewer can grep the name — which is why it beats borrowing a neighbouring
 * concept: on graft's own graph that borrowing labelled the freshness gate
 * "Graph Extraction and Loading", which misleads worse than any path.
 */
export function hubLabel(names: string[], fallback: string): string {
  const [head] = names.filter(Boolean);
  // The hub alone, with no "+8" tail: how many symbols came with it is already the
  // circle's second line and the table's own column, and repeating it in the label
  // turned "writeGraph" into "writeGraph +8", which reads as a version number.
  return head ? shortLabel(head) : fallback;
}

/**
 * Group dependents into modules. `origins` carries, per dependent, the changed
 * files whose walk actually reached it — so a module's `from` is the real arrow
 * set, not every changed file in the PR.
 */
function groupByModule(
  impacted: Impacted[],
  changed: ChangedFile[],
  origins: Map<string, Set<string>>,
  modules: ModuleIndex,
): { modules: ImpactedModule[]; testModules: ImpactedModule[] } {
  const changedPaths = new Set(changed.map((c) => c.path));
  const byKey = new Map<string, ImpactedModule>();

  for (const hit of impacted) {
    // A dependent inside a file the PR already changes is not "reach" — it is the
    // diff. Reviewers see it in the diff itself; repeating it as blast radius is
    // what makes these comments feel like noise.
    if (changedPaths.has(hit.path)) continue;
    // Cluster by concept where one exists, else by directory. Clustering and
    // LABELLING are separate steps now: the key only has to be stable, while the
    // label goes through the ladder below and may end up naming a symbol.
    const key = modules.conceptOf(hit.path) ?? dirLabel(hit.path);
    let mod = byKey.get(key);
    if (!mod) {
      mod = { label: key, labelSource: "symbol", key, files: [], symbols: [], from: [] };
      byKey.set(key, mod);
    }
    mod.symbols.push(hit);
    if (!mod.files.includes(hit.path)) mod.files.push(hit.path);
  }

  for (const mod of byKey.values()) {
    const from = new Set<string>();
    for (const s of mod.symbols) for (const p of origins.get(s.id) ?? []) from.add(p);
    mod.from = [...from].sort();
    mod.files.sort();
    mod.symbols.sort((a, b) => a.depth - b.depth || a.path.localeCompare(b.path));
    // Shallowest symbol first after that sort, so it is the cluster's hub: the
    // thing one hop from the diff rather than an arbitrary member.
    const concept = sharedConcept(mod.files, modules);
    mod.label = concept ?? hubLabel(mod.symbols.map((s) => s.name), mod.key);
    mod.labelSource = concept ? "concept" : "symbol";
  }

  // Test-only modules are separated, not just sorted last. On a repo with a test
  // per module they are the majority of the graph's dependents — graft's own 24-file
  // PR produced 31 modules, 24 of them a single test file — so leaving them in the
  // same list means they crowd out every module a reviewer needs whatever the caps
  // are. "Your tests reference the thing you changed" is one line, not 24 sections.
  const bySize = (a: ImpactedModule, b: ImpactedModule) =>
    b.symbols.length - a.symbols.length || a.label.localeCompare(b.label);
  const all = [...byKey.values()];
  return {
    modules: all.filter((m) => !isTestOnly(m)).sort(bySize),
    testModules: all.filter(isTestOnly).sort(bySize),
  };
}

/**
 * Directory groups the diff is folded down to before anything is drawn.
 *
 * Kept here rather than in the renderer because it is a statement about the diff,
 * not about the picture: five areas is roughly what a reviewer holds in their head,
 * and the renderer then draws all of them.
 */
const MAX_AREAS = 5;

/**
 * Fold directory groups into their parents until there are at most `max`.
 *
 * The deepest group goes first, and only into a parent that already exists, so
 * `src/ai/llm/` joins `src/ai/` rather than everything collapsing towards the repo
 * root. When no group has an existing parent, one is created — but never at the top
 * level, since a single `(root)` area is no grouping at all.
 */
function coarsen(groups: Map<string, string[]>, max: number): void {
  const depth = (dir: string) => dir.split("/").length;
  while (groups.size > max) {
    const keys = [...groups.keys()].sort((a, b) => depth(b) - depth(a) || (groups.get(a)!.length - groups.get(b)!.length));
    const pick =
      keys.find((k) => groups.has(parentDir(k)) && parentDir(k) !== "") ??
      keys.find((k) => parentDir(k) !== "");
    if (!pick) return;
    const parent = parentDir(pick);
    groups.set(parent, [...(groups.get(parent) ?? []), ...groups.get(pick)!]);
    groups.delete(pick);
  }
}

const TEST_PATH = /(^|\/)(tests?|specs?|__tests__)\/|\.(test|spec)\.[cm]?[jt]sx?$|_test\.(go|py|rb)$/i;

/** True when every file in the module is a test file. */
function isTestOnly(mod: ImpactedModule): boolean {
  return mod.files.length > 0 && mod.files.every((f) => TEST_PATH.test(f));
}