ucn 3.7.47 → 3.8.0

package/.claude/skills/ucn/SKILL.md

@@ -49,7 +49,17 @@ ucn impact score_trend --exclude=test  # Only production callers
 
 Replaces: grep for the function name → manually filtering definitions vs calls vs imports → reading context around each match.
 
-### 3. `trace` — Understand execution flow
+### 3. `blast` — Transitive blast radius
+
+Walks UP the caller chain recursively. Shows the full tree of functions affected transitively if you change something. Like `impact` but recursive — answers "what breaks if I change this, including indirect callers?"
+
+```bash
+ucn blast helper                     # callers of callers (depth 3)
+ucn blast helper --depth=5           # deeper chain
+ucn blast helper --exclude=test      # skip test callers
+```
+
+### 4. `trace` — Understand execution flow (downward)
 
 Draws the call tree downward from any function. Compact by default; setting `--depth=N` shows the full tree to that depth with all children expanded.
 
@@ -61,7 +71,7 @@ ucn trace generate_report --all      # all children at default depth
 
 Shows the entire pipeline — what `generate_report` calls, what those functions call, etc. — as an indented tree. No file reading needed. Invaluable for understanding orchestrator functions or entry points.
 
-### 4. `fn` / `class` — Extract without reading the whole file
+### 5. `fn` / `class` — Extract without reading the whole file
 
 Pull one or more functions out of a large file. Supports comma-separated names for bulk extraction.
 
@@ -71,7 +81,7 @@ ucn fn parse,format,validate        # Extract multiple functions in one call
 ucn class MarketDataFetcher
 ```
 
-### 5. `deadcode` — Find unused code
+### 6. `deadcode` — Find unused code
 
 Lists all functions and classes with zero callers across the project.
 
@@ -86,6 +96,9 @@ ucn deadcode --exclude=test         # Skip test files (most useful)
 |-----------|---------|-------------|
 | Quick callers + callees list | `ucn context <name>` | Who calls it and what it calls. Results are numbered for `expand`. Use instead of `about` when you just need the call graph, not source code |
 | Need function + all its helpers inline | `ucn smart <name>` | Returns function source with every helper it calls expanded below it. Use instead of `about` when you need code, not metadata |
+| Full transitive blast radius | `ucn blast <name> --depth=5` | Callers of callers — the full chain of what breaks if you change something |
+| How execution reaches a function | `ucn reverse-trace <name>` | Walk UP callers to entry points (★ marked). Shows how code flows to this function. Default depth=5 |
+| Which tests to run after a change | `ucn affected-tests <name>` | Blast + test detection: shows test files, coverage %, uncovered functions. Use `--depth=N` to control depth |
 | What changed and who's affected | `ucn diff-impact --base=main` | Shows changed functions + their callers from git diff |
 | Checking if a refactor broke signatures | `ucn verify <name>` | Validates all call sites match the function's parameter count |
 | Understanding a file's role in the project | `ucn imports <file>` | What it depends on |
@@ -97,10 +110,16 @@ ucn deadcode --exclude=test         # Skip test files (most useful)
 | Text search with context | `ucn search term --context=3` | Like grep -C 3, shows surrounding lines |
 | Regex search (default) | `ucn search '\d+'` | Search supports regex by default (alternation, character classes, etc.) |
 | Text search filtered | `ucn search term --exclude=test` | Search only in matching files |
+| Structural search (index) | `ucn search --type=function --param=Request` | Query the symbol table, not text. Finds functions by param, return type, decorator, etc. |
+| Find all db.* calls | `ucn search --type=call --receiver=db` | Search call sites by receiver — something grep can't do |
+| Find exported functions | `ucn search --type=function --exported` | Only exported/public symbols |
+| Find unused symbols | `ucn search --type=function --unused` | Mini deadcode: zero callers |
+| Find decorated functions | `ucn search --decorator=Route` | Functions/classes with a specific decorator/annotation |
 | Finding all usages (not just calls) | `ucn usages <name>` | Groups into: definitions, calls, imports, type references |
 | Finding sibling/related functions | `ucn related <name>` | Name-based + structural matching (same file, shared deps). Not semantic — best for parse/format pairs |
 | Preview a rename or param change | `ucn plan <name> --rename-to=new_name` | Shows what would change without doing it |
 | File-level dependency tree | `ucn graph <file> --depth=1` | Visual import tree. Setting `--depth=N` expands all children. Can be noisy — use depth=1 for large projects. For function-level flow, use `trace` instead |
+| Are there circular dependencies? | `ucn circular-deps` | Detect circular import chains. `--file=<pattern>` filters to cycles involving a file. `--exclude=test` skips test files |
 | Find which tests cover a function | `ucn tests <name>` | Test files and test function names |
 | Extract specific lines from a file | `ucn lines --file=<file> --range=10-20` | Pull a line range without reading the whole file |
 | Find type definitions | `ucn typedef <name>` | Interfaces, enums, structs, traits, type aliases |
@@ -153,6 +172,13 @@ ucn [target] <command> [name] [--flags]
 | `--include-uncertain` | Include ambiguous/uncertain matches in `context`/`smart`/`about` |
 | `--include-exported` | Include exported symbols in `deadcode` results |
 | `--include-decorated` | Include decorated/annotated symbols in `deadcode` results |
+| `--type=<kind>` | Structural search: `function`, `class`, `call`, `method`, `type`. Triggers index query instead of text grep |
+| `--param=<name>` | Structural search: filter by parameter name or type (e.g., `--param=Request`) |
+| `--receiver=<name>` | Structural search: filter calls by receiver (e.g., `--receiver=db` for all db.* calls) |
+| `--returns=<type>` | Structural search: filter by return type (e.g., `--returns=error`) |
+| `--decorator=<name>` | Structural search: filter by decorator/annotation (e.g., `--decorator=Route`) |
+| `--exported` | Structural search: only exported/public symbols |
+| `--unused` | Structural search: only symbols with zero callers |
 
 ## Workflow Integration
 
@@ -164,7 +190,9 @@ ucn trace problematic_function --depth=2  # See what it calls
 
 **Before modifying a function:**
 ```bash
-ucn impact the_function                 # Who will break?
+ucn impact the_function                 # Who will break? (direct callers)
+ucn blast the_function                  # Who will break? (full transitive chain)
+ucn affected-tests the_function         # Which tests to run after the change?
 ucn smart the_function                  # See it + its helpers
 # ... make changes ...
 ucn verify the_function                 # Did all call sites survive?

package/README.md

@@ -38,7 +38,7 @@ Supports JS/TS, Python, Go, Rust, Java, and HTML. Runs locally.
                             │
                      ┌──────┴──────┐
                      │ UCN Engine  │
-                     │ 28 commands │
+                     │  commands   │
                      │ tree-sitter │
                      └─────────────┘
 ```
@@ -138,7 +138,7 @@ VS Code uses `.vscode/mcp.json`:
 
 </details>
 
-All 28 commands ship as a single MCP tool - under 2KB of context.
+All commands ship as a single MCP tool - under 2KB of context.
 
 ### Agent Skill (no server needed)
 
@@ -265,28 +265,31 @@ ucn deadcode --exclude=test                # what can be deleted?
 
 ---
 
-## All 28 commands
+## All commands
 
 ```
   UNDERSTAND                          MODIFY SAFELY
   ─────────────────────               ─────────────────────
   about         full picture          impact          all call sites
-  context       callers + callees     diff-impact     git diff + callers
-  smart         function + helpers    verify          signature check
-  trace         call tree             plan            refactor preview
+  context       callers + callees     blast           transitive impact
+  smart         function + helpers    diff-impact     git diff + callers
+  trace         call tree             verify          signature check
+  reverse-trace callers → root        plan            refactor preview
 
   FIND & EXTRACT                      ARCHITECTURE
   ─────────────────────               ─────────────────────
   find          locate definitions    imports         file dependencies
   usages        all occurrences       exporters       reverse dependencies
   fn            extract function      graph           dependency tree
-  class         extract class         related         sibling functions
-  toc           project overview      tests           find test coverage
-  deadcode      unused code           stacktrace      error trace context
-  search        text search           api             public API surface
-  example       best usage example    typedef         type definitions
-  lines         extract line range    file-exports    file's exports
-  expand        drill into context    stats           project stats
+  class         extract class         circular-deps   import cycles
+  toc           project overview      related         sibling functions
+  deadcode      unused code           tests           find test coverage
+  search        text search           affected-tests  tests for changes
+  example       best usage example    stacktrace      error trace context
+  lines         extract line range    api             public API surface
+  expand        drill into context    typedef         type definitions
+                                      file-exports    file's exports
+                                      stats           project stats
 ```
 
 ---

package/cli/index.js

@@ -104,6 +104,14 @@ function parseFlags(tokens) {
         className: getValueFlag('--class-name'),
         limit: parseInt(getValueFlag('--limit') || '0') || undefined,
         maxFiles: parseInt(getValueFlag('--max-files') || '0') || undefined,
+        // Structural search flags
+        type: getValueFlag('--type'),
+        param: getValueFlag('--param'),
+        receiver: getValueFlag('--receiver'),
+        returns: getValueFlag('--returns'),
+        decorator: getValueFlag('--decorator'),
+        exported: tokens.includes('--exported'),
+        unused: tokens.includes('--unused'),
     };
 }
 
@@ -128,7 +136,8 @@ const knownFlags = new Set([
     '--default', '--top', '--no-follow-symlinks',
     '--base', '--staged', '--stack',
     '--regex', '--no-regex', '--functions',
-    '--max-lines', '--class-name', '--limit', '--max-files'
+    '--max-lines', '--class-name', '--limit', '--max-files',
+    '--type', '--param', '--receiver', '--returns', '--decorator', '--exported', '--unused'
 ]);
 
 // Handle help flag
@@ -287,7 +296,9 @@ function runFileCommand(filePath, command, arg) {
 
     // Require arg for commands that need it
     const needsArg = { fn: 'fn <name>', class: 'class <name>', find: 'find <name>', usages: 'usages <name>', search: 'search <term>', lines: 'lines <start-end>', typedef: 'typedef <name>' };
-    if (needsArg[canonical]) {
+    // Structural search doesn't require term
+    const isStructural = flags.type || flags.param || flags.receiver || flags.returns || flags.decorator || flags.exported || flags.unused;
+    if (needsArg[canonical] && !(canonical === 'search' && isStructural)) {
         requireArg(arg, `Usage: ucn <file> ${needsArg[canonical]}`);
     }
 
@@ -342,7 +353,11 @@ function runFileCommand(filePath, command, arg) {
             printOutput(result, r => output.formatUsagesJson(r, arg), r => output.formatUsages(r, arg));
             break;
         case 'search':
-            printOutput(result, r => output.formatSearchJson(r, arg), r => output.formatSearch(r, arg));
+            if (result && result.meta && result.meta.mode === 'structural') {
+                printOutput(result, output.formatStructuralSearchJson, output.formatStructuralSearch);
+            } else {
+                printOutput(result, r => output.formatSearchJson(r, arg), r => output.formatSearch(r, arg));
+            }
             break;
         case 'typedef':
             printOutput(result, r => output.formatTypedefJson(r, arg), r => output.formatTypedef(r, arg));
@@ -537,6 +552,13 @@ function runProjectCommand(rootDir, command, arg) {
             break;
         }
 
+        case 'blast': {
+            const { ok, result, error } = execute(index, 'blast', { name: arg, ...flags });
+            if (!ok) fail(error);
+            printOutput(result, output.formatBlastJson, output.formatBlast);
+            break;
+        }
+
         case 'plan': {
             const { ok, result, error } = execute(index, 'plan', { name: arg, ...flags });
             if (!ok) fail(error);
@@ -551,6 +573,13 @@ function runProjectCommand(rootDir, command, arg) {
             break;
         }
 
+        case 'reverseTrace': {
+            const { ok, result, error } = execute(index, 'reverseTrace', { name: arg, ...flags });
+            if (!ok) fail(error);
+            printOutput(result, output.formatReverseTraceJson, output.formatReverseTrace);
+            break;
+        }
+
         case 'stacktrace': {
             const { ok, result, error } = execute(index, 'stacktrace', { stack: arg });
             if (!ok) fail(error);
@@ -646,6 +675,13 @@ function runProjectCommand(rootDir, command, arg) {
             break;
         }
 
+        case 'circularDeps': {
+            const { ok, result, error } = execute(index, 'circularDeps', { file: flags.file, exclude: flags.exclude });
+            if (!ok) fail(error);
+            printOutput(result, output.formatCircularDepsJson, output.formatCircularDeps);
+            break;
+        }
+
         // ── Remaining commands ──────────────────────────────────────────
 
         case 'typedef': {
@@ -668,6 +704,13 @@ function runProjectCommand(rootDir, command, arg) {
             break;
         }
 
+        case 'affectedTests': {
+            const { ok, result, error } = execute(index, 'affectedTests', { name: arg, ...flags });
+            if (!ok) fail(error);
+            printOutput(result, output.formatAffectedTestsJson, output.formatAffectedTests);
+            break;
+        }
+
         case 'api': {
             const { ok, result, error, note } = execute(index, 'api', { file: arg || flags.file, limit: flags.limit });
             if (!ok) fail(error);
@@ -680,12 +723,16 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'search': {
-            const { ok, result, error } = execute(index, 'search', { term: arg, ...flags });
+            const { ok, result, error, structural } = execute(index, 'search', { term: arg, ...flags });
             if (!ok) fail(error);
-            printOutput(result,
-                r => output.formatSearchJson(r, arg),
-                r => output.formatSearch(r, arg)
-            );
+            if (structural) {
+                printOutput(result, output.formatStructuralSearchJson, output.formatStructuralSearch);
+            } else {
+                printOutput(result,
+                    r => output.formatSearchJson(r, arg),
+                    r => output.formatSearch(r, arg)
+                );
+            }
             break;
         }
 
@@ -993,7 +1040,9 @@ UNDERSTAND CODE (UCN's strength - semantic analysis)
   context <name>      Who calls this + what it calls (numbered for expand)
   smart <name>        Function + all dependencies inline
   impact <name>       What breaks if changed (call sites grouped by file)
+  blast <name>        Transitive blast radius (callers of callers, --depth=N)
   trace <name>        Call tree visualization (--depth=N expands all children)
+  reverse-trace <name> Upward call chain to entry points (--depth=N, default 5)
   related <name>      Find similar functions (same file, shared deps)
   example <name>      Best usage example with context
 
@@ -1004,7 +1053,9 @@ FIND CODE
   usages <name>       All usages grouped: definitions, calls, imports, references
   toc                 Table of contents (compact; --detailed lists all symbols)
   search <term>       Text search (regex default, --context=N, --exclude=, --in=)
+                      Structural: --type=function|class|call --param= --returns= --decorator= --exported --unused
   tests <name>        Find test files for a function
+  affected-tests <n>  Tests affected by a change (blast + test detection, --depth=N)
 
 ═══════════════════════════════════════════════════════════════════════════════
 EXTRACT CODE
@@ -1021,6 +1072,7 @@ FILE DEPENDENCIES
   exporters <file>    Who imports this file
   file-exports <file> What does file export
   graph <file>        Full dependency tree (--depth=N, --direction=imports|importers|both)
+  circular-deps       Detect circular import chains (--file=, --exclude=)
 
 ═══════════════════════════════════════════════════════════════════════════════
 REFACTORING HELPERS
@@ -1128,18 +1180,23 @@ Commands:
   expand <N>             Show code for item N from context
   smart <name>           Function + dependencies
   impact <name>          What breaks if changed
+  blast <name>           Transitive blast radius (--depth=N)
   trace <name>           Call tree (--depth=N)
+  reverse-trace <name>   Upward to entry points (--depth=N)
   example <name>         Best usage example
   related <name>         Sibling functions
   fn <name>[,n2,...]     Extract function(s) (--file=)
   class <name>           Extract class code (--file=)
   lines <range>          Extract lines (--file= required)
   graph <file>           File dependency tree (--direction=, --depth=)
+  circular-deps          Circular import chains (--file=, --exclude=)
   file-exports <file>    File's exported symbols
   imports <file>         What file imports
   exporters <file>       Who imports file
   tests <name>           Find tests (--calls-only)
+  affected-tests <n>     Tests affected by a change (--depth=N)
   search <term>          Text search (--context=N, --exclude=, --in=)
+                         Structural: --type= --param= --returns= --decorator= --exported --unused
   typedef <name>         Find type definitions
   deadcode               Find unused functions/classes
   verify <name>          Check call sites match signature
@@ -1349,6 +1406,13 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             break;
         }
 
+        case 'blast': {
+            const { ok, result, error } = execute(index, 'blast', { name: arg, ...iflags });
+            if (!ok) { console.log(error); return; }
+            console.log(output.formatBlast(result));
+            break;
+        }
+
         case 'trace': {
             const { ok, result, error } = execute(index, 'trace', { name: arg, ...iflags });
             if (!ok) { console.log(error); return; }
@@ -1356,6 +1420,13 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             break;
         }
 
+        case 'reverseTrace': {
+            const { ok, result, error } = execute(index, 'reverseTrace', { name: arg, ...iflags });
+            if (!ok) { console.log(error); return; }
+            console.log(output.formatReverseTrace(result));
+            break;
+        }
+
         case 'graph': {
             const { ok, result, error } = execute(index, 'graph', { file: arg, ...iflags });
             if (!ok) { console.log(error); return; }
@@ -1364,6 +1435,13 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             break;
         }
 
+        case 'circularDeps': {
+            const { ok, result, error } = execute(index, 'circularDeps', { file: iflags.file, exclude: iflags.exclude });
+            if (!ok) { console.log(error); return; }
+            console.log(output.formatCircularDeps(result));
+            break;
+        }
+
         case 'fileExports': {
             const { ok, result, error } = execute(index, 'fileExports', { file: arg });
             if (!ok) { console.log(error); return; }
@@ -1392,10 +1470,21 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             break;
         }
 
+        case 'affectedTests': {
+            const { ok, result, error } = execute(index, 'affectedTests', { name: arg, ...iflags });
+            if (!ok) { console.log(error); return; }
+            console.log(output.formatAffectedTests(result));
+            break;
+        }
+
         case 'search': {
-            const { ok, result, error } = execute(index, 'search', { term: arg, ...iflags });
+            const { ok, result, error, structural } = execute(index, 'search', { term: arg, ...iflags });
             if (!ok) { console.log(error); return; }
-            console.log(output.formatSearch(result, arg));
+            if (structural) {
+                console.log(output.formatStructuralSearch(result));
+            } else {
+                console.log(output.formatSearch(result, arg));
+            }
             break;
         }
 

package/core/callers.js

@@ -136,7 +136,13 @@ function findCallers(index, name, options = {}) {
     let pendingCount = 0;
     const maxResults = options.maxResults;
 
-    for (const [filePath, fileEntry] of index.files) {
+    // Use inverted callee index to skip files that don't contain calls to this name
+    const calleeFiles = index.getCalleeFiles(name);
+    const fileIterator = calleeFiles
+        ? [...calleeFiles].map(fp => [fp, index.files.get(fp)]).filter(([, fe]) => fe)
+        : index.files;
+
+    for (const [filePath, fileEntry] of fileIterator) {
         // Early exit when maxResults is reached
         if (maxResults && pendingCount >= maxResults) break;
         try {
@@ -361,6 +367,32 @@ function findCallers(index, name, options = {}) {
                     continue;
                 }
 
+                // Import-graph disambiguation for JS/TS/Python: when multiple definitions of
+                // the same name exist and this call has no bindingId, check whether the calling
+                // file imports from the target definition's file. Skips false positives like
+                // user_b importing from b.js being reported as a caller of a.js:process.
+                // Go/Java/Rust are excluded — they use package/module scoping, not file imports.
+                if (!bindingId && options.targetDefinitions && definitions.length > 1 &&
+                    fileEntry.language !== 'go' && fileEntry.language !== 'java' && fileEntry.language !== 'rust') {
+                    const targetFiles = new Set(targetDefs.map(d => d.file).filter(Boolean));
+                    if (targetFiles.size > 0 && !targetFiles.has(filePath)) {
+                        const imports = index.importGraph.get(filePath) || [];
+                        const importsTarget = imports.some(imp => targetFiles.has(imp));
+                        if (!importsTarget) {
+                            // Check one level of re-exports (barrel files)
+                            let foundViaReexport = false;
+                            for (const imp of imports) {
+                                const transImports = index.importGraph.get(imp) || [];
+                                if (transImports.some(ti => targetFiles.has(ti))) {
+                                    foundViaReexport = true;
+                                    break;
+                                }
+                            }
+                            if (!foundViaReexport) continue;
+                        }
+                    }
+                }
+
                 // Go unexported visibility: lowercase functions are package-private.
                 // Only allow callers from the same package directory.
                 if (fileEntry.language === 'go' && /^[a-z]/.test(name)) {
@@ -375,7 +407,9 @@ function findCallers(index, name, options = {}) {
                 // Go/Java/Rust: method vs non-method cross-matching filter.
                 // Prevents t.Errorf() (method call) from matching standalone func Errorf,
                 // and cli.Run() (package call, isMethod:false) from matching DeploymentController.Run.
-                if (!bindingId && !resolvedBySameClass &&
+                // Rust path calls (module::func(), Type::new()) bypass this filter — they're
+                // scoped_identifier calls that can target both standalone functions and impl methods.
+                if (!bindingId && !resolvedBySameClass && !call.isPathCall &&
                     (fileEntry.language === 'go' || fileEntry.language === 'java' || fileEntry.language === 'rust')) {
                     const targetHasClass = targetDefs.some(d => d.className);
                     if (call.isMethod && !targetHasClass) {

package/core/deadcode.js

@@ -7,6 +7,20 @@
 
 const { detectLanguage, getParser, getLanguageModule, safeParse } = require('../languages');
 const { isTestFile } = require('./discovery');
+const { escapeRegExp } = require('./shared');
+
+/** Check if a position in a line is inside a string literal (quotes/backticks) */
+function isInsideString(line, pos) {
+    let inSingle = false, inDouble = false, inBacktick = false;
+    for (let j = 0; j < pos; j++) {
+        const ch = line[j];
+        if (ch === '\\') { j++; continue; }
+        if (ch === '"' && !inSingle && !inBacktick) inDouble = !inDouble;
+        if (ch === "'" && !inDouble && !inBacktick) inSingle = !inSingle;
+        if (ch === '`' && !inDouble && !inSingle) inBacktick = !inBacktick;
+    }
+    return inSingle || inDouble || inBacktick;
+}
 
 /**
  * Build a usage index for identifiers in the codebase (optimized for deadcode)
@@ -25,6 +39,19 @@ function buildUsageIndex(index, filterNames) {
 
             const content = index._readFile(filePath);
 
+            // Text pre-filter: skip files that don't contain any target names
+            // (avoids expensive tree-sitter parse + AST traversal for irrelevant files)
+            if (filterNames && filterNames.size > 0) {
+                let hasAny = false;
+                for (const name of filterNames) {
+                    if (content.includes(name)) {
+                        hasAny = true;
+                        break;
+                    }
+                }
+                if (!hasAny) continue;
+            }
+
             // For HTML files, parse the virtual JS content instead of raw HTML
             // (HTML tree-sitter sees script content as raw_text, not JS identifiers)
             let tree;
@@ -163,6 +190,11 @@ function deadcode(index, options = {}) {
     let excludedDecorated = 0;
     let excludedExported = 0;
 
+    // Ensure callee index is built (lazy, reused across operations)
+    if (!index.calleeIndex) {
+        index.buildCalleeIndex();
+    }
+
     // Collect callable symbol names to reduce usage index scope
     const callableTypes = ['function', 'method', 'static', 'public', 'abstract', 'constructor'];
     const callableNames = new Set();
@@ -172,8 +204,71 @@ function deadcode(index, options = {}) {
         }
     }
 
-    // Build usage index once (instead of per-symbol), filtered to callable names only
-    const usageIndex = buildUsageIndex(index, callableNames);
+    // Pre-filter: names in the callee index have call sites → definitely used → not dead.
+    const potentiallyDeadNames = new Set();
+    for (const name of callableNames) {
+        if (!index.calleeIndex.has(name)) {
+            potentiallyDeadNames.add(name);
+        }
+    }
+
+    // Build usage index for potentially dead names using text scan (no tree-sitter reparsing).
+    // The callee index already covers all call-based usages. For remaining names, a word-boundary
+    // text scan catches imports, exports, shorthand properties, type refs, and variable refs.
+    // Trade-off: may match names in comments/strings (false "used" → fewer dead code reports),
+    // but avoids ~1.9s of tree-sitter re-parsing. buildUsageIndex() is kept for direct callers.
+    const usageIndex = new Map();
+    if (potentiallyDeadNames.size > 0) {
+        for (const [filePath, fileEntry] of index.files) {
+            try {
+                const content = index._readFile(filePath);
+                const lines = content.split('\n');
+                for (const name of potentiallyDeadNames) {
+                    if (!content.includes(name)) continue;
+                    const nameLen = name.length;
+                    for (let i = 0; i < lines.length; i++) {
+                        const line = lines[i];
+                        if (!line.includes(name)) continue;
+                        // Skip line if entirely inside a line comment (// or #)
+                        const commentIdx = line.indexOf('//');
+                        const hashIdx = line.indexOf('#');
+                        let searchFrom = 0;
+                        while (searchFrom < line.length) {
+                            const pos = line.indexOf(name, searchFrom);
+                            if (pos === -1) break;
+                            searchFrom = pos + 1;
+                            // Word boundary check
+                            if (pos > 0 && /\w/.test(line[pos - 1])) continue;
+                            if (pos + nameLen < line.length && /\w/.test(line[pos + nameLen])) continue;
+                            // Skip if inside a // comment (not :// URL)
+                            if (commentIdx !== -1 && commentIdx < pos &&
+                                (commentIdx === 0 || line[commentIdx - 1] !== ':')) continue;
+                            // Skip if inside a # comment (Python — # preceded by whitespace or at start)
+                            if (hashIdx !== -1 && hashIdx < pos &&
+                                (hashIdx === 0 || /\s/.test(line[hashIdx - 1]))) continue;
+                            // Skip if inside a string literal
+                            if (isInsideString(line, pos)) continue;
+                            // Skip property/field access: preceded by '.' unless followed by '(' (method call)
+                            if (pos > 0 && line[pos - 1] === '.' &&
+                                (pos + nameLen >= line.length || line[pos + nameLen] !== '(')) continue;
+                            // Skip object literal key: name followed by ':' (not '::' for Rust paths)
+                            const afterChar = pos + nameLen < line.length ? line[pos + nameLen] : '';
+                            const afterChar2 = pos + nameLen + 1 < line.length ? line[pos + nameLen + 1] : '';
+                            if (afterChar === ':' && afterChar2 !== ':') continue;
+                            // Valid reference found
+                            if (!usageIndex.has(name)) usageIndex.set(name, []);
+                            usageIndex.get(name).push({
+                                file: filePath,
+                                line: i + 1,
+                                relativePath: fileEntry.relativePath
+                            });
+                            break; // one match per line is enough for deadcode
+                        }
+                    }
+                }
+            } catch {}
+        }
+    }
 
     for (const [name, symbols] of index.symbols) {
         for (const symbol of symbols) {
@@ -308,7 +403,12 @@ function deadcode(index, options = {}) {
                 continue;
             }
 
-            // Use pre-built index for O(1) lookup instead of O(files) scan
+            // Fast path: name has call sites in callee index → definitely used → not dead
+            if (index.calleeIndex.has(name)) {
+                continue;
+            }
+
+            // Slow path: check AST-based usage index for remaining names
             const allUsages = usageIndex.get(name) || [];
 
             // Filter out usages that are at the definition location