ucn 3.4.2 → 3.4.3

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

@@ -1,142 +1,140 @@
 ---
 name: ucn
-description: Universal Code Navigator - extracts specific functions and their relationships (callers, callees, dependencies) without reading entire files. Use when you need one function from a large file or need to understand what calls/is called by a function. Saves context in codebases 1000+ LOC. Skip for simple text search, tiny codebases, or unsupported languages (only JS/TS, Python, Go, Rust, Java).
+description: "Code relationship analyzer (callers, call trees, impact, dead code) via tree-sitter AST. PREFER over grep+read when you need: who calls a function, what breaks if you change it, or the full call chain of a pipeline. One `ucn about` replaces 3-4 grep+read cycles. One `ucn trace` maps an entire execution flow without reading any files. Works on Python, JS/TS, Go, Rust, Java. Skip for plain text search or codebases under 500 LOC."
 allowed-tools: Bash(ucn *), Bash(npx ucn *)
 argument-hint: "[command] [symbol-name] [--flags]"
 ---
 
-# UCN - Universal Code Navigator
+# UCN — Universal Code Navigator
 
-UCN uses tree-sitter ASTs to understand code structure: functions, classes, callers, callees, imports, and dependencies. It works on JavaScript/TypeScript, Python, Go, Rust, and Java.
+Understands code structure via tree-sitter ASTs: who calls what, what breaks if you change something, full call trees, dead code. Works on Python, JS/TS, Go, Rust, Java.
 
-## When to Use vs Skip
+## When to Reach for UCN Instead of Grep/Read
 
-**Use UCN when** the codebase is 1000+ LOC and you need:
-- Who calls a function or what it calls
-- What breaks if you change something
-- One function from a large file (without reading the whole file)
-- Unused code detection, dependency graphs
+**Use UCN when your next action would be:**
 
-**Skip UCN when:**
-- Simple text search (TODOs, error messages) — use grep
-- Codebase < 500 LOC — just read the files
-- Language not supported — use grep/read
+- "Let me grep for all callers of this function" → `ucn impact <name>` — finds every call site, grouped by file, with args shown
+- "Let me read this 800-line file to find one function" → `ucn fn <name> --file=<hint>` — extracts just that function
+- "Let me trace through this code to understand the flow" → `ucn trace <name> --depth=3` — shows the full call tree without reading any files
+- "I need to understand this function before changing it" → `ucn about <name>` — returns definition + callers + callees + tests + source in one call
+- "I wonder if anything still uses this code" → `ucn deadcode` — lists every function/class with zero callers
+
+**Stick with grep/read when:**
+
+- Searching for a string literal, error message, TODO, or config value
+- The codebase is under 500 LOC — just read the files
+- Language not supported (only Python, JS/TS, Go, Rust, Java)
 - Finding files by name — use glob
 
-## Command Format
+## The 5 Commands You'll Use Most
 
-```
-ucn [target] <command> [name] [--flags]
+### 1. `about` — First stop for any investigation
+
+One command returns: definition, source code, who calls it, what it calls, related tests.
+
+```bash
+ucn about compute_composite
 ```
 
-**Target** (optional, defaults to current directory):
-- Omit or `.` — current project directory (most common)
-- `path/to/file.js` — single file mode
-- `path/to/dir` — specific project directory
-- `"src/**/*.py"` — glob pattern (quote it)
+Replaces: grep for definition → read the file → grep for callers → grep for tests. All in one call.
+
+### 2. `impact` — Before changing any function
+
+Shows every call site with arguments and surrounding context. Essential before modifying a signature, renaming, or deleting.
 
-**Examples of correct invocation:**
 ```bash
-ucn about handleRequest
-ucn fn parseConfig --file=utils
-ucn toc
-ucn src/api/routes.js fn handleRequest
-ucn impact createUser --exclude=test
+ucn impact score_trend              # Every caller, grouped by file
+ucn impact score_trend --exclude=test  # Only production callers
 ```
 
-## Commands
-
-### Understand Code
-| Command | Args | What it returns |
-|---------|------|-----------------|
-| `about <name>` | symbol name | Definition + callers + callees + tests + source code. **Start here.** |
-| `context <name>` | symbol name | Callers and callees (numbered — use `expand N` to see code) |
-| `smart <name>` | symbol name | Function source + all helper functions it calls, inline |
-| `impact <name>` | symbol name | Every call site grouped by file. Use before modifying a function. |
-| `trace <name>` | symbol name | Call tree (who calls who) at `--depth=N` (default 3) |
-| `example <name>` | symbol name | Best real usage example with surrounding context |
-
-### Find Code
-| Command | Args | What it returns |
-|---------|------|-----------------|
-| `find <name>` | symbol name | Definitions ranked by usage count (top 5) |
-| `usages <name>` | symbol name | All usages grouped: definitions, calls, imports, references |
-| `toc` | none | Table of contents: all functions, classes, exports |
-| `tests <name>` | symbol name | Test files and test functions for the given symbol |
-| `search <text>` | search term | Text search (grep-like, but respects project ignores) |
-| `deadcode` | none | Lists all functions/classes with zero callers |
-
-### Extract Code
-| Command | Args | What it returns |
-|---------|------|-----------------|
-| `fn <name>` | function name | Full function source code |
-| `class <name>` | class name | Full class source code |
-| `lines <range>` | e.g. `50-100` | Lines from file. In project mode requires `--file=<path>` |
-| `expand <N>` | number | Source code for numbered item from last `context` output |
-
-### Dependencies
-| Command | Args | What it returns |
-|---------|------|-----------------|
-| `imports <file>` | relative path | What the file imports (modules, symbols) |
-| `exporters <file>` | relative path | Which files import this file |
-| `file-exports <file>` | relative path | What the file exports |
-| `graph <file>` | relative path | Dependency tree at `--depth=N` |
-
-### Refactoring
-| Command | Args | What it returns |
-|---------|------|-----------------|
-| `verify <name>` | function name | Checks all call sites match the function's signature |
-| `plan <name>` | function name | Preview refactoring with `--rename-to`, `--add-param`, `--remove-param` |
-| `related <name>` | symbol name | Functions in same file or sharing dependencies |
+Replaces: grep for the function name → manually filtering definitions vs calls vs imports → reading context around each match.
 
-## Key Flags
+### 3. `trace` — Understand execution flow
+
+Draws the call tree downward from any function. Depth-limited.
 
-| Flag | Works with | Effect |
-|------|-----------|--------|
-| `--file=<pattern>` | any symbol command | Filter by file path when name is ambiguous (e.g., `--file=routes`) |
-| `--exclude=a,b` | any | Exclude files matching patterns (e.g., `--exclude=test,mock`) |
-| `--in=<path>` | any | Only search within path (e.g., `--in=src/core`) |
-| `--include-tests` | any | Include test files in results (excluded by default) |
-| `--include-methods` | `context`, `smart` | Include `obj.method()` calls (only direct calls shown by default) |
-| `--depth=N` | `trace`, `graph`, `about`, `find` | Tree/expansion depth (default 3) |
-| `--context=N` | `usages`, `search` | Lines of context around each match |
-| `--json` | any | Machine-readable JSON output |
-| `--code-only` | `search` | Exclude matches in comments and strings |
-| `--with-types` | `smart`, `about` | Include type definitions |
-| `--top=N` / `--all` | `find`, `usages` | Limit results to top N, or show all |
-| `--no-cache` | any | Skip cached index (use after file changes) |
-| `--clear-cache` | any | Delete cached index before running |
-
-## Common Patterns
-
-**Investigate a function (first stop):**
 ```bash
-ucn about handleRequest
+ucn trace generate_report --depth=3
 ```
 
-**Before modifying a function:**
+This 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
+
+Pull one function or class out of a large file. Saves hundreds of lines of context window.
+
 ```bash
-ucn impact handleRequest          # See all callers
-ucn smart handleRequest           # See function + its helpers
+ucn fn handle_request --file=api    # --file disambiguates when name exists in multiple files
+ucn class MarketDataFetcher
 ```
 
-**Extract one function from a large file:**
+### 5. `deadcode` — Find unused code
+
+Lists all functions and classes with zero callers across the project.
+
 ```bash
-ucn fn handleRequest --file=api   # Disambiguate by file path
+ucn deadcode                        # Everything
+ucn deadcode --exclude=test         # Skip test files (most useful)
+```
+
+## When to Use the Other Commands
+
+| Situation | Command | What it does |
+|-----------|---------|-------------|
+| Need function + all its helpers inline | `ucn smart <name>` | Returns function source with every helper it calls expanded below it |
+| 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 |
+| Understanding who depends on a file | `ucn exporters <file>` | Which files import it |
+| Quick project overview | `ucn toc` | Every file with function/class counts and line counts |
+| Finding all usages (not just calls) | `ucn usages <name>` | Groups into: definitions, calls, imports, type references |
+| Finding related code to refactor together | `ucn related <name>` | Functions sharing dependencies or in same file |
+| Preview a rename or param change | `ucn plan <name> --rename-to=new_name` | Shows what would change without doing it |
+| Dependency tree for a file | `ucn graph <file> --depth=2` | Visual import tree |
+| Find which tests cover a function | `ucn tests <name>` | Test files and test function names |
+
+## Command Format
+
+```
+ucn [target] <command> [name] [--flags]
 ```
 
-**Find unused code:**
+**Target** (optional, defaults to current directory):
+- Omit — scans current project (most common)
+- `path/to/file.py` — single file
+- `path/to/dir` — specific directory
+- `"src/**/*.py"` — glob pattern (quote it)
+
+## Key Flags
+
+| Flag | When to use it |
+|------|---------------|
+| `--file=<pattern>` | Disambiguate when a name exists in multiple files (e.g., `--file=api`) |
+| `--exclude=test,mock` | Focus on production code only |
+| `--in=src/core` | Limit search to a subdirectory |
+| `--depth=N` | Control tree depth for `trace` and `graph` (default 3) |
+| `--include-tests` | Include test files in results (excluded by default) |
+| `--include-methods` | Include `obj.method()` calls in `context`/`smart` (only direct calls shown by default) |
+| `--no-cache` | Force re-index after editing files |
+| `--context=N` | Lines of surrounding context in `usages`/`search` output |
+
+## Workflow Integration
+
+**Investigating a bug:**
 ```bash
-ucn deadcode
+ucn about problematic_function          # Understand it fully
+ucn trace problematic_function --depth=2  # See what it calls
 ```
 
-**Understand a file's role:**
+**Before modifying a function:**
 ```bash
-ucn imports core/project.js       # What it depends on
-ucn exporters core/project.js     # Who depends on it
+ucn impact the_function                 # Who will break?
+ucn smart the_function                  # See it + its helpers
+# ... make your changes ...
+ucn verify the_function                 # Did all call sites survive?
 ```
 
-**Multiple queries (keeps index in memory):**
+**Periodic maintenance:**
 ```bash
-ucn --interactive
+ucn deadcode --exclude=test             # What can be deleted?
+ucn toc                                 # Project overview
 ```

package/README.md

@@ -267,6 +267,28 @@ Quick Start:
   ucn --interactive                   # Multiple queries
 ```
 
+## Workflows
+
+**Investigating a bug:**
+```bash
+ucn about problematic_function          # Understand it fully
+ucn trace problematic_function --depth=2  # See what it calls
+```
+
+**Before modifying a function:**
+```bash
+ucn impact the_function                 # Who will break?
+ucn smart the_function                  # See it + its helpers
+# ... make your changes ...
+ucn verify the_function                 # Did all call sites survive?
+```
+
+**Periodic cleanup:**
+```bash
+ucn deadcode --exclude=test             # What can be deleted?
+ucn toc                                 # Project overview
+```
+
 ## License
 
 MIT

package/cli/index.js

@@ -2226,7 +2226,7 @@ FIND CODE
 ═══════════════════════════════════════════════════════════════════════════════
   find <name>         Find symbol definitions (top 5 by usage count)
   usages <name>       All usages grouped: definitions, calls, imports, references
-  toc                 Table of contents (functions, classes, state)
+  toc                 Table of contents (compact; --detailed lists all symbols)
   search <term>       Text search (for simple patterns, consider grep instead)
   tests <name>        Find test files for a function
 
@@ -2275,6 +2275,9 @@ Common Flags:
   --top=N / --all     Limit or show all results
   --include-tests     Include test files
   --include-methods   Include method calls (obj.fn) in caller/callee analysis
+  --include-uncertain Include ambiguous/uncertain matches
+  --include-exported  Include exported symbols in deadcode
+  --detailed          List all symbols in toc (compact by default)
   --no-cache          Disable caching
   --clear-cache       Clear cache before running
   --no-follow-symlinks  Don't follow symbolic links

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.4.2",
+  "version": "3.4.3",
   "description": "Code navigation built by AI, for AI. Reduces context usage when working with large codebases.",
   "main": "index.js",
   "bin": {