ucn 5.2.2 → 5.3.1

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

@@ -43,6 +43,10 @@ Persistent indexes live in a per-user, project-keyed cache rather than the analy
 
 Supported source families are JavaScript/TypeScript/TSX, Python, Go, Rust, Java, C, C++, C#, and HTML inline JavaScript/event handlers. C/C++ uses `compile_commands.json` when available to classify headers and resolve include paths. Recoverable preprocessor branches contribute AST-proven source facts, so a single selected configuration does not silently erase definitions or calls; disagreeing conditional macro identities stay visible as unverified. C++ resolution uses namespace ownership, static overload shape (including arrays), and macro-parameter requalification. C# resolution uses declared property/field receiver types plus overload and hiding discipline. This is portable AST analysis, not a compiler build; macros, templates, generated code, reflection, and external dependency semantics can remain unverified.
 
+`repo` refines its HOT list exactly for up to 400 candidate definitions per
+run; when a large repository exhausts that budget the HOT header says so and
+the ranking is approximate. `repo --sections=stats --hot` is always exact.
+
 `repo` readiness is task-specific. Its headline is navigation readiness;
 refactor, deletion, semantic recall, and the sampled evidence mix are separate
 dimensions. The confirmed/unverified percentage is a classification profile,
@@ -65,6 +69,16 @@ identity; matching attribute syntax with an unresolved receiver stays
 unverified. These are change dependencies, not fabricated caller edges, so
 the caller `ACCOUNT` remains a call-shaped partition.
 
+When the selected definition is a type, interface, enum, trait, or record,
+`impact` adds a `TYPE REFERENCE SITES` band: annotation and reference sites
+confirmed by an import link to the definition's file (or package scope in
+Go/Java), the rest visible as unverified with a reason. `DEPENDENCY SITES`
+counts them; `CALL SITES` stays call-shaped.
+
+Target-less `impact` and `check` diff the working tree against `HEAD` AND
+include untracked, non-ignored source files as whole-file additions, so new
+modules are checked before `git add`. `--staged` keeps its index-only meaning.
+
 An observed-text zero is not semantic zero or safe-delete proof. Numeric evidence values are ordinal ranking weights, not probabilities.
 
 When a plain name selects more than one definition, action-oriented commands
@@ -95,6 +109,40 @@ definition as an implicit repository-wide target.
 | Generate review candidates | `ucn deadcode`; `ucn audit-async` |
 | Resolve runtime frames | `ucn stacktrace <text>` |
 
+## In a shell, next to grep
+
+`ucn` is a Bash tool as much as an MCP tool. Two flags make it compose like
+`grep -n` so a shell-first agent can keep its reflexes and still get symbol
+answers:
+
+```bash
+ucn find handleRequest --lines            # path:line:signature   # kind
+ucn show handleRequest --lines            # callers as path:line:text; unverified ones end in "\t# unverified: <reason>"
+ucn show handleRequest --lines --sections=callees
+ucn usages handleRequest --lines          # every literal-name line; non-call kinds tagged "# import" / "# definition"
+ucn search 'retry(' --lines               # grep -n output, code-aware scope
+ucn impact handleRequest --lines
+ucn source handleRequest --raw            # the code and nothing else, ready for an exact-string edit
+ucn source src/server.js:40-80 --raw
+```
+
+Records go to stdout; the `ACCOUNT` / `CONTRACT` lines, notes, and the
+same-name disambiguation go to stderr prefixed `# ` (MCP keeps them in the one
+text block, and `--raw` appends its note as one trailing `# ` line there).
+`--lines` lists the whole band without default row/character caps, so pipe through
+`grep -v '# unverified'` for the confirmed tier or `cut -d: -f1 | sort | uniq -c`
+for callers per file. Nothing to list prints nothing and exits 1, grep's
+contract; errors exit 2. Explicit `--top`/`--limit` still apply and disclose
+omissions. `show --lines` accepts only callers/callees sections; target-less
+`impact --lines` lists Git-diff callers with per-target accounting. Closing a
+pipe with `head` is supported. `source --raw` extracts full large classes too;
+`--max-lines` truncation is disclosed on stderr. An explicit `--max-chars`
+fails before stdout if the complete shell output exceeds it. Unusual path
+characters (backslash/tab/CR/LF) are escaped; use JSON for exact filenames.
+`trace` and `tests` scripting uses `--json`. Use `grep` for literals, messages, configuration, and unsupported
+languages; use `ucn ... --lines` when the question is a symbol, a caller, or a
+definition, and `--raw` when the next step is an edit.
+
 ## Breaking-change protocol
 
 1. Pin the exact definition with `find`.
@@ -135,9 +183,17 @@ the old spelling. Read `changeSummary` and every review item. `plan` previews
 only: it does not modify files, run a compiler, or prove runtime compatibility.
 
 For `deps --cycles`, `eager` means every edge executes at module scope.
-`deferred` means at least one Python edge is function-local, so the chain is
-not an unconditional import-time cycle; it remains visible because invoking
-that function during initialization can still matter.
+`deferred` means at least one edge does not: a function-local import (Python
+`def`/`lambda` bodies; JS/TS `require()`/`import()` inside any function,
+including `() => require()` thunks), a Python `if TYPE_CHECKING:` import, or a
+TypeScript type-only import. Each deferred edge names its reason. A deferred
+chain is not an unconditional import-time cycle; function-local chains stay
+visible because invoking that function during initialization can still matter.
+Cycles are enumerated completely and independently of build history (capped at
+500 with a disclosed truncation; groups above 2000 files skip enumeration);
+`CYCLE GROUPS` and the files-in-cycles count remain complete even when the
+enumerated cycle counts are lower bounds. `CYCLE GROUPS` lists each strongly connected
+file set, the unit a refactor has to break.
 
 ## Efficient use
 

package/.claude/skills/ucn/references/commands.md

@@ -32,7 +32,7 @@ structural or code-only search.
 | Command | Purpose |
 |---|---|
 | `repo` | Repository orientation. Select `summary,files,stats,health` with `--sections`; `--deep` includes readiness evidence. Skipped unsupported source is listed with a grep/language-tool handoff. |
-| `deps <file>` | File dependency graph. Use `--direction=imports\|importers\|both`, `--detailed`, or `--cycles`. Python cycles are classified as eager or function-local/deferred without dropping either kind. |
+| `deps <file>` | File dependency graph. Use `--direction=imports\|importers\|both`, `--detailed`, or `--cycles`. Cycles distinguish eager edges from function-local, Python typing-guarded, and TypeScript type-only edges. Complete cycle groups remain visible when enumeration is capped. |
 | `api [file]` | Static exported/public surface for a project or file. |
 | `entrypoints` | Framework, route, task, test, and runtime entry points. |
 | `endpoints` | Server/client HTTP surface; `--bridge` adds advisory matching. |
@@ -65,6 +65,8 @@ Symbol-listing commands emit handles such as `src/api.ts:42:handler`. Pass the f
 | `--compact` / `--no-compact` | Select token-efficient or full semantic output. |
 | `--range=N-M` | Extract an explicit line range with `source --file=<path>`. |
 | `--json` | Emit the stable CLI `{ meta, data }` envelope; `meta.contract` carries the truth boundary, decision safety, and next actions. |
+| `--lines` | `find/usages/search/show/impact`: uncapped `path:line:text` listings, with tier tags after a tab. `show` accepts callers/callees sections; default callers. Accounting and notes go to stderr. Exit 0 for records, 1 for none, 2 for errors. Explicit row limits disclose omissions. |
+| `--raw` | `source`: code only, including full large classes. Notes and explicit `--max-lines` truncation travel on stderr. In CLI shell modes, exceeding an explicit `--max-chars` fails before stdout instead of truncating it. |
 | `--expand-unverified` | Follow possible caller edges while preserving their unverified status. |
 | `--base=<ref>` / `--staged` | Scope Git-diff `impact` or target-less `check`. |
 | `--no-cache` / `--clear-cache` | Bypass or clear the current project's per-user cache. Set `UCN_CACHE_DIR` to override its root. |