ucn 4.0.2 → 4.1.0

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

@@ -1,6 +1,6 @@
 ---
 name: ucn
-description: "Code intelligence toolkit — extract functions, trace callers, analyze impact, detect dead code without reading whole files. 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 JS/TS, Python, Go, Rust, Java, HTML. Skip for plain text search or codebases under 500 LOC."
+description: "Code intelligence toolkit — extract functions, trace callers, analyze impact, detect dead code without reading whole files. 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. `ucn orient` gives a one-screen overview of any new repo. One `ucn about` replaces 3-4 grep+read cycles. One `ucn trace` maps an entire execution flow without reading any files. Works on JS/TS, Python, Go, Rust, Java, HTML. Skip for plain text search or codebases under 500 LOC."
 allowed-tools: Bash(ucn *), Bash(npx ucn *)
 argument-hint: "[command] [symbol-name] [--flags]"
 ---
@@ -13,6 +13,7 @@ Extract functions, trace call chains, find callers, and detect dead code — wit
 
 **Use UCN when the next action would be:**
 
+- "I just opened this repo, where do I start?" → `ucn orient` — one screen: size, top dirs, hot functions, entry points, trust verdict
 - "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
@@ -88,7 +89,7 @@ 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.
+Lists all functions and classes with zero callers across the project — class-like symbols (classes, structs, interfaces, traits, enums, namespaces) are audited alongside functions. 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. Symbols whose only call sites sit inside their own same-name definitions are claimed and marked `[only self-references — recursive]` — the group is unreachable from outside.
 
 ```bash
 ucn deadcode                        # Everything
@@ -149,6 +150,17 @@ ucn entrypoints --file=routes/           # Scoped to files
 ucn entrypoints --exclude-tests          # Hide test fixtures (JUnit @Test, pytest, Rust #[test], etc.)
 ```
 
+### 11. `orient` — First command in a new repo
+
+One screen: size + language mix, densest directories, most-called production functions, entry-point counts, and the trust verdict. Composes what would otherwise take four calls (`toc` + `stats --hot` + `entrypoints` + `doctor`).
+
+```bash
+ucn orient            # run this before anything else in an unfamiliar codebase
+ucn orient --top=15   # longer dir/hot lists
+```
+
+The `Next:` line suggests concrete follow-ups, starting with `about` on the hottest production function.
+
 ## When to Use the Other Commands
 
 | Situation | Command | What it does |
@@ -164,6 +176,7 @@ ucn entrypoints --exclude-tests          # Hide test fixtures (JUnit @Test, pyte
 | Understanding who depends on a file | `ucn exporters <file>` | Which files import it |
 | See what a file exports | `ucn file-exports <file>` | All exported functions, classes, variables with signatures |
 | Quick project overview | `ucn toc` | Every file with function/class counts and line counts |
+| Just entered an unfamiliar repo | `ucn orient` | One screen: size, top dirs, hot functions, entry points, trust verdict. Run it first |
 | Project complexity stats | `ucn stats` | File counts, symbol counts, lines by language. `--functions` for per-function line counts. `--hot --top=N` for the most-called functions (orientation primitive on a new repo) |
 | Find by glob pattern | `ucn find "handle*"` | Locate definitions matching a glob (supports * and ?) |
 | Text search with context | `ucn search term --context=3` | Like grep -C 3, shows surrounding lines |
@@ -217,7 +230,7 @@ ucn entrypoints --exclude-tests          # Hide test fixtures (JUnit @Test, pyte
 
 `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)
+## Reading Tiered Output (about / context / impact / trace / blast / reverse-trace / affected-tests / diff-impact / verify / plan / check)
 
 Caller answers are a **partition of every text occurrence** of the symbol — nothing is silently hidden. Sections:
 
@@ -232,7 +245,18 @@ Caller answers are a **partition of every text occurrence** of the symbol — no
 
 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.
+Flags: `--min-confidence=0.7` filters confirmed edges (hidden count appears in FILTERED). `--include-uncertain` and `--include-methods` have **no effect** on tiered commands (about/context/impact/trace/blast/reverse-trace/affected-tests/diff-impact/verify/plan/smart) — everything is always shown, tiered by evidence.
+
+### Refactor commands run the same contract (v4)
+
+- `verify` arg-checks the **confirmed** band only; candidates without evidence render in `UNVERIFIED CALL SITES (N)` with reasons and are NOT arg-checked (they may target another symbol). A wrong-arity method call with binding evidence is flagged **by default** now. The `ACCOUNT:` line reconciles.
+- `plan` plans changes for confirmed sites; `UNVERIFIED CALL SITES` lists sites that MAY also need the change — review them before refactoring. Plan and verify agree by construction.
+- `diff-impact` reports per-changed-function confirmed `Callers` + `Unverified call sites` + a per-symbol `ACCOUNT:` line. `check` shows `N callers (+M unverified)` per changed function; ORPHAN requires zero candidates in BOTH tiers.
+- `context`/`smart` also account the **callee** side: `CALLEES — UNVERIFIED (N)` entries + a `CALLEE ACCOUNT:` arithmetic line.
+
+### Advisory commands self-label
+
+`related`, `example`, `stacktrace`, and `endpoints --bridge` print an `Advisory:` line (and carry an `advisory` field in JSON): their answers are ranked heuristics, not verified claims. Contracted commands carry accounts; advisory commands say so — there is no third category.
 
 ### Tree commands (trace / blast / reverse-trace / affected-tests)
 
@@ -281,7 +305,7 @@ ucn [target] <command> [name] [--flags]
 | `--expand-unverified` | `blast`/`reverse-trace`: follow unverified caller edges in the tree. Downstream nodes are marked as unverified chains — possible, not confirmed, impact |
 | `--include-tests` | Include test files in usage counts (`about`) and results (`find`, `usages`, `deadcode`). Callers always include tests. |
 | `--exclude-tests` | Exclude test entries from `entrypoints` (tests are included by default since they ARE entry points). |
-| `--include-methods` | Include `obj.method()` calls in caller/callee analysis. Implied (no-op) for `about`/`context`/`impact` — method calls are always analyzed and tiered by receiver evidence. Applies to `verify`, `blast`, `smart`, `trace`, `reverse-trace`, `affected-tests` |
+| `--include-methods` | Include `obj.method()` callee expansion in `trace`/`smart`. No effect on caller-direction commands (`about`/`context`/`impact`/`verify`/`blast`/`reverse-trace`/`affected-tests`) — method calls are always analyzed and tiered by receiver evidence |
 | `--base=<ref>` | Git ref for diff-impact (default: HEAD) |
 | `--staged` | Analyze staged changes (diff-impact) |
 | `--no-cache` | Force re-index after editing files |
@@ -292,7 +316,7 @@ ucn [target] <command> [name] [--flags]
 | `--hot` | List top N most-called functions in `stats` (use with `--top=N`, default 10). Best orientation primitive when entering a new repo |
 | `--diverse` | Cluster `example` call sites by argument shape and return one representative per cluster (use with `--top=N`, default 3) |
 | `--git` | Attach git enrichment to `about` / `brief`: last commit (ISO + author) and recent change count (last 30 days). Skipped silently when not a git repo |
-| `--json` | Machine-readable JSON output. Some commands wrap in `{meta, data}` (e.g., `find`, `deadcode`); others return flat objects (e.g., `about`, `impact`, `verify`, `plan`, `imports`) — check each command's output shape |
+| `--json` | Machine-readable JSON output. Most commands wrap in `{meta, data}` (e.g., `find`, `deadcode`, `context`, `verify`, `plan`, `diff-impact` — completeness signals and the ACCOUNT live in `meta`); `about` and `impact` return their full result object flat — check each command's output shape |
 | `--code-only` | Exclude matches in comments and strings (`search`/`usages`) |
 | `--with-types` | Include related type definitions in `smart`/`about` output |
 | `--detailed` | Show full symbol listing per file in `toc` |
@@ -303,7 +327,7 @@ ucn [target] <command> [name] [--flags]
 | `--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. Implied (no-op) for `about`/`context`/`impact` — unverified callers are always shown in their own tier. Applies to `blast`, `smart`, `trace`, `reverse-trace`, `affected-tests` |
+| `--include-uncertain` | No effect on tiered commands — unverified candidates are always shown in their own section with reasons |
 | `--hide-confidence` | Hide confidence scores (shown by default) in `context`/`about` |
 | `--min-confidence=N` | Filter edges below confidence threshold (e.g., `--min-confidence=0.7` keeps only high-confidence edges) |
 | `--calls-only` | Only show call/test-case matches in `tests` (skip file-level results) |

package/README.md

@@ -39,8 +39,9 @@ And it's built to be **trusted**: every "who calls this?" splits into what UCN c
 ---
 
 ```bash
-npm install -g ucn
+npm install -g ucn             # Node.js 20+
 
+ucn orient                     # first look at any repo: size, hot spots, trust
 ucn trace main --depth=3       # full execution flow
 ucn about handleRequest        # definition + callers + callees + tests
 ucn impact handleRequest       # every call site with arguments
@@ -53,28 +54,28 @@ ucn deadcode --exclude=test    # unused code, AST-verified
 $ ucn trace build --depth=2
 
 build
-├── detectProjectPattern (core/discovery.js:431) 1x
+├── detectProjectPattern (core/discovery.js:450) 1x
 ├── parseGitignore (core/discovery.js:131) 1x
-├── expandGlob (core/discovery.js:191) 1x
-│   ├── parseGlobPattern (core/discovery.js:227) 1x
-│   ├── walkDir (core/discovery.js:284) 1x
-│   └── compareNames (core/discovery.js:170) 1x
+├── expandGlob (core/discovery.js:199) 1x
+│   ├── parseGlobPattern (core/discovery.js:238) 1x
+│   ├── walkDir (core/discovery.js:295) 1x
+│   └── compareNames (core/discovery.js:178) 1x
 ├── parallelBuild (core/parallel-build.js:25) 1x
-├── indexFile (core/project.js:310) 1x
-│   ├── addSymbol (core/project.js:410) 4x
-│   ├── detectLanguage (languages/index.js:288) 1x
+├── indexFile (core/project.js:397) 1x
+│   ├── addSymbol (core/project.js:502) 4x
+│   ├── detectLanguage (languages/index.js:344) 1x
 │   ├── parse (core/parser.js:69) 1x
 │   ├── extractImports (core/imports.js:19) 1x
 │   └── extractExports (core/imports.js:44) 1x
-├── buildImportGraph (core/project.js:648) 1x
-└── buildInheritanceGraph (core/project.js:653) 1x
+├── buildImportGraph (core/project.js:798) 1x
+└── buildInheritanceGraph (core/project.js:803) 1x
     … calls UCN can't prove a receiver for (arr.push(), obj.get()) show as
       [unverified] leaves — abridged here
 
-CALLEE ACCOUNT: 23 nodes · 329 call sites = 43 confirmed + 151 unverified + 34 builtin + 101 excluded
+CALLEE ACCOUNT: 26 nodes expanded · 394 call sites = 61 confirmed + 162 unverified (162 uncertain-receiver) + 68 external/builtin + 103 excluded
 ```
 
-One command, no files opened — and the `CALLEE ACCOUNT:` line proves all 329 calls were sorted, nothing dropped.
+One command, no files opened — and the `CALLEE ACCOUNT:` line proves all 394 calls were sorted, nothing dropped.
 
 ---
 
@@ -87,19 +88,19 @@ $ ucn about expandGlob
 
 expandGlob (function)
 ════════════════════════════════════════════════════════════
-core/discovery.js:191-222  →  core/discovery.js:191:expandGlob
+core/discovery.js:199-233  →  core/discovery.js:199:expandGlob
 expandGlob (pattern: string, options: number = {}) : string[]
 
-USAGES: 6 total
-  3 calls, 3 imports, 0 references
+USAGES: 8 total
+  3 calls, 3 imports, 2 references
 
 CALLERS — CONFIRMED (7, 3 prod + 4 test):
   evidence: scope-match (all)
-  cli/index.js:1201 [runGlobCommand]
+  cli/index.js:1267 [runGlobCommand]
     const files = expandGlob(pattern);
-  core/cache.js:466 [isCacheStale]
+  core/cache.js:548 [isCacheStale] [unreachable]
     const currentFiles = expandGlob(pattern, globOpts);
-  core/project.js:192 [build]
+  core/project.js:257 [build]
     files = expandGlob(pattern, globOpts);
   test callers:
   test/integration.test.js:167
@@ -108,12 +109,12 @@ CALLERS — CONFIRMED (7, 3 prod + 4 test):
 
 CALLEES (3):
   evidence: exact-binding (all)
-  parseGlobPattern [utility] - core/discovery.js:227 (1x)
-  walkDir [utility] {fs} - core/discovery.js:284 (1x)
-  compareNames [utility] - core/discovery.js:170 (1x)
+  parseGlobPattern [utility] - core/discovery.js:238 (1x)
+  walkDir [utility] {fs} - core/discovery.js:295 (1x)
+  compareNames [utility] - core/discovery.js:178 (1x)
 
 ACCOUNT: "expandGlob" occurs on 14 lines in 6 files: 7 confirmed, 0 unverified,
-  7 non-call (4 import, 1 definition, 1 reference, 1 other-text), 0 other-target, 0 unaccounted
+  7 non-call (4 import, 1 definition, 2 reference, 0 other-text), 0 other-target, 0 unaccounted
 
 TESTS: 5 matches in 1 file(s)
 ```
@@ -127,30 +128,31 @@ UCN doesn't just find a name — it tells you how sure it is. Every answer from
 ```
 $ ucn impact saveCache
 
-CALL SITES: 2 confirmed + 9 unverified
+CALL SITES: 2 confirmed + 11 unverified
 
 test/regression-go.test.js (2 calls)
-  :2004
+  :2007
     saveCache(index, cachePath);
 
-UNVERIFIED CALL SITES (9) — call syntax, no binding/receiver evidence:
-  mcp/server.js:779: index.saveCache(); (method-ambiguous)
-  test/cache.test.js:1779: index.saveCache(); (method-ambiguous)
-  ... (7 more)
+UNVERIFIED CALL SITES (11) — call syntax, no binding/receiver evidence:
+  core/project.js:2126: saveCache(cachePath) { ... } (call-not-resolved)
+  mcp/server.js:810: try { index.saveCache(); } catch (_) ... (method-ambiguous)
+  test/cache.test.js:1804: index.saveCache(); (method-ambiguous)
+  ... (8 more)
 
-ACCOUNT: "saveCache" occurs on 47 lines in 8 files: 2 confirmed, 9 unverified,
-  9 non-call (2 import, 1 definition, 0 reference, 6 other-text), 27 other-target, 0 unaccounted
+ACCOUNT: "saveCache" occurs on 55 lines in 8 files: 2 confirmed, 11 unverified,
+  11 non-call (2 import, 1 definition, 1 reference, 7 other-text), 31 other-target, 0 unaccounted
 ```
 
-UCN sorts every one of the 47 places the name appears:
+UCN sorts every one of the 55 places the name appears:
 
 - **2 confirmed** — call sites it can prove resolve to *this* `saveCache`.
-- **9 unverified** — real call sites it found but won't claim. `index.saveCache()` has an untyped receiver, so UCN can't prove which `saveCache` runs; it shows the site and the reason (`method-ambiguous`) instead of guessing.
-- **27 other-target** — occurrences that belong to a *different* `saveCache`, kept separate so they never pollute the answer.
-- **9 non-call** — imports, the definition, plain text.
+- **11 unverified** — real call sites it found but won't claim. `index.saveCache()` has an untyped receiver, so UCN can't prove which `saveCache` runs; it shows the site and the reason (`method-ambiguous`) instead of guessing.
+- **31 other-target** — occurrences that belong to a *different* `saveCache`, kept separate so they never pollute the answer.
+- **11 non-call** — imports, the definition, plain text.
 - **`0 unaccounted`** — the partition is complete. Nothing was dropped on the floor.
 
-The payoff: a **confirmed** answer is safe to refactor against, and an empty result with `0 unaccounted` means the symbol truly has no callers. UCN never hides a caller — and never invents one.
+The payoff: a **confirmed** answer is safe to refactor against, and a clean zero — no confirmed, no unverified, `0 unaccounted` — is a trustworthy zero (measured: 68 of 69 clean-zero samples across the 10-repo board agree with the compiler oracles; the one disagreement is a `new X()` on an old-style constructor function, which lands in the non-call counts, still visible). One caveat before deleting anything: callers aren't the only usages — if the NON-CALL counts are nonzero, run `ucn usages` to see what they are.
 
 ### Measured against ground truth
 
@@ -161,10 +163,10 @@ This isn't a promise — it's a gate. CI re-derives UCN's caller answers from re
 | TypeScript / JavaScript | ts-morph | 99.4–100% |
 | Python | pyright (LSP) | 97.7–99.9% |
 | Go | gopls | 99.9–100% |
-| Rust | rust-analyzer | 98.9–100% |
-| Java | jdtls | 96.2% |
+| Rust | rust-analyzer | 99.0–100% |
+| Java | jdtls | 96.6% |
 
-Ten pinned real-world repos (zod, express, httpx, rich, cobra, grpc-go, ripgrep, cursive, gson, preact-signals), three sampling seeds, every run gated at `missing-unexplained = 0`. The tree commands — `trace`, `blast`, `reverse-trace`, `affected-tests` — follow the same rule: confirmed trunk, uncertain branches flagged (`--expand-unverified` to follow). Run `ucn doctor` for the trust report on *your* repo.
+Ten pinned real-world repos (zod, express, httpx, rich, cobra, grpc-go, ripgrep, cursive, gson, preact-signals), three sampling seeds, every run gated at `missing-unexplained = 0` — plus a weekly fresh-repo arm: two unpinned repos the engine was never tuned on, same gate. The tree commands — `trace`, `blast`, `reverse-trace`, `affected-tests` — follow the same rule: confirmed trunk, uncertain branches flagged (`--expand-unverified` to follow). Run `ucn doctor` for the trust report on *your* repo.
 
 ## Change code without breaking things
 
@@ -237,6 +239,36 @@ Changed: 3 functions
 
 ## Get the lay of the land in a new repo
 
+One command answers "what is this codebase?" — size and language mix, where the code lives, the most-called production functions, entry points, and how far to trust the index:
+
+```
+$ ucn orient
+
+PROJECT ORIENTATION — /path/to/project
+════════════════════════════════════════════════════════════
+169 files · 2111 symbols · javascript 67%, rust 8%, typescript 8%, java 7%, go 5%, python 5%
+
+TOP DIRS (by symbols):
+  core            516 symbols · 29 file(s)
+  languages       282 symbols · 8 file(s)
+  test            209 symbols · 29 file(s)
+  core/output     142 symbols · 14 file(s)
+  ...
+
+HOT (most-called production functions, top 8 of 1028):
+  execute — 1124 call(s) · core/execute.js:1608
+  ProjectIndex.build — 340 call(s) · core/project.js:221
+  getParser — 150 call(s) · languages/index.js:312
+  ...
+
+ENTRY POINTS: 389 — test 284, runtime 72, http 32, di 1
+TRUST: MEDIUM — 41 dynamic import(s), 13 eval, 6 reflection  (ucn doctor for detail)
+
+Next: ucn about execute · ucn toc --detailed · ucn stats --hot --top=20 · ucn doctor --deep
+```
+
+Then drill in:
+
 ```
 $ ucn brief fetch_user
 fetch_user(user_id: int): dict
@@ -251,9 +283,9 @@ fetch_user(user_id: int): dict
 $ ucn doctor
 
 UCN Trust Report — /path/to/project
-Index: 144 files, 1569 symbols
-Languages: javascript (74%), typescript (13%), java (4%), python (3%), rust (3%), go (3%)
-Cache: fresh, 221ms build
+Index: 169 files, 2104 symbols
+Languages: javascript (72%), typescript (14%), java (4%), python (4%), rust (4%), go (3%)
+Cache: fresh, 344ms build
 ...
 Trust level: HIGH
 ```
@@ -289,10 +321,10 @@ Test files to run (20):
 POSSIBLY AFFECTED (1) — reachable only through unverified call edges:
   doctor
 
-Uncovered (10): runGlobCommand, main, runProjectCommand, runFileCommand, evaluateRepo, ...
+Uncovered (12): runGlobCommand, main, isCacheStale, runProjectCommand, runFileCommand, ...
   ⚠ These affected functions have no test references
 
-Summary: 15 affected → 20 test files, 5/15 functions covered (33%) · 1 possibly affected (unverified chains)
+Summary: 15 affected → 20 test files, 3/15 functions covered (20%) · 1 possibly affected (unverified chains)
 ```
 
 The confirmed closure is what you run; `POSSIBLY AFFECTED` lists functions reached only through unverified edges — extra tests worth a look, kept separate.
@@ -300,17 +332,24 @@ The confirmed closure is what you run; `POSSIBLY AFFECTED` lists functions reach
 ## Find unused code
 
 ```
-$ ucn deadcode --exclude=test
+$ ucn deadcode --exclude=test        # run on ripgrep
 
-Dead code: 2 unused symbol(s)
+Dead code: 8 unused symbol(s)
 
-core/output/analysis.js
-  [  29-  32] formatHistogramLine (function)
-  [  41-  44] shouldShowReachability (function)
+crates/globset/src/serde_impl.rs
+  [  38-  42] Glob.deserialize (method)
+  [  70-  74] GlobSet.deserialize (method)
+crates/matcher/src/lib.rs
+  [ 397- 399] Captures.as_match (method)
+  [ 669- 678] Matcher.try_find_iter (method) [only self-references — recursive]
+  [ 796- 806] Matcher.try_captures_iter (method) [only self-references — recursive]
+  ...
 
-353 exported symbol(s) excluded (all have callers). Use --include-exported to audit them.
+921 exported symbol(s) excluded from the audit (public API may have external callers). Use --include-exported to audit them.
 ```
 
+Classes, structs, traits, and enums are audited alongside functions. Symbols whose only call sites live inside their own definitions are claimed too, marked `[only self-references — recursive]`. Deadcode claims are re-derived against compiler/LSP ground truth in CI — a default-audit claim with an oracle-visible reference fails the build.
+
 Find missing-await bugs:
 
 ```