@mrciphersmith/keryx 0.2.9

package/src/gdgraph/repomap.ts

@@ -0,0 +1,193 @@
+// Ranked, token-budgeted repo map (specification.md §8.3; T-B7, B-4/C0-8).
+//
+// Ranks files (or symbols, when the layer is present) via personalized PageRank
+// and renders `path + top symbols + signatures` into
+// `.metaproject/data/gdgraph/artifacts/repomap.md`, enforcing a hard token
+// budget. Overflow entries are dropped in rank order with a stable
+// "… N entries omitted …" marker. The token estimator mirrors gdctx's byte
+// budget idiom (default `chars-div-4`). Deterministic: a re-run diff is empty.
+
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { GdgraphConfig } from "./config";
+import { personalizedPageRank, type RankEdge } from "./pagerank";
+import type { GraphData, SymbolNode } from "./types";
+
+export interface RepomapEntry {
+  path: string;
+  score: number;
+  symbols: string[];
+}
+
+export interface RepomapOptions {
+  budget?: number;
+  seed?: string[];
+}
+
+export interface RepomapResult {
+  path: string;
+  content: string;
+  entries: RepomapEntry[];
+  tokens: number;
+  omitted: number;
+}
+
+// Local token estimator — the documented `chars-div-4` default (AC3.2). Kept
+// tiny + local since there is no shared gdctx estimator in this repo.
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+// The stable omission marker (AC3.2). `count` varies; the shape is fixed.
+function omissionMarker(count: number): string {
+  return `\n… ${count} entries omitted …\n`;
+}
+
+function repomapArtifactPath(cwd: string): string {
+  return path.join(cwd, ".metaproject", "data", "gdgraph", "artifacts", "repomap.md");
+}
+
+// Build the weighted rank edges from the graph: import edges w=1.0, and — when
+// the symbol layer is present — CALL edges w=callWeight and `defines` w=0.5.
+export function buildRankEdges(graph: GraphData, config: GdgraphConfig): RankEdge[] {
+  const edges: RankEdge[] = [];
+  for (const edge of graph.edges) {
+    if (edge.kind === "imports") {
+      edges.push({ from: edge.from, to: edge.to, weight: 1.0 });
+    }
+  }
+  for (const call of graph.calls ?? []) {
+    if (call.kind === "calls") {
+      edges.push({ from: call.from, to: call.to, weight: config.repomap.callWeight });
+    } else if (call.kind === "defines") {
+      edges.push({ from: call.from, to: call.to, weight: 0.5 });
+    }
+  }
+  return edges;
+}
+
+function renderSymbol(symbol: SymbolNode): string {
+  if (symbol.signature && symbol.signature.length > 0) {
+    return symbol.signature;
+  }
+  const container = symbol.container ? `${symbol.container}.` : "";
+  return `${symbol.kind} ${container}${symbol.name}`;
+}
+
+function topSymbols(graph: GraphData, filePath: string, max: number): string[] {
+  const symbols = (graph.symbols ?? [])
+    .filter((symbol) => symbol.path === filePath)
+    .sort((a, b) =>
+      a.startLine !== b.startLine
+        ? a.startLine - b.startLine
+        : a.name < b.name
+          ? -1
+          : a.name > b.name
+            ? 1
+            : 0,
+    )
+    .slice(0, max);
+  return symbols.map(renderSymbol);
+}
+
+function renderEntryBlock(entry: RepomapEntry): string {
+  const lines = [`## ${entry.path}`];
+  for (const symbol of entry.symbols) {
+    lines.push(`- ${symbol}`);
+  }
+  return `${lines.join("\n")}\n\n`;
+}
+
+const HEADER = [
+  "# gdgraph Repomap",
+  "",
+  "Ranked by personalized PageRank over the import/call graph.",
+  "",
+  "",
+].join("\n");
+
+// Compute the ranked, budget-fitted repomap. Pure over the in-memory graph +
+// config; no I/O. `writeRepomap` persists the result.
+export function computeRepomap(
+  graph: GraphData,
+  config: GdgraphConfig,
+  options: RepomapOptions = {},
+): RepomapResult {
+  const budget = options.budget ?? config.repomap.tokenBudget;
+
+  // Rank file nodes (the stable, always-present layer).
+  const fileNodes = graph.nodes.filter((node) => node.kind === "file").map((node) => node.path);
+  const rankEdges = buildRankEdges(graph, config);
+
+  const personalization = new Map<string, number>();
+  for (const seed of options.seed ?? []) {
+    const normalized = seed.replace(/^\.\//, "");
+    const match = fileNodes.find((file) => file === normalized || file.endsWith(normalized));
+    if (match) {
+      personalization.set(match, (personalization.get(match) ?? 0) + 1);
+    }
+  }
+
+  const ranked = personalizedPageRank(fileNodes, rankEdges, {
+    damping: config.repomap.damping,
+    iterations: config.repomap.iterations,
+    tolerance: config.repomap.tolerance,
+    ...(personalization.size > 0 ? { personalization } : {}),
+  });
+
+  const allEntries: RepomapEntry[] = ranked.map((node) => ({
+    path: node.id,
+    score: node.score,
+    symbols: topSymbols(graph, node.id, config.repomap.maxSymbolsPerFile),
+  }));
+
+  // Greedily fill within the budget, always leaving room for the marker.
+  let out = HEADER;
+  const rendered: RepomapEntry[] = [];
+  for (const entry of allEntries) {
+    const trial = out + renderEntryBlock(entry);
+    if (estimateTokens(trial) <= budget) {
+      out = trial;
+      rendered.push(entry);
+    } else {
+      break;
+    }
+  }
+
+  let omitted = allEntries.length - rendered.length;
+  if (omitted > 0) {
+    // Ensure the final content (incl. marker) stays within budget; pop entries
+    // until the marker fits (AC3.2 hard bound).
+    while (rendered.length > 0 && estimateTokens(out + omissionMarker(omitted)) > budget) {
+      const popped = rendered.pop();
+      if (popped) {
+        out = out.slice(0, out.length - renderEntryBlock(popped).length);
+        omitted += 1;
+      }
+    }
+    out += omissionMarker(omitted);
+  }
+
+  return {
+    path: repomapArtifactPath("."),
+    content: out,
+    entries: rendered,
+    tokens: estimateTokens(out),
+    omitted,
+  };
+}
+
+// Compute + persist `artifacts/repomap.md`. Re-running yields a byte-identical
+// file (deterministic ranking + rendering).
+export async function writeRepomap(
+  cwd: string,
+  graph: GraphData,
+  config: GdgraphConfig,
+  options: RepomapOptions = {},
+): Promise<RepomapResult> {
+  const result = computeRepomap(graph, config, options);
+  const artifactPath = repomapArtifactPath(cwd);
+  await mkdir(path.dirname(artifactPath), { recursive: true });
+  await writeFile(artifactPath, result.content, "utf8");
+  return { ...result, path: artifactPath };
+}

package/src/gdgraph/service.test.ts

@@ -0,0 +1,59 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "bun:test";
+import { createGdgraphService } from "./service";
+
+async function makeProject(): Promise<string> {
+  const root = await mkdtemp(path.join(tmpdir(), "keryx-svc-"));
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(path.join(root, "src", "a.ts"), "export const a = 1;\n");
+  await writeFile(path.join(root, "src", "b.ts"), "import { a } from './a';\nexport const b = a;\n");
+  await writeFile(path.join(root, "src", "c.ts"), "import { b } from './b';\nexport const c = b;\n");
+  return root;
+}
+
+test("AC5.3/T-1 — service.affected is a pure in-process method (transport-independent)", async () => {
+  const root = await makeProject();
+  try {
+    const service = createGdgraphService();
+    await service.build(root);
+    // depth 2 closure of a: b (hop1) + c (hop2).
+    const affected = await service.affected(root, "src/a.ts", { depth: 2 });
+    expect(affected.dependents).toEqual(["src/b.ts", "src/c.ts"]);
+    // default depth (config) = 1 ⇒ only direct dependents.
+    const shallow = await service.affected(root, "src/a.ts");
+    expect(shallow.dependents).toEqual(["src/b.ts"]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("AC5.3/T-1 — service.repomap writes artifacts/repomap.md deterministically", async () => {
+  const root = await makeProject();
+  try {
+    const service = createGdgraphService();
+    await service.build(root);
+    const first = await service.repomap(root, { budget: 2000 });
+    expect(first.path).toContain(path.join("artifacts", "repomap.md"));
+    expect(first.tokens).toBeLessThanOrEqual(2000);
+    const second = await service.repomap(root, { budget: 2000 });
+    expect(second.content).toBe(first.content);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("service.query returns cycles + orphans over the built graph", async () => {
+  const root = await makeProject();
+  try {
+    const service = createGdgraphService();
+    await service.build(root);
+    const cycles = await service.query(root, "cycles");
+    expect(Array.isArray(cycles)).toBe(true);
+    const orphans = await service.query(root, "orphans");
+    expect(Array.isArray(orphans)).toBe(true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/gdgraph/service.ts

@@ -0,0 +1,51 @@
+// Canonical in-process gdgraph service facade (specification.md §7; T-B1, M-2).
+//
+// `createGdgraphService()` is the transport-independent contract Block A's MCP
+// Tools wrap (`gdgraph.affected`, etc.) — no new logic lives in `mcp/`. Every
+// method is pure over storage + config (no network, no optional dep on the
+// default path) and unit-testable without any transport (T-1).
+
+import { buildGraph } from "./build";
+import { computeAffected, type AffectedOptions, type AffectedResult } from "./affected";
+import { loadGdgraphConfig } from "./config";
+import { getCycles, getOrphans, loadGraph } from "./query";
+import { writeRepomap, type RepomapOptions, type RepomapResult } from "./repomap";
+import type { GraphData } from "./types";
+
+export interface GdgraphService {
+  build(cwd: string): Promise<{ nodes: number; edges: number; summaryPath: string }>;
+  loadGraph(cwd: string): Promise<GraphData>;
+  affected(cwd: string, target: string, options?: AffectedOptions): Promise<AffectedResult>;
+  repomap(cwd: string, options?: RepomapOptions): Promise<RepomapResult>;
+  query(cwd: string, q: "cycles" | "orphans"): Promise<string[] | string[][]>;
+}
+
+export function createGdgraphService(): GdgraphService {
+  return {
+    async build(cwd) {
+      return buildGraph(cwd);
+    },
+
+    async loadGraph(cwd) {
+      return loadGraph(cwd);
+    },
+
+    async affected(cwd, target, options = {}) {
+      const config = await loadGdgraphConfig(cwd);
+      const graph = await loadGraph(cwd);
+      const depth = options.depth ?? config.affected.defaultDepth;
+      return computeAffected(graph, target, { ...options, depth });
+    },
+
+    async repomap(cwd, options = {}) {
+      const config = await loadGdgraphConfig(cwd);
+      const graph = await loadGraph(cwd);
+      return writeRepomap(cwd, graph, config, options);
+    },
+
+    async query(cwd, q) {
+      const graph = await loadGraph(cwd);
+      return q === "cycles" ? getCycles(graph) : getOrphans(graph);
+    },
+  };
+}

package/src/gdgraph/staleness.ts

@@ -0,0 +1,20 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+
+// Cheap, low-noise graph-staleness signal: the graph is "maybe stale" when the
+// repo's `.git/HEAD` (which changes on commit / branch switch) is newer than the
+// built graph storage. Unlike "uncommitted changes", this does NOT fire on every
+// working-tree edit during active development — only after the repo state moved
+// since the last build. Best-effort: any error ⇒ not stale (never warns wrongly).
+export async function graphMaybeStale(cwd: string): Promise<boolean> {
+  const nodes = path.join(cwd, ".metaproject", "data", "gdgraph", "storage", "nodes.jsonl");
+  const head = path.join(cwd, ".git", "HEAD");
+  try {
+    const [nodesStat, headStat] = await Promise.all([stat(nodes), stat(head)]);
+    return headStat.mtimeMs > nodesStat.mtimeMs;
+  } catch {
+    return false;
+  }
+}
+
+export const STALE_NOTE = "note: repo moved since the last graph build — `keryx gdgraph build` to refresh.";

package/src/gdgraph/symbol.test.ts

@@ -0,0 +1,89 @@
+import { expect, test } from "bun:test";
+import { querySymbol, resolveSymbols, transitiveCallers } from "./symbol";
+import type { GraphData, SymbolNode, CallEdge } from "./types";
+
+function sym(id: string, name: string, path: string, startLine: number): SymbolNode {
+  return { id, kind: "function", path, name, container: null, startLine, endLine: startLine + 5, language: "typescript" };
+}
+function call(from: string, to: string, resolved: boolean): CallEdge {
+  return { id: `${from}->${to}`, from, to, kind: resolved ? "calls" : "unresolved-call", resolved };
+}
+
+const A = sym("src/a.ts#foo", "foo", "src/a.ts", 10);
+const B = sym("src/b.ts#bar", "bar", "src/b.ts", 20);
+const C = sym("src/c.ts#Foo", "Foo", "src/c.ts", 5);
+
+const GRAPH: GraphData = {
+  nodes: [],
+  edges: [],
+  symbols: [A, B, C],
+  calls: [
+    call("src/b.ts#bar", "src/a.ts#foo", true), // bar calls foo
+    call("src/a.ts#foo", "src/c.ts#Foo", true), // foo calls Foo
+    call("src/a.ts#foo", "someUnknown.method", false), // foo calls unresolved
+  ],
+};
+
+test("resolveSymbols prefers exact name, then case-insensitive, then substring", () => {
+  expect(resolveSymbols(GRAPH.symbols!, "foo").map((s) => s.id)).toEqual(["src/a.ts#foo"]);
+  // case-insensitive tier only when no exact: "FOO" -> foo (exact 'foo'? no; ci matches foo AND Foo)
+  const ci = resolveSymbols(GRAPH.symbols!, "FOO").map((s) => s.name).sort();
+  expect(ci).toEqual(["Foo", "foo"]);
+  // substring tier
+  expect(resolveSymbols(GRAPH.symbols!, "ba").map((s) => s.name)).toEqual(["bar"]);
+});
+
+test("querySymbol returns definition, callers, and callees", () => {
+  const r = querySymbol(GRAPH, "foo");
+  expect(r.definitions.map((d) => d.id)).toEqual(["src/a.ts#foo"]);
+  // bar calls foo -> caller
+  expect(r.callers.map((c) => c.label)).toEqual(["bar (src/b.ts:20)"]);
+  // foo calls Foo (resolved) + someUnknown.method (unresolved)
+  const labels = r.callees.map((c) => c.label);
+  expect(labels).toContain("Foo (src/c.ts:5)");
+  expect(labels).toContain("someUnknown.method");
+  const unresolved = r.callees.find((c) => c.label === "someUnknown.method");
+  expect(unresolved?.resolved).toBe(false);
+});
+
+test("querySymbol on no match returns empty definitions", () => {
+  expect(querySymbol(GRAPH, "nonexistent").definitions).toEqual([]);
+});
+
+test("querySymbol tolerates a graph with no symbol layer", () => {
+  const r = querySymbol({ nodes: [], edges: [] }, "foo");
+  expect(r.definitions).toEqual([]);
+  expect(r.callers).toEqual([]);
+});
+
+test("transitiveCallers walks the reverse call graph with hop distances", () => {
+  // chain: baz -> bar -> foo (bar calls foo, baz calls bar)
+  const graph: GraphData = {
+    nodes: [],
+    edges: [],
+    symbols: [A, B, sym("src/d.ts#baz", "baz", "src/d.ts", 40)],
+    calls: [
+      call("src/b.ts#bar", "src/a.ts#foo", true),
+      call("src/d.ts#baz", "src/b.ts#bar", true),
+    ],
+  };
+  const impact = transitiveCallers(graph, ["src/a.ts#foo"], 5);
+  const byName = Object.fromEntries(impact.map((n) => [n.label.split(" ")[0], n.hop]));
+  expect(byName["bar"]).toBe(1);
+  expect(byName["baz"]).toBe(2);
+  expect(impact.some((n) => n.label.startsWith("foo"))).toBe(false); // seed excluded
+});
+
+test("transitiveCallers respects maxDepth", () => {
+  const graph: GraphData = {
+    nodes: [],
+    edges: [],
+    symbols: [A, B, sym("src/d.ts#baz", "baz", "src/d.ts", 40)],
+    calls: [
+      call("src/b.ts#bar", "src/a.ts#foo", true),
+      call("src/d.ts#baz", "src/b.ts#bar", true),
+    ],
+  };
+  const impact = transitiveCallers(graph, ["src/a.ts#foo"], 1);
+  expect(impact.map((n) => n.label.split(" ")[0])).toEqual(["bar"]); // baz is hop 2, excluded
+});

package/src/gdgraph/symbol.ts

@@ -0,0 +1,123 @@
+import type { CallEdge, GraphData, SymbolNode } from "./types";
+
+// Symbol-level query over the (optional) tree-sitter layer: "where is X defined /
+// who calls X / what does X call". Pure over the in-memory graph; the CLI layer
+// handles the "symbol layer not active" case when `graph.symbols` is absent.
+
+export interface SymbolRef {
+  // Display label: "name (path:line)" for a resolved symbol, else the raw token.
+  label: string;
+  resolved: boolean;
+}
+
+export interface SymbolQueryResult {
+  query: string;
+  definitions: SymbolNode[];
+  callers: SymbolRef[];
+  callees: SymbolRef[];
+}
+
+// Resolve a name to matching symbols: exact name, then case-insensitive, then
+// substring — stopping at the first tier that yields hits so precise names win.
+export function resolveSymbols(symbols: SymbolNode[], name: string, limit = 25): SymbolNode[] {
+  const q = name.trim();
+  if (!q) return [];
+  const lower = q.toLowerCase();
+
+  const exact = symbols.filter((s) => s.name === q);
+  if (exact.length > 0) return exact.slice(0, limit);
+
+  const ci = symbols.filter((s) => s.name.toLowerCase() === lower);
+  if (ci.length > 0) return ci.slice(0, limit);
+
+  return symbols.filter((s) => s.name.toLowerCase().includes(lower)).slice(0, limit);
+}
+
+function labelFor(token: string, byId: Map<string, SymbolNode>): SymbolRef {
+  const symbol = byId.get(token);
+  if (symbol) {
+    return { label: `${symbol.name} (${symbol.path}:${symbol.startLine})`, resolved: true };
+  }
+  return { label: token, resolved: false };
+}
+
+function dedupeRefs(refs: SymbolRef[]): SymbolRef[] {
+  const seen = new Set<string>();
+  const out: SymbolRef[] = [];
+  for (const ref of refs) {
+    if (seen.has(ref.label)) continue;
+    seen.add(ref.label);
+    out.push(ref);
+  }
+  return out;
+}
+
+export interface ImpactNode {
+  label: string;
+  hop: number;
+}
+
+// Transitive caller blast radius over the call graph: "if I change these
+// symbols, which symbols (transitively) call them" — the symbol-level impact
+// that file-level `affected` cannot express. Reverse BFS over resolved call
+// edges up to `maxDepth`, nearest hop wins, seeds excluded.
+export function transitiveCallers(
+  graph: GraphData,
+  seedIds: string[],
+  maxDepth: number,
+): ImpactNode[] {
+  const calls = (graph.calls ?? []).filter((c) => c.kind === "calls");
+  const byId = new Map((graph.symbols ?? []).map((s) => [s.id, s]));
+  // callee id -> set of caller ids
+  const callersOf = new Map<string, Set<string>>();
+  for (const call of calls) {
+    if (!callersOf.has(call.to)) callersOf.set(call.to, new Set());
+    callersOf.get(call.to)!.add(call.from);
+  }
+
+  const hop = new Map<string, number>();
+  let frontier = new Set(seedIds);
+  for (const seed of seedIds) hop.set(seed, 0);
+
+  for (let depth = 1; depth <= maxDepth; depth += 1) {
+    const next = new Set<string>();
+    for (const id of frontier) {
+      for (const caller of callersOf.get(id) ?? []) {
+        if (!hop.has(caller)) {
+          hop.set(caller, depth);
+          next.add(caller);
+        }
+      }
+    }
+    if (next.size === 0) break;
+    frontier = next;
+  }
+
+  const out: ImpactNode[] = [];
+  for (const [id, h] of hop) {
+    if (h === 0) continue; // exclude the seeds themselves
+    const symbol = byId.get(id);
+    if (symbol) {
+      out.push({ label: `${symbol.name} (${symbol.path}:${symbol.startLine})`, hop: h });
+    }
+  }
+  return out.sort((a, b) => a.hop - b.hop || a.label.localeCompare(b.label));
+}
+
+export function querySymbol(graph: GraphData, name: string): SymbolQueryResult {
+  const symbols = graph.symbols ?? [];
+  const calls = graph.calls ?? [];
+  const definitions = resolveSymbols(symbols, name);
+  const ids = new Set(definitions.map((s) => s.id));
+  const byId = new Map(symbols.map((s) => [s.id, s]));
+
+  const callEdges = calls.filter((c: CallEdge) => c.kind === "calls" || c.kind === "unresolved-call");
+  const callers = dedupeRefs(
+    callEdges.filter((c) => ids.has(c.to)).map((c) => labelFor(c.from, byId)),
+  ).sort((a, b) => a.label.localeCompare(b.label));
+  const callees = dedupeRefs(
+    callEdges.filter((c) => ids.has(c.from)).map((c) => labelFor(c.to, byId)),
+  ).sort((a, b) => a.label.localeCompare(b.label));
+
+  return { query: name, definitions, callers, callees };
+}

package/src/gdgraph/symbols-capability.test.ts

@@ -0,0 +1,41 @@
+import { expect, test } from "bun:test";
+import { isTreesitterEnabled, setTreesitterEnabled, TREESITTER_CAPABILITY } from "./symbols-capability";
+
+test("enable adds the capability entry to an empty manifest", () => {
+  const next = setTreesitterEnabled({}, true);
+  expect(isTreesitterEnabled(next)).toBe(true);
+  const caps = (next.modules as any).gdgraph.capabilities;
+  expect(caps).toHaveLength(1);
+  expect(caps[0]).toMatchObject({ id: TREESITTER_CAPABILITY, enabled: true, kind: "ceiling" });
+});
+
+test("disable flips enabled to false", () => {
+  const enabled = setTreesitterEnabled({}, true);
+  const disabled = setTreesitterEnabled(enabled, false);
+  expect(isTreesitterEnabled(disabled)).toBe(false);
+});
+
+test("is idempotent — never duplicates the capability entry", () => {
+  let m: Record<string, unknown> = {};
+  m = setTreesitterEnabled(m, true);
+  m = setTreesitterEnabled(m, true);
+  const caps = (m.modules as any).gdgraph.capabilities.filter(
+    (c: any) => c.id === TREESITTER_CAPABILITY,
+  );
+  expect(caps).toHaveLength(1);
+});
+
+test("preserves other gdgraph capabilities and other modules", () => {
+  const manifest = {
+    modules: {
+      gdgraph: { enabled: true, capabilities: [{ id: "gdgraph.other", enabled: true }] },
+      security: { enabled: true },
+    },
+    schemaVersion: 1,
+  };
+  const next = setTreesitterEnabled(manifest, true) as any;
+  const ids = next.modules.gdgraph.capabilities.map((c: any) => c.id).sort();
+  expect(ids).toEqual(["gdgraph.other", "gdgraph.treesitter"]);
+  expect(next.modules.security).toEqual({ enabled: true });
+  expect(next.schemaVersion).toBe(1);
+});

package/src/gdgraph/symbols-capability.ts

@@ -0,0 +1,49 @@
+// Enable/disable the `gdgraph.treesitter` capability in a parsed
+// `metaproject.json` — the opt-in switch for the symbol layer. Pure manifest
+// transforms (the command layer owns file IO), merge-safe: preserves any other
+// gdgraph capabilities and never rewrites unrelated modules.
+
+export const TREESITTER_CAPABILITY = "gdgraph.treesitter";
+
+type Json = Record<string, unknown>;
+
+function treesitterEntry(enabled: boolean): Json {
+  return {
+    id: TREESITTER_CAPABILITY,
+    enabled,
+    kind: "ceiling",
+    optionalDependency: "web-tree-sitter",
+  };
+}
+
+// Return a new manifest with the gdgraph.treesitter capability set to `enabled`,
+// adding the gdgraph module capabilities array if absent. Other capabilities and
+// modules are preserved untouched.
+export function setTreesitterEnabled(manifest: Json, enabled: boolean): Json {
+  const modules =
+    typeof manifest.modules === "object" && manifest.modules !== null
+      ? { ...(manifest.modules as Json) }
+      : {};
+  const gdgraph =
+    typeof modules.gdgraph === "object" && modules.gdgraph !== null
+      ? { ...(modules.gdgraph as Json) }
+      : {};
+
+  const existing = Array.isArray(gdgraph.capabilities) ? (gdgraph.capabilities as unknown[]) : [];
+  const others = existing.filter(
+    (c) => !(c && typeof c === "object" && (c as Json).id === TREESITTER_CAPABILITY),
+  );
+  gdgraph.capabilities = [...others, treesitterEntry(enabled)];
+  modules.gdgraph = gdgraph;
+  return { ...manifest, modules };
+}
+
+// Whether the manifest has gdgraph.treesitter enabled.
+export function isTreesitterEnabled(manifest: Json): boolean {
+  const modules = manifest.modules as Json | undefined;
+  const gdgraph = modules?.gdgraph as Json | undefined;
+  const caps = Array.isArray(gdgraph?.capabilities) ? (gdgraph?.capabilities as unknown[]) : [];
+  return caps.some(
+    (c) => c && typeof c === "object" && (c as Json).id === TREESITTER_CAPABILITY && (c as Json).enabled === true,
+  );
+}

package/src/gdgraph/target.ts

@@ -0,0 +1,56 @@
+// Shared graph-target resolution for `affected` / `getAffected`.
+//
+// Both entry points used to resolve a user-supplied path with ONE predicate:
+//
+//   nodes.find(n => n.path === normalized || n.path.endsWith(normalized))
+//
+// which has two defects. `find` returns the FIRST hit in node order, so a suffix
+// match that sorts earlier beats a later exact match — with a nested checkout in
+// the graph, `src/lib/fs.ts` resolved to `.claude/worktrees/<wt>/src/lib/fs.ts`.
+// And `endsWith` is not path-segment aware, so `fs.ts` also matches `myfs.ts`.
+// Worst of all, an ambiguous target was silently resolved to one arbitrary
+// candidate and the answer was reported as if it were exact.
+//
+// Resolution is now two-pass — exact match first, then a suffix match anchored to
+// a `/` boundary — and an ambiguous suffix REFUSES rather than guessing, the way
+// `resolveFlowDir` does (`src/flow/store.ts:86`). Acting on a guessed node is how
+// a blast-radius answer ends up describing a different file than the caller asked
+// about.
+
+import path from "node:path";
+import type { GraphData } from "./types";
+
+export function normalizeTarget(target: string): string {
+  return target.replace(/^\.\//, "").split(path.sep).join("/");
+}
+
+// Resolve `target` to a node path. Returns the normalized target unchanged when
+// nothing matches (callers then report an empty blast radius, as before).
+// Throws when the target is an ambiguous suffix of several distinct nodes.
+export function resolveGraphTarget(graph: GraphData, target: string): string {
+  const normalized = normalizeTarget(target);
+
+  // Pass 1 — exact path. An exact match is never ambiguous and always wins.
+  if (graph.nodes.some((item) => item.path === normalized)) {
+    return normalized;
+  }
+
+  // Pass 2 — suffix match on a `/` boundary, so `lib/fs.ts` matches
+  // `src/lib/fs.ts` but `fs.ts` does not match `src/lib/myfs.ts`.
+  const suffix = `/${normalized}`;
+  const candidates = [
+    ...new Set(
+      graph.nodes.filter((item) => item.path.endsWith(suffix)).map((item) => item.path),
+    ),
+  ].sort();
+
+  if (candidates.length > 1) {
+    throw new Error(
+      `Graph target "${target}" is ambiguous — ${candidates.length} files match it:\n` +
+        candidates.map((candidate) => `  - ${candidate}`).join("\n") +
+        "\nRe-run with the full repository-relative path.",
+    );
+  }
+
+  return candidates[0] ?? normalized;
+}