ucn

# UCN - Universal Code Navigator

See what code does before you touch it.

[![npm](https://img.shields.io/npm/v/ucn)](https://www.npmjs.com/package/ucn)
[![tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/mleoca/0e10a790e16ab61ddd233e05645e203e/raw/ucn-tests.json)](https://github.com/mleoca/ucn/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/ucn)](LICENSE)

If you work with AI Agents, add UCN as a [Skill or MCP tool](#ai-setup). One tool
gives the agent compact, source-linked answers to caller, impact, and test
questions, with uncertainty labeled instead of guessed.

Find symbols, trace callers, check impact, pick the right tests, extract exact
source, and spot dead code - from your terminal or your AI agent.

Supports JavaScript, TypeScript, JSX/TSX, Python, Go, Rust, Java, C, C++, C#,
and HTML inline scripts. All commands, one engine, three ways to use it:

```text
  Terminal              AI Agents           Agent Skills
       │                    │                    │
      CLI                  MCP                 Skill
       └────────────────────┼────────────────────┘
                            │
                     ┌──────┴──────┐
                     │ UCN Engine  │
                     │  commands   │
                     │ tree-sitter │
                     └─────────────┘
```

Your tools can already find text. UCN finds *the function* - its definition,
its callers, its blast radius, its tests - and tells you how sure it is. It
parses code the way a compiler does (tree-sitter ASTs, not regex) and answers
the questions you actually have: who calls this? what breaks if I change it?
which tests should I run? is this dead?

It's deliberately lightweight:

- **No required background process** - the CLI parses on demand, answers, and
  exits. MCP stays warm only when you choose to run it.
- **No language servers, no compilation** - tree-sitter does the analysis
  without building the project.
- **No config** - point it at a directory and ask.

And it's built for auditable trust. grep hands you raw matches to sift
yourself; UCN separates proven edges from possible ones, explains every
exclusion, and reconciles every occurrence of the name it searched. It never
turns a zero into a deletion claim. CI re-derives its answers from real
compilers and language servers (ts-morph, Pyright, gopls, rust-analyzer,
JDT LS, Roslyn, clangd) on pinned production repositories. See
[Answers you can trust](#answers-you-can-trust).

<img src="https://raw.githubusercontent.com/mleoca/ucn/main/assets/demo.svg" alt="ucn show on ripgrep: signature, 123 confirmed callers with evidence types, and the ACCOUNT line reconciling all 136 occurrences of the name" width="100%">

<sub>Real output: one `ucn show` on [ripgrep](https://github.com/BurntSushi/ripgrep) - signature, 123 proven callers with their evidence, and an account of every occurrence of the name. No files opened.</sub>

## Start here

```bash
npm install -g ucn                    # Node.js 20+

cd your-project
ucn repo                              # what is this codebase?
ucn find handleRequest                # exact definitions, stable handles
ucn show src/server.ts:42:handleRequest              # the full picture
ucn trace src/server.ts:42:handleRequest --direction=callers
ucn impact src/server.ts:42:handleRequest            # every call site, with evidence
ucn tests src/server.ts:42:handleRequest --depth=3   # which tests to run
```

The first command builds an incremental index; the rest reuse it. The cache
lives outside your project directory, so there's nothing to gitignore.

## Understand code you didn't write

What does this function do, who calls it, and how sure is the answer?
`ucn show` gathers everything useful about one symbol: signature, source,
callers, callees, tests, types, dependencies, examples. Project it down to
just the sections you need:

```text
$ ucn show detectLanguage --sections=summary,callers,callees --compact

SUMMARY
───────
detectLanguage(filePath: string, projectRoot = null): string|null
  languages/index.js:420-428  (9 lines)
  handle: languages/index.js:420:detectLanguage
  "Detect language from file path"
  async: no  |  side_effects: [none]  |  complexity: branches=1, depth=1

RELATIONSHIPS
─────────────
CALLERS — CONFIRMED (51, 30 prod + 21 test):
  evidence: scope-match (all)
  [1] cli/index.js:604 [runFileCommand]: const language = detectLanguage(filePath);
  [7] core/build-worker.js:39 [processFile]: const language = detectLanguage(filePath, rootDir);
  [17] core/project.js:472 [build]: const language = detectLanguage(filePath, this.root);
  [34] test/parser-unit.test.js:19: assert.strictEqual(detectLanguage('file.js'), 'javascript');
  ... 47 more callers

CALLEES (1):
  evidence: exact-binding (all)
  [52] detectHeaderLanguage {fs} - core/compilation-database.js:217
CALLEES — UNVERIFIED (1) — call syntax, receiver/binding unresolved:
  toLowerCase ×1 — possible-dispatch L422

ACCOUNT: "detectLanguage" occurs on 79 lines in 20 files: 51 confirmed, 0 unverified,
  28 non-call (18 import, 1 definition, 3 reference, 6 other-text), 0 other-target, 0 unaccounted
CONTRACT: literal-name text partition complete; semantic completeness is not claimed
  (aliases, indirect calls, generated code, and runtime dispatch may exist).
```

`find` returns stable handles in `file:line:name` form. Pass a handle to any
command to pin the answer to one definition, even when several files or classes
reuse the same name.

## Follow the execution path

What happens when `build()` runs?

```text
$ ucn trace build --depth=2

build
├── compareNames (core/discovery.js:293) [regular] 3x
├── recordDiscoveryIssue (core/project.js:346) 2x
│   └── [unverified] push — method-ambiguous L351
├── detectProjectPattern (core/discovery.js:760) [utility] 1x
├── parseGitignore (core/discovery.js:253) [utility] 1x
│   ├── gitignoreFiles (core/discovery.js:234) [utility] 1x
│   ├── compareNames (core/discovery.js:293) [utility] 1x (see above)
│   └── parseGitignoreFile (core/discovery.js:152) [utility] 1x
├── gitTrackedPaths (core/discovery.js:266) [utility] 1x
│   ├── hasGitMetadata (core/discovery.js:224) [utility] 1x
│   └── [unverified] dirname — method-ambiguous L281,L284
└── ... more callees

CALLEE ACCOUNT: 11 nodes expanded · 210 call sites = 31 confirmed + 33 unverified
  (25 method-ambiguous, 1 possible-dispatch, 7 uncertain-receiver) + 86 external/builtin + 60 excluded
```

`trace` walks callees, callers, or callers all the way up to runtime entry
points (`--direction=callers --to=entrypoints`). Proven edges form the tree;
calls UCN can't prove a receiver for show up as `[unverified]` leaves with a
reason. The account line reconciles every call site in the expanded tree, so
unresolved dispatch stays visible and counted instead of quietly vanishing.

## Answers you can trust

UCN doesn't turn every matching name into a semantic claim. Watch it work
through a name with two definitions and a pile of ambiguous method calls:

```text
$ ucn impact saveCache

Impact analysis for saveCache
core/cache.js:610
Note: Found 2 definitions for "saveCache". Using core/cache.js:610. Also in: core/project.js:2380. Use file= to disambiguate.
CALL SITES: 5 confirmed + 15 unverified
  Files affected: 3
BY FILE:
  core/project.js:2380 [saveCache]: saveCache(cachePath) { return indexCache.saveCache(this, cachePath); }
  test/prerelease-audit.test.js:1493: saveCache(built, cacheFile);
  ... (3 more)
UNVERIFIED CALL SITES (15) — call syntax, no binding/receiver evidence:
  mcp/server.js:517: try { index.saveCache(); } catch (_) { /* best-effort */ } (possible-dispatch via local receiver)
  test/cache.test.js:124: index.saveCache(); (possible-dispatch via local receiver)
  (+13 more)
ACCOUNT: "saveCache" occurs on 68 lines in 11 files: 5 confirmed, 15 unverified,
  12 non-call (3 import, 1 definition, 1 reference, 7 other-text), 36 other-target, 0 unaccounted
CONTRACT: literal-name text partition complete; semantic completeness is not claimed
  (aliases, indirect calls, generated code, and runtime dispatch may exist).
```

UCN sorted all 68 places the name appears:

- **5 confirmed** - call sites it can *prove* resolve to this `saveCache`,
  via a binding, import, receiver type, qualified path, or same-class evidence.
- **15 unverified** - real call syntax it refuses to claim. `index.saveCache()`
  sits on an untyped receiver, so the site stays visible with its reason
  (`possible-dispatch via local receiver`) instead of being guessed or dropped.
- **36 other-target** - occurrences that belong to the *other* `saveCache`,
  kept out of the answer instead of quietly inflating it.
- **12 non-call** - imports, the definition, comments, strings.
- **0 unaccounted** - every observed line landed in exactly one bucket.

That's the payoff: an answer you (or your agent) can audit, instead of an
opaque match count. A confirmed edge is evidence about the pinned target. An
unverified edge is a review item with a stated reason. And a clean zero is an
*observed-text* zero, not a safe-to-delete claim: aliases, generated code,
reflection, runtime registration, and external consumers can live beyond the
indexed evidence, and `ucn repo --sections=health --deep` reports exactly those
blind spots. Even when output is truncated to fit an agent's budget, the
ACCOUNT, CONTRACT, and WARNING lines survive the cut.

### Measured against ground truth

Don't take the tiers on faith. Release gates re-derive UCN's answers from real
compilers and language servers on a ten-repository board of pinned production
codebases, and publishing is blocked unless they pass. The latest full
release-board run (2026-08-11):

| Repository | Pinned commit | Oracle | Caller precision | Caller recall | Callee prec / recall | Command checks |
|---|---|---|---:|---:|---:|---:|
| [preact-signals](https://github.com/preactjs/signals) | [`e0ce9fdf`](https://github.com/preactjs/signals/commit/e0ce9