@mishasinitcyn/betterrank 0.1.9 → 0.2.1

package/README.md

@@ -16,11 +16,23 @@ npm install -g @mishasinitcyn/betterrank
 # Get a ranked overview of any project
 betterrank map --root /path/to/project
 
+# View a file's skeleton without reading the whole thing
+betterrank outline src/auth.py
+
+# Expand a specific function to see its full source
+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
@@ -45,6 +57,45 @@ JavaScript, TypeScript, Python, Rust, Go, Java, Ruby, C, C++, C#, PHP
 
 ## Commands
 
+### `outline` — File skeleton with collapsed bodies
+
+View a file's structure without reading the entire thing. Function and class bodies are collapsed to `... (N lines)`. Expand specific symbols by name. **No `--root` required** — works on any file standalone.
+
+```bash
+# Skeleton view: imports, signatures, constants — bodies collapsed
+betterrank outline src/auth.py
+
+# Expand a specific function to see its full source
+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 (with `--annotate`):**
+```
+   1│ from fastapi import APIRouter, Depends
+   2│ from core.auth import verify_auth
+   3│
+   4│ router = APIRouter(prefix="/api")
+   5│
+   6│ @router.get("/users")
+   7│ async def list_users(db = Depends(get_db)):
+    │   ... (25 lines)                                          ← 2 callers
+  33│
+  34│ @router.post("/users")
+  35│ async def create_user(data: UserCreate, db = Depends(get_db)):
+    │   ... (40 lines)                                          ← 5 callers
+```
+
+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
 
 Summary of the most structurally important definitions, ranked by PageRank. Default limit is 50 symbols.
@@ -77,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
@@ -99,6 +211,14 @@ betterrank neighborhood src/auth.ts --root /path/to/project --count
 betterrank neighborhood src/auth.ts --root /path/to/project --hops 2 --limit 10
 ```
 
+### `orphans` — Find disconnected files/symbols
+
+```bash
+betterrank orphans --root /path/to/project                          # orphan files
+betterrank orphans --level symbol --root /path/to/project           # orphan symbols
+betterrank orphans --level symbol --kind function --root /path/to/project
+```
+
 ### `structure` — File tree with symbol counts
 
 ```bash
@@ -135,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.1.9",
+  "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

@@ -2,6 +2,7 @@
 
 import { CodeIndex } from './index.js';
 import { resolve, relative, isAbsolute } from 'path';
+import { readFile } from 'fs/promises';
 
 const DEFAULT_LIMIT = 50;
 const DEFAULT_DEPTH = 3;
@@ -11,11 +12,14 @@ betterrank <command> [options]
 
 Commands:
   ui          [--port N]                            Launch web UI (default port: 3333)
+  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)
@@ -32,6 +36,28 @@ Global flags:
 `.trim();
 
 const COMMAND_HELP = {
+  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.
+
+Without symbol names: shows the file skeleton — imports, constants, and
+function/class signatures with bodies replaced by "... (N lines)".
+
+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
+  --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/auth.py --annotate --root ./backend`,
+
   map: `betterrank map [--focus file1,file2] [--root <path>]
 
 Aider-style repo map: the most structurally important definitions ranked by PageRank.
@@ -94,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>]
 
@@ -230,6 +291,47 @@ async function main() {
     return; // Keep process alive (server is listening)
   }
 
+  // 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] [--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);
+
+    let source;
+    try {
+      source = await readFile(absPath, 'utf-8');
+    } catch (err) {
+      console.error(`Cannot read file: ${absPath}`);
+      console.error(err.message);
+      process.exit(1);
+    }
+
+    const relPath = relative(root, absPath);
+    const { buildOutline } = await import('./outline.js');
+
+    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;
+  }
+
   const projectRoot = resolve(flags.root || process.cwd());
   if (!flags.root) {
     process.stderr.write(`⚠ No --root specified, using cwd: ${projectRoot}\n`);
@@ -371,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);
@@ -387,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

@@ -0,0 +1,158 @@
+import { parseFile, SUPPORTED_EXTENSIONS } from './parser.js';
+import { extname } from 'path';
+
+const MIN_COLLAPSE_LINES = 2;
+
+/**
+ * Build an outline view of a source file.
+ *
+ * Without expandSymbols: returns a skeleton with function/class bodies collapsed.
+ * With expandSymbols: returns the full source of the specified symbols.
+ *
+ * @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 = [], { callerCounts } = {}) {
+  const lines = source.split('\n');
+  const pad = Math.max(String(lines.length).length, 4);
+
+  const ext = extname(filePath);
+  if (!SUPPORTED_EXTENSIONS.includes(ext)) {
+    return rawView(lines, pad);
+  }
+
+  const parsed = parseFile(filePath, source);
+  if (!parsed || parsed.definitions.length === 0) {
+    return rawView(lines, pad);
+  }
+
+  // Deduplicate definitions by lineStart (decorated_definition can cause dupes)
+  const seenLines = new Set();
+  const defs = parsed.definitions
+    .filter(d => {
+      if (seenLines.has(d.lineStart)) return false;
+      seenLines.add(d.lineStart);
+      return true;
+    })
+    .sort((a, b) => a.lineStart - b.lineStart);
+
+  if (expandSymbols.length > 0) {
+    return expandMode(lines, defs, filePath, expandSymbols, pad);
+  }
+  return outlineMode(lines, defs, pad, callerCounts);
+}
+
+function rawView(lines, pad) {
+  return lines.map((l, i) => `${String(i + 1).padStart(pad)}│ ${l}`).join('\n');
+}
+
+function expandMode(lines, defs, filePath, expandSymbols, pad) {
+  const output = [];
+
+  for (const symName of expandSymbols) {
+    const matches = defs.filter(d => d.name === symName);
+
+    if (matches.length === 0) {
+      output.push(`Symbol "${symName}" not found in ${filePath}`);
+      const similar = [...new Set(
+        defs.filter(d => d.name.toLowerCase().includes(symName.toLowerCase()))
+          .map(d => d.name)
+      )].slice(0, 5);
+      if (similar.length > 0) {
+        output.push(`Did you mean: ${similar.join(', ')}`);
+      } else {
+        output.push(`Available: ${defs.map(d => d.name).join(', ')}`);
+      }
+      continue;
+    }
+
+    for (const def of matches) {
+      if (matches.length > 1 || expandSymbols.length > 1) {
+        output.push(`── ${def.name} (${filePath}:${def.lineStart}-${def.lineEnd}) ──`);
+      }
+      for (let i = def.lineStart; i <= def.lineEnd; i++) {
+        output.push(`${String(i).padStart(pad)}│ ${lines[i - 1]}`);
+      }
+      if (matches.length > 1) output.push('');
+    }
+  }
+
+  return output.join('\n').trimEnd();
+}
+
+function outlineMode(lines, defs, pad, callerCounts) {
+  // Detect containers: definitions that have child definitions inside them
+  const containers = new Set();
+  for (const def of defs) {
+    for (const other of defs) {
+      if (other === def) continue;
+      if (other.lineStart > def.lineStart && other.lineEnd <= def.lineEnd) {
+        containers.add(def);
+        break;
+      }
+    }
+  }
+
+  // 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;
+    if (!def.bodyStartLine) continue;
+    if (def.bodyStartLine > def.lineEnd) continue;
+
+    const bodyLineCount = def.lineEnd - def.bodyStartLine + 1;
+    if (bodyLineCount < MIN_COLLAPSE_LINES) continue;
+
+    collapseRanges.push({
+      start: def.bodyStartLine,
+      end: def.lineEnd,
+      lineCount: bodyLineCount,
+      name: def.name,
+    });
+  }
+
+  collapseRanges.sort((a, b) => a.start - b.start);
+
+  // Walk lines, skipping collapsed ranges
+  const output = [];
+  let lineNum = 1;
+  let rangeIdx = 0;
+
+  while (lineNum <= lines.length) {
+    if (rangeIdx < collapseRanges.length && collapseRanges[rangeIdx].start === lineNum) {
+      const range = collapseRanges[rangeIdx];
+      const bodyLine = lines[lineNum - 1];
+      const indent = bodyLine ? bodyLine.match(/^\s*/)[0] : '';
+      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;
+    }
+
+    output.push(`${String(lineNum).padStart(pad)}│ ${lines[lineNum - 1]}`);
+    lineNum++;
+  }
+
+  return output.join('\n');
+}

package/src/parser.js

@@ -246,6 +246,26 @@ const KIND_MAP = {
   decorated_definition: 'function',
 };
 
+/**
+ * Find the body/block node of a definition, drilling into wrappers like
+ * lexical_declaration → variable_declarator → arrow_function → body.
+ */
+function findBodyNode(node) {
+  let body = node.childForFieldName('body');
+  if (body) return body;
+
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    body = child.childForFieldName('body');
+    if (body) return body;
+    for (let j = 0; j < child.namedChildCount; j++) {
+      body = child.namedChild(j).childForFieldName('body');
+      if (body) return body;
+    }
+  }
+  return null;
+}
+
 function nodeKind(nodeType) {
   return KIND_MAP[nodeType] || 'other';
 }
@@ -309,6 +329,17 @@ function parseFile(filePath, source) {
         if (!nameCapture) continue;
         const defNode = defCapture || nameCapture;
 
+        // Compute where body content starts (for outline collapsing)
+        const bodyNode = findBodyNode(defNode.node);
+        let bodyStartLine = null;
+        if (bodyNode) {
+          const bodyRow = bodyNode.startPosition.row;    // 0-indexed
+          const defRow = defNode.node.startPosition.row; // 0-indexed
+          // If body opens on same line as def (JS: `function foo() {`),
+          // content starts on next line. Otherwise body IS the content.
+          bodyStartLine = bodyRow === defRow ? bodyRow + 2 : bodyRow + 1; // 1-indexed
+        }
+
         definitions.push({
           name: nameCapture.node.text,
           kind: nodeKind(defNode.node.type),
@@ -316,6 +347,7 @@ function parseFile(filePath, source) {
           lineStart: defNode.node.startPosition.row + 1,
           lineEnd: defNode.node.endPosition.row + 1,
           signature: extractSignature(defNode.node, langName),
+          bodyStartLine,
         });
       }
     } catch (e) {