feat(map): add smart depth for adaptive tree expansion

Implement information density heuristic for tree pruning:
- Expand directories with componentCount >= threshold
- Always show first 2 levels for basic structure
- Collapse sparse directories to save tokens
- Configurable via smartDepth and smartDepthThreshold options

Improves token efficiency by focusing on interesting code areas.

Author: prosdev

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

@@ -489,6 +489,125 @@ describe('Codebase Map', () => {
     });
   });
 
+  describe('Smart Depth', () => {
+    it('should expand dense directories when smartDepth is enabled', async () => {
+      // Create a structure with varying density
+      const mixedDensity: SearchResult[] = [
+        // Dense directory - 15 components
+        ...Array.from({ length: 15 }, (_, i) => ({
+          id: `packages/core/src/dense/file${i}.ts:fn:1`,
+          score: 0.9,
+          metadata: {
+            path: `packages/core/src/dense/file${i}.ts`,
+            type: 'function',
+            name: `fn${i}`,
+            exported: true,
+          },
+        })),
+        // Sparse directory - 2 components
+        ...Array.from({ length: 2 }, (_, i) => ({
+          id: `packages/core/src/sparse/file${i}.ts:fn:1`,
+          score: 0.9,
+          metadata: {
+            path: `packages/core/src/sparse/file${i}.ts`,
+            type: 'function',
+            name: `fn${i}`,
+            exported: true,
+          },
+        })),
+      ];
+
+      const indexer = createMockIndexer(mixedDensity);
+      const map = await generateCodebaseMap(indexer, {
+        depth: 5,
+        smartDepth: true,
+        smartDepthThreshold: 10,
+      });
+
+      // Find the core node
+      const findNode = (node: typeof map.root, name: string): typeof map.root | null => {
+        if (node.name === name) return node;
+        for (const child of node.children) {
+          const found = findNode(child, name);
+          if (found) return found;
+        }
+        return null;
+      };
+
+      const srcNode = findNode(map.root, 'src');
+      expect(srcNode).not.toBeNull();
+
+      // Dense should be expanded (has children or is at leaf level)
+      const denseNode = srcNode?.children.find((c) => c.name === 'dense');
+      expect(denseNode).toBeDefined();
+      expect(denseNode?.componentCount).toBe(15);
+
+      // Sparse should also exist but may be collapsed
+      const sparseNode = srcNode?.children.find((c) => c.name === 'sparse');
+      expect(sparseNode).toBeDefined();
+      expect(sparseNode?.componentCount).toBe(2);
+    });
+
+    it('should always expand first 2 levels regardless of density', async () => {
+      const sparseResults: SearchResult[] = [
+        {
+          id: 'packages/tiny/src/file.ts:fn:1',
+          score: 0.9,
+          metadata: {
+            path: 'packages/tiny/src/file.ts',
+            type: 'function',
+            name: 'fn',
+            exported: true,
+          },
+        },
+      ];
+
+      const indexer = createMockIndexer(sparseResults);
+      const map = await generateCodebaseMap(indexer, {
+        depth: 5,
+        smartDepth: true,
+        smartDepthThreshold: 100, // Very high threshold
+      });
+
+      // Should still show packages and tiny (first 2 levels)
+      const packagesNode = map.root.children.find((c) => c.name === 'packages');
+      expect(packagesNode).toBeDefined();
+      expect(packagesNode?.children.length).toBeGreaterThan(0);
+    });
+
+    it('should not use smart depth when disabled', async () => {
+      const results: SearchResult[] = Array.from({ length: 5 }, (_, i) => ({
+        id: `a/b/c/d/e/file${i}.ts:fn:1`,
+        score: 0.9,
+        metadata: {
+          path: `a/b/c/d/e/file${i}.ts`,
+          type: 'function',
+          name: `fn${i}`,
+          exported: true,
+        },
+      }));
+
+      const indexer = createMockIndexer(results);
+      const mapWithSmart = await generateCodebaseMap(indexer, {
+        depth: 3,
+        smartDepth: true,
+        smartDepthThreshold: 1,
+      });
+      const mapWithoutSmart = await generateCodebaseMap(indexer, {
+        depth: 3,
+        smartDepth: false,
+      });
+
+      // Without smart depth, should strictly follow depth limit
+      const countDepth = (node: typeof mapWithSmart.root, d = 0): number => {
+        if (node.children.length === 0) return d;
+        return Math.max(...node.children.map((c) => countDepth(c, d + 1)));
+      };
+
+      expect(countDepth(mapWithoutSmart.root)).toBeLessThanOrEqual(3);
+    });
+  });
+
   describe('Edge Cases', () => {
     it('should handle empty results', async () => {
       const indexer = createMockIndexer([]);

packages/core/src/map/index.ts

@@ -18,6 +18,8 @@ const DEFAULT_OPTIONS: Required<MapOptions> = {
   maxExportsPerDir: 5,
   includeHotPaths: true,
   maxHotPaths: 5,
+  smartDepth: false,
+  smartDepthThreshold: 10,
   tokenBudget: 2000,
 };
 
@@ -98,8 +100,12 @@ function buildDirectoryTree(docs: SearchResult[], opts: Required<MapOptions>): M
     insertIntoTree(root, dir, dirDocs, opts);
   }
 
-  // Prune tree to depth
-  pruneToDepth(root, opts.depth);
+  // Prune tree to depth (smart or fixed)
+  if (opts.smartDepth) {
+    smartPruneTree(root, opts.depth, opts.smartDepthThreshold);
+  } else {
+    pruneToDepth(root, opts.depth);
+  }
 
   // Sort children alphabetically
   sortTree(root);
@@ -206,6 +212,38 @@ function pruneToDepth(node: MapNode, depth: number, currentDepth = 0): void {
   }
 }
 
+/**
+ * Smart prune tree - expand dense directories, collapse sparse ones
+ * Uses information density heuristic: expand if componentCount >= threshold
+ */
+function smartPruneTree(
+  node: MapNode,
+  maxDepth: number,
+  threshold: number,
+  currentDepth = 0
+): void {
+  // Always stop at max depth
+  if (currentDepth >= maxDepth) {
+    node.children = [];
+    return;
+  }
+
+  // For each child, decide whether to expand or collapse
+  for (const child of node.children) {
+    // Expand if:
+    // 1. We're within first 2 levels (always show some structure)
+    // 2. OR the child has enough components to be "interesting"
+    const shouldExpand = currentDepth < 2 || child.componentCount >= threshold;
+
+    if (shouldExpand) {
+      smartPruneTree(child, maxDepth, threshold, currentDepth + 1);
+    } else {
+      // Collapse this branch - it's too sparse to be interesting
+      child.children = [];
+    }
+  }
+}
+
 /**
  * Sort tree children alphabetically
  */

packages/core/src/map/types.ts

@@ -51,6 +51,10 @@ export interface MapOptions {
   includeHotPaths?: boolean;
   /** Maximum hot paths to show (default: 5) */
   maxHotPaths?: number;
+  /** Use smart depth - expand dense directories, collapse sparse ones (default: false) */
+  smartDepth?: boolean;
+  /** Minimum components to expand a directory when using smart depth (default: 10) */
+  smartDepthThreshold?: number;
   /** Token budget for output (default: 2000) */
   tokenBudget?: number;
 }