@mishasinitcyn/betterrank 0.2.0 → 0.2.1

package/README.md

@@ -25,8 +25,14 @@ betterrank outline src/auth.py authenticate_user
 # Search for symbols by name or parameter
 betterrank search auth --root /path/to/project
 
-# Who calls this function?
-betterrank callers authenticateUser --root /path/to/project
+# Who calls this function? (with call site context)
+betterrank callers authenticateUser --root /path/to/project --context
+
+# Trace the full call chain from entry point to function
+betterrank trace calculate_bid --root /path/to/project
+
+# What symbols changed and what might break?
+betterrank diff --root /path/to/project
 
 # What depends on this file?
 betterrank dependents src/auth/handlers.ts --root /path/to/project
@@ -65,11 +71,14 @@ betterrank outline src/auth.py authenticate_user
 # Expand multiple symbols
 betterrank outline src/auth.py validate,process
 
+# Show caller counts next to each function (requires --root)
+betterrank outline src/auth.py --annotate --root ./backend
+
 # Resolve path relative to a root
 betterrank outline src/auth.py --root ./backend
 ```
 
-**Example output:**
+**Example output (with `--annotate`):**
 ```
    1│ from fastapi import APIRouter, Depends
    2│ from core.auth import verify_auth
@@ -78,14 +87,14 @@ betterrank outline src/auth.py --root ./backend
    5│
    6│ @router.get("/users")
    7│ async def list_users(db = Depends(get_db)):
-    │   ... (25 lines)
+    │   ... (25 lines)                                          ← 2 callers
   33│
   34│ @router.post("/users")
   35│ async def create_user(data: UserCreate, db = Depends(get_db)):
-    │   ... (40 lines)
+    │   ... (40 lines)                                          ← 5 callers
 ```
 
-Typical compression: **3-5x** (a 2000-line file becomes ~400 lines of outline).
+Typical compression: **3-5x** (a 2000-line file becomes ~400 lines of outline). Annotations show how many *external* files reference each function — instantly see what's critical vs dead code.
 
 ### `map` — Repo map
 
@@ -119,7 +128,68 @@ betterrank symbols --root /path/to/project --kind function
 ### `callers` — Who calls this symbol
 
 ```bash
+# File names only
 betterrank callers authenticateUser --root /path/to/project
+
+# With call site context lines (default 2 lines around each site)
+betterrank callers authenticateUser --root /path/to/project --context
+
+# Custom context window
+betterrank callers authenticateUser --root /path/to/project --context 3
+```
+
+**Example output (with `--context`):**
+```
+src/engine/pipeline.py:
+      16│ from app.engine.bidding import run_auction
+      17│
+
+     153│     return await run_auction(
+     154│         searched=campaigns,
+     155│         publisher=config.publisher,
+
+src/api/serve.py:
+     145│     bid = await run_auction(searched, publisher=pub_id)
+```
+
+### `trace` — Recursive caller chain
+
+Walk UP the call graph from a symbol to see the full path from entry points to your function. At each hop, resolves which function in the caller file contains the call site.
+
+```bash
+betterrank trace calculate_bid --root /path/to/project
+betterrank trace calculate_bid --root /path/to/project --depth 5
+```
+
+**Example output:**
+```
+calculate_bid (src/engine/bidding.py:489)
+  ← run_auction (src/engine/bidding.py:833)
+    ← handle_request (src/engine/pipeline.py:153)
+      ← app (src/main.py:45)
+```
+
+### `diff` — Git-aware blast radius
+
+Shows which symbols changed in the working tree and how many external files call each changed symbol. Compares current disk state against a git ref.
+
+```bash
+# Uncommitted changes vs HEAD
+betterrank diff --root /path/to/project
+
+# Changes since a specific commit or branch
+betterrank diff --ref main --root /path/to/project
+betterrank diff --ref HEAD~5 --root /path/to/project
+```
+
+**Example output:**
+```
+src/engine/bidding.py:
+  ~ [function] calculate_bid  (3 callers)
+  + [function] compute_value_multi
+  - [function] old_quality_score  (1 caller)
+
+⚠ 4 external callers of modified/removed symbols
 ```
 
 ### `deps` — What does this file import
@@ -185,7 +255,8 @@ const idx = new CodeIndex('/path/to/project');
 
 const map = await idx.map({ limit: 100, focusFiles: ['src/main.ts'] });
 const results = await idx.search({ query: 'auth', kind: 'function', limit: 10 });
-const callers = await idx.callers({ symbol: 'authenticate' });
+const callers = await idx.callers({ symbol: 'authenticate', context: 2 });
+const counts = await idx.getCallerCounts('src/auth.ts');
 const deps = await idx.dependencies({ file: 'src/auth.ts' });
 const dependents = await idx.dependents({ file: 'src/auth.ts' });
 const hood = await idx.neighborhood({ file: 'src/auth.ts', hops: 2, maxFiles: 10 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mishasinitcyn/betterrank",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Structural code index with PageRank-ranked repo maps, symbol search, call-graph queries, and dependency analysis. Built on tree-sitter and graphology.",
   "type": "module",
   "main": "src/index.js",

package/src/cli.js

@@ -12,12 +12,14 @@ betterrank <command> [options]
 
 Commands:
   ui          [--port N]                            Launch web UI (default port: 3333)
-  outline     <file> [symbol1,symbol2]              File skeleton with collapsed bodies
+  outline     <file> [symbol1,symbol2] [--annotate]  File skeleton (--annotate for caller counts)
   map         [--focus file1,file2]                 Repo map (ranked by PageRank)
   search      <query> [--kind type]                 Substring search on symbol names + signatures (ranked by PageRank)
   structure   [--depth N]                           File tree with symbol counts (default depth: ${DEFAULT_DEPTH})
   symbols     [--file path] [--kind type]           List definitions (ranked by PageRank)
-  callers     <symbol> [--file path]                All call sites (ranked by importance)
+  callers     <symbol> [--file path] [--context]     All call sites (ranked, with context lines)
+  trace       <symbol> [--depth N]                  Recursive caller chain (call tree)
+  diff        [--ref <commit>]                      Git-aware blast radius (changed symbols + callers)
   deps        <file>                                What this file imports (ranked)
   dependents  <file>                                What imports this file (ranked)
   neighborhood <file> [--hops N] [--max-files N]    Local subgraph (ranked by PageRank)
@@ -34,7 +36,7 @@ Global flags:
 `.trim();
 
 const COMMAND_HELP = {
-  outline: `betterrank outline <file> [symbol1,symbol2,...] [--root <path>]
+  outline: `betterrank outline <file> [symbol1,symbol2,...] [--annotate --root <path>]
 
 View a file's structure with function/class bodies collapsed, or expand
 specific symbols to see their full source.
@@ -46,13 +48,15 @@ With symbol names (comma-separated): shows the full source of those
 specific functions/classes with line numbers.
 
 Options:
-  --root <path>   Resolve file path relative to this directory
+  --root <path>     Resolve file path relative to this directory
+  --annotate        Show caller counts next to each function (requires --root)
 
 Examples:
   betterrank outline src/auth.py
   betterrank outline src/auth.py authenticate_user
   betterrank outline src/auth.py validate,process
-  betterrank outline src/handlers.ts --root ./backend`,
+  betterrank outline src/handlers.ts --root ./backend
+  betterrank outline src/auth.py --annotate --root ./backend`,
 
   map: `betterrank map [--focus file1,file2] [--root <path>]
 
@@ -116,19 +120,54 @@ Examples:
   betterrank symbols --file src/auth/handlers.ts --root ./backend
   betterrank symbols --kind class --root . --limit 20`,
 
-  callers: `betterrank callers <symbol> [--file path] [--root <path>]
+  callers: `betterrank callers <symbol> [--file path] [--context [N]] [--root <path>]
 
 Find all files that reference a symbol. Ranked by file-level PageRank.
 
 Options:
   --file <path>    Disambiguate when multiple symbols share a name
+  --context [N]    Show N lines of context around each call site (default: 2)
   --count          Return count only
   --offset N       Skip first N results
   --limit N        Max results (default: ${DEFAULT_LIMIT})
 
 Examples:
   betterrank callers authenticateUser --root ./backend
-  betterrank callers resolve --file src/utils.ts --root .`,
+  betterrank callers authenticateUser --root ./backend --context
+  betterrank callers resolve --file src/utils.ts --root . --context 3`,
+
+  trace: `betterrank trace <symbol> [--depth N] [--file path] [--root <path>]
+
+Recursive caller chain — walk UP the call graph from a symbol to see
+the full path from entry points to your function.
+
+At each hop, resolves which function in the caller file contains the
+call site. Displays as an indented tree.
+
+Options:
+  --depth N        Max hops upward (default: 3)
+  --file <path>    Disambiguate when multiple symbols share a name
+
+Examples:
+  betterrank trace calculate_bid --root .
+  betterrank trace send_to_firehose --root . --depth 4
+  betterrank trace authenticate --file src/auth.ts --root .`,
+
+  diff: `betterrank diff [--ref <commit>] [--root <path>]
+
+Git-aware blast radius — shows which symbols changed in the working tree
+and how many external files call each changed symbol.
+
+Compares current files on disk against the indexed state. Shows added,
+removed, and modified symbols with their caller counts.
+
+Options:
+  --ref <commit>   Git ref to diff against (default: HEAD)
+
+Examples:
+  betterrank diff --root .
+  betterrank diff --ref main --root .
+  betterrank diff --ref HEAD~3 --root .`,
 
   deps: `betterrank deps <file> [--root <path>]
 
@@ -252,14 +291,20 @@ async function main() {
     return; // Keep process alive (server is listening)
   }
 
-  // Outline command — standalone, no CodeIndex needed
+  // Outline command — standalone by default, needs CodeIndex for --annotate
   if (command === 'outline') {
     const filePath = flags._positional[0];
     if (!filePath) {
-      console.error('Usage: betterrank outline <file> [symbol1,symbol2]');
+      console.error('Usage: betterrank outline <file> [symbol1,symbol2] [--annotate --root <path>]');
       process.exit(1);
     }
     const expandSymbols = flags._positional[1] ? flags._positional[1].split(',') : [];
+    const annotate = flags.annotate === true;
+
+    if (annotate && !flags.root) {
+      console.error('outline --annotate requires --root for graph data');
+      process.exit(1);
+    }
 
     const root = flags.root ? resolve(flags.root) : process.cwd();
     const absPath = isAbsolute(filePath) ? filePath : resolve(root, filePath);
@@ -275,7 +320,14 @@ async function main() {
 
     const relPath = relative(root, absPath);
     const { buildOutline } = await import('./outline.js');
-    const result = buildOutline(source, relPath, expandSymbols);
+
+    let callerCounts;
+    if (annotate) {
+      const idx = new CodeIndex(resolve(flags.root));
+      callerCounts = await idx.getCallerCounts(relPath);
+    }
+
+    const result = buildOutline(source, relPath, expandSymbols, { callerCounts });
     console.log(result);
     return;
   }
@@ -421,9 +473,29 @@ async function main() {
       const symbol = flags._positional[0];
       if (!symbol) { console.error('Usage: betterrank callers <symbol> [--file path]'); process.exit(1); }
       const effectiveLimit = countMode ? undefined : (userLimit !== undefined ? userLimit : DEFAULT_LIMIT);
-      const result = await idx.callers({ symbol, file: normalizeFilePath(flags.file), count: countMode, offset, limit: effectiveLimit });
+      const contextLines = flags.context === true ? 2 : (flags.context ? parseInt(flags.context, 10) : 0);
+      const result = await idx.callers({ symbol, file: normalizeFilePath(flags.file), count: countMode, offset, limit: effectiveLimit, context: contextLines });
       if (countMode) {
         console.log(`total: ${result.total}`);
+      } else if (contextLines > 0) {
+        // Rich output with call-site context
+        const pad = 6;
+        for (const c of result) {
+          console.log(`${c.file}:`);
+          if (c.sites && c.sites.length > 0) {
+            for (const site of c.sites) {
+              for (const t of site.text) {
+                console.log(`  ${String(t.line).padStart(pad)}│ ${t.content}`);
+              }
+              console.log('');
+            }
+          } else {
+            console.log('  (no call sites found in source)\n');
+          }
+        }
+        if (result.length === 0) {
+          console.log('(no callers found)');
+        }
       } else {
         for (const c of result) {
           console.log(c.file);
@@ -437,6 +509,52 @@ async function main() {
       break;
     }
 
+    case 'trace': {
+      const symbol = flags._positional[0];
+      if (!symbol) { console.error('Usage: betterrank trace <symbol> [--depth N]'); process.exit(1); }
+      const traceDepth = flags.depth ? parseInt(flags.depth, 10) : 3;
+      const tree = await idx.trace({ symbol, file: normalizeFilePath(flags.file), depth: traceDepth });
+      if (!tree) {
+        console.log(`(symbol "${symbol}" not found)`);
+      } else {
+        const printNode = (node, depth) => {
+          const indent = depth === 0 ? '' : '  '.repeat(depth) + '← ';
+          const loc = `(${node.file}:${node.line || '?'})`;
+          console.log(`${indent}${node.name} ${loc}`);
+          for (const caller of node.callers) {
+            printNode(caller, depth + 1);
+          }
+        };
+        printNode(tree, 0);
+      }
+      break;
+    }
+
+    case 'diff': {
+      const result = await idx.diff({ ref: flags.ref || 'HEAD' });
+      if (result.error) {
+        console.error(result.error);
+        break;
+      }
+      if (result.changed.length === 0) {
+        console.log('(no symbol changes detected)');
+        break;
+      }
+      for (const entry of result.changed) {
+        console.log(`${entry.file}:`);
+        for (const s of entry.symbols) {
+          const tag = s.change === 'added' ? '+' : s.change === 'removed' ? '-' : '~';
+          const callerNote = s.callerCount > 0 ? `  (${s.callerCount} caller${s.callerCount === 1 ? '' : 's'})` : '';
+          console.log(`  ${tag} [${s.kind}] ${s.name}${callerNote}`);
+        }
+        console.log('');
+      }
+      if (result.totalCallers > 0) {
+        console.log(`⚠ ${result.totalCallers} external caller${result.totalCallers === 1 ? '' : 's'} of modified/removed symbols`);
+      }
+      break;
+    }
+
     case 'deps': {
       const file = normalizeFilePath(flags._positional[0]);
       if (!file) { console.error('Usage: betterrank deps <file>'); process.exit(1); }

package/src/index.js

@@ -2,6 +2,7 @@ import { readFile } from 'fs/promises';
 import { join, dirname, relative, sep, basename } from 'path';
 import { CodeIndexCache } from './cache.js';
 import { rankedSymbols } from './graph.js';
+import { parseFile } from './parser.js';
 
 // ── Orphan false-positive filters ──────────────────────────────────────────
 //
@@ -457,15 +458,19 @@ class CodeIndex {
    * Results are ranked by file-level PageRank (most important callers first).
    * Supports offset/limit pagination and count-only mode.
    *
+   * When `context` > 0, reads each caller file from disk and extracts
+   * the actual call-site lines with surrounding context.
+   *
    * @param {object} opts
    * @param {string} opts.symbol - Symbol name
    * @param {string} [opts.file] - Disambiguate by file
+   * @param {number} [opts.context=0] - Lines of context around each call site (0 = off)
    * @param {number} [opts.offset] - Skip first N results
    * @param {number} [opts.limit] - Max results to return
    * @param {boolean} [opts.count] - If true, return only { total }
-   * @returns {Array<{file}>|{total: number}}
+   * @returns {Array<{file, sites?}>|{total: number}}
    */
-  async callers({ symbol, file, offset, limit, count = false }) {
+  async callers({ symbol, file, offset, limit, count = false, context = 0 }) {
     await this._ensureReady();
     const graph = this.cache.getGraph();
     if (!graph) return count ? { total: 0 } : [];
@@ -499,7 +504,56 @@ class CodeIndex {
     for (const r of results) delete r._score;
 
     if (count) return { total: results.length };
-    return paginate(results, { offset, limit }).items;
+
+    const paged = paginate(results, { offset, limit }).items;
+
+    if (context > 0) {
+      // Match call sites: symbol followed by ( — avoids string literals and definitions
+      const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const callPattern = new RegExp(`(?<![a-zA-Z0-9_])${escaped}\\s*\\(`);
+      // Fallback: import/from lines that reference the symbol
+      const importPattern = new RegExp(`(?:import|from)\\s.*\\b${escaped}\\b`);
+
+      // Collect the target symbol's own definition ranges to exclude
+      const defRanges = [];
+      for (const tk of targetKeys) {
+        try {
+          const attrs = graph.getNodeAttributes(tk);
+          if (attrs.type === 'symbol') defRanges.push({ file: attrs.file, start: attrs.lineStart, end: attrs.lineEnd });
+        } catch { /* skip */ }
+      }
+
+      for (const entry of paged) {
+        entry.sites = [];
+        try {
+          const absPath = join(this.projectRoot, entry.file);
+          const source = await readFile(absPath, 'utf-8');
+          const lines = source.split('\n');
+
+          for (let i = 0; i < lines.length; i++) {
+            const lineNum = i + 1;
+            // Skip lines inside the symbol's own definition
+            const inDef = defRanges.some(r => r.file === entry.file && lineNum >= r.start && lineNum <= r.end);
+            if (inDef) continue;
+
+            const line = lines[i];
+            if (!callPattern.test(line) && !importPattern.test(line)) continue;
+
+            const start = Math.max(0, i - context);
+            const end = Math.min(lines.length - 1, i + context);
+            const text = [];
+            for (let j = start; j <= end; j++) {
+              text.push({ line: j + 1, content: lines[j] });
+            }
+            entry.sites.push({ line: lineNum, text });
+          }
+        } catch {
+          // File unreadable — skip context for this caller
+        }
+      }
+    }
+
+    return paged;
   }
 
   /**
@@ -908,6 +962,318 @@ class CodeIndex {
     return { nodes, edges };
   }
 
+  /**
+   * Get caller counts for all symbols defined in a file.
+   * Returns a Map<symbolName, number> where the count is unique
+   * files that reference each symbol (excluding self-references).
+   *
+   * @param {string} file - Relative file path
+   * @returns {Map<string, number>}
+   */
+  async getCallerCounts(file) {
+    await this._ensureReady();
+    const graph = this.cache.getGraph();
+    if (!graph) return new Map();
+
+    const counts = new Map();
+    graph.forEachNode((node, attrs) => {
+      if (attrs.type !== 'symbol') return;
+      if (attrs.file !== file) return;
+
+      const callerFiles = new Set();
+      graph.forEachInEdge(node, (_edge, edgeAttrs, source) => {
+        if (edgeAttrs.type !== 'REFERENCES') return;
+        const sourceAttrs = graph.getNodeAttributes(source);
+        const sourceFile = sourceAttrs.file || source;
+        if (sourceFile !== file) callerFiles.add(sourceFile);
+      });
+
+      if (callerFiles.size > 0) {
+        counts.set(attrs.name, callerFiles.size);
+      }
+    });
+
+    return counts;
+  }
+
+  /**
+   * Recursive caller chain — walk UP the call graph from a symbol.
+   * At each hop, resolves which function in the caller file contains
+   * the call site by cross-referencing line numbers with definitions.
+   *
+   * Returns a tree: { name, file, line, callers: [...] }
+   *
+   * @param {object} opts
+   * @param {string} opts.symbol - Starting symbol name
+   * @param {string} [opts.file] - Disambiguate by file
+   * @param {number} [opts.depth=3] - Max hops upward
+   * @returns {object} Tree root node
+   */
+  async trace({ symbol, file, depth = 3 }) {
+    await this._ensureReady();
+    const graph = this.cache.getGraph();
+    if (!graph) return null;
+
+    // Find the target symbol node(s)
+    const targetKeys = [];
+    graph.forEachNode((node, attrs) => {
+      if (attrs.type !== 'symbol') return;
+      if (attrs.name !== symbol) return;
+      if (file && attrs.file !== file) return;
+      targetKeys.push(node);
+    });
+
+    if (targetKeys.length === 0) return null;
+
+    // Use the first match (highest PageRank if multiple)
+    const ranked = this._getRanked();
+    const scoreMap = new Map(ranked);
+    targetKeys.sort((a, b) => (scoreMap.get(b) || 0) - (scoreMap.get(a) || 0));
+    const rootKey = targetKeys[0];
+    const rootAttrs = graph.getNodeAttributes(rootKey);
+
+    // Cache of file -> definitions (avoid re-parsing the same file)
+    const defCache = new Map();
+
+    const getFileDefs = async (filePath) => {
+      if (defCache.has(filePath)) return defCache.get(filePath);
+      try {
+        const absPath = join(this.projectRoot, filePath);
+        const source = await readFile(absPath, 'utf-8');
+        const parsed = parseFile(filePath, source);
+        const defs = parsed ? parsed.definitions.sort((a, b) => a.lineStart - b.lineStart) : [];
+        defCache.set(filePath, defs);
+        return defs;
+      } catch {
+        defCache.set(filePath, []);
+        return [];
+      }
+    };
+
+    // Find which definition in a file contains a given line
+    const findContainingDef = (defs, line) => {
+      for (let i = defs.length - 1; i >= 0; i--) {
+        if (line >= defs[i].lineStart && line <= defs[i].lineEnd) return defs[i];
+      }
+      return null;
+    };
+
+    // BFS upward through callers
+    const visited = new Set(); // "file::symbol" keys to prevent cycles
+
+    const buildNode = async (symbolName, symbolFile, symbolLine, currentDepth) => {
+      const nodeKey = `${symbolFile}::${symbolName}`;
+      const node = { name: symbolName, file: symbolFile, line: symbolLine, callers: [] };
+
+      if (currentDepth >= depth) return node;
+      if (visited.has(nodeKey)) return node;
+      visited.add(nodeKey);
+
+      // Find this symbol in the graph
+      const symKeys = [];
+      graph.forEachNode((gNode, attrs) => {
+        if (attrs.type !== 'symbol') return;
+        if (attrs.name !== symbolName) return;
+        if (attrs.file !== symbolFile) return;
+        symKeys.push(gNode);
+      });
+
+      // Collect caller files
+      const callerFiles = new Set();
+      for (const sk of symKeys) {
+        graph.forEachInEdge(sk, (_edge, attrs, source) => {
+          if (attrs.type !== 'REFERENCES') return;
+          const sourceAttrs = graph.getNodeAttributes(source);
+          const sf = sourceAttrs.file || source;
+          if (sf !== symbolFile) callerFiles.add(sf);
+        });
+      }
+
+      // For each caller file, find which function contains the call
+      const callPattern = new RegExp(
+        `(?<![a-zA-Z0-9_])${symbolName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\(`
+      );
+
+      for (const callerFile of callerFiles) {
+        try {
+          const absPath = join(this.projectRoot, callerFile);
+          const source = await readFile(absPath, 'utf-8');
+          const lines = source.split('\n');
+          const defs = await getFileDefs(callerFile);
+
+          // Find the first call site line
+          let callLine = null;
+          for (let i = 0; i < lines.length; i++) {
+            if (callPattern.test(lines[i])) { callLine = i + 1; break; }
+          }
+
+          // Resolve to containing function
+          const containingDef = callLine ? findContainingDef(defs, callLine) : null;
+
+          if (containingDef) {
+            const callerNode = await buildNode(containingDef.name, callerFile, containingDef.lineStart, currentDepth + 1);
+            node.callers.push(callerNode);
+          } else {
+            // Top-level call (not inside any function) — show as file-level
+            node.callers.push({ name: `<module>`, file: callerFile, line: callLine, callers: [] });
+          }
+        } catch {
+          // Skip unreadable files
+        }
+      }
+
+      // Sort callers by file for deterministic output
+      node.callers.sort((a, b) => a.file.localeCompare(b.file));
+      return node;
+    };
+
+    return buildNode(rootAttrs.name, rootAttrs.file, rootAttrs.lineStart, 0);
+  }
+
+  /**
+   * Git-aware blast radius — what symbols changed and who calls them.
+   *
+   * Compares the working tree (or a git ref) against the index to find
+   * added, removed, and modified symbols, then looks up their callers.
+   *
+   * @param {object} [opts]
+   * @param {string} [opts.ref] - Git ref to diff against (default: HEAD)
+   * @returns {{ changed: Array<{file, symbols: Array<{name, kind, change, callerCount}>}>, totalCallers: number }}
+   */
+  async diff({ ref = 'HEAD' } = {}) {
+    await this._ensureReady();
+    const graph = this.cache.getGraph();
+    if (!graph) return { changed: [], totalCallers: 0 };
+
+    // Get changed files from git
+    const { execSync } = await import('child_process');
+    let changedFiles;
+    try {
+      const output = execSync(`git diff --name-only ${ref}`, {
+        cwd: this.projectRoot,
+        encoding: 'utf-8',
+        timeout: 10000,
+      }).trim();
+      if (!output) return { changed: [], totalCallers: 0 };
+      changedFiles = output.split('\n').filter(Boolean);
+    } catch {
+      return { changed: [], totalCallers: 0, error: 'git diff failed — is this a git repo?' };
+    }
+
+    // Also include untracked new files
+    try {
+      const untracked = execSync('git ls-files --others --exclude-standard', {
+        cwd: this.projectRoot,
+        encoding: 'utf-8',
+        timeout: 10000,
+      }).trim();
+      if (untracked) {
+        for (const f of untracked.split('\n').filter(Boolean)) {
+          if (!changedFiles.includes(f)) changedFiles.push(f);
+        }
+      }
+    } catch { /* ignore */ }
+
+    const results = [];
+    let totalCallers = 0;
+
+    for (const filePath of changedFiles) {
+      // Get OLD symbols from git ref
+      const oldSymbols = new Map();
+      try {
+        const oldSource = execSync(`git show ${ref}:${filePath}`, {
+          cwd: this.projectRoot,
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 10000,
+        });
+        const oldParsed = parseFile(filePath, oldSource);
+        if (oldParsed) {
+          for (const def of oldParsed.definitions) {
+            oldSymbols.set(def.name, { kind: def.kind, signature: def.signature });
+          }
+        }
+      } catch {
+        // File is new (doesn't exist in ref) — all symbols are "added"
+      }
+
+      // Get graph keys for caller lookups on current symbols
+      const graphKeys = new Map();
+      graph.forEachNode((node, attrs) => {
+        if (attrs.type !== 'symbol' || attrs.file !== filePath) return;
+        graphKeys.set(attrs.name, node);
+      });
+
+      // Parse the CURRENT file from disk
+      let currentSymbols = new Map();
+      try {
+        const absPath = join(this.projectRoot, filePath);
+        const source = await readFile(absPath, 'utf-8');
+        const parsed = parseFile(filePath, source);
+        if (parsed) {
+          for (const def of parsed.definitions) {
+            currentSymbols.set(def.name, {
+              kind: def.kind,
+              signature: def.signature,
+            });
+          }
+        }
+      } catch {
+        // File might be deleted — all old symbols are "removed"
+      }
+
+      const symbolChanges = [];
+
+      // Detect removed symbols (in old ref, not on disk)
+      for (const [name, old] of oldSymbols) {
+        if (!currentSymbols.has(name)) {
+          const gk = graphKeys.get(name);
+          const callerCount = gk ? this._countExternalCallers(graph, gk, filePath) : 0;
+          symbolChanges.push({ name, kind: old.kind, change: 'removed', signature: old.signature, callerCount });
+          totalCallers += callerCount;
+        }
+      }
+
+      // Detect added and modified symbols
+      for (const [name, current] of currentSymbols) {
+        const old = oldSymbols.get(name);
+        if (!old) {
+          symbolChanges.push({ name, kind: current.kind, change: 'added', signature: current.signature, callerCount: 0 });
+        } else if (old.signature !== current.signature) {
+          const gk = graphKeys.get(name);
+          const callerCount = gk ? this._countExternalCallers(graph, gk, filePath) : 0;
+          symbolChanges.push({ name, kind: current.kind, change: 'modified', signature: current.signature, callerCount });
+          totalCallers += callerCount;
+        }
+      }
+
+      if (symbolChanges.length > 0) {
+        symbolChanges.sort((a, b) => b.callerCount - a.callerCount);
+        results.push({ file: filePath, symbols: symbolChanges });
+      }
+    }
+
+    results.sort((a, b) => {
+      const aMax = Math.max(0, ...a.symbols.map(s => s.callerCount));
+      const bMax = Math.max(0, ...b.symbols.map(s => s.callerCount));
+      return bMax - aMax;
+    });
+
+    return { changed: results, totalCallers };
+  }
+
+  /** Count unique external files that reference a symbol node. */
+  _countExternalCallers(graph, symbolKey, symbolFile) {
+    const files = new Set();
+    graph.forEachInEdge(symbolKey, (_edge, attrs, source) => {
+      if (attrs.type !== 'REFERENCES') return;
+      const sourceAttrs = graph.getNodeAttributes(source);
+      const sf = sourceAttrs.file || source;
+      if (sf !== symbolFile) files.add(sf);
+    });
+    return files.size;
+  }
+
   /**
    * Force a full rebuild.
    */

package/src/outline.js

@@ -12,9 +12,11 @@ const MIN_COLLAPSE_LINES = 2;
  * @param {string} source - File contents
  * @param {string} filePath - File path (for language detection)
  * @param {string[]} expandSymbols - Symbol names to expand (empty = outline mode)
+ * @param {object} [opts]
+ * @param {Map<string,number>} [opts.callerCounts] - Map of symbol name → caller file count (for --annotate)
  * @returns {string} Formatted output with line numbers
  */
-export function buildOutline(source, filePath, expandSymbols = []) {
+export function buildOutline(source, filePath, expandSymbols = [], { callerCounts } = {}) {
   const lines = source.split('\n');
   const pad = Math.max(String(lines.length).length, 4);
 
@@ -41,7 +43,7 @@ export function buildOutline(source, filePath, expandSymbols = []) {
   if (expandSymbols.length > 0) {
     return expandMode(lines, defs, filePath, expandSymbols, pad);
   }
-  return outlineMode(lines, defs, pad);
+  return outlineMode(lines, defs, pad, callerCounts);
 }
 
 function rawView(lines, pad) {
@@ -82,7 +84,7 @@ function expandMode(lines, defs, filePath, expandSymbols, pad) {
   return output.join('\n').trimEnd();
 }
 
-function outlineMode(lines, defs, pad) {
+function outlineMode(lines, defs, pad, callerCounts) {
   // Detect containers: definitions that have child definitions inside them
   const containers = new Set();
   for (const def of defs) {
@@ -96,6 +98,7 @@ function outlineMode(lines, defs, pad) {
   }
 
   // Build collapse ranges for leaf definitions with sufficient body size
+  // Track which definition each collapse range belongs to (for annotations)
   const collapseRanges = [];
   for (const def of defs) {
     if (containers.has(def)) continue;
@@ -109,6 +112,7 @@ function outlineMode(lines, defs, pad) {
       start: def.bodyStartLine,
       end: def.lineEnd,
       lineCount: bodyLineCount,
+      name: def.name,
     });
   }
 
@@ -122,10 +126,25 @@ function outlineMode(lines, defs, pad) {
   while (lineNum <= lines.length) {
     if (rangeIdx < collapseRanges.length && collapseRanges[rangeIdx].start === lineNum) {
       const range = collapseRanges[rangeIdx];
-      // Use the indent of the first body line for natural alignment
       const bodyLine = lines[lineNum - 1];
       const indent = bodyLine ? bodyLine.match(/^\s*/)[0] : '';
-      output.push(`${' '.repeat(pad)}│ ${indent}... (${range.lineCount} lines)`);
+      let marker = `${' '.repeat(pad)}│ ${indent}... (${range.lineCount} lines)`;
+
+      // Append caller annotation if available
+      if (callerCounts && callerCounts.has(range.name)) {
+        const count = callerCounts.get(range.name);
+        const annotation = count === 1 ? '← 1 caller' : `← ${count} callers`;
+        // Right-pad to align annotations
+        const minWidth = 60;
+        if (marker.length < minWidth) {
+          marker += ' '.repeat(minWidth - marker.length);
+        } else {
+          marker += '  ';
+        }
+        marker += annotation;
+      }
+
+      output.push(marker);
       lineNum = range.end + 1;
       rangeIdx++;
       continue;