ucn 3.7.44 → 3.7.46

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

@@ -1,17 +1,17 @@
 ---
 name: ucn
-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 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. 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]"
 ---
 
 # UCN — Universal Code Navigator
 
-Understands code structure via tree-sitter ASTs: who calls what, what breaks if you change something, full call trees, dead code. Works on JS/TS, Python, Go, Rust, Java. Also parses HTML files (inline scripts and event handlers).
+Extract functions, trace call chains, find callers, and detect dead code — without reading entire files. Works on JS/TS, Python, Go, Rust, Java, and HTML (inline scripts and event handlers).
 
 ## When to Reach for UCN Instead of Grep/Read
 
-**Use UCN when your next action would be:**
+**Use UCN when the next action would be:**
 
 - "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
@@ -164,7 +164,7 @@ ucn trace problematic_function --depth=2  # See what it calls
 ```bash
 ucn impact the_function                 # Who will break?
 ucn smart the_function                  # See it + its helpers
-# ... make your changes ...
+# ... make changes ...
 ucn verify the_function                 # Did all call sites survive?
 ```
 

package/README.md

@@ -1,14 +1,14 @@
-# UCN — Universal Code Navigator
+# UCN - Universal Code Navigator
 
-AST-powered code intelligence from the terminal.
+Code intelligence for AI agents and developers - understand, extract, and navigate code without reading whole files.
 
-UCN answers structural code questions instantly:
-- Who calls this function?
-- What breaks if I change this signature?
-- What changed in this diff, and who depends on it?
-- What code is safe to delete?
+Precise answers to structural code questions:
+- Who calls this function? → without grepping the whole project
+- What breaks if I change this? → every call site, with arguments
+- What does this function do? → extracted with dependencies inline
+- What code is safe to delete? → verified unused symbols
 
-Instead of reading full files, UCN gives precise, AST-verified answers.
+One command replaces 3-4 grep+read cycles. Powered by tree-sitter.
 
 [![npm](https://img.shields.io/npm/v/ucn)](https://www.npmjs.com/package/ucn)
 [![license](https://img.shields.io/npm/l/ucn)](LICENSE)
@@ -20,22 +20,21 @@ Instead of reading full files, UCN gives precise, AST-verified answers.
 ```bash
 npm install -g ucn
 
+ucn toc                   # project overview
+ucn fn handleRequest      # extract a function without reading the file
 ucn about handleRequest   # full picture: definition, callers, callees, tests
 ucn impact handleRequest  # all call sites with arguments
 ucn trace main --depth=3  # call tree, no file reads
 ucn deadcode              # unused functions, AST-verified
-ucn fn handleRequest      # extract a function without reading the file
-ucn toc                   # project overview
-ucn --interactive         # REPL mode, index stays in memory
 ```
 
-Parses JS/TS, Python, Go, Rust, Java, and HTML with tree-sitter. Runs locally.
+Supports JS/TS, Python, Go, Rust, Java, and HTML. Runs locally.
 
 ```
-  Terminal              AI Agents              Agent Skills
-       │                    │                       │
-      CLI                  MCP                    Skill
-       └────────────────────┼───────────────────────┘
+  Terminal              AI Agents           Agent Skills
+       │                    │                    │
+      CLI                  MCP                 Skill
+       └────────────────────┼────────────────────┘
                             │
                      ┌──────┴──────┐
                      │ UCN Engine  │
@@ -48,7 +47,7 @@ Parses JS/TS, Python, Go, Rust, Java, and HTML with tree-sitter. Runs locally.
 
 ## Why UCN
 
-UCN uses tree-sitter to parse code into an AST, then builds a call graph and symbol table on top of it. Instead of matching text, it understands which functions call which, what depends on what, and what's unused. Everything runs locally.
+AI agents waste tokens reading entire files to find one function, or grep for callers and miss half of them. UCN builds a structural index of the codebase - it knows which functions call which, what depends on what, and what's unused. One command gives what would take 3-4 file reads and greps.
 
 "What happens when `build()` runs?"
 
@@ -139,7 +138,7 @@ VS Code uses `.vscode/mcp.json`:
 
 </details>
 
-All 28 commands ship as a single MCP tool, under 2KB of schema in the agent's context.
+All 28 commands ship as a single MCP tool - under 2KB of context.
 
 ### Agent Skill (no server needed)
 
@@ -294,13 +293,13 @@ ucn deadcode --exclude=test                # what can be deleted?
 
 ## Limitations
 
-UCN is static AST analysis, not runtime instrumentation.
+UCN analyzes code structure statically - it doesn't run code.
 
-- **5 languages + HTML** — JS/TS, Python, Go, Rust, Java. Falls back to text search for others.
-- **Static analysis only** — Can't follow `eval()`, `getattr()`, reflection, or other dynamic dispatch.
-- **Duck-typed methods** — `obj.method()` in JS/TS/Python is marked "uncertain" when the receiver type is ambiguous. Go/Rust/Java resolve with high confidence.
-- **Single project scope** — Follows imports within the project but not into `node_modules` or `site-packages`.
-- **First-query index time** — A few seconds on large projects. Cached incrementally after that.
+- **5 languages + HTML** - JS/TS, Python, Go, Rust, Java. Falls back to text search for others.
+- **Static analysis only** - Can't follow `eval()`, `getattr()`, reflection, or other dynamic dispatch.
+- **Duck-typed methods** - `obj.method()` in JS/TS/Python is marked "uncertain" when the receiver type is ambiguous. Go/Rust/Java resolve with high confidence.
+- **Single project scope** - Follows imports within the project but not into `node_modules` or `site-packages`.
+- **First-query index time** - A few seconds on large projects. Cached incrementally after that.
 
 ---
 

package/core/execute.js

@@ -99,6 +99,24 @@ function checkFileError(result, file) {
     return null;
 }
 
+/**
+ * Validate that className filter actually matches a definition.
+ * Returns error string if className is invalid, null if OK.
+ */
+function validateClassName(index, name, className) {
+    if (!className) return null;
+    const allDefs = index.symbols.get(name);
+    if (!allDefs || allDefs.length === 0) return null; // no defs at all — let the command handle "not found"
+    const matching = allDefs.filter(d => d.className === className);
+    if (matching.length > 0) return null; // className matched
+    // className specified but no definitions match
+    const available = [...new Set(allDefs.filter(d => d.className).map(d => d.className))];
+    if (available.length > 0) {
+        return `Symbol "${name}" not found in class "${className}". Available in: ${available.join(', ')}.`;
+    }
+    return `Symbol "${name}" is not a method of any class. Defined in: ${allDefs[0].relativePath}:${allDefs[0].startLine}.`;
+}
+
 /** Parse a number param (handles string from CLI, number from MCP). */
 function num(val, fallback) {
     if (val == null) return fallback;
@@ -162,6 +180,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const classErr = validateClassName(index, p.name, p.className);
+        if (classErr) return { ok: false, error: classErr };
         const result = index.context(p.name, {
             includeMethods: p.includeMethods,
             includeUncertain: p.includeUncertain || false,
@@ -177,6 +197,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const classErr = validateClassName(index, p.name, p.className);
+        if (classErr) return { ok: false, error: classErr };
         const result = index.impact(p.name, {
             file: p.file,
             className: p.className,
@@ -291,6 +313,7 @@ const HANDLERS = {
             topLevel: p.topLevel,
             all: p.all,
             top: num(p.top, undefined),
+            file: p.file,
         });
         return { ok: true, result };
     },
@@ -562,6 +585,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const classErr = validateClassName(index, p.name, p.className);
+        if (classErr) return { ok: false, error: classErr };
         const result = index.verify(p.name, { file: p.file, className: p.className });
         return { ok: true, result };
     },
@@ -570,6 +595,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const classErr = validateClassName(index, p.name, p.className);
+        if (classErr) return { ok: false, error: classErr };
         if (!p.addParam && !p.removeParam && !p.renameTo) {
             return { ok: false, error: 'Plan requires an operation: add_param, remove_param, or rename_to.' };
         }

package/core/project.js

@@ -919,6 +919,21 @@ class ProjectIndex {
             }
         }
 
+        // For methods (symbols with className), objects can be passed as parameters
+        // to files with no import relationship to the definition file.
+        // Expand to all project files that mention the name (fast text pre-check).
+        if (symbol.className) {
+            for (const filePath of this.files.keys()) {
+                if (relevantFiles.has(filePath)) continue;
+                try {
+                    const content = this._readFile(filePath);
+                    if (content.includes(name)) {
+                        relevantFiles.add(filePath);
+                    }
+                } catch (e) { /* skip unreadable */ }
+            }
+        }
+
         let calls = 0;
         let definitions = 0;
         let imports = 0;
@@ -3393,7 +3408,38 @@ class ProjectIndex {
         let totalDynamic = 0;
         let totalTests = 0;
 
+        // When file= is specified, scope to matching files only
+        let fileFilter = null;
+        if (options.file) {
+            const resolved = this.findFile(options.file);
+            if (resolved) {
+                fileFilter = new Set([resolved]);
+            } else {
+                // Try substring match for partial paths
+                const matching = [];
+                for (const fp of this.files.keys()) {
+                    const rp = path.relative(this.root, fp);
+                    if (rp.includes(options.file) || fp.includes(options.file)) {
+                        matching.push(fp);
+                    }
+                }
+                if (matching.length > 0) {
+                    fileFilter = new Set(matching);
+                } else {
+                    return {
+                        meta: { complete: true, skipped: 0, dynamicImports: 0, uncertain: 0 },
+                        totals: { files: 0, lines: 0, functions: 0, classes: 0, state: 0, testFiles: 0 },
+                        summary: { topFunctionFiles: [], topLineFiles: [], entryFiles: [] },
+                        files: [],
+                        hiddenFiles: 0,
+                        error: `File not found in project: ${options.file}`
+                    };
+                }
+            }
+        }
+
         for (const [filePath, fileEntry] of this.files) {
+            if (fileFilter && !fileFilter.has(filePath)) continue;
             let functions = fileEntry.symbols.filter(s =>
                 s.type === 'function' || s.type === 'method' || s.type === 'static' ||
                 s.type === 'constructor' || s.type === 'public' || s.type === 'abstract'

package/core/verify.js

@@ -482,7 +482,23 @@ function plan(index, name, options = {}) {
             name: options.addParam,
             ...(options.defaultValue && { default: options.defaultValue })
         };
-        newParams.push(newParam);
+
+        // When adding a required param (no default), insert before the first
+        // optional param to avoid producing invalid signatures in Python/TS
+        // (required params must precede optional ones).
+        if (!options.defaultValue) {
+            const firstOptIdx = newParams.findIndex(p => p.optional || p.default !== undefined);
+            if (firstOptIdx !== -1) {
+                // Also skip self/cls/&self/&mut self at position 0
+                const insertIdx = Math.max(firstOptIdx,
+                    (newParams.length > 0 && ['self', 'cls', '&self', '&mut self'].includes(newParams[0].name)) ? 1 : 0);
+                newParams.splice(insertIdx, 0, newParam);
+            } else {
+                newParams.push(newParam);
+            }
+        } else {
+            newParams.push(newParam);
+        }
 
         // Generate new signature
         const paramsList = newParams.map(p => {

package/mcp/server.js

@@ -158,7 +158,7 @@ function requireName(name) {
 // CONSOLIDATED TOOL REGISTRATION
 // ============================================================================
 
-const TOOL_DESCRIPTION = `Universal Code Navigator powered by tree-sitter ASTs. Analyzes code structure — functions, callers, callees, dependencies — across JavaScript/TypeScript, Python, Go, Rust, Java, and HTML (inline scripts and event handlers). Use instead of grep/read for code relationships.
+const TOOL_DESCRIPTION = `Code intelligence toolkit for AI agents. Extract specific functions, trace call chains, find all callers, and detect dead code — without reading entire files or scanning full projects. Use instead of grep/read for code relationships. Supports JavaScript/TypeScript, Python, Go, Rust, Java, and HTML.
 
 TOP 5 (covers 90% of tasks): about, impact, trace, find, deadcode
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "ucn",
-  "version": "3.7.44",
+  "version": "3.7.46",
   "mcpName": "io.github.mleoca/ucn",
-  "description": "Universal Code Navigator — AST-based call graph analysis for AI agents. Find callers, trace impact, detect dead code across JS/TS, Python, Go, Rust, Java, and HTML. CLI, MCP server, and agent skill.",
+  "description": "Code intelligence toolkit for AI agents — extract functions, trace call chains, find callers, detect dead code without reading entire files. Works as MCP server, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java.",
   "main": "index.js",
   "bin": {
     "ucn": "cli/index.js",
@@ -16,28 +16,29 @@
     "mcp",
     "mcp-server",
     "model-context-protocol",
+    "ai-agent",
+    "ai-coding",
+    "code-intelligence",
     "code-navigation",
     "code-analysis",
-    "static-analysis",
+    "code-extraction",
     "call-graph",
     "callers",
     "impact-analysis",
     "dead-code",
     "deadcode",
-    "ast",
-    "tree-sitter",
-    "parser",
-    "skill",
     "agent-skill",
+    "skill",
     "cli",
-    "ai-agent",
+    "tree-sitter",
+    "ast",
+    "static-analysis",
     "javascript",
     "typescript",
     "python",
     "go",
     "rust",
-    "java",
-    "html"
+    "java"
   ],
   "author": "Constantin-Mihail Leoca (https://github.com/mleoca)",
   "repository": {