feat(core,mcp): cached dependency graph for scale

Build dependency graph at index time and save as JSON. Load cached
graph in dev_map and dev_refs instead of fetching all docs via getAll.
Incremental graph updates via file watcher. Falls back to current
approach if cache is missing or corrupted.

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

Author: prosdev

packages/core/src/indexer/index.ts

@@ -10,7 +10,9 @@ import * as fs from 'node:fs/promises';
 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 { scanRepository } from '../scanner';
+import { getStorageFilePaths } from '../storage/path';
 import type { EmbeddingDocument, LinearMergeResult, SearchOptions, SearchResult } from '../vector';
 import { VectorStorage } from '../vector';
 import { StatsAggregator } from './stats-aggregator';
@@ -183,6 +185,23 @@ export class RepositoryIndexer {
         `Linear Merge complete: ${mergeResult.upserted} upserted, ${mergeResult.skipped} unchanged, ${mergeResult.deleted} removed`
       );
 
+      // Build and cache dependency graph
+      try {
+        const graphDocs = embeddingDocuments.map((d) => ({
+          id: d.id,
+          score: 0,
+          metadata: d.metadata,
+        }));
+        const graph = buildDependencyGraph(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');
+      } catch (graphError) {
+        // Non-fatal — graph is a performance optimization, not required
+        logger?.warn({ error: graphError }, 'Failed to cache dependency graph');
+      }
+
       // Phase 4: Complete
       const endTime = new Date();
       onProgress?.({

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

@@ -9,8 +9,12 @@ import { describe, expect, it } from 'vitest';
 import {
   buildDependencyGraph,
   connectedComponents,
+  deserializeGraph,
+  loadOrBuildGraph,
   pageRank,
+  serializeGraph,
   shortestPath,
+  updateGraphIncremental,
   type WeightedEdge,
 } from '../graph';
 
@@ -333,3 +337,178 @@ describe('shortestPath', () => {
     expect(shortestPath(new Map(), 'X', 'Y')).toBeNull();
   });
 });
+
+// ============================================================================
+// Serialization
+// ============================================================================
+
+describe('serializeGraph / deserializeGraph', () => {
+  it('should round-trip correctly', () => {
+    const graph = new Map<string, WeightedEdge[]>();
+    graph.set('src/a.ts', [edge('src/b.ts', 1.414), edge('src/c.ts', 1)]);
+    graph.set('src/b.ts', [edge('src/c.ts', 2)]);
+
+    const json = serializeGraph(graph);
+    const restored = deserializeGraph(json);
+
+    expect(restored).not.toBeNull();
+    expect(restored!.size).toBe(2);
+    expect(restored!.get('src/a.ts')).toEqual([
+      { target: 'src/b.ts', weight: 1.414 },
+      { target: 'src/c.ts', weight: 1 },
+    ]);
+    expect(restored!.get('src/b.ts')).toEqual([{ target: 'src/c.ts', weight: 2 }]);
+  });
+
+  it('should include metadata in serialized JSON', () => {
+    const graph = new Map<string, WeightedEdge[]>();
+    graph.set('a', [edge('b')]);
+
+    const parsed = JSON.parse(serializeGraph(graph));
+    expect(parsed.version).toBe(1);
+    expect(parsed.nodeCount).toBe(1);
+    expect(parsed.edgeCount).toBe(1);
+    expect(parsed.generatedAt).toBeTruthy();
+  });
+
+  it('should return null for invalid JSON', () => {
+    expect(deserializeGraph('not json')).toBeNull();
+  });
+
+  it('should return null for wrong version', () => {
+    const json = JSON.stringify({ version: 99, graph: {} });
+    expect(deserializeGraph(json)).toBeNull();
+  });
+
+  it('should return null for missing graph field', () => {
+    const json = JSON.stringify({ version: 1 });
+    expect(deserializeGraph(json)).toBeNull();
+  });
+
+  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);
+  });
+});
+
+// ============================================================================
+// loadOrBuildGraph
+// ============================================================================
+
+describe('loadOrBuildGraph', () => {
+  it('should call fallback when graphPath is undefined', async () => {
+    const fallbackDocs = [
+      {
+        id: '1',
+        score: 0,
+        metadata: {
+          path: 'src/a.ts',
+          callees: [{ name: 'foo', file: 'src/b.ts', line: 1 }],
+        },
+      },
+    ];
+
+    const graph = await loadOrBuildGraph(undefined, async () => fallbackDocs);
+    expect(graph.get('src/a.ts')).toBeDefined();
+  });
+
+  it('should call fallback when graphPath file does not exist', async () => {
+    const fallbackDocs = [
+      {
+        id: '1',
+        score: 0,
+        metadata: {
+          path: 'src/x.ts',
+          callees: [{ name: 'bar', file: 'src/y.ts', line: 1 }],
+        },
+      },
+    ];
+
+    const graph = await loadOrBuildGraph('/nonexistent/path.json', async () => fallbackDocs);
+    expect(graph.get('src/x.ts')).toBeDefined();
+  });
+});
+
+// ============================================================================
+// updateGraphIncremental
+// ============================================================================
+
+describe('updateGraphIncremental', () => {
+  it('should add edges for new files', () => {
+    const existing = new Map<string, WeightedEdge[]>();
+    existing.set('src/a.ts', [edge('src/b.ts')]);
+
+    const changedDocs = [
+      {
+        id: '1',
+        score: 0,
+        metadata: {
+          path: 'src/c.ts',
+          callees: [{ name: 'foo', file: 'src/d.ts', line: 1 }],
+        },
+      },
+    ];
+
+    const updated = updateGraphIncremental(existing, changedDocs, []);
+    expect(updated.get('src/a.ts')).toBeDefined(); // Kept
+    expect(updated.get('src/c.ts')).toBeDefined(); // Added
+  });
+
+  it('should remove edges for deleted files', () => {
+    const existing = new Map<string, WeightedEdge[]>();
+    existing.set('src/a.ts', [edge('src/b.ts')]);
+    existing.set('src/b.ts', [edge('src/c.ts')]);
+
+    const updated = updateGraphIncremental(existing, [], ['src/a.ts']);
+    expect(updated.has('src/a.ts')).toBe(false); // Removed
+    expect(updated.get('src/b.ts')).toBeDefined(); // Kept
+  });
+
+  it('should replace edges for changed files', () => {
+    const existing = new Map<string, WeightedEdge[]>();
+    existing.set('src/a.ts', [edge('src/old.ts')]);
+
+    const changedDocs = [
+      {
+        id: '1',
+        score: 0,
+        metadata: {
+          path: 'src/a.ts',
+          callees: [{ name: 'foo', file: 'src/new.ts', line: 1 }],
+        },
+      },
+    ];
+
+    const updated = updateGraphIncremental(existing, changedDocs, []);
+    const edges = updated.get('src/a.ts')!;
+    expect(edges.length).toBe(1);
+    expect(edges[0].target).toBe('src/new.ts'); // Replaced
+  });
+
+  it('should not mutate the existing graph', () => {
+    const existing = new Map<string, WeightedEdge[]>();
+    existing.set('src/a.ts', [edge('src/b.ts')]);
+
+    updateGraphIncremental(existing, [], ['src/a.ts']);
+    expect(existing.has('src/a.ts')).toBe(true); // Original unchanged
+  });
+
+  it('should handle empty existing graph', () => {
+    const changedDocs = [
+      {
+        id: '1',
+        score: 0,
+        metadata: {
+          path: 'src/a.ts',
+          callees: [{ name: 'foo', file: 'src/b.ts', line: 1 }],
+        },
+      },
+    ];
+
+    const updated = updateGraphIncremental(new Map(), changedDocs, []);
+    expect(updated.get('src/a.ts')).toBeDefined();
+  });
+});

packages/core/src/map/graph.ts

@@ -11,6 +11,7 @@
  * which uses NetworkX PageRank over a weighted dependency graph.
  */
 
+import * as fs from 'node:fs/promises';
 import type { SearchResult } from '../vector/types';
 
 // ============================================================================
@@ -22,6 +23,14 @@ export interface WeightedEdge {
   weight: number;
 }
 
+export interface CachedGraph {
+  version: 1;
+  generatedAt: string;
+  nodeCount: number;
+  edgeCount: number;
+  graph: Record<string, WeightedEdge[]>;
+}
+
 // ============================================================================
 // Graph Builder
 // ============================================================================
@@ -258,3 +267,106 @@ export function shortestPath(
 
   return null;
 }
+
+// ============================================================================
+// Serialization
+// ============================================================================
+
+const GRAPH_VERSION = 1;
+
+/**
+ * Serialize a dependency graph to JSON string.
+ */
+export function serializeGraph(graph: Map<string, WeightedEdge[]>): string {
+  let edgeCount = 0;
+  const obj: Record<string, WeightedEdge[]> = {};
+  for (const [key, edges] of graph) {
+    obj[key] = edges;
+    edgeCount += edges.length;
+  }
+  const cached: CachedGraph = {
+    version: GRAPH_VERSION,
+    generatedAt: new Date().toISOString(),
+    nodeCount: graph.size,
+    edgeCount,
+    graph: obj,
+  };
+  return JSON.stringify(cached);
+}
+
+/**
+ * Deserialize a JSON string to a dependency graph.
+ * Returns null if JSON is invalid or version doesn't match.
+ */
+export function deserializeGraph(json: string): Map<string, WeightedEdge[]> | null {
+  try {
+    const data = JSON.parse(json) as CachedGraph;
+    if (data.version !== GRAPH_VERSION) return null;
+    if (!data.graph || typeof data.graph !== 'object') return null;
+
+    const graph = new Map<string, WeightedEdge[]>();
+    for (const [key, edges] of Object.entries(data.graph)) {
+      graph.set(key, edges as WeightedEdge[]);
+    }
+    return graph;
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// Load / Build
+// ============================================================================
+
+/**
+ * Load dependency graph from cache, or build from docs as fallback.
+ */
+export async function loadOrBuildGraph(
+  graphPath: string | undefined,
+  fallbackDocs: () => Promise<SearchResult[]>
+): Promise<Map<string, WeightedEdge[]>> {
+  if (graphPath) {
+    try {
+      const json = await fs.readFile(graphPath, 'utf-8');
+      const graph = deserializeGraph(json);
+      if (graph) return graph;
+    } catch {
+      // File missing or unreadable — fall through to build
+    }
+  }
+
+  const docs = await fallbackDocs();
+  return buildDependencyGraph(docs);
+}
+
+// ============================================================================
+// Incremental Update
+// ============================================================================
+
+/**
+ * Update a dependency graph incrementally.
+ *
+ * For changed/new files: remove old edges from those files, add new edges.
+ * For deleted files: remove all edges from those files.
+ * Returns a new graph (does not mutate existing).
+ */
+export function updateGraphIncremental(
+  existing: Map<string, WeightedEdge[]>,
+  changedDocs: SearchResult[],
+  deletedFiles: string[]
+): Map<string, WeightedEdge[]> {
+  const updated = new Map(existing);
+
+  // Remove edges for deleted files
+  for (const file of deletedFiles) {
+    updated.delete(file);
+  }
+
+  // Build graph from changed docs, then merge
+  const changedGraph = buildDependencyGraph(changedDocs);
+  for (const [file, edges] of changedGraph) {
+    updated.set(file, edges);
+  }
+
+  return updated;
+}

packages/core/src/map/index.ts

@@ -10,7 +10,7 @@ import { stripFocusPrefix } from '../indexer/utils/change-frequency.js';
 import { getFileIcon } from '../utils/icons';
 import type { SearchResult } from '../vector/types';
 import type { LocalGitExtractor } from './git-extractor';
-import { buildDependencyGraph, connectedComponents, pageRank } from './graph';
+import { connectedComponents, loadOrBuildGraph, pageRank } from './graph';
 import type {
   ChangeFrequency,
   CodebaseMap,
@@ -45,6 +45,8 @@ export interface MapGenerationContext {
   indexer: RepositoryIndexer;
   gitExtractor?: LocalGitExtractor;
   logger?: Logger;
+  /** Path to cached dependency-graph.json — avoids rebuilding from getAll */
+  graphPath?: string;
 }
 
 /**
@@ -120,9 +122,9 @@ export async function generateCodebaseMap(
     'Counted components'
   );
 
-  // Build dependency graph once, share between hot paths and components
+  // Load cached dependency graph or build from docs as fallback
   const t7 = Date.now();
-  const graph = buildDependencyGraph(allDocs);
+  const graph = await loadOrBuildGraph(context.graphPath, async () => allDocs);
   const hotPaths = opts.includeHotPaths ? computeHotPaths(allDocs, graph, opts.maxHotPaths) : [];
   const rawComponents = connectedComponents(graph);
   const components = rawComponents

packages/core/src/storage/__tests__/path.test.ts

@@ -188,6 +188,7 @@ describe('Storage Path Utilities', () => {
       const paths = getStorageFilePaths(storagePath);
 
       expect(paths.vectors).toBe(path.join(storagePath, 'vectors'));
+      expect(paths.dependencyGraph).toBe(path.join(storagePath, 'dependency-graph.json'));
       expect(paths.githubState).toBe(path.join(storagePath, 'github-state.json'));
       expect(paths.metadata).toBe(path.join(storagePath, 'metadata.json'));
       expect(paths.indexerState).toBe(path.join(storagePath, 'indexer-state.json'));