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.

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.

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?"

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.

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.

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.

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.

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.

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 into one output. Lists changed/added/deleted functions, flags signature drift across call sites, calls out new functions with no callers, and recommends which tests to run.

ucn check                  # vs HEAD
ucn check --base=main      # vs main branch
ucn check --staged         # only staged changes

10. entrypoints — Detect framework entry points

Lists functions registered as framework handlers (HTTP routes, DI beans, job schedulers, etc.). Detects patterns across Express, FastAPI, Flask, Spring, Gin, Actix, Celery, pytest, and more.

ucn entrypoints                          # All detected entry points (tests included by default)
ucn entrypoints --type=http              # HTTP routes only
ucn entrypoints --framework=express      # Specific framework
ucn entrypoints --file=routes/           # Scoped to files
ucn entrypoints --exclude-tests          # Hide test fixtures (JUnit @Test, pytest, Rust #[test], etc.)

When to Use the Other Commands

Regex Notes (search command)

search uses JavaScript regex (the V8 engine), not grep BRE/ERE. Common gotchas:

• Alternation is a|b, not a\|b. ucn search "flask|fastapi|django" works; ucn search "flask\|fastapi\|django" matches the literal string.
• (, [, { outside character classes do not need escaping for literal match in most cases — but normal JS regex semantics apply (you can still escape them for clarity).
• Wrap the pattern in single quotes so the shell does not interpret special characters (*, ?, \, $, etc.).
• Default is case-insensitive; pass --case-sensitive to flip.
• --no-regex forces literal-string search if you need to match regex metacharacters as text without escaping.

Reading Call-Site Patterns

verify, impact, and about annotate call sites with structural classification flags. Watch for these in summary lines (Patterns: 4 in try, 4 in callback) and per-call-site entries:

audit-async is the focused tool for the awaited=false case across an entire async function body.

Reading Tiered Output (about / context / impact / trace / blast / reverse-trace / affected-tests)

Caller answers are a partition of every text occurrence of the symbol — nothing is silently hidden. Sections:

• CALLERS — CONFIRMED (N, X prod + Y test): — edges with binding/receiver/import evidence. Prod callers listed first, then a test callers: subheader. An evidence: line aggregates resolution labels for the section.
• CALLERS — UNVERIFIED (N) — call syntax, no binding/receiver evidence: — name-matched call sites the engine could not verify, one line each with the reason (method-no-evidence, ambiguous-binding, call-not-resolved). Capped at 10; --all lifts the cap. Treat these as possible callers when refactoring.
• NON-CALL OCCURRENCES: N (...) — imports/definitions/references/other-text, counts only (drill in with ucn usages <name>).
• ACCOUNT: — the reconciliation line. Every ground line is in exactly one bucket; 0 unaccounted means the partition is complete. +N beyond-text callers are alias-resolved call sites plain text search would miss.
• WARNING: N unparsed file(s) ... — files containing the symbol that failed to parse. Their lines were NOT analyzed — fall back to text search for those files.
• FILTERED: N hidden by flags — entries your display flags hid (they still count in ACCOUNT).

Trust rules: a CONFIRMED(0) + UNVERIFIED(0) answer with 0 unaccounted and no WARNING means the symbol genuinely has no callers — safe to act on, same as a clean grep. Any UNVERIFIED entries or WARNINGs mean: verify those sites before a breaking change.

Resolution labels in evidence: lines (high to low): exact-binding (0.98, import/binding evidence) · same-class (0.92) · receiver-hint (0.80, inferred receiver type) · scope-match (0.65, import/receiver-binding scope evidence) · name-only (0.40) · uncertain (0.25). Confirmed tier = scope-match and above. JSON output keeps per-edge decimals plus tier.

Flags: --min-confidence=0.7 filters confirmed edges (hidden count appears in FILTERED). --include-uncertain is an implied no-op for about/context/impact/trace/blast/reverse-trace/affected-tests (everything is shown, tiered); it keeps its meaning for smart/verify. --include-methods is an implied no-op for about/context/impact.

Tree commands (trace / blast / reverse-trace / affected-tests)

The tree trunk holds confirmed edges only. Unverified caller candidates render in an UNVERIFIED EDGES section with parent attribution (at <node> (hop N): file:line [enclosing fn] (reason)) and are not expanded by default — pass --expand-unverified to follow them; every downstream node is then marked [⚠ via <reason>] / [⚠ unverified chain] and counted as possibly affected, never confirmed. Unresolved callee calls (trace down) render as [unverified] name — reason leaves under their node. Reconciliation lines:

• ACCOUNT: — the root hop's text-ground partition (same as context/impact).
• TREE ACCOUNT: — interior conservation: nodes expanded, confirmed/unverified/excluded edge counts by reason, depth-limit cuts.
• CALLEE ACCOUNT: (trace down) — every call site in every expanded node lands in confirmed/unverified/external/excluded/filtered.

reverse-trace marks ★ entry point only when a node has zero candidates in both tiers; zero confirmed with unverified candidates shows ⚠ no confirmed callers — N unverified instead. affected-tests splits its answer into the confirmed band (Test files to run, coverage, Uncovered) and a POSSIBLY AFFECTED band (functions + test files reachable only through unverified chains).

Symbol Handles (stable IDs)

Every result that lists a symbol emits a handle in the form relativePath:line:name (e.g. core/api.ts:42:handler). Pass it back to any name-accepting command and resolution is pinned to that exact definition — no name disambiguation, no --file needed.

ucn find handler                  # → emits  src/api.ts:42:handler
ucn brief src/api.ts:42:handler   # pins to that exact one
ucn impact src/api.ts:42:handler  # same

The shorter relativePath:line form (no :name) also works — UCN looks up the symbol by location. Plain names (handler) still work for the fuzzy/heuristic path.

Command Format

ucn [target] <command> [name] [--flags]

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

Workflow Integration

Investigating a bug:

ucn about problematic_function          # Understand it fully
ucn trace problematic_function --depth=2  # See what it calls

Before modifying a function:

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?

Before committing:

ucn diff-impact                         # What changed vs HEAD + who calls it
ucn diff-impact --base=main             # What changed vs main branch
ucn diff-impact --staged                # Only staged changes

Periodic maintenance:

ucn deadcode --exclude=test             # What can be deleted?
ucn toc                                 # Project overview