ucn

# UCN — Universal Code Navigator

Extract functions, trace call chains, find callers, and detect dead code — without reading entire files. Works on JS/TS, Python, Go, Rust, Java, and HTML (inline scripts and event handlers).

## When to Reach for UCN Instead of Grep/Read

**Use UCN when the next action would be:**

- "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 JS/TS, Python, Go, Rust, Java, HTML)
- Finding files by name — use glob

## The Commands You'll Use Most

### 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
```

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, without truncation. Essential before modifying a signature, renaming, or deleting.

```bash
ucn impact score_trend              # Every caller, grouped by file
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. `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
ucn blast helper --expand-unverified # follow unverified edges too (marked ⚠, possible impact)
```

The tree trunk is confirmed-evidence-only; dispatch-possible/ambiguous caller candidates appear in an `UNVERIFIED EDGES` section (see "Reading Tiered Output" below).

### 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.

```bash
ucn trace generate_report            # compact (depth 3, limited breadth)
ucn trace generate_report --depth=5  # full tree to depth 5, all children shown
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.

**Prefer `trace` over chained `about` calls.** If you find yourself running `ucn about` 4–5 times in a row to follow a call chain (entry → leaves), one `ucn trace <fn> --depth=N` returns the same information in a single call. Use `--depth=N` to limit how deep the tree goes.

### 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.

```bash
ucn fn handle_request --file=api    # --file disambiguates when name exists in multiple files
ucn fn parse,format,validate        # Extract multiple functions in one call
ucn class MarketDataFetcher
```

### 6. `deadcode` — Find unused code

Lists all functions and classes with zero callers across the project. Framework entry points (Express routes, Spring controllers, Celery tasks, etc.) and exported/public API symbols — including methods of exported classes in JS/TS/Python — are automatically excluded (`--include-exported` audits them). Interface/trait method declarations are labeled `[declared on interface X — contract surface, not executable code]`: unreferenced is true, but deleting one changes the API contract, not dead logic.

```bash
ucn deadcode                        # Everything
ucn deadcode --exclude=test         # Skip test files (most useful)
ucn deadcode --include-decorated    # Include framework-registered functions
ucn deadcode --include-exported     # Audit exported/public API symbols too
```

### 7. `brief` — One-screen "before-I-touch-this" summary

AST-only summary of a function: typed signature, first sentence of docstring,
side-effect classification (fs/network/process/global_mutation), and complexity
metrics (branches, depth, line count). Lighter than `about`, more useful than
`fn` when you don't need the body.

```bash
ucn brief fetch_user
# fetch_user(user_id: int): dict
#   svc.py:4-8  (5 lines)
#   "Fetch a user from the API."
#   async: no  |  side_effects: [fs, network, process]  |  complexity: branches=2, depth=2
```

### 8. `doctor` — Project trust report

One command that tells you how much UCN trusts the index for this project:
file/symbol counts, language breakdown, dynamic-import / eval / reflection
blind spots, parse failures, and a verdict (HIGH/MEDIUM/LOW). Add `--deep` to
sample resolution coverage and bucket edges by confidence.

```bash
ucn doctor                # fast: counts + blind spots + verdict
ucn doctor --deep         # also samples resolution coverage
ucn doctor --in=src/core  # scope to a subtree
```

### 9. `check` — Pre-commit summary

Composes `diff-impact` + `verify` + `affected-tests