ucn 3.1.8 → 3.3.0

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

@@ -2,76 +2,141 @@
 name: ucn
 description: Universal Code Navigator - extracts specific functions and their relationships (callers, callees, dependencies) without reading entire files. Use when you need one function from a large file or need to understand what calls/is called by a function. Saves context in codebases 1000+ LOC. Skip for simple text search, tiny codebases, or unsupported languages (only JS/TS, Python, Go, Rust, Java).
 allowed-tools: Bash(ucn *), Bash(npx ucn *)
-argument-hint: "[command] [symbol-name]"
+argument-hint: "[command] [symbol-name] [--flags]"
 ---
 
-# UCN - Semantic Code Navigation
+# UCN - Universal Code Navigator
 
-## When to Use
+UCN uses tree-sitter ASTs to understand code structure: functions, classes, callers, callees, imports, and dependencies. It works on JavaScript/TypeScript, Python, Go, Rust, and Java.
 
-UCN parses code into ASTs, so it understands structure - not just text patterns.
+## When to Use vs Skip
 
-**Use UCN when:**
-- You need to understand relationships (callers, callees, dependencies)
-- You're about to modify code and need to know the impact
-- You want to extract a specific function without reading the whole file
-- Codebase is 1000+ LOC (indexing overhead pays off)
+**Use UCN when** the codebase is 1000+ LOC and you need:
+- Who calls a function or what it calls
+- What breaks if you change something
+- One function from a large file (without reading the whole file)
+- Unused code detection, dependency graphs
 
 **Skip UCN when:**
-- Simple text search (error messages, TODOs, literals)
-- Codebase is tiny (< 500 LOC) - just read the files
-- Language not supported (C, Ruby, PHP, etc.)
+- Simple text search (TODOs, error messages) — use grep
+- Codebase < 500 LOC — just read the files
+- Language not supported — use grep/read
+- Finding files by name — use glob
 
-## Commands
+## Command Format
 
-### Understanding Code
-```bash
-ucn about <name>      # Definition, callers, callees, tests, code
-ucn context <name>    # Callers + callees
-ucn smart <name>      # Function + dependencies inline
-ucn impact <name>     # All call sites by file
-ucn trace <name>      # Call tree
-ucn example <name>    # Best usage example with context
+```
+ucn [target] <command> [name] [--flags]
 ```
 
-### Finding Code
+**Target** (optional, defaults to current directory):
+- Omit or `.` — current project directory (most common)
+- `path/to/file.js` — single file mode
+- `path/to/dir` — specific project directory
+- `"src/**/*.py"` — glob pattern (quote it)
+
+**Examples of correct invocation:**
 ```bash
-ucn find <name>       # Find definitions
-ucn usages <name>     # All usages by type
-ucn toc               # Table of contents
-ucn tests <name>      # Find tests for a function
-ucn deadcode          # Find unused functions/classes
+ucn about handleRequest
+ucn fn parseConfig --file=utils
+ucn toc
+ucn src/api/routes.js fn handleRequest
+ucn impact createUser --exclude=test
 ```
 
-### Extracting Code
+## Commands
+
+### Understand Code
+| Command | Args | What it returns |
+|---------|------|-----------------|
+| `about <name>` | symbol name | Definition + callers + callees + tests + source code. **Start here.** |
+| `context <name>` | symbol name | Callers and callees (numbered — use `expand N` to see code) |
+| `smart <name>` | symbol name | Function source + all helper functions it calls, inline |
+| `impact <name>` | symbol name | Every call site grouped by file. Use before modifying a function. |
+| `trace <name>` | symbol name | Call tree (who calls who) at `--depth=N` (default 3) |
+| `example <name>` | symbol name | Best real usage example with surrounding context |
+
+### Find Code
+| Command | Args | What it returns |
+|---------|------|-----------------|
+| `find <name>` | symbol name | Definitions ranked by usage count (top 5) |
+| `usages <name>` | symbol name | All usages grouped: definitions, calls, imports, references |
+| `toc` | none | Table of contents: all functions, classes, exports |
+| `tests <name>` | symbol name | Test files and test functions for the given symbol |
+| `search <text>` | search term | Text search (grep-like, but respects project ignores) |
+| `deadcode` | none | Lists all functions/classes with zero callers |
+
+### Extract Code
+| Command | Args | What it returns |
+|---------|------|-----------------|
+| `fn <name>` | function name | Full function source code |
+| `class <name>` | class name | Full class source code |
+| `lines <range>` | e.g. `50-100` | Lines from file. In project mode requires `--file=<path>` |
+| `expand <N>` | number | Source code for numbered item from last `context` output |
+
+### Dependencies
+| Command | Args | What it returns |
+|---------|------|-----------------|
+| `imports <file>` | relative path | What the file imports (modules, symbols) |
+| `exporters <file>` | relative path | Which files import this file |
+| `file-exports <file>` | relative path | What the file exports |
+| `graph <file>` | relative path | Dependency tree at `--depth=N` |
+
+### Refactoring
+| Command | Args | What it returns |
+|---------|------|-----------------|
+| `verify <name>` | function name | Checks all call sites match the function's signature |
+| `plan <name>` | function name | Preview refactoring with `--rename-to`, `--add-param`, `--remove-param` |
+| `related <name>` | symbol name | Functions in same file or sharing dependencies |
+
+## Key Flags
+
+| Flag | Works with | Effect |
+|------|-----------|--------|
+| `--file=<pattern>` | any symbol command | Filter by file path when name is ambiguous (e.g., `--file=routes`) |
+| `--exclude=a,b` | any | Exclude files matching patterns (e.g., `--exclude=test,mock`) |
+| `--in=<path>` | any | Only search within path (e.g., `--in=src/core`) |
+| `--include-tests` | any | Include test files in results (excluded by default) |
+| `--include-methods` | `context`, `smart` | Include `obj.method()` calls (only direct calls shown by default) |
+| `--depth=N` | `trace`, `graph`, `about`, `find` | Tree/expansion depth (default 3) |
+| `--context=N` | `usages`, `search` | Lines of context around each match |
+| `--json` | any | Machine-readable JSON output |
+| `--code-only` | `search` | Exclude matches in comments and strings |
+| `--with-types` | `smart`, `about` | Include type definitions |
+| `--top=N` / `--all` | `find`, `usages` | Limit results to top N, or show all |
+| `--no-cache` | any | Skip cached index (use after file changes) |
+| `--clear-cache` | any | Delete cached index before running |
+
+## Common Patterns
+
+**Investigate a function (first stop):**
 ```bash
-ucn fn <name>                    # Extract function
-ucn fn <name> --file routes      # Disambiguate by path
-ucn class <name>                 # Extract class
+ucn about handleRequest
 ```
 
-### Dependencies
+**Before modifying a function:**
 ```bash
-ucn imports <file>      # What this file imports
-ucn exporters <file>    # Who imports this file
-ucn file-exports <file> # What this file exports
-ucn graph <file>        # Dependency tree
+ucn impact handleRequest          # See all callers
+ucn smart handleRequest           # See function + its helpers
 ```
 
-## Flags
+**Extract one function from a large file:**
+```bash
+ucn fn handleRequest --file=api   # Disambiguate by file path
+```
 
-- `--file <pattern>` - Filter by file path
-- `--exclude=test,mock` - Exclude files
-- `--depth=N` - Tree depth
-- `--context=N` - Lines of context around matches
-- `--code-only` - Filter out comments and strings
-- `--include-methods` - Include obj.method() calls
-- `--include-tests` - Include test files
-- `--no-cache` - Disable caching
-- `--clear-cache` - Clear cache before running
+**Find unused code:**
+```bash
+ucn deadcode
+```
 
-## More Info
+**Understand a file's role:**
+```bash
+ucn imports core/project.js       # What it depends on
+ucn exporters core/project.js     # Who depends on it
+```
 
+**Multiple queries (keeps index in memory):**
 ```bash
-ucn --help            # Full command reference
+ucn --interactive
 ```

package/README.md

@@ -1,38 +1,140 @@
 # UCN - Universal Code Navigator
 
-When working with large codebases or even vibe coding all into a single large file, AI agents often need to read entire files just to understand a single function. This eats up the context rather fast, so the intent is to keep the agents perform better with their context clean than rather cluttered.
+AI agents working with large codebases often read entire files just to understand a single function. UCN uses tree-sitter ASTs to extract exactly what you need — functions, callers, callees, dependencies — without wasting context.
 
-## Example
+## Examples
 
-A 2000-line file and need to understand `handleRequest`:
+**Extract a function** from a large file without reading it:
+```
+$ ucn fn expandGlob
+core/discovery.js:135
+[ 135- 166] expandGlob(pattern, options = {})
+────────────────────────────────────────────────────────────
+function expandGlob(pattern, options = {}) {
+    const root = path.resolve(options.root || process.cwd());
+    const ignores = options.ignores || DEFAULT_IGNORES;
+    ...
+    return files.sort(compareNames);
+}
+```
 
-```bash
-$ ucn fn handleRequest
-src/api/routes.js:145
-[145-162] handleRequest(req, res)
-────────────────────────────────────────────────────────
-function handleRequest(req, res) {
-  const validated = validateInput(req.body);
-  const result = processData(validated);
-  return sendResponse(res, result);
+**See who calls a function and what it calls:**
+```
+$ ucn context expandGlob
+Context for expandGlob:
+════════════════════════════════════════════════════════════
+
+CALLERS (7):
+  [1] cli/index.js:1847 [runGlobCommand]
+    const files = expandGlob(pattern);
+  [2] core/project.js:81
+    const files = expandGlob(pattern, {
+  [3] core/project.js:3434
+    const currentFiles = expandGlob(pattern, { root: this.root });
+  ...
+
+CALLEES (2):
+  [8] parseGlobPattern [utility] - core/discovery.js:171
+  [9] walkDir [utility] - core/discovery.js:227
+```
+
+**See what breaks if you change a function:**
+```
+$ ucn impact shouldIgnore
+Impact analysis for shouldIgnore
+════════════════════════════════════════════════════════════
+core/discovery.js:289
+shouldIgnore (name, ignores, parentDir)
+
+CALL SITES: 2
+  Files affected: 1
+
+BY FILE:
+
+core/discovery.js (2 calls)
+  :255 [walkDir]
+    if (shouldIgnore(entry.name, options.ignores, dir)) continue;
+    args: entry.name, options.ignores, dir
+  :373 [detectProjectPattern]
+    !shouldIgnore(entry.name, DEFAULT_IGNORES)) {
+    args: entry.name, DEFAULT_IGNORES
+```
+
+**Get a function with all its dependencies inline:**
+```
+$ ucn smart shouldIgnore
+shouldIgnore (/Users/mihail/ucn/core/discovery.js:289)
+════════════════════════════════════════════════════════════
+function shouldIgnore(name, ignores, parentDir) {
+    for (const pattern of ignores) {
+        if (pattern.includes('*')) {
+            const regex = globToRegex(pattern);
+            ...
+        }
+    }
+    ...
 }
 
-$ ucn context handleRequest
-CALLERS (3):
-  src/server.js:45 [startServer]
-  src/middleware.js:23 [authMiddleware]
-  test/api.test.js:67 [testHandler]
+─── DEPENDENCIES ───
 
-CALLEES (3):
-  validateInput - src/utils/validation.js:12
-  processData - src/services/data.js:89
-  sendResponse - src/utils/response.js:34
+// globToRegex [utility] (core/discovery.js:208)
+function globToRegex(glob) {
+    let regex = glob.replace(/[.+^$[\]\\]/g, '\\$&');
+    ...
+    return new RegExp('^' + regex + '$');
+}
 ```
 
-18 lines of context instead of 2000.
+**Trace the call tree:**
+```
+$ ucn trace expandGlob --depth=2
+Call tree for expandGlob
+════════════════════════════════════════════════════════════
+
+expandGlob
+├── parseGlobPattern (core/discovery.js:171) [utility] 1x
+│   └── globToRegex (core/discovery.js:208) [utility] 1x
+└── walkDir (core/discovery.js:227) [utility] 1x
+    └── shouldIgnore (core/discovery.js:289) [utility] 1x
+```
+
+**Find unused code:**
+```
+$ ucn deadcode
+Dead code: 15 unused symbol(s)
+
+cli/index.js
+  [1649-1654] extractFunctionNameFromContent (function)
+core/project.js
+  [1664-1694] findReExportsOf (method)
+  [1998-2020] withCompleteness (method)
+...
+```
+
+**See a file's dependencies:**
+```
+$ ucn imports core/project.js
+Imports in core/project.js:
+
+INTERNAL:
+  ./discovery
+    -> core/discovery.js
+    expandGlob, findProjectRoot, detectProjectPattern, isTestFile
+  ./imports
+    -> core/imports.js
+    extractImports, extractExports, resolveImport
+  ./parser
+    -> core/parser.js
+    parseFile
+  ../languages
+    -> languages/index.js
+    detectLanguage, getParser, getLanguageModule, PARSE_OPTIONS, safeParse
+
+EXTERNAL:
+  fs, path, crypto
+```
 
 ## Supported Languages
-The supported languages can grow as tree-sitter supports many, but for my use cases I've added support for:  
 
 JavaScript, TypeScript, Python, Go, Rust, Java
 
@@ -75,49 +177,65 @@ cp -r ucn/.claude/skills/ucn ~/.agents/skills/
 ## Usage
 
 ```
+UCN - Universal Code Navigator
+
+Supported: JavaScript, TypeScript, Python, Go, Rust, Java
+
 Usage:
   ucn [command] [args]            Project mode (current directory)
   ucn <file> [command] [args]     Single file mode
   ucn <dir> [command] [args]      Project mode (specific directory)
   ucn "pattern" [command] [args]  Glob pattern mode
 
-UNDERSTAND CODE
-  about <name>        Full picture (definition, callers, callees, tests, code)
-  context <name>      Who calls this + what it calls
+═══════════════════════════════════════════════════════════════════════════════
+UNDERSTAND CODE (UCN's strength - semantic analysis)
+═══════════════════════════════════════════════════════════════════════════════
+  about <name>        RECOMMENDED: Full picture (definition, callers, callees, tests, code)
+  context <name>      Who calls this + what it calls (numbered for expand)
   smart <name>        Function + all dependencies inline
   impact <name>       What breaks if changed (call sites grouped by file)
   trace <name>        Call tree visualization (--depth=N)
 
+═══════════════════════════════════════════════════════════════════════════════
 FIND CODE
+═══════════════════════════════════════════════════════════════════════════════
   find <name>         Find symbol definitions (top 5 by usage count)
   usages <name>       All usages grouped: definitions, calls, imports, references
-  toc                 Table of contents (functions, classes, state)
-  search <term>       Text search
+  toc                 Table of contents (compact; --detailed lists all symbols)
+  search <term>       Text search (for simple patterns, consider grep instead)
   tests <name>        Find test files for a function
 
+═══════════════════════════════════════════════════════════════════════════════
 EXTRACT CODE
+═══════════════════════════════════════════════════════════════════════════════
   fn <name>           Extract function (--file to disambiguate)
   class <name>        Extract class
   lines <range>       Extract line range (e.g., lines 50-100)
   expand <N>          Show code for item N from context output
 
+═══════════════════════════════════════════════════════════════════════════════
 FILE DEPENDENCIES
+═══════════════════════════════════════════════════════════════════════════════
   imports <file>      What does file import
   exporters <file>    Who imports this file
   file-exports <file> What does file export
   graph <file>        Full dependency tree (--depth=N)
 
+═══════════════════════════════════════════════════════════════════════════════
 REFACTORING HELPERS
+═══════════════════════════════════════════════════════════════════════════════
   plan <name>         Preview refactoring (--add-param, --remove-param, --rename-to)
   verify <name>       Check all call sites match signature
   deadcode            Find unused functions/classes
   related <name>      Find similar functions (same file, shared deps)
 
+═══════════════════════════════════════════════════════════════════════════════
 OTHER
+═══════════════════════════════════════════════════════════════════════════════
   api                 Show exported/public symbols
   typedef <name>      Find type definitions
   stats               Project statistics
-  stacktrace <text>   Parse stack trace, show code at each frame
+  stacktrace <text>   Parse stack trace, show code at each frame (alias: stack)
   example <name>      Best usage example with context
 
 Common Flags:
@@ -132,9 +250,21 @@ Common Flags:
   --top=N / --all     Limit or show all results
   --include-tests     Include test files
   --include-methods   Include method calls (obj.fn) in caller/callee analysis
+  --include-uncertain Include ambiguous/uncertain call matches
+  --include-exported  Include exported symbols in deadcode
+  --detailed          List all symbols in toc (compact counts by default)
   --no-cache          Disable caching
   --clear-cache       Clear cache before running
+  --no-follow-symlinks  Don't follow symbolic links
   -i, --interactive   Keep index in memory for multiple queries
+
+Quick Start:
+  ucn toc                             # See project structure (compact)
+  ucn toc --detailed                  # List all functions/classes
+  ucn about handleRequest             # Understand a function
+  ucn impact handleRequest            # Before modifying
+  ucn fn handleRequest --file api     # Extract specific function
+  ucn --interactive                   # Multiple queries
 ```
 
 ## License