ucn 3.4.2 → 3.4.4

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

@@ -1,142 +1,140 @@
 ---
 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).
+description: "Code relationship analyzer (callers, call trees, impact, dead code) via tree-sitter AST. 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 Python, JS/TS, Go, Rust, Java. Skip for plain text search or codebases under 500 LOC."
 allowed-tools: Bash(ucn *), Bash(npx ucn *)
 argument-hint: "[command] [symbol-name] [--flags]"
 ---
 
-# UCN - Universal Code Navigator
+# UCN — Universal Code Navigator
 
-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.
+Understands code structure via tree-sitter ASTs: who calls what, what breaks if you change something, full call trees, dead code. Works on Python, JS/TS, Go, Rust, Java.
 
-## When to Use vs Skip
+## When to Reach for UCN Instead of Grep/Read
 
-**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
+**Use UCN when your next action would be:**
 
-**Skip UCN when:**
-- Simple text search (TODOs, error messages) — use grep
-- Codebase < 500 LOC — just read the files
-- Language not supported — use grep/read
+- "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 Python, JS/TS, Go, Rust, Java)
 - Finding files by name — use glob
 
-## Command Format
+## The 5 Commands You'll Use Most
 
-```
-ucn [target] <command> [name] [--flags]
+### 1. `about` — First stop for any investigation
+
+One command returns: definition, source code, who calls it, what it calls, related tests.
+
+```bash
+ucn about compute_composite
 ```
 
-**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)
+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. Essential before modifying a signature, renaming, or deleting.
 
-**Examples of correct invocation:**
 ```bash
-ucn about handleRequest
-ucn fn parseConfig --file=utils
-ucn toc
-ucn src/api/routes.js fn handleRequest
-ucn impact createUser --exclude=test
+ucn impact score_trend              # Every caller, grouped by file
+ucn impact score_trend --exclude=test  # Only production callers
 ```
 
-## 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 |
+Replaces: grep for the function name → manually filtering definitions vs calls vs imports → reading context around each match.
 
-## Key Flags
+### 3. `trace` — Understand execution flow
+
+Draws the call tree downward from any function. Depth-limited.
 
-| 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 about handleRequest
+ucn trace generate_report --depth=3
 ```
 
-**Before modifying a function:**
+This 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.
+
+### 4. `fn` / `class` — Extract without reading the whole file
+
+Pull one function or class out of a large file. Saves hundreds of lines of context window.
+
 ```bash
-ucn impact handleRequest          # See all callers
-ucn smart handleRequest           # See function + its helpers
+ucn fn handle_request --file=api    # --file disambiguates when name exists in multiple files
+ucn class MarketDataFetcher
 ```
 
-**Extract one function from a large file:**
+### 5. `deadcode` — Find unused code
+
+Lists all functions and classes with zero callers across the project.
+
 ```bash
-ucn fn handleRequest --file=api   # Disambiguate by file path
+ucn deadcode                        # Everything
+ucn deadcode --exclude=test         # Skip test files (most useful)
+```
+
+## When to Use the Other Commands
+
+| Situation | Command | What it does |
+|-----------|---------|-------------|
+| Need function + all its helpers inline | `ucn smart <name>` | Returns function source with every helper it calls expanded below it |
+| Checking if a refactor broke signatures | `ucn verify <name>` | Validates all call sites match the function's parameter count |
+| Understanding a file's role in the project | `ucn imports <file>` | What it depends on |
+| Understanding who depends on a file | `ucn exporters <file>` | Which files import it |
+| Quick project overview | `ucn toc` | Every file with function/class counts and line counts |
+| Finding all usages (not just calls) | `ucn usages <name>` | Groups into: definitions, calls, imports, type references |
+| Finding related code to refactor together | `ucn related <name>` | Functions sharing dependencies or in same file |
+| Preview a rename or param change | `ucn plan <name> --rename-to=new_name` | Shows what would change without doing it |
+| Dependency tree for a file | `ucn graph <file> --depth=2` | Visual import tree |
+| Find which tests cover a function | `ucn tests <name>` | Test files and test function names |
+
+## Command Format
+
+```
+ucn [target] <command> [name] [--flags]
 ```
 
-**Find unused code:**
+**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
+
+| Flag | When to use it |
+|------|---------------|
+| `--file=<pattern>` | Disambiguate when a name exists in multiple files (e.g., `--file=api`) |
+| `--exclude=test,mock` | Focus on production code only |
+| `--in=src/core` | Limit search to a subdirectory |
+| `--depth=N` | Control tree depth for `trace` and `graph` (default 3) |
+| `--include-tests` | Include test files in results (excluded by default) |
+| `--include-methods` | Include `obj.method()` calls in `context`/`smart` (only direct calls shown by default) |
+| `--no-cache` | Force re-index after editing files |
+| `--context=N` | Lines of surrounding context in `usages`/`search` output |
+
+## Workflow Integration
+
+**Investigating a bug:**
 ```bash
-ucn deadcode
+ucn about problematic_function          # Understand it fully
+ucn trace problematic_function --depth=2  # See what it calls
 ```
 
-**Understand a file's role:**
+**Before modifying a function:**
 ```bash
-ucn imports core/project.js       # What it depends on
-ucn exporters core/project.js     # Who depends on it
+ucn impact the_function                 # Who will break?
+ucn smart the_function                  # See it + its helpers
+# ... make your changes ...
+ucn verify the_function                 # Did all call sites survive?
 ```
 
-**Multiple queries (keeps index in memory):**
+**Periodic maintenance:**
 ```bash
-ucn --interactive
+ucn deadcode --exclude=test             # What can be deleted?
+ucn toc                                 # Project overview
 ```

package/README.md

@@ -267,6 +267,28 @@ Quick Start:
   ucn --interactive                   # Multiple queries
 ```
 
+## Workflows
+
+**Investigating a bug:**
+```bash
+ucn about problematic_function          # Understand it fully
+ucn trace problematic_function --depth=2  # See what it calls
+```
+
+**Before modifying a function:**
+```bash
+ucn impact the_function                 # Who will break?
+ucn smart the_function                  # See it + its helpers
+# ... make your changes ...
+ucn verify the_function                 # Did all call sites survive?
+```
+
+**Periodic cleanup:**
+```bash
+ucn deadcode --exclude=test             # What can be deleted?
+ucn toc                                 # Project overview
+```
+
 ## License
 
 MIT

package/cli/index.js

@@ -2226,7 +2226,7 @@ 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)
+  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
 
@@ -2275,6 +2275,9 @@ 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 matches
+  --include-exported  Include exported symbols in deadcode
+  --detailed          List all symbols in toc (compact by default)
   --no-cache          Disable caching
   --clear-cache       Clear cache before running
   --no-follow-symlinks  Don't follow symbolic links

package/core/project.js

@@ -1021,8 +1021,8 @@ class ProjectIndex {
                             const matchesDef = definitions.some(d => d.className === targetClass);
                             if (!matchesDef) continue;
                             // Falls through to add as caller
-                        } else if (fileEntry.language === 'python' && ['self', 'cls'].includes(call.receiver)) {
-                            // self.method() / cls.method() — resolve to same-class method
+                        } else if (['self', 'cls', 'this'].includes(call.receiver)) {
+                            // self.method() / cls.method() / this.method() — resolve to same-class method
                             const callerSymbol = this.findEnclosingFunction(filePath, call.line, true);
                             if (!callerSymbol?.className) continue;
                             // Check if any definition of searched function belongs to caller's class
@@ -1030,8 +1030,6 @@ class ProjectIndex {
                             if (!matchesDef) continue;
                             // Falls through to add as caller
                         } else {
-                            // Always skip this/self/cls calls (internal state access, not function calls)
-                            if (['this', 'self', 'cls'].includes(call.receiver)) continue;
                             // Go doesn't use this/self/cls - always include Go method calls
                             // For other languages, skip method calls unless explicitly requested
                             if (fileEntry.language !== 'go' && !options.includeMethods) continue;
@@ -1143,14 +1141,14 @@ class ProjectIndex {
 
                 // Smart method call handling:
                 // - Go: include all method calls (Go doesn't use this/self/cls)
-                // - Python self.method(): resolve to same-class method (handled below)
+                // - self/this.method(): resolve to same-class method (handled below)
                 // - Python self.attr.method(): resolve via selfAttribute (handled below)
                 // - Other languages: skip method calls unless explicitly requested
                 if (call.isMethod) {
                     if (call.selfAttribute && language === 'python') {
                         // Will be resolved in second pass below
-                    } else if (language === 'python' && ['self', 'cls'].includes(call.receiver)) {
-                        // self.method() / cls.method() — resolve to same-class method below
+                    } else if (['self', 'cls', 'this'].includes(call.receiver)) {
+                        // self.method() / cls.method() / this.method() — resolve to same-class method below
                     } else if (language !== 'go' && !options.includeMethods) {
                         continue;
                     }
@@ -1166,8 +1164,8 @@ class ProjectIndex {
                     continue;
                 }
 
-                // Collect Python self.method() calls for same-class resolution
-                if (language === 'python' && call.isMethod && ['self', 'cls'].includes(call.receiver)) {
+                // Collect self/this.method() calls for same-class resolution
+                if (call.isMethod && ['self', 'cls', 'this'].includes(call.receiver)) {
                     if (!selfMethodCalls) selfMethodCalls = [];
                     selfMethodCalls.push(call);
                     continue;
@@ -1255,7 +1253,7 @@ class ProjectIndex {
                 }
             }
 
-            // Third pass: resolve Python self.method() calls to same-class methods
+            // Third pass: resolve self/this.method() calls to same-class methods
             if (selfMethodCalls && def.className) {
                 for (const call of selfMethodCalls) {
                     const symbols = this.symbols.get(call.name);
@@ -1590,7 +1588,7 @@ class ProjectIndex {
         const fileEntry = this.files.get(filePath);
         if (!fileEntry) return null;
 
-        const nonCallableTypes = new Set(['class', 'struct', 'interface', 'type', 'state']);
+        const nonCallableTypes = new Set(['class', 'struct', 'interface', 'type', 'state', 'impl']);
         for (const symbol of fileEntry.symbols) {
             if (!nonCallableTypes.has(symbol.type) &&
                 symbol.startLine <= lineNum &&

package/languages/java.js

@@ -567,7 +567,7 @@ function findCallsInCode(code, parser) {
                     name: nameNode.text,
                     line: node.startPosition.row + 1,
                     isMethod: !!objNode,
-                    receiver: objNode?.type === 'identifier' ? objNode.text : undefined,
+                    receiver: (objNode?.type === 'identifier' || objNode?.type === 'this') ? objNode.text : undefined,
                     enclosingFunction
                 });
             }

package/languages/rust.js

@@ -622,7 +622,7 @@ function findCallsInCode(code, parser) {
                         name: fieldNode.text,
                         line: node.startPosition.row + 1,
                         isMethod: true,
-                        receiver: valueNode?.type === 'identifier' ? valueNode.text : undefined,
+                        receiver: (valueNode?.type === 'identifier' || valueNode?.type === 'self') ? valueNode.text : undefined,
                         enclosingFunction
                     });
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.4.2",
+  "version": "3.4.4",
   "description": "Code navigation built by AI, for AI. Reduces context usage when working with large codebases.",
   "main": "index.js",
   "bin": {

package/test/parser.test.js

@@ -6188,6 +6188,164 @@ class Line:
     });
 });
 
+describe('Regression: JS this.method() same-class resolution', () => {
+    it('findCallees should resolve this.method() to same-class methods', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-jsthis-'));
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"test"}');
+            fs.writeFileSync(path.join(tmpDir, 'service.js'), `
+class DataService {
+    _fetchRemote(key, days) {
+        return this._makeRequest(\`/api/\${key}\`);
+    }
+
+    _makeRequest(url) {
+        return null;
+    }
+
+    getRecords(key, days = 365) {
+        if (this._isValid(key)) {
+            return this._fetchRemote(key, days);
+        }
+        return null;
+    }
+
+    _isValid(key) {
+        return key.length > 0;
+    }
+}
+`);
+            const index = new ProjectIndex(tmpDir);
+            index.build('**/*.js', { quiet: true });
+
+            // getRecords should have _fetchRemote and _isValid as callees
+            const defs = index.symbols.get('getRecords');
+            assert.ok(defs && defs.length > 0, 'Should find getRecords');
+            const callees = index.findCallees(defs[0]);
+            const calleeNames = callees.map(c => c.name);
+            assert.ok(calleeNames.includes('_fetchRemote'),
+                `Should resolve this._fetchRemote(), got: ${calleeNames.join(', ')}`);
+            assert.ok(calleeNames.includes('_isValid'),
+                `Should resolve this._isValid(), got: ${calleeNames.join(', ')}`);
+
+            // _fetchRemote should have getRecords as caller
+            const callers = index.findCallers('_fetchRemote');
+            const callerNames = callers.map(c => c.callerName);
+            assert.ok(callerNames.includes('getRecords'),
+                `Should find getRecords as caller of _fetchRemote, got: ${callerNames.join(', ')}`);
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
+
+describe('Regression: Java this.method() same-class resolution', () => {
+    it('findCallees should resolve this.method() to same-class methods', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-javathis-'));
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'pom.xml'), '<project></project>');
+            fs.writeFileSync(path.join(tmpDir, 'DataService.java'), `
+public class DataService {
+    private Object fetchRemote(String key, int days) {
+        return this.makeRequest("/api/" + key);
+    }
+
+    private Object makeRequest(String url) {
+        return null;
+    }
+
+    public Object getRecords(String key) {
+        if (this.isValid(key)) {
+            return this.fetchRemote(key, 365);
+        }
+        return null;
+    }
+
+    private boolean isValid(String key) {
+        return key.length() > 0;
+    }
+}
+`);
+            const index = new ProjectIndex(tmpDir);
+            index.build('**/*.java', { quiet: true });
+
+            // getRecords should have fetchRemote and isValid as callees
+            const defs = index.symbols.get('getRecords');
+            assert.ok(defs && defs.length > 0, 'Should find getRecords');
+            const callees = index.findCallees(defs[0]);
+            const calleeNames = callees.map(c => c.name);
+            assert.ok(calleeNames.includes('fetchRemote'),
+                `Should resolve this.fetchRemote(), got: ${calleeNames.join(', ')}`);
+            assert.ok(calleeNames.includes('isValid'),
+                `Should resolve this.isValid(), got: ${calleeNames.join(', ')}`);
+
+            // fetchRemote should have getRecords as caller
+            const callers = index.findCallers('fetchRemote');
+            const callerNames = callers.map(c => c.callerName);
+            assert.ok(callerNames.includes('getRecords'),
+                `Should find getRecords as caller of fetchRemote, got: ${callerNames.join(', ')}`);
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
+
+describe('Regression: Rust self.method() same-class resolution', () => {
+    it('findCallees should resolve self.method() to same-class methods', () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-rustself-'));
+        try {
+            fs.writeFileSync(path.join(tmpDir, 'Cargo.toml'), '[package]\nname = "test"');
+            fs.mkdirSync(path.join(tmpDir, 'src'), { recursive: true });
+            fs.writeFileSync(path.join(tmpDir, 'src', 'service.rs'), `
+struct DataService {
+    base_url: String,
+}
+
+impl DataService {
+    fn fetch_remote(&self, key: &str, days: i32) -> Option<String> {
+        self.make_request(&format!("/api/{}", key))
+    }
+
+    fn make_request(&self, url: &str) -> Option<String> {
+        None
+    }
+
+    fn get_records(&self, key: &str) -> Option<String> {
+        if self.is_valid(key) {
+            return self.fetch_remote(key, 365);
+        }
+        None
+    }
+
+    fn is_valid(&self, key: &str) -> bool {
+        !key.is_empty()
+    }
+}
+`);
+            const index = new ProjectIndex(tmpDir);
+            index.build('**/*.rs', { quiet: true });
+
+            // get_records should have fetch_remote and is_valid as callees
+            const defs = index.symbols.get('get_records');
+            assert.ok(defs && defs.length > 0, 'Should find get_records');
+            const callees = index.findCallees(defs[0]);
+            const calleeNames = callees.map(c => c.name);
+            assert.ok(calleeNames.includes('fetch_remote'),
+                `Should resolve self.fetch_remote(), got: ${calleeNames.join(', ')}`);
+            assert.ok(calleeNames.includes('is_valid'),
+                `Should resolve self.is_valid(), got: ${calleeNames.join(', ')}`);
+
+            // fetch_remote should have get_records as caller
+            const callers = index.findCallers('fetch_remote');
+            const callerNames = callers.map(c => c.callerName);
+            assert.ok(callerNames.includes('get_records'),
+                `Should find get_records as caller of fetch_remote, got: ${callerNames.join(', ')}`);
+        } finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});
+
 describe('Regression: Python self.method() same-class resolution', () => {
     it('findCallees should resolve self.method() to same-class methods', () => {
         const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ucn-selfmethod-'));