feat(core): build and persist reverse callee index in graph v2

Add reverse callee index that maps callee names to their callers.
Built at index time from the same scan data as the dependency graph,
persisted inside dependency-graph.json as v2 format (single atomic
write prevents drift). Compound keys (file:name) for TS, bare names
for tree-sitter languages. Secondary name index for O(1) bare-name
lookups. Incremental updates via updateReverseIndexIncremental.

- New module: packages/core/src/map/reverse-index.ts
- CachedGraph v1→v2 (backward compatible — v1 loads with null reverse)
- serializeGraph/deserializeGraph updated for v2
- loadOrBuildGraph returns { graph, reverseIndex }
- All callers updated: map/index.ts, cli/refs.ts, refs-adapter.ts,
  incremental-indexer.ts
- 25 new tests in reverse-index.test.ts

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: prosdev

packages/cli/src/commands/refs.ts

@@ -70,7 +70,7 @@ export const refsCommand = new Command('refs')
       // Handle --depends-on
       if (options.dependsOn) {
         spinner.text = `Tracing path: ${name} → ${options.dependsOn}`;
-        const graph = await loadOrBuildGraph(filePaths.dependencyGraph, async () =>
+        const { graph } = await loadOrBuildGraph(filePaths.dependencyGraph, async () =>
           indexer.getAll({ limit: 50000 })
         );
         const sourceFile = (target.metadata.path as string) || '';

packages/core/src/indexer/index.ts

@@ -11,6 +11,7 @@ import * as path from 'node:path';
 import type { Logger } from '@prosdevlab/kero';
 import type { EventBus } from '../events/types.js';
 import { buildDependencyGraph, serializeGraph } from '../map/graph';
+import { buildReverseCalleeIndex } from '../map/reverse-index';
 import { scanRepository } from '../scanner';
 import { getStorageFilePaths } from '../storage/path';
 import type { EmbeddingDocument, LinearMergeResult, SearchOptions, SearchResult } from '../vector';
@@ -196,10 +197,14 @@ export class RepositoryIndexer {
           metadata: d.metadata,
         }));
         const graph = buildDependencyGraph(graphDocs);
+        const reverseIndex = buildReverseCalleeIndex(graphDocs);
         const storagePath = path.dirname(this.config.vectorStorePath);
         const graphPath = getStorageFilePaths(storagePath).dependencyGraph;
-        await fs.writeFile(graphPath, serializeGraph(graph), 'utf-8');
-        logger?.info({ nodes: graph.size }, 'Dependency graph cached');
+        await fs.writeFile(graphPath, serializeGraph(graph, reverseIndex), 'utf-8');
+        logger?.info(
+          { nodes: graph.size, reverseIndexKeys: reverseIndex.size },
+          'Dependency graph + reverse index cached'
+        );
       } catch (graphError) {
         // Non-fatal — graph is a performance optimization, not required
         logger?.warn({ error: graphError }, 'Failed to cache dependency graph');

packages/core/src/map/__tests__/graph.test.ts

@@ -343,34 +343,69 @@ describe('shortestPath', () => {
 // ============================================================================
 
 describe('serializeGraph / deserializeGraph', () => {
-  it('should round-trip correctly', () => {
+  it('should round-trip graph correctly', () => {
     const graph = new Map<string, WeightedEdge[]>();
     graph.set('src/a.ts', [edge('src/b.ts', 1.5), edge('src/c.ts', 1)]);
     graph.set('src/b.ts', [edge('src/c.ts', 2)]);
 
     const json = serializeGraph(graph);
-    const restored = deserializeGraph(json);
+    const result = deserializeGraph(json);
 
-    expect(restored).not.toBeNull();
-    expect(restored!.size).toBe(2);
-    expect(restored!.get('src/a.ts')).toEqual([
+    expect(result).not.toBeNull();
+    expect(result!.graph.size).toBe(2);
+    expect(result!.graph.get('src/a.ts')).toEqual([
       { target: 'src/b.ts', weight: 1.5 },
       { target: 'src/c.ts', weight: 1 },
     ]);
-    expect(restored!.get('src/b.ts')).toEqual([{ target: 'src/c.ts', weight: 2 }]);
+    expect(result!.graph.get('src/b.ts')).toEqual([{ target: 'src/c.ts', weight: 2 }]);
   });
 
-  it('should include metadata in serialized JSON', () => {
+  it('should round-trip graph + reverse index (v2)', () => {
+    const graph = new Map([['a.ts', [edge('b.ts')]]]);
+    const reverseIndex = new Map([
+      ['b.ts:funcB', [{ name: 'funcA', file: 'a.ts', line: 5, type: 'function' }]],
+    ]);
+
+    const json = serializeGraph(graph, reverseIndex);
+    const result = deserializeGraph(json);
+
+    expect(result!.graph).toEqual(graph);
+    expect(result!.reverseIndex).toEqual(reverseIndex);
+  });
+
+  it('should serialize as v2', () => {
     const graph = new Map<string, WeightedEdge[]>();
     graph.set('a', [edge('b')]);
 
     const parsed = JSON.parse(serializeGraph(graph));
-    expect(parsed.version).toBe(1);
+    expect(parsed.version).toBe(2);
     expect(parsed.nodeCount).toBe(1);
     expect(parsed.edgeCount).toBe(1);
     expect(parsed.generatedAt).toBeTruthy();
   });
 
+  it('should accept generatedAt parameter for testability', () => {
+    const graph = new Map<string, WeightedEdge[]>();
+    const json = serializeGraph(graph, undefined, '2026-01-01T00:00:00Z');
+    const parsed = JSON.parse(json);
+    expect(parsed.generatedAt).toBe('2026-01-01T00:00:00Z');
+  });
+
+  it('should deserialize v1 graph with null reverse index', () => {
+    const v1Json = JSON.stringify({
+      version: 1,
+      generatedAt: '',
+      nodeCount: 1,
+      edgeCount: 1,
+      graph: { 'a.ts': [{ target: 'b.ts', weight: 1 }] },
+    });
+    const result = deserializeGraph(v1Json);
+
+    expect(result).not.toBeNull();
+    expect(result!.graph.size).toBe(1);
+    expect(result!.reverseIndex).toBeNull();
+  });
+
   it('should return null for invalid JSON', () => {
     expect(deserializeGraph('not json')).toBeNull();
   });
@@ -388,9 +423,9 @@ describe('serializeGraph / deserializeGraph', () => {
   it('should handle empty graph', () => {
     const graph = new Map<string, WeightedEdge[]>();
     const json = serializeGraph(graph);
-    const restored = deserializeGraph(json);
-    expect(restored).not.toBeNull();
-    expect(restored!.size).toBe(0);
+    const result = deserializeGraph(json);
+    expect(result).not.toBeNull();
+    expect(result!.graph.size).toBe(0);
   });
 });
 
@@ -411,8 +446,9 @@ describe('loadOrBuildGraph', () => {
       },
     ];
 
-    const graph = await loadOrBuildGraph(undefined, async () => fallbackDocs);
-    expect(graph.get('src/a.ts')).toBeDefined();
+    const result = await loadOrBuildGraph(undefined, async () => fallbackDocs);
+    expect(result.graph.get('src/a.ts')).toBeDefined();
+    expect(result.reverseIndex).toBeNull(); // fallback doesn't build reverse index
   });
 
   it('should call fallback when graphPath file does not exist', async () => {
@@ -427,8 +463,8 @@ describe('loadOrBuildGraph', () => {
       },
     ];
 
-    const graph = await loadOrBuildGraph('/nonexistent/path.json', async () => fallbackDocs);
-    expect(graph.get('src/x.ts')).toBeDefined();
+    const result = await loadOrBuildGraph('/nonexistent/path.json', async () => fallbackDocs);
+    expect(result.graph.get('src/x.ts')).toBeDefined();
   });
 });