feat(mcp): wire reverse callee index into CLI refs and MCP adapter

Replace broken semantic-search caller detection with reverse index
lookups. Both CLI refs and MCP refs adapter now use lookupCallers/
lookupClassCallers from core instead of searching for the target name
and scanning 100 candidates' callees.

- CLI refs: loads reverse index via loadOrBuildGraph, uses lookupCallers
- MCP refs adapter: caches reverse + name index alongside graph (60s TTL)
- getCallersFromIndex replaces getCallers (no more SearchService call)
- loadOrBuildGraph fallback now builds reverse index from docs
- getDependencyGraph handles missing indexer gracefully
- Updated refs-adapter tests with mock indexer for reverse index

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

Author: prosdev

packages/cli/src/commands/refs.ts

@@ -1,9 +1,12 @@
 import * as path from 'node:path';
 import {
+  buildNameIndex,
   ensureStorageDirectory,
   getStorageFilePaths,
   getStoragePath,
   loadOrBuildGraph,
+  lookupCallers,
+  lookupClassCallers,
   RepositoryIndexer,
   type SearchResult,
   shortestPath,
@@ -109,32 +112,26 @@ export const refsCommand = new Command('refs')
         callees = (rawCallees || []).slice(0, limit);
       }
 
-      // Get callers
+      // Get callers from reverse index
       const callers: Array<{ name: string; file?: string; line: number; type?: string }> = [];
       if (direction === 'callers' || direction === 'both') {
-        const targetName = target.metadata.name as string;
-        const candidates = await indexer.search(targetName, { limit: 100 });
-
-        for (const candidate of candidates) {
-          if (candidate.id === target.id) continue;
-          const candidateCallees = candidate.metadata.callees as CalleeInfo[] | undefined;
-          if (!candidateCallees) continue;
-
-          const callsTarget = candidateCallees.some(
-            (c) =>
-              c.name === targetName ||
-              c.name.endsWith(`.${targetName}`) ||
-              targetName.endsWith(`.${c.name}`)
-          );
+        const { reverseIndex } = await loadOrBuildGraph(filePaths.dependencyGraph, async () =>
+          indexer.getAll({ limit: 50000 })
+        );
+
+        if (reverseIndex) {
+          const nameIndex = buildNameIndex(reverseIndex);
+          const targetName = (target.metadata.name as string) || '';
+          const targetFile = (target.metadata.path as string) || '';
+          const targetType = target.metadata.type as string;
+
+          const found =
+            targetType === 'class'
+              ? lookupClassCallers(reverseIndex, nameIndex, targetName, targetFile, limit)
+              : lookupCallers(reverseIndex, nameIndex, targetName, targetFile, limit);
 
-          if (callsTarget) {
-            callers.push({
-              name: (candidate.metadata.name as string) || 'unknown',
-              file: candidate.metadata.path as string,
-              line: (candidate.metadata.startLine as number) || 0,
-              type: candidate.metadata.type as string,
-            });
-            if (callers.length >= limit) break;
+          for (const c of found) {
+            callers.push({ name: c.name, file: c.file, line: c.line, type: c.type });
           }
         }
       }

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

@@ -448,7 +448,9 @@ describe('loadOrBuildGraph', () => {
 
     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
+    // Fallback builds reverse index from the same docs
+    expect(result.reverseIndex).not.toBeNull();
+    expect(result.reverseIndex!.get('src/b.ts:foo')).toBeDefined();
   });
 
   it('should call fallback when graphPath file does not exist', async () => {

packages/core/src/map/graph.ts

@@ -13,6 +13,7 @@
 
 import * as fs from 'node:fs/promises';
 import type { SearchResult } from '../vector/types';
+import { buildReverseCalleeIndex } from './reverse-index';
 import type { CallerEntry } from './types';
 
 // ============================================================================
@@ -377,7 +378,10 @@ export async function loadOrBuildGraph(
   }
 
   const docs = await fallbackDocs();
-  return { graph: buildDependencyGraph(docs), reverseIndex: null };
+  return {
+    graph: buildDependencyGraph(docs),
+    reverseIndex: docs.length > 0 ? buildReverseCalleeIndex(docs) : null,
+  };
 }
 
 // ============================================================================

packages/mcp-server/src/adapters/__tests__/refs-adapter.test.ts

@@ -74,9 +74,17 @@ describe('RefsAdapter', () => {
       search: vi.fn().mockResolvedValue(mockSearchResults),
     } as unknown as SearchService;
 
-    // Create adapter
+    // Create mock indexer for reverse index building
+    const mockIndexer = {
+      getAll: vi.fn().mockResolvedValue(mockSearchResults),
+      initialize: vi.fn(),
+      close: vi.fn(),
+    };
+
+    // Create adapter with indexer so reverse index can be built
     adapter = new RefsAdapter({
       searchService: mockSearchService,
+      indexer: mockIndexer as any,
       defaultLimit: 20,
     });
 
@@ -349,8 +357,14 @@ describe('RefsAdapter', () => {
     });
 
     it('should return error when indexer is not available', async () => {
-      // The base adapter (no indexer) should fail for dependsOn
-      const result = await adapter.execute(
+      // Create an adapter without indexer — dependsOn requires it
+      const adapterNoIndexer = new RefsAdapter({
+        searchService: mockSearchService,
+        defaultLimit: 20,
+      });
+      await adapterNoIndexer.initialize(context);
+
+      const result = await adapterNoIndexer.execute(
         { name: 'createPlan', dependsOn: 'src/api.ts' },
         execContext
       );

packages/mcp-server/src/adapters/built-in/refs-adapter.ts

@@ -5,11 +5,18 @@
 
 import type {
   CalleeInfo,
+  CallerEntry,
   RepositoryIndexer,
   SearchResult,
   SearchService,
 } from '@prosdevlab/dev-agent-core';
-import { loadOrBuildGraph, shortestPath } from '@prosdevlab/dev-agent-core';
+import {
+  buildNameIndex,
+  loadOrBuildGraph,
+  lookupCallers,
+  lookupClassCallers,
+  shortestPath,
+} from '@prosdevlab/dev-agent-core';
 import { estimateTokensForText, startTimer } from '../../formatters/utils';
 import { RefsArgsSchema } from '../../schemas/index.js';
 import { ToolAdapter } from '../tool-adapter';
@@ -78,6 +85,8 @@ export class RefsAdapter extends ToolAdapter {
   private indexer?: RepositoryIndexer;
   private graphPath?: string;
   private cachedGraph?: Map<string, import('@prosdevlab/dev-agent-core').WeightedEdge[]>;
+  private cachedReverseIndex: Map<string, CallerEntry[]> | null = null;
+  private cachedNameIndex: Map<string, string[]> | null = null;
   private cachedGraphTime = 0;
 
   constructor(config: RefsAdapterConfig) {
@@ -110,8 +119,9 @@ export class RefsAdapter extends ToolAdapter {
     }
 
     const result = await loadOrBuildGraph(this.graphPath, async () => {
+      if (!this.indexer) return [];
       const DOC_LIMIT = 50_000;
-      const allDocs = await this.indexer!.getAll({ limit: DOC_LIMIT });
+      const allDocs = await this.indexer.getAll({ limit: DOC_LIMIT });
       if (allDocs.length >= DOC_LIMIT) {
         console.error(
           `[dev-agent] Warning: dependency graph hit ${DOC_LIMIT} doc limit. Results may be incomplete.`
@@ -120,6 +130,8 @@ export class RefsAdapter extends ToolAdapter {
       return allDocs;
     });
     this.cachedGraph = result.graph;
+    this.cachedReverseIndex = result.reverseIndex;
+    this.cachedNameIndex = result.reverseIndex ? buildNameIndex(result.reverseIndex) : null;
     this.cachedGraphTime = Date.now();
     return this.cachedGraph;
   }
@@ -251,7 +263,9 @@ export class RefsAdapter extends ToolAdapter {
 
       // Get callers if requested
       if (direction === 'callers' || direction === 'both') {
-        result.callers = await this.getCallers(target, limit);
+        // Ensure graph (and reverse index) is loaded before looking up callers
+        await this.getDependencyGraph();
+        result.callers = this.getCallersFromIndex(target, limit);
       }
 
       const content = this.formatOutput(result, direction);
@@ -322,47 +336,39 @@ export class RefsAdapter extends ToolAdapter {
   }
 
   /**
-   * Find callers by searching all indexed components for callees that reference the target
+   * Find callers using the reverse callee index.
+   * Falls back to empty results if no reverse index is available (v1 graph).
    */
-  private async getCallers(target: SearchResult, limit: number): Promise<RefResult[]> {
-    const targetName = target.metadata.name;
-    if (!targetName) return [];
-
-    // Search for components that might call this target
-    // We search broadly and then filter by callees
-    const candidates = await this.searchService.search(targetName, { limit: 100 });
-
-    const callers: RefResult[] = [];
-
-    for (const candidate of candidates) {
-      // Skip the target itself
-      if (candidate.id === target.id) continue;
-
-      const callees = candidate.metadata.callees as CalleeInfo[] | undefined;
-      if (!callees) continue;
-
-      // Check if any callee matches our target
-      const callsTarget = callees.some(
-        (c) =>
-          c.name === targetName ||
-          c.name.endsWith(`.${targetName}`) ||
-          targetName.endsWith(`.${c.name}`)
-      );
-
-      if (callsTarget) {
-        callers.push({
-          name: candidate.metadata.name || 'unknown',
-          file: candidate.metadata.path,
-          line: candidate.metadata.startLine || 0,
-          type: candidate.metadata.type as string,
-          snippet: candidate.metadata.signature as string | undefined,
-        });
-
-        if (callers.length >= limit) break;
-      }
-    }
-
-    return callers;
+  private getCallersFromIndex(target: SearchResult, limit: number): RefResult[] {
+    if (!this.cachedReverseIndex || !this.cachedNameIndex) return [];
+
+    const targetName = (target.metadata.name as string) || '';
+    const targetFile = (target.metadata.path as string) || '';
+    const targetType = target.metadata.type as string;
+
+    const callers =
+      targetType === 'class'
+        ? lookupClassCallers(
+            this.cachedReverseIndex,
+            this.cachedNameIndex,
+            targetName,
+            targetFile,
+            limit
+          )
+        : lookupCallers(
+            this.cachedReverseIndex,
+            this.cachedNameIndex,
+            targetName,
+            targetFile,
+            limit
+          );
+
+    return callers.map((c) => ({
+      name: c.name,
+      file: c.file,
+      line: c.line,
+      type: c.type,
+    }));
   }
 
   /**