feat(map): add hot paths showing most referenced files

Compute and display files with most incoming references:
- Count callers from indexed metadata
- Count callees pointing to files
- Sort by reference count, limit to maxHotPaths
- Display in formatted output with ref counts

Hot paths help AI assistants identify central/important code.

Author: prosdev

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

@@ -337,6 +337,158 @@ describe('Codebase Map', () => {
     });
   });
 
+  describe('Hot Paths', () => {
+    it('should compute hot paths from callers data', async () => {
+      const resultsWithCallers: SearchResult[] = [
+        {
+          id: 'src/core.ts:coreFunction:1',
+          score: 0.9,
+          metadata: {
+            path: 'src/core.ts',
+            type: 'function',
+            name: 'coreFunction',
+            exported: true,
+            callers: [
+              { name: 'caller1', file: 'src/a.ts', startLine: 10 },
+              { name: 'caller2', file: 'src/b.ts', startLine: 20 },
+              { name: 'caller3', file: 'src/c.ts', startLine: 30 },
+            ],
+          },
+        },
+        {
+          id: 'src/utils.ts:utilFunction:1',
+          score: 0.8,
+          metadata: {
+            path: 'src/utils.ts',
+            type: 'function',
+            name: 'utilFunction',
+            exported: true,
+            callers: [{ name: 'caller1', file: 'src/a.ts', startLine: 15 }],
+          },
+        },
+      ];
+
+      const indexer = createMockIndexer(resultsWithCallers);
+      const map = await generateCodebaseMap(indexer, { includeHotPaths: true });
+
+      expect(map.hotPaths.length).toBeGreaterThan(0);
+      // coreFunction should be first (more callers)
+      expect(map.hotPaths[0].file).toBe('src/core.ts');
+      expect(map.hotPaths[0].incomingRefs).toBe(3);
+    });
+
+    it('should compute hot paths from callees data', async () => {
+      const resultsWithCallees: SearchResult[] = [
+        {
+          id: 'src/main.ts:main:1',
+          score: 0.9,
+          metadata: {
+            path: 'src/main.ts',
+            type: 'function',
+            name: 'main',
+            exported: true,
+            callees: [
+              { name: 'helper', file: 'src/helpers.ts', line: 10 },
+              { name: 'helper', file: 'src/helpers.ts', line: 10 },
+            ],
+          },
+        },
+        {
+          id: 'src/other.ts:other:1',
+          score: 0.8,
+          metadata: {
+            path: 'src/other.ts',
+            type: 'function',
+            name: 'other',
+            exported: true,
+            callees: [{ name: 'helper', file: 'src/helpers.ts', line: 10 }],
+          },
+        },
+      ];
+
+      const indexer = createMockIndexer(resultsWithCallees);
+      const map = await generateCodebaseMap(indexer, { includeHotPaths: true });
+
+      expect(map.hotPaths.length).toBeGreaterThan(0);
+      // helpers.ts should be referenced most
+      expect(map.hotPaths[0].file).toBe('src/helpers.ts');
+      expect(map.hotPaths[0].incomingRefs).toBe(3);
+    });
+
+    it('should limit hot paths to maxHotPaths', async () => {
+      const manyRefs: SearchResult[] = Array.from({ length: 20 }, (_, i) => ({
+        id: `src/file${i}.ts:fn:1`,
+        score: 0.9,
+        metadata: {
+          path: `src/file${i}.ts`,
+          type: 'function',
+          name: `fn${i}`,
+          exported: true,
+          callers: Array.from({ length: 20 - i }, (_, j) => ({
+            name: `caller${j}`,
+            file: `src/other${j}.ts`,
+            startLine: j * 10,
+          })),
+        },
+      }));
+
+      const indexer = createMockIndexer(manyRefs);
+      const map = await generateCodebaseMap(indexer, { includeHotPaths: true, maxHotPaths: 3 });
+
+      expect(map.hotPaths.length).toBe(3);
+      // Should be sorted by refs descending
+      expect(map.hotPaths[0].incomingRefs).toBeGreaterThanOrEqual(map.hotPaths[1].incomingRefs);
+    });
+
+    it('should not include hot paths when disabled', async () => {
+      const resultsWithCallers: SearchResult[] = [
+        {
+          id: 'src/core.ts:coreFunction:1',
+          score: 0.9,
+          metadata: {
+            path: 'src/core.ts',
+            type: 'function',
+            name: 'coreFunction',
+            exported: true,
+            callers: [{ name: 'caller1', file: 'src/a.ts', startLine: 10 }],
+          },
+        },
+      ];
+
+      const indexer = createMockIndexer(resultsWithCallers);
+      const map = await generateCodebaseMap(indexer, { includeHotPaths: false });
+
+      expect(map.hotPaths.length).toBe(0);
+    });
+
+    it('should format hot paths in output', async () => {
+      const resultsWithCallers: SearchResult[] = [
+        {
+          id: 'src/core.ts:coreFunction:1',
+          score: 0.9,
+          metadata: {
+            path: 'src/core.ts',
+            type: 'function',
+            name: 'coreFunction',
+            exported: true,
+            callers: [
+              { name: 'caller1', file: 'src/a.ts', startLine: 10 },
+              { name: 'caller2', file: 'src/b.ts', startLine: 20 },
+            ],
+          },
+        },
+      ];
+
+      const indexer = createMockIndexer(resultsWithCallers);
+      const map = await generateCodebaseMap(indexer, { includeHotPaths: true });
+      const output = formatCodebaseMap(map, { includeHotPaths: true });
+
+      expect(output).toContain('## Hot Paths');
+      expect(output).toContain('src/core.ts');
+      expect(output).toContain('2 refs');
+    });
+  });
+
   describe('Edge Cases', () => {
     it('should handle empty results', async () => {
       const indexer = createMockIndexer([]);

packages/core/src/map/index.ts

@@ -6,7 +6,7 @@
 import * as path from 'node:path';
 import type { RepositoryIndexer } from '../indexer';
 import type { SearchResult } from '../vector/types';
-import type { CodebaseMap, ExportInfo, MapNode, MapOptions } from './types';
+import type { CodebaseMap, ExportInfo, HotPath, MapNode, MapOptions } from './types';
 
 export * from './types';
 
@@ -16,6 +16,8 @@ const DEFAULT_OPTIONS: Required<MapOptions> = {
   focus: '',
   includeExports: true,
   maxExportsPerDir: 5,
+  includeHotPaths: true,
+  maxHotPaths: 5,
   tokenBudget: 2000,
 };
 
@@ -46,10 +48,14 @@ export async function generateCodebaseMap(
   const totalComponents = countComponents(root);
   const totalDirectories = countDirectories(root);
 
+  // Compute hot paths (most referenced files)
+  const hotPaths = opts.includeHotPaths ? computeHotPaths(allDocs, opts.maxHotPaths) : [];
+
   return {
     root,
     totalComponents,
     totalDirectories,
+    hotPaths,
     generatedAt: new Date().toISOString(),
   };
 }
@@ -228,6 +234,54 @@ function countDirectories(node: MapNode): number {
   return count;
 }
 
+/**
+ * Compute hot paths - files with the most incoming references
+ */
+function computeHotPaths(docs: SearchResult[], maxPaths: number): HotPath[] {
+  // Count incoming references per file
+  const refCounts = new Map<string, { count: number; component?: string }>();
+
+  for (const doc of docs) {
+    const callers = doc.metadata.callers as Array<{ file: string }> | undefined;
+    if (callers && Array.isArray(callers)) {
+      // This document is called by others - count it
+      const filePath = (doc.metadata.path as string) || (doc.metadata.file as string) || '';
+      if (filePath) {
+        const existing = refCounts.get(filePath) || { count: 0 };
+        existing.count += callers.length;
+        existing.component = existing.component || (doc.metadata.name as string);
+        refCounts.set(filePath, existing);
+      }
+    }
+  }
+
+  // Also count based on callees pointing to files
+  for (const doc of docs) {
+    const callees = doc.metadata.callees as Array<{ file: string; name: string }> | undefined;
+    if (callees && Array.isArray(callees)) {
+      for (const callee of callees) {
+        if (callee.file) {
+          const existing = refCounts.get(callee.file) || { count: 0 };
+          existing.count += 1;
+          refCounts.set(callee.file, existing);
+        }
+      }
+    }
+  }
+
+  // Sort by count and take top N
+  const sorted = Array.from(refCounts.entries())
+    .map(([file, data]) => ({
+      file,
+      incomingRefs: data.count,
+      primaryComponent: data.component,
+    }))
+    .sort((a, b) => b.incomingRefs - a.incomingRefs)
+    .slice(0, maxPaths);
+
+  return sorted;
+}
+
 /**
  * Format codebase map as readable text
  */
@@ -238,7 +292,20 @@ export function formatCodebaseMap(map: CodebaseMap, options: MapOptions = {}): s
   lines.push('# Codebase Map');
   lines.push('');
 
+  // Format hot paths if present
+  if (opts.includeHotPaths && map.hotPaths.length > 0) {
+    lines.push('## Hot Paths (most referenced)');
+    for (let i = 0; i < map.hotPaths.length; i++) {
+      const hp = map.hotPaths[i];
+      const component = hp.primaryComponent ? ` (${hp.primaryComponent})` : '';
+      lines.push(`${i + 1}. \`${hp.file}\`${component} - ${hp.incomingRefs} refs`);
+    }
+    lines.push('');
+  }
+
   // Format tree
+  lines.push('## Directory Structure');
+  lines.push('');
   formatNode(map.root, lines, '', true, opts);
 
   lines.push('');

packages/core/src/map/types.ts

@@ -47,10 +47,26 @@ export interface MapOptions {
   includeExports?: boolean;
   /** Maximum exports to show per directory (default: 5) */
   maxExportsPerDir?: number;
+  /** Include hot paths - most referenced files (default: true) */
+  includeHotPaths?: boolean;
+  /** Maximum hot paths to show (default: 5) */
+  maxHotPaths?: number;
   /** Token budget for output (default: 2000) */
   tokenBudget?: number;
 }
 
+/**
+ * Information about a frequently referenced file
+ */
+export interface HotPath {
+  /** File path */
+  file: string;
+  /** Number of incoming references (callers) */
+  incomingRefs: number;
+  /** Primary component name in this file */
+  primaryComponent?: string;
+}
+
 /**
  * Result of codebase map generation
  */
@@ -61,6 +77,8 @@ export interface CodebaseMap {
   totalComponents: number;
   /** Total number of directories */
   totalDirectories: number;
+  /** Most referenced files (hot paths) */
+  hotPaths: HotPath[];
   /** Generation timestamp */
   generatedAt: string;
 }