ucn 3.8.16 → 3.8.18

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

@@ -157,11 +157,11 @@ ucn [target] <command> [name] [--flags]
 
 | Flag | When to use it |
 |------|---------------|
-| `--class-name=X` | Scope to specific class (e.g., `--class-name=Repository` for method `save`) |
+| `--class-name=X` | Scope to specific class (e.g., `--class-name=Repository` for method `save`). Works with `fn`, `about`, `context`, `impact`, `tests`, `example`, `typedef`, `verify`, `plan` |
 | `--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). Also expands all children — no breadth limit |
+| `--depth=N` | Control tree depth for `trace`, `graph`, and detail level for `find` (default 3). Also expands all children — no breadth limit |
 | `--all` | Expand truncated sections in `about`, `trace`, `graph`, `related` |
 | `--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) |

package/cli/index.js

@@ -10,11 +10,10 @@
 const fs = require('fs');
 const path = require('path');
 
-const { parseFile, detectLanguage } = require('../core/parser');
+const { detectLanguage } = require('../core/parser');
 const { ProjectIndex } = require('../core/project');
 const { expandGlob, findProjectRoot } = require('../core/discovery');
 const output = require('../core/output');
-const { escapeRegExp } = require('../core/shared');
 const { getCliCommandSet, resolveCommand, FLAG_APPLICABILITY, toCliName } = require('../core/registry');
 const { execute } = require('../core/execute');
 const { ExpandCache } = require('../core/expand-cache');
@@ -658,7 +657,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'class': {
             requireArg(arg, 'Usage: ucn . class <name>');
-            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: flags.file, all: flags.all, maxLines: flags.maxLines, className: flags.className });
+            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: flags.file, all: flags.all, maxLines: flags.maxLines });
             if (!ok) fail(error);
             if (note) console.error(note);
             printOutput(result, output.formatClassResultJson, output.formatClassResult);
@@ -703,7 +702,7 @@ function runProjectCommand(rootDir, command, arg) {
             const { ok, result, error } = execute(index, 'fileExports', { file: filePath });
             if (!ok) fail(error);
             printOutput(result,
-                output.formatFileExportsJson,
+                r => output.formatFileExportsJson(r, filePath),
                 r => output.formatFileExports(r, filePath)
             );
             break;
@@ -904,164 +903,85 @@ function runGlobCommand(pattern, command, arg) {
         process.exit(1);
     }
 
-    switch (command) {
-        case 'toc': {
-            let totalFunctions = 0;
-            let totalClasses = 0;
-            let totalState = 0;
-            let totalLines = 0;
-            const byFile = [];
-
-            for (const file of files) {
-                try {
-                    const result = parseFile(file);
-                    let functions = result.functions;
-                    if (flags.topLevel) {
-                        functions = functions.filter(fn => !fn.isNested && (!fn.indent || fn.indent === 0));
-                    }
-                    totalFunctions += functions.length;
-                    totalClasses += result.classes.length;
-                    totalState += result.stateObjects.length;
-                    totalLines += result.totalLines;
-                    byFile.push({
-                        file,
-                        language: result.language,
-                        lines: result.totalLines,
-                        functions,
-                        classes: result.classes,
-                        state: result.stateObjects
-                    });
-                } catch (e) {
-                    // Skip unparseable files
-                }
-            }
-
-            // Convert glob toc to shared formatter format
-            const toc = {
-                totals: { files: files.length, lines: totalLines, functions: totalFunctions, classes: totalClasses, state: totalState },
-                files: byFile.map(f => ({
-                    file: f.file,
-                    lines: f.lines,
-                    functions: f.functions.length,
-                    classes: f.classes.length,
-                    state: f.stateObjects ? f.stateObjects.length : (f.state ? f.state.length : 0)
-                })),
-                meta: {}
-            };
-            if (flags.json) {
-                console.log(output.formatTocJson(toc));
-            } else {
-                console.log(output.formatToc(toc, {
-                    detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol'
-                }));
-            }
-            break;
-        }
-
-        case 'find':
-            if (!arg) {
-                console.error('Usage: ucn "pattern" find <name>');
-                process.exit(1);
-            }
-            findInGlobFiles(files, arg);
-            break;
+    const canonical = resolveCommand(command, 'cli') || command;
 
-        case 'search':
-            if (!arg) {
-                console.error('Usage: ucn "pattern" search <term>');
-                process.exit(1);
-            }
-            searchGlobFiles(files, arg);
-            break;
+    // Build a temporary index over the matched files and route through execute().
+    // This gives glob mode the same semantics as project mode: test exclusions,
+    // limit, all flags — no bespoke logic, no parity drift.
+    const rootDir = findProjectRoot(path.dirname(files[0]));
+    const index = new ProjectIndex(rootDir);
+    index.build(files, { quiet: true });
 
-        default:
-            console.error(`Command "${command}" not supported in glob mode`);
-            process.exit(1);
+    // Supported commands — anything that works with an index
+    const supportedGlobCommands = new Set(['toc', 'find', 'search', 'fn', 'class', 'usages', 'deadcode', 'typedef', 'stats']);
+    if (!supportedGlobCommands.has(canonical)) {
+        console.error(`Command "${command}" not supported in glob mode. Supported: ${[...supportedGlobCommands].join(', ')}`);
+        process.exit(1);
     }
-}
-
-function findInGlobFiles(files, name) {
-    const allMatches = [];
-    const lowerName = name.toLowerCase();
-
-    for (const file of files) {
-        try {
-            const result = parseFile(file);
-
-            for (const fn of result.functions) {
-                if (flags.exact ? fn.name === name : fn.name.toLowerCase().includes(lowerName)) {
-                    allMatches.push({ ...fn, type: 'function', relativePath: file });
-                }
-            }
 
-            for (const cls of result.classes) {
-                if (flags.exact ? cls.name === name : cls.name.toLowerCase().includes(lowerName)) {
-                    allMatches.push({ ...cls, relativePath: file });
-                }
-            }
-        } catch (e) {
-            // Skip
+    // Build params — same as project mode
+    const params = {};
+    if (['find', 'usages', 'fn', 'class', 'typedef'].includes(canonical)) {
+        if (!arg) {
+            console.error(`Usage: ucn "pattern" ${command} <name>`);
+            process.exit(1);
         }
+        params.name = arg;
     }
-
-    if (flags.json) {
-        console.log(output.formatSymbolJson(allMatches, name));
-    } else {
-        console.log(output.formatFindDetailed(allMatches, name, { depth: flags.depth, top: flags.top, all: flags.all }));
-    }
-}
-
-function searchGlobFiles(files, term) {
-    const results = [];
-    const useRegex = flags.regex !== false; // Default: regex ON
-    let regex;
-    if (useRegex) {
-        try { regex = new RegExp(term, flags.caseSensitive ? '' : 'i'); } catch (e) { regex = new RegExp(escapeRegExp(term), flags.caseSensitive ? '' : 'i'); }
-    } else {
-        regex = new RegExp(escapeRegExp(term), flags.caseSensitive ? '' : 'i');
+    if (canonical === 'search') {
+        if (!arg && !flags.type) {
+            console.error('Usage: ucn "pattern" search <term>');
+            process.exit(1);
+        }
+        params.term = arg;
     }
+    Object.assign(params, flags);
 
-    for (const file of files) {
-        try {
-            const content = fs.readFileSync(file, 'utf-8');
-            const lines = content.split('\n');
-            const matches = [];
-
-            lines.forEach((line, idx) => {
-                if (regex.test(line)) {
-                    if (flags.codeOnly && isCommentOrString(line)) {
-                        return;
-                    }
-
-                    const match = { line: idx + 1, content: line };
-
-                    if (flags.context > 0) {
-                        const before = [];
-                        const after = [];
-                        for (let i = 1; i <= flags.context; i++) {
-                            if (idx - i >= 0) before.unshift(lines[idx - i]);
-                            if (idx + i < lines.length) after.push(lines[idx + i]);
-                        }
-                        match.before = before;
-                        match.after = after;
-                    }
-
-                    matches.push(match);
-                }
-            });
+    const { ok, result, error, note, structural } = execute(index, canonical, params);
+    if (!ok) fail(error);
+    if (note) console.error(note);
 
-            if (matches.length > 0) {
-                results.push({ file, matches });
+    // Format output — same formatters as project mode
+    switch (canonical) {
+        case 'toc':
+            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'
+            }));
+            break;
+        case 'find':
+            printOutput(result,
+                r => output.formatSymbolJson(r, arg),
+                r => output.formatFindDetailed(r, arg, { depth: flags.depth, top: flags.top, all: flags.all })
+            );
+            break;
+        case 'search':
+            if (structural) {
+                printOutput(result, output.formatStructuralSearchJson, output.formatStructuralSearch);
+            } else {
+                printOutput(result,
+                    r => output.formatSearchJson(r, arg),
+                    r => output.formatSearch(r, arg)
+                );
             }
-        } catch (e) {
-            // Skip
-        }
-    }
-
-    if (flags.json) {
-        console.log(output.formatSearchJson(results, term));
-    } else {
-        console.log(output.formatSearch(results, term));
+            break;
+        case 'fn':
+            printOutput(result, output.formatFnResultJson, output.formatFnResult);
+            break;
+        case 'class':
+            printOutput(result, output.formatClassResultJson, output.formatClassResult);
+            break;
+        case 'usages':
+            printOutput(result, r => output.formatUsagesJson(r, arg), r => output.formatUsages(r, arg));
+            break;
+        case 'deadcode':
+            printOutput(result, output.formatDeadcodeJson, r => output.formatDeadcode(r, { top: flags.top }));
+            break;
+        case 'typedef':
+            printOutput(result, r => output.formatTypedefJson(r, arg), r => output.formatTypedef(r, arg));
+            break;
+        case 'stats':
+            printOutput(result, output.formatStatsJson, r => output.formatStats(r, { top: flags.top }));
+            break;
     }
 }
 
@@ -1069,13 +989,6 @@ function searchGlobFiles(files, term) {
 // HELPERS
 // ============================================================================
 
-function isCommentOrString(line) {
-    const trimmed = line.trim();
-    return trimmed.startsWith('//') ||
-        trimmed.startsWith('#') ||
-        trimmed.startsWith('*') ||
-        trimmed.startsWith('/*');
-}
 
 function printUsage() {
     console.log(`UCN - Universal Code Navigator

package/core/output/graph.js

@@ -120,14 +120,14 @@ function formatFileExports(exports, filePath) {
     return lines.join('\n');
 }
 
-function formatFileExportsJson(result) {
+function formatFileExportsJson(result, filePath) {
     if (!result) return JSON.stringify({ found: false });
+    // result is an array of exported symbols from index.fileExports()
     return JSON.stringify({
-        meta: { command: 'fileExports', file: result.file },
+        meta: { command: 'fileExports', file: filePath || (Array.isArray(result) ? result[0]?.file : result.file) },
         data: {
-            file: result.file,
-            exports: result.exports || [],
-            reExports: result.reExports || [],
+            file: filePath || (Array.isArray(result) ? result[0]?.file : result.file),
+            exports: Array.isArray(result) ? result : (result.exports || []),
         },
     }, null, 2);
 }

package/core/project.js

@@ -158,28 +158,35 @@ class ProjectIndex {
         const startTime = Date.now();
         const quiet = options.quiet !== false;
 
-        if (!pattern) {
-            pattern = detectProjectPattern(this.root);
-        }
+        // Accept pre-expanded file array (glob mode) or a pattern string
+        let files;
+        if (Array.isArray(pattern)) {
+            files = pattern;
+        } else {
+            if (!pattern) {
+                pattern = detectProjectPattern(this.root);
+            }
 
-        const globOpts = {
-            root: this.root,
-            maxFiles: options.maxFiles || this.config.maxFiles || 50000,
-            followSymlinks: options.followSymlinks
-        };
+            const globOpts = {
+                root: this.root,
+                maxFiles: options.maxFiles || this.config.maxFiles || 50000,
+                followSymlinks: options.followSymlinks
+            };
 
-        // Merge .gitignore and .ucn.json exclude into file discovery
-        const gitignorePatterns = parseGitignore(this.root);
-        const configExclude = this.config.exclude || [];
-        if (gitignorePatterns.length > 0 || configExclude.length > 0) {
-            globOpts.ignores = [...DEFAULT_IGNORES, ...gitignorePatterns, ...configExclude];
-        }
+            // Merge .gitignore and .ucn.json exclude into file discovery
+            const gitignorePatterns = parseGitignore(this.root);
+            const configExclude = this.config.exclude || [];
+            if (gitignorePatterns.length > 0 || configExclude.length > 0) {
+                globOpts.ignores = [...DEFAULT_IGNORES, ...gitignorePatterns, ...configExclude];
+            }
 
-        const files = expandGlob(pattern, globOpts);
+            files = expandGlob(pattern, globOpts);
+        }
 
         // Track if files were truncated by maxFiles limit
-        if (files.length >= globOpts.maxFiles) {
-            this.truncated = { indexed: files.length, maxFiles: globOpts.maxFiles };
+        const maxFiles = options.maxFiles || this.config.maxFiles || 50000;
+        if (!Array.isArray(pattern) && files.length >= maxFiles) {
+            this.truncated = { indexed: files.length, maxFiles };
         } else {
             this.truncated = null;
         }

package/core/registry.js

@@ -116,7 +116,7 @@ const FLAG_APPLICABILITY = {
     entrypoints:  ['file', 'exclude', 'includeTests', 'limit', 'type', 'framework'],
     // Extracting code
     fn:           ['file', 'className', 'all'],
-    class:        ['file', 'className', 'all', 'maxLines'],
+    class:        ['file', 'all', 'maxLines'],
     lines:        ['file', 'range'],
     expand:       [],
     // File dependencies

package/core/search.js

@@ -845,11 +845,15 @@ function tests(index, nameOrFile, options = {}) {
     const callPattern = new RegExp(escapeRegExp(searchTerm) + '\\s*\\(');
     const strPattern = new RegExp("['\"`]" + escapeRegExp(searchTerm) + "['\"`]");
 
-    // When className is provided, build a pattern to scope matches.
-    // We require the test file to also reference the class name (import, instantiation, or receiver).
+    // When className is provided, build patterns for match-level scoping.
     const classNameFilter = options.className
         ? new RegExp('\\b' + escapeRegExp(options.className) + '\\b')
         : null;
+    // Match-level class scoping: for calls, check receiver or nearby context;
+    // e.g., "new ClassName().method()" or "instance.method()" where instance is typed.
+    const classReceiverPattern = options.className
+        ? new RegExp('\\b' + escapeRegExp(options.className) + '\\s*[\\.\\(]')
+        : null;
 
     for (const { path: testPath, entry } of testFiles) {
         try {
@@ -861,6 +865,64 @@ function tests(index, nameOrFile, options = {}) {
             }
 
             const lines = content.split('\n');
+
+            // Build a map of variable names → line ranges where they're bound to the target class.
+            // Tracks reassignment: a variable is only an instance of the target class between
+            // its assignment to that class and any subsequent reassignment to something else.
+            // Pre-compiles receiver regexes for O(1) per-line checks.
+            const instanceVarReceiverRegexes = []; // [{regex, fromLine, toLine}]
+            if (options.className) {
+                const cn = escapeRegExp(options.className);
+                const bindingPattern = new RegExp(
+                    '(?:const|let|var|)\\s+(\\w+)\\s*=\\s*(?:new\\s+' + cn + '|' + cn + '\\.\\w+)\\s*\\(', 'g'
+                );
+                // Also detect reassignment to a DIFFERENT class/value
+                const reassignPattern = /(\w+)\s*=\s*(?:new\s+\w|[^=])/g;
+
+                // First pass: find all bindings to the target class
+                const bindings = []; // [{varName, line}]
+                for (let i = 0; i < lines.length; i++) {
+                    let m;
+                    bindingPattern.lastIndex = 0;
+                    while ((m = bindingPattern.exec(lines[i])) !== null) {
+                        bindings.push({ varName: m[1], line: i });
+                    }
+                }
+
+                // Second pass: for each binding, find where the var is reassigned (scope end)
+                const escapedTerm = escapeRegExp(searchTerm);
+                for (const b of bindings) {
+                    let toLine = lines.length; // default: valid until end of file
+                    for (let i = b.line + 1; i < lines.length; i++) {
+                        // Check if this variable is reassigned to something else
+                        const line = lines[i];
+                        if (new RegExp('\\b' + escapeRegExp(b.varName) + '\\s*=\\s*(?!\\s*=)').test(line)
+                            && !bindingPattern.test(line)) {
+                            toLine = i;
+                            break;
+                        }
+                    }
+                    instanceVarReceiverRegexes.push({
+                        regex: new RegExp('\\b' + escapeRegExp(b.varName) + '\\.' + escapedTerm + '\\s*\\('),
+                        nameRegex: new RegExp('\\b' + escapeRegExp(b.varName) + '\\b'),
+                        fromLine: b.line,
+                        toLine,
+                    });
+                }
+            }
+
+            // Check if a line's receiver is the target class (direct or via bound variable).
+            function lineHasClassReceiver(line, lineIdx) {
+                if (classNameFilter.test(line)) return true;
+                // Check pre-compiled instance variable regexes (scoped to assignment range)
+                for (const entry of instanceVarReceiverRegexes) {
+                    if (lineIdx >= entry.fromLine && lineIdx < entry.toLine) {
+                        if (entry.regex.test(line) || entry.nameRegex.test(line)) return true;
+                    }
+                }
+                return false;
+            }
+
             const matches = [];
 
             lines.forEach((line, idx) => {
@@ -880,6 +942,40 @@ function tests(index, nameOrFile, options = {}) {
                         }
                     }
 
+                    // Match-level className scoping: for call matches,
+                    // the class name or a bound instance variable must appear
+                    // on the same line as the method call.
+                    if (classReceiverPattern && matchType === 'call') {
+                        if (!lineHasClassReceiver(line, idx)) return; // skip — different receiver
+                    }
+
+                    // For reference matches, check same line or ±1 line.
+                    if (classReceiverPattern && matchType === 'reference') {
+                        let classNearby = lineHasClassReceiver(line, idx);
+                        if (!classNearby && idx > 0) classNearby = lineHasClassReceiver(lines[idx - 1], idx - 1);
+                        if (!classNearby && idx + 1 < lines.length) classNearby = lineHasClassReceiver(lines[idx + 1], idx + 1);
+                        if (!classNearby) return; // skip this match
+                    }
+
+                    // For test-case matches with className, keep if the test
+                    // description mentions the class or the test body
+                    // references the class (directly or via bound instance).
+                    if (classNameFilter && matchType === 'test-case') {
+                        let classInContext = classNameFilter.test(line);
+                        if (!classInContext) {
+                            // Look forward into the test body for class usage
+                            for (let d = 1; d <= 5 && !classInContext; d++) {
+                                if (idx + d < lines.length) {
+                                    const bodyLine = lines[idx + d];
+                                    // Stop at next test-case boundary
+                                    if (/\b(describe|it|test|spec)\s*\(/.test(bodyLine)) break;
+                                    if (lineHasClassReceiver(bodyLine, idx + d)) classInContext = true;
+                                }
+                            }
+                        }
+                        if (!classInContext) return; // skip test-case not related to this class
+                    }
+
                     matches.push({
                         line: idx + 1,
                         content: line.trim(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.8.16",
+  "version": "3.8.18",
   "mcpName": "io.github.mleoca/ucn",
   "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",