ucn 3.7.46 → 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 |
@@ -145,12 +164,21 @@ ucn [target] <command> [name] [--flags]
 | `--detailed` | Show full symbol listing per file in `toc` |
 | `--top-level` | Show only top-level functions in `toc` (exclude nested/indented) |
 | `--top=N` | Limit result count (default: 10 for most commands) |
+| `--limit=N` | Limit result count for `find`, `usages`, `search`, `deadcode`, `api`, `toc` |
+| `--max-files=N` | Max files to index (for large projects with 10K+ files) |
 | `--max-lines=N` | Max source lines for `class` (large classes show summary by default) |
 | `--case-sensitive` | Case-sensitive text search (default: case-insensitive) |
 | `--exact` | Exact name match only in `find`/`typedef` (no substring) |
 | `--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
 
@@ -162,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

@@ -102,6 +102,16 @@ function parseFlags(tokens) {
         regex: tokens.includes('--no-regex') ? false : undefined,
         functions: tokens.includes('--functions'),
         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'),
     };
 }
 
@@ -126,7 +136,8 @@ const knownFlags = new Set([
     '--default', '--top', '--no-follow-symlinks',
     '--base', '--staged', '--stack',
     '--regex', '--no-regex', '--functions',
-    '--max-lines', '--class-name'
+    '--max-lines', '--class-name', '--limit', '--max-files',
+    '--type', '--param', '--receiver', '--returns', '--decorator', '--exported', '--unused'
 ]);
 
 // Handle help flag
@@ -285,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]}`);
     }
 
@@ -340,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));
@@ -396,7 +413,7 @@ function runProjectCommand(rootDir, command, arg) {
     // If cache was loaded but stale, force rebuild to avoid duplicates
     let needsCacheSave = false;
     if (!usedCache) {
-        index.build(null, { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks });
+        index.build(null, { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, maxFiles: flags.maxFiles });
         needsCacheSave = flags.cache;
     }
 
@@ -408,8 +425,9 @@ function runProjectCommand(rootDir, command, arg) {
         // ── Commands using shared executor ───────────────────────────────
 
         case 'toc': {
-            const { ok, result, error } = execute(index, 'toc', flags);
+            const { ok, result, error, note } = execute(index, 'toc', flags);
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result, output.formatTocJson, r => output.formatToc(r, {
                 detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol',
                 uncertainHint: 'use --include-uncertain to include all'
@@ -429,8 +447,9 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'usages': {
-            const { ok, result, error } = execute(index, 'usages', { name: arg, ...flags });
+            const { ok, result, error, note } = execute(index, 'usages', { name: arg, ...flags });
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result,
                 r => output.formatUsagesJson(r, arg),
                 r => output.formatUsages(r, arg)
@@ -533,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);
@@ -547,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);
@@ -642,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': {
@@ -664,9 +704,17 @@ 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 } = execute(index, 'api', { file: arg });
+            const { ok, result, error, note } = execute(index, 'api', { file: arg || flags.file, limit: flags.limit });
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result,
                 r => output.formatApiJson(r, arg),
                 r => output.formatApi(r, arg)
@@ -675,18 +723,23 @@ 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;
         }
 
         case 'deadcode': {
-            const { ok, result, error } = execute(index, 'deadcode', { ...flags, in: flags.in || subdirScope });
+            const { ok, result, error, note } = execute(index, 'deadcode', { ...flags, in: flags.in || subdirScope });
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result,
                 output.formatDeadcodeJson,
                 r => output.formatDeadcode(r, {
@@ -987,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
 
@@ -998,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
@@ -1015,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
@@ -1040,6 +1098,8 @@ Common Flags:
   --direction=X       Graph direction: imports, importers, or both (default: both)
   --all               Expand truncated sections (about, trace, graph, related)
   --top=N             Limit results (find, deadcode)
+  --limit=N           Limit result count (find, usages, search, deadcode, api, toc)
+  --max-files=N       Max files to index (large projects)
   --context=N         Lines of context around matches
   --json              Machine-readable output
   --code-only         Filter out comments and strings
@@ -1120,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
@@ -1341,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; }
@@ -1348,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; }
@@ -1356,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; }
@@ -1384,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;
         }