ucn 3.7.45 → 3.7.47

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
@@ -145,6 +145,8 @@ ucn [target] <command> [name] [--flags]
 | `--detailed` | Show full symbol listing per file in `toc` |
 | `--top-level` | Show only top-level functions in `toc` (exclude nested/indented) |
 | `--top=N` | Limit result count (default: 10 for most commands) |
+| `--limit=N` | Limit result count for `find`, `usages`, `search`, `deadcode`, `api`, `toc` |
+| `--max-files=N` | Max files to index (for large projects with 10K+ files) |
 | `--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) |
@@ -164,7 +166,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/cli/index.js

@@ -102,6 +102,8 @@ function parseFlags(tokens) {
         regex: tokens.includes('--no-regex') ? false : undefined,
         functions: tokens.includes('--functions'),
         className: getValueFlag('--class-name'),
+        limit: parseInt(getValueFlag('--limit') || '0') || undefined,
+        maxFiles: parseInt(getValueFlag('--max-files') || '0') || undefined,
     };
 }
 
@@ -126,7 +128,7 @@ const knownFlags = new Set([
     '--default', '--top', '--no-follow-symlinks',
     '--base', '--staged', '--stack',
     '--regex', '--no-regex', '--functions',
-    '--max-lines', '--class-name'
+    '--max-lines', '--class-name', '--limit', '--max-files'
 ]);
 
 // Handle help flag
@@ -396,7 +398,7 @@ function runProjectCommand(rootDir, command, arg) {
     // If cache was loaded but stale, force rebuild to avoid duplicates
     let needsCacheSave = false;
     if (!usedCache) {
-        index.build(null, { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks });
+        index.build(null, { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, maxFiles: flags.maxFiles });
         needsCacheSave = flags.cache;
     }
 
@@ -408,8 +410,9 @@ function runProjectCommand(rootDir, command, arg) {
         // ── Commands using shared executor ───────────────────────────────
 
         case 'toc': {
-            const { ok, result, error } = execute(index, 'toc', flags);
+            const { ok, result, error, note } = execute(index, 'toc', flags);
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result, output.formatTocJson, r => output.formatToc(r, {
                 detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol',
                 uncertainHint: 'use --include-uncertain to include all'
@@ -429,8 +432,9 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'usages': {
-            const { ok, result, error } = execute(index, 'usages', { name: arg, ...flags });
+            const { ok, result, error, note } = execute(index, 'usages', { name: arg, ...flags });
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result,
                 r => output.formatUsagesJson(r, arg),
                 r => output.formatUsages(r, arg)
@@ -665,8 +669,9 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'api': {
-            const { ok, result, error } = execute(index, 'api', { file: arg });
+            const { ok, result, error, note } = execute(index, 'api', { file: arg || flags.file, limit: flags.limit });
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result,
                 r => output.formatApiJson(r, arg),
                 r => output.formatApi(r, arg)
@@ -685,8 +690,9 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'deadcode': {
-            const { ok, result, error } = execute(index, 'deadcode', { ...flags, in: flags.in || subdirScope });
+            const { ok, result, error, note } = execute(index, 'deadcode', { ...flags, in: flags.in || subdirScope });
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result,
                 output.formatDeadcodeJson,
                 r => output.formatDeadcode(r, {
@@ -1040,6 +1046,8 @@ Common Flags:
   --direction=X       Graph direction: imports, importers, or both (default: both)
   --all               Expand truncated sections (about, trace, graph, related)
   --top=N             Limit results (find, deadcode)
+  --limit=N           Limit result count (find, usages, search, deadcode, api, toc)
+  --max-files=N       Max files to index (large projects)
   --context=N         Lines of context around matches
   --json              Machine-readable output
   --code-only         Filter out comments and strings

package/core/cache.js

@@ -30,10 +30,10 @@ function saveCache(index, cachePath) {
 
     const cacheFile = cachePath || path.join(cacheDir, 'index.json');
 
-    // Prepare callsCache for serialization (exclude content to save space)
+    // Prepare callsCache for serialization (exclude content, use relative paths)
     const callsCacheData = [];
     for (const [filePath, entry] of index.callsCache) {
-        callsCacheData.push([filePath, {
+        callsCacheData.push([path.relative(index.root, filePath), {
             mtime: entry.mtime,
             hash: entry.hash,
             calls: entry.calls
@@ -41,23 +41,71 @@ function saveCache(index, cachePath) {
         }]);
     }
 
+    // Hash config to detect when graph rebuild is needed on load
+    const configHash = crypto.createHash('md5')
+        .update(JSON.stringify(index.config || {})).digest('hex');
+
+    // Strip redundant fields from symbols and file entries to reduce cache size.
+    // v6: All paths stored as relative paths (saves ~60% on large codebases).
+    // symbol.file = path.join(root, symbol.relativePath) — reconstructable
+    // symbol.bindingId = relativePath:type:startLine — reconstructable
+    // fileEntry.path = Map key — redundant
+    // fileEntry.relativePath = now the Map key — redundant
+    const root = index.root;
+    const strippedSymbols = [];
+    for (const [name, defs] of index.symbols) {
+        const stripped = defs.map(s => {
+            const { file, bindingId, ...rest } = s;
+            return rest;
+        });
+        strippedSymbols.push([name, stripped]);
+    }
+    // Files: use relativePath as key, strip path, relativePath, symbols, and bindings from entries.
+    // symbols/bindings are already stored in the top-level symbols map — no need to duplicate.
+    const strippedFiles = [];
+    for (const [, entry] of index.files) {
+        const { path: _p, relativePath: rp, symbols: _s, bindings: _b, ...rest } = entry;
+        strippedFiles.push([rp, rest]);
+    }
+
+    // Convert graph paths from absolute to relative
+    const relGraph = (graph) => {
+        const result = [];
+        for (const [absKey, absValues] of graph) {
+            const relKey = path.relative(root, absKey);
+            const relValues = absValues.map(v => path.relative(root, v));
+            result.push([relKey, relValues]);
+        }
+        return result;
+    };
+
     const cacheData = {
-        version: 4,  // v4: className, memberType, isMethod for all languages
+        version: 7,  // v7: strip symbols/bindings from file entries (dedup ~45% cache reduction)
         ucnVersion: UCN_VERSION,  // Invalidate cache when UCN is updated
-        root: index.root,
+        configHash,
+        root,
         buildTime: index.buildTime,
         timestamp: Date.now(),
-        files: Array.from(index.files.entries()),
-        symbols: Array.from(index.symbols.entries()),
-        importGraph: Array.from(index.importGraph.entries()),
-        exportGraph: Array.from(index.exportGraph.entries()),
+        files: strippedFiles,
+        symbols: strippedSymbols,
+        importGraph: relGraph(index.importGraph),
+        exportGraph: relGraph(index.exportGraph),
+        // extendsGraph/extendedByGraph use class names as keys (not file paths)
         extendsGraph: Array.from(index.extendsGraph.entries()),
         extendedByGraph: Array.from(index.extendedByGraph.entries()),
-        callsCache: callsCacheData,
-        failedFiles: index.failedFiles ? Array.from(index.failedFiles) : []
+        failedFiles: index.failedFiles
+            ? Array.from(index.failedFiles).map(f => path.relative(root, f))
+            : []
     };
 
     fs.writeFileSync(cacheFile, JSON.stringify(cacheData));
+
+    // Save callsCache to a separate file (lazy-loaded on demand)
+    if (callsCacheData.length > 0) {
+        const callsCacheFile = path.join(path.dirname(cacheFile), 'calls-cache.json');
+        fs.writeFileSync(callsCacheFile, JSON.stringify(callsCacheData));
+    }
+
     return cacheFile;
 }
 
@@ -78,9 +126,8 @@ function loadCache(index, cachePath) {
         const cacheData = JSON.parse(fs.readFileSync(cacheFile, 'utf-8'));
 
         // Check version compatibility
-        // v4 adds className, memberType, isMethod for all languages
-        // Only accept exactly version 4 (or future versions handled explicitly)
-        if (cacheData.version !== 4) {
+        // v7: symbols/bindings stripped from file entries (dedup)
+        if (cacheData.version !== 7) {
             return false;
         }
 
@@ -97,13 +144,57 @@ function loadCache(index, cachePath) {
             return false;
         }
 
-        index.files = new Map(cacheData.files);
+        const root = cacheData.root || index.root;
+
+        // Reconstruct files Map: relative key → absolute key, restore path and relativePath
+        // Initialize symbols/bindings arrays (will be populated from top-level symbols)
+        index.files = new Map();
+        for (const [relPath, entry] of cacheData.files) {
+            const absPath = path.join(root, relPath);
+            entry.path = absPath;
+            entry.relativePath = relPath;
+            if (!entry.symbols) entry.symbols = [];
+            if (!entry.bindings) entry.bindings = [];
+            index.files.set(absPath, entry);
+        }
+
+        // Reconstruct symbols: restore file and bindingId from relativePath
+        // Also rebuild fileEntry.symbols and fileEntry.bindings from top-level data
         index.symbols = new Map(cacheData.symbols);
-        index.importGraph = new Map(cacheData.importGraph);
-        index.exportGraph = new Map(cacheData.exportGraph);
+        for (const [, defs] of index.symbols) {
+            for (const s of defs) {
+                if (!s.file && s.relativePath) s.file = path.join(root, s.relativePath);
+                if (!s.bindingId && s.relativePath && s.type && s.startLine) {
+                    s.bindingId = `${s.relativePath}:${s.type}:${s.startLine}`;
+                }
+                // Rebuild fileEntry.symbols and bindings from top-level symbols
+                const fileEntry = index.files.get(s.file);
+                if (fileEntry) {
+                    fileEntry.symbols.push(s);
+                    fileEntry.bindings.push({
+                        id: s.bindingId,
+                        name: s.name,
+                        type: s.type,
+                        startLine: s.startLine
+                    });
+                }
+            }
+        }
+
+        // Reconstruct graphs: relative paths → absolute paths
+        const absGraph = (data) => {
+            const m = new Map();
+            for (const [relKey, relValues] of data) {
+                m.set(path.join(root, relKey), relValues.map(v => path.join(root, v)));
+            }
+            return m;
+        };
+        index.importGraph = absGraph(cacheData.importGraph);
+        index.exportGraph = absGraph(cacheData.exportGraph);
         index.buildTime = cacheData.buildTime;
 
         // Restore optional graphs if present
+        // extendsGraph/extendedByGraph use class names as keys (not file paths)
         if (Array.isArray(cacheData.extendsGraph)) {
             index.extendsGraph = new Map(cacheData.extendsGraph);
         }
@@ -111,19 +202,26 @@ function loadCache(index, cachePath) {
             index.extendedByGraph = new Map(cacheData.extendedByGraph);
         }
 
-        // Restore callsCache if present (v2+)
-        if (Array.isArray(cacheData.callsCache)) {
-            index.callsCache = new Map(cacheData.callsCache);
+        // Eagerly load callsCache from separate file.
+        // Prevents 10K cold tree-sitter re-parses (2GB+ peak) when findCallers runs.
+        if (index.callsCache.size === 0) {
+            loadCallsCache(index);
         }
 
-        // Restore failedFiles if present
+        // Restore failedFiles if present (convert relative paths back to absolute)
         if (Array.isArray(cacheData.failedFiles)) {
-            index.failedFiles = new Set(cacheData.failedFiles);
+            index.failedFiles = new Set(
+                cacheData.failedFiles.map(f => path.isAbsolute(f) ? f : path.join(root, f))
+            );
         }
 
-        // Rebuild derived graphs to ensure consistency with current config
-        index.buildImportGraph();
-        index.buildInheritanceGraph();
+        // Only rebuild graphs if config changed (e.g., aliases modified)
+        const currentConfigHash = crypto.createHash('md5')
+            .update(JSON.stringify(index.config || {})).digest('hex');
+        if (currentConfigHash !== cacheData.configHash) {
+            index.buildImportGraph();
+            index.buildInheritanceGraph();
+        }
 
         return true;
     } catch (e) {
@@ -137,32 +235,9 @@ function loadCache(index, cachePath) {
  * @returns {boolean} - True if cache needs rebuilding
  */
 function isCacheStale(index) {
-    // Check for new files added to project
-    // Use same ignores as build() — .gitignore + .ucn.json exclude
-    const pattern = detectProjectPattern(index.root);
-    const globOpts = { root: index.root };
-    const gitignorePatterns = parseGitignore(index.root);
-    const configExclude = index.config.exclude || [];
-    if (gitignorePatterns.length > 0 || configExclude.length > 0) {
-        globOpts.ignores = [...DEFAULT_IGNORES, ...gitignorePatterns, ...configExclude];
-    }
-    const currentFiles = expandGlob(pattern, globOpts);
-    const cachedPaths = new Set(index.files.keys());
-
-    for (const file of currentFiles) {
-        if (!cachedPaths.has(file) && !(index.failedFiles && index.failedFiles.has(file))) {
-            return true; // New file found
-        }
-    }
-
-    // Check existing cached files for modifications/deletions
+    // Fast path: check cached files for modifications/deletions first (stat-only).
+    // This returns early without the expensive directory walk when any file changed.
     for (const [filePath, fileEntry] of index.files) {
-        // File deleted
-        if (!fs.existsSync(filePath)) {
-            return true;
-        }
-
-        // File modified - check size first, then mtime, then hash
         try {
             const stat = fs.statSync(filePath);
 
@@ -183,11 +258,61 @@ function isCacheStale(index) {
                 return true;
             }
         } catch (e) {
-            return true;
+            return true; // File deleted or inaccessible
+        }
+    }
+
+    // Slow path: glob the project to detect new files added since last build.
+    // Only reached when all cached files are unchanged.
+    const pattern = detectProjectPattern(index.root);
+    const globOpts = { root: index.root };
+    const gitignorePatterns = parseGitignore(index.root);
+    const configExclude = index.config.exclude || [];
+    if (gitignorePatterns.length > 0 || configExclude.length > 0) {
+        globOpts.ignores = [...DEFAULT_IGNORES, ...gitignorePatterns, ...configExclude];
+    }
+    const currentFiles = expandGlob(pattern, globOpts);
+    const cachedPaths = new Set(index.files.keys());
+
+    for (const file of currentFiles) {
+        if (!cachedPaths.has(file) && !(index.failedFiles && index.failedFiles.has(file))) {
+            return true; // New file found
         }
     }
 
     return false;
 }
 
-module.exports = { saveCache, loadCache, isCacheStale };
+/**
+ * Load callsCache from separate file on demand.
+ * Only loads if callsCache is empty (not already populated from inline or prior load).
+ * @param {object} index - ProjectIndex instance
+ * @returns {boolean} - True if loaded successfully
+ */
+function loadCallsCache(index) {
+    if (index.callsCache.size > 0) return true; // Already populated
+    if (index._callsCacheLoaded) return false;   // Already attempted, file didn't exist
+    index._callsCacheLoaded = true;
+
+    const callsCacheFile = path.join(index.root, '.ucn-cache', 'calls-cache.json');
+    if (!fs.existsSync(callsCacheFile)) return false;
+
+    try {
+        const data = JSON.parse(fs.readFileSync(callsCacheFile, 'utf-8'));
+        if (Array.isArray(data)) {
+            // Convert relative paths back to absolute
+            const absData = data.map(([relPath, entry]) => {
+                // Handle both relative (v6+) and absolute (legacy) paths
+                const absPath = path.isAbsolute(relPath) ? relPath : path.join(index.root, relPath);
+                return [absPath, entry];
+            });
+            index.callsCache = new Map(absData);
+            return true;
+        }
+    } catch (e) {
+        // Corrupted file — ignore
+    }
+    return false;
+}
+
+module.exports = { saveCache, loadCache, loadCallsCache, isCacheStale };