fix(core,mcp): address code review — single graph build, BFS perf, traceTo error

- Build dependency graph once, pass to both computeHotPaths and connectedComponents
- Return explicit error when traceTo is set but indexer is missing
- Document directed-only limitation in traceTo description
- Switch BFS from queue.shift() (O(n)) to index-based (O(1))
- Require 2+ path segments for subsystem labels (avoid "packages" alone)
- Track traceTo adapter test gap in scratchpad

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

Author: prosdev

.changeset/graph-algorithms.md

@@ -0,0 +1,11 @@
+---
+'@prosdevlab/dev-agent': patch
+---
+
+Graph algorithms for dev_map and dev_refs
+
+- `dev_map` hot paths now use PageRank over the weighted dependency graph — files depended on by other important files rank higher
+- `dev_map` shows connected subsystems ("Subsystems: packages/core (45 files), packages/cli (12 files)")
+- `dev_refs` new `traceTo` parameter traces the dependency chain between files through the call graph
+- All algorithms are hand-rolled pure functions (~230 lines), no new dependencies
+- Inspired by aider's repo map (PageRank over dependency graphs)

.claude/scratchpad.md

@@ -25,6 +25,7 @@
 
 ## Test Gaps
 
+- **RefsAdapter integration test with `traceTo`.** The `traceTo` path tracing feature is tested at the algorithm level (shortestPath in graph.test.ts) but not at the adapter level. Needs a test that constructs RefsAdapter with a mock indexer, calls `execute()` with `traceTo`, and verifies the path output format. Also needs a test for the error case when indexer is missing.
 - **InspectAdapter integration test with PatternMatcher.** The InspectAdapter test constructs without a `patternMatcher` — the AST path is never exercised through the MCP layer. Needs a test that constructs `InspectAdapter` with `createPatternMatcher()`, mocks the search service, calls `execute()`, and verifies AST-enhanced results flow through. Requires mock search service setup — larger integration test scope.
 
 ## Notes

packages/core/src/map/graph.ts

@@ -189,13 +189,14 @@ export function connectedComponents(graph: Map<string, WeightedEdge[]>): string[
   for (const node of allNodes) {
     if (visited.has(node)) continue;
 
-    // BFS from this node
+    // BFS from this node (index-based to avoid O(n) shift)
     const component: string[] = [];
     const queue = [node];
+    let qi = 0;
     visited.add(node);
 
-    while (queue.length > 0) {
-      const current = queue.shift()!;
+    while (qi < queue.length) {
+      const current = queue[qi++];
       component.push(current);
       for (const neighbor of adj.get(current) || []) {
         if (!visited.has(neighbor)) {
@@ -232,9 +233,10 @@ export function shortestPath(
   const visited = new Set<string>([from]);
   const parent = new Map<string, string>();
   const queue = [from];
+  let qi = 0;
 
-  while (queue.length > 0) {
-    const current = queue.shift()!;
+  while (qi < queue.length) {
+    const current = queue[qi++];
     for (const { target } of graph.get(current) || []) {
       if (visited.has(target)) continue;
       visited.add(target);

packages/core/src/map/index.ts

@@ -117,10 +117,10 @@ export async function generateCodebaseMap(
     'Counted components'
   );
 
-  // Compute hot paths and connected components (share the dependency graph)
+  // Build dependency graph once, share between hot paths and components
   const t7 = Date.now();
-  const hotPaths = opts.includeHotPaths ? computeHotPaths(allDocs, opts.maxHotPaths) : [];
   const graph = buildDependencyGraph(allDocs);
+  const hotPaths = opts.includeHotPaths ? computeHotPaths(allDocs, graph, opts.maxHotPaths) : [];
   const rawComponents = connectedComponents(graph);
   const components = rawComponents
     .filter((c) => c.length > 1) // Only show multi-file subsystems
@@ -462,8 +462,11 @@ function applyChangeFrequency(node: MapNode, frequencyMap: Map<string, ChangeFre
  * Files that are depended on by other important files rank higher.
  * Sort by PageRank score, display real incoming edge count.
  */
-function computeHotPaths(docs: SearchResult[], maxPaths: number): HotPath[] {
-  const graph = buildDependencyGraph(docs);
+function computeHotPaths(
+  docs: SearchResult[],
+  graph: Map<string, import('./graph').WeightedEdge[]>,
+  maxPaths: number
+): HotPath[] {
   const ranks = pageRank(graph);
 
   // Count real incoming edges per file (distinct source files)
@@ -590,5 +593,8 @@ function findCommonPrefix(files: string[]): string {
       prefix = prefix.substring(0, prefix.lastIndexOf('/'));
     }
   }
-  return prefix;
+  // Require at least 2 path segments for a meaningful label
+  // "packages" alone is too generic; "packages/core" is useful
+  const segments = prefix.split('/').filter(Boolean);
+  return segments.length >= 2 ? prefix : '';
 }

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

@@ -120,7 +120,7 @@ export class RefsAdapter extends ToolAdapter {
             type: 'string',
             description:
               "Trace the dependency chain from this function's file to a target file " +
-              '(e.g., "src/database.ts"). Shows the shortest path through the call graph.',
+              '(e.g., "src/database.ts"). Follows directed call graph edges (A calls B, not B calls A).',
           },
         },
         required: ['name'],
@@ -158,6 +158,17 @@ export class RefsAdapter extends ToolAdapter {
       }
 
       // Handle traceTo — find shortest dependency path
+      if (traceTo && !this.indexer) {
+        return {
+          success: false,
+          error: {
+            code: 'INDEX_REQUIRED',
+            message: 'Path tracing requires a repository index.',
+            suggestion: 'Run "dev index" to index the repository first.',
+          },
+        };
+      }
+
       if (traceTo && this.indexer) {
         const sourceFile = (target.metadata.path as string) || '';
         const allDocs = await this.indexer.getAll({ limit: 10000 });

website/content/docs/tools/dev-map.mdx

@@ -63,14 +63,25 @@ This helps AI assistants quickly understand codebase organization and activity.
 
 ## Features
 
-### Hot Paths
+### Hot Paths (PageRank)
 
-Shows the most referenced files in your codebase. These are typically:
-- Core utilities used everywhere
-- Base classes/interfaces
-- Central orchestrators
+Shows the most architecturally important files in your codebase, ranked by PageRank
+over the weighted dependency graph. Unlike simple reference counting, PageRank identifies
+files that are depended on by other important files — not just files with many direct imports.
 
-Useful for understanding which code is most critical.
+Inspired by [aider's repo map](https://github.com/Aider-AI/aider).
+
+### Subsystems
+
+Shows connected components in the dependency graph — groups of files that depend on each
+other, forming independent subsystems. Helps agents understand codebase boundaries.
+
+```
+Subsystems (3 connected):
+  1. packages/core (45 files)
+  2. packages/cli (12 files)
+  3. packages/mcp-server (18 files)
+```
 
 ### Change Frequency ✨ v0.4
 

website/content/docs/tools/dev-refs.mdx

@@ -17,6 +17,7 @@ This is invaluable for understanding impact of changes and navigating unfamiliar
 | `name` | string | required | Symbol name to query |
 | `direction` | string | `"both"` | `"callers"`, `"callees"`, or `"both"` |
 | `limit` | number | `10` | Maximum results |
+| `traceTo` | string | — | Trace dependency chain to a target file (e.g., `"src/database.ts"`) |
 | `tokenBudget` | number | `2000` | Max tokens for output |
 
 ## Examples
@@ -84,6 +85,28 @@ What does the validateToken function call?
 }
 ```
 
+### Trace Dependency Path
+
+> "How does the auth module reach the database?"
+
+```json
+{
+  "name": "authenticate",
+  "traceTo": "src/database.ts"
+}
+```
+
+**Output:**
+```
+## Dependency Path: src/auth.ts → src/database.ts
+
+src/auth.ts → src/user-service.ts → src/repository.ts → src/database.ts
+
+**3 hops**
+```
+
+Follows directed call graph edges (A calls B). Returns "No path found" if files are in separate subsystems.
+
 ## Use Cases
 
 ### Impact Analysis

website/content/latest-version.ts

@@ -4,10 +4,10 @@
  */
 
 export const latestVersion = {
-  version: '0.10.5',
-  title: 'AST-Based Pattern Analysis',
+  version: '0.10.6',
+  title: 'Graph Algorithms for dev_map and dev_refs',
   date: 'March 31, 2026',
   summary:
-    'dev_patterns uses tree-sitter AST queries for more accurate detection of error handling, imports, and type coverage across .ts, .tsx, .js, .jsx files.',
-  link: '/updates#v0105--ast-based-pattern-analysis',
+    'PageRank-based file ranking, subsystem detection, and dependency path tracing via traceTo.',
+  link: '/updates#v0106--graph-algorithms-for-dev_map-and-dev_refs',
 } as const;

website/content/updates/index.mdx

@@ -9,6 +9,21 @@ What's new in dev-agent. We ship improvements regularly to help AI assistants un
 
 ---
 
+## v0.10.6 — Graph Algorithms for dev_map and dev_refs
+
+*March 31, 2026*
+
+**PageRank-based file ranking, subsystem detection, and dependency path tracing.**
+
+- `dev_map` hot paths now use PageRank over the weighted dependency graph — files depended on by other important files rank higher than files with many shallow references
+- `dev_map` shows connected subsystems: groups of interdependent files identified via graph analysis
+- `dev_refs` new `traceTo` parameter: `dev_refs { name: "authenticate", traceTo: "src/database.ts" }` → traces the shortest dependency chain between files
+- Weighted edges with sqrt dampening (inspired by [aider's repo map](https://github.com/Aider-AI/aider))
+- PageRank: 2,000 nodes + 10,000 edges in 4ms — no performance impact
+- All algorithms hand-rolled (~230 lines), no new dependencies
+
+---
+
 ## v0.10.5 — AST-Based Pattern Analysis
 
 *March 31, 2026*