ucn 3.7.11 → 3.7.12

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

@@ -92,6 +92,7 @@ ucn deadcode --exclude=test         # Skip test files (most useful)
 | Quick project overview | `ucn toc` | Every file with function/class counts and line counts |
 | Find by glob pattern | `ucn find "handle*"` | Locate definitions matching a glob (supports * and ?) |
 | Text search with context | `ucn search term --context=3` | Like grep -C 3, shows surrounding lines |
+| Regex search | `ucn search '\d+' --regex` | Search with regex patterns (alternation, character classes, etc.) |
 | Text search filtered | `ucn search term --exclude=test` | Search only in matching files |
 | Finding all usages (not just calls) | `ucn usages <name>` | Groups into: definitions, calls, imports, type references |
 | Finding sibling/related functions | `ucn related <name>` | Name-based + structural matching (same file, shared deps). Not semantic — best for parse/format pairs |
@@ -126,6 +127,8 @@ ucn [target] <command> [name] [--flags]
 | `--staged` | Analyze staged changes (diff-impact) |
 | `--no-cache` | Force re-index after editing files |
 | `--context=N` | Lines of surrounding context in `usages`/`search` output |
+| `--regex` | Use search term as a regex pattern |
+| `--functions` | Show per-function line counts in `stats` (complexity audit) |
 
 ## Workflow Integration
 

package/.mcpregistry_github_token

@@ -1 +1 @@
-ghu_gwrBjpCa3Gl8WuJxABQ8XOgRdbPfFf36TmIA
+ghu_Jo1ldIUK4d6zLMSctdSV2Jx8UkoXa50x6epI

package/.mcpregistry_registry_token

@@ -1 +1 @@
-{"token":"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtY3AtcmVnaXN0cnkiLCJleHAiOjE3NzE3ODU4MTAsIm5iZiI6MTc3MTc4NTUxMCwiaWF0IjoxNzcxNzg1NTEwLCJhdXRoX21ldGhvZCI6ImdpdGh1Yi1hdCIsImF1dGhfbWV0aG9kX3N1YiI6Im1sZW9jYSIsInBlcm1pc3Npb25zIjpbeyJhY3Rpb24iOiJwdWJsaXNoIiwicmVzb3VyY2UiOiJpby5naXRodWIubWxlb2NhLyoifV19.DW2gbu6Lnoc43CqRsxlhrIy3CQaMxAlLykOfYP3lY08d0FHVmXhg9gUt6qt2G6ihn-G99tA6oOf8tGvxUteeBQ","expires_at":1771785810}
+{"token":"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtY3AtcmVnaXN0cnkiLCJleHAiOjE3NzE5NjQ2MjMsIm5iZiI6MTc3MTk2NDMyMywiaWF0IjoxNzcxOTY0MzIzLCJhdXRoX21ldGhvZCI6ImdpdGh1Yi1hdCIsImF1dGhfbWV0aG9kX3N1YiI6Im1sZW9jYSIsInBlcm1pc3Npb25zIjpbeyJhY3Rpb24iOiJwdWJsaXNoIiwicmVzb3VyY2UiOiJpby5naXRodWIubWxlb2NhLyoifV19.weq7KLw5cAAB7qZpxtU45meX0nLUU1vTiHlzFB5Ecf9OTFtKM63-JSwYBXrr410pdt-7CgW6pV6aGruoIpiIBw","expires_at":1771964623}

package/cli/index.js

@@ -82,7 +82,11 @@ const flags = {
     followSymlinks: !args.includes('--no-follow-symlinks'),
     // Diff-impact options
     base: args.find(a => a.startsWith('--base='))?.split('=')[1] || null,
-    staged: args.includes('--staged')
+    staged: args.includes('--staged'),
+    // Regex search mode
+    regex: args.includes('--regex'),
+    // Stats: per-function line counts
+    functions: args.includes('--functions')
 };
 
 // Handle --file flag with space
@@ -101,7 +105,8 @@ const knownFlags = new Set([
     '--file', '--context', '--exclude', '--not', '--in',
     '--depth', '--direction', '--add-param', '--remove-param', '--rename-to',
     '--default', '--top', '--no-follow-symlinks',
-    '--base', '--staged'
+    '--base', '--staged',
+    '--regex', '--functions'
 ]);
 
 // Handle help flag
@@ -905,7 +910,7 @@ function runProjectCommand(rootDir, command, arg) {
             if (arg.includes(',')) {
                 const fnNames = arg.split(',').map(n => n.trim()).filter(Boolean);
                 for (let i = 0; i < fnNames.length; i++) {
-                    if (i > 0) console.log('');
+                    if (i > 0) console.log('\n' + '═'.repeat(60) + '\n');
                     extractFunctionFromProject(index, fnNames[i]);
                 }
             } else {
@@ -1016,7 +1021,7 @@ function runProjectCommand(rootDir, command, arg) {
         case 'search': {
             requireArg(arg, 'Usage: ucn . search <term>');
             const searchExclude = flags.includeTests ? flags.exclude : addTestExclusions(flags.exclude);
-            const searchResults = index.search(arg, { codeOnly: flags.codeOnly, context: flags.context, caseSensitive: flags.caseSensitive, exclude: searchExclude, in: flags.in });
+            const searchResults = index.search(arg, { codeOnly: flags.codeOnly, context: flags.context, caseSensitive: flags.caseSensitive, exclude: searchExclude, in: flags.in, regex: flags.regex });
             printOutput(searchResults,
                 r => output.formatSearchJson(r, arg),
                 r => output.formatSearch(r, arg)
@@ -1040,8 +1045,11 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'stats': {
-            const stats = index.getStats();
-            printOutput(stats, output.formatStatsJson, output.formatStats);
+            const stats = index.getStats({ functions: flags.functions });
+            printOutput(stats,
+                output.formatStatsJson,
+                r => output.formatStats(r, { top: flags.top })
+            );
             break;
         }
 
@@ -1506,7 +1514,7 @@ function findInGlobFiles(files, name) {
 
 function searchGlobFiles(files, term) {
     const results = [];
-    const regex = new RegExp(escapeRegExp(term), flags.caseSensitive ? '' : 'i');
+    const regex = flags.regex ? new RegExp(term, flags.caseSensitive ? '' : 'i') : new RegExp(escapeRegExp(term), flags.caseSensitive ? '' : 'i');
 
     for (const file of files) {
         try {
@@ -1557,7 +1565,7 @@ function searchGlobFiles(files, term) {
 // ============================================================================
 
 function searchFile(filePath, lines, term) {
-    const regex = new RegExp(escapeRegExp(term), flags.caseSensitive ? '' : 'i');
+    const regex = flags.regex ? new RegExp(term, flags.caseSensitive ? '' : 'i') : new RegExp(escapeRegExp(term), flags.caseSensitive ? '' : 'i');
     const matches = [];
 
     lines.forEach((line, idx) => {
@@ -1686,7 +1694,7 @@ FIND CODE
   find <name>         Find symbol definitions (supports glob: find "handle*")
   usages <name>       All usages grouped: definitions, calls, imports, references
   toc                 Table of contents (compact; --detailed lists all symbols)
-  search <term>       Text search (--context=N, --exclude=, --in=)
+  search <term>       Text search (--context=N, --exclude=, --in=, --regex)
   tests <name>        Find test files for a function
 
 ═══════════════════════════════════════════════════════════════════════════════
@@ -1719,7 +1727,7 @@ OTHER
 ═══════════════════════════════════════════════════════════════════════════════
   api                 Show exported/public symbols
   typedef <name>      Find type definitions
-  stats               Project statistics
+  stats               Project statistics (--functions for per-function line counts)
   stacktrace <text>   Parse stack trace, show code at each frame (alias: stack)
   example <name>      Best usage example with context
 
@@ -1739,6 +1747,8 @@ Common Flags:
   --include-methods   Include method calls (obj.fn) in caller/callee analysis
   --include-uncertain Include ambiguous/uncertain matches
   --include-exported  Include exported symbols in deadcode
+  --regex             Use search term as a regex pattern
+  --functions         Show per-function line counts (stats command)
   --include-decorated Include decorated/annotated symbols in deadcode
   --exact             Exact name match only (find)
   --calls-only        Only show call/test-case matches (tests)
@@ -1898,6 +1908,8 @@ function parseInteractiveFlags(tokens) {
         base: tokens.find(a => a.startsWith('--base='))?.split('=')[1] || null,
         staged: tokens.includes('--staged'),
         maxLines: parseInt(tokens.find(a => a.startsWith('--max-lines='))?.split('=')[1] || '0') || null,
+        regex: tokens.includes('--regex'),
+        functions: tokens.includes('--functions'),
     };
 }
 
@@ -2011,7 +2023,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
             if (arg.includes(',')) {
                 const fnNames = arg.split(',').map(n => n.trim()).filter(Boolean);
                 for (let i = 0; i < fnNames.length; i++) {
-                    if (i > 0) console.log('');
+                    if (i > 0) console.log('\n' + '═'.repeat(60) + '\n');
                     extractFunctionFromProject(index, fnNames[i], iflags);
                 }
             } else {
@@ -2104,7 +2116,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
                 console.log('Usage: search <term>');
                 return;
             }
-            const results = index.search(arg, { codeOnly: iflags.codeOnly, caseSensitive: iflags.caseSensitive, context: iflags.context, exclude: iflags.exclude, in: iflags.in });
+            const results = index.search(arg, { codeOnly: iflags.codeOnly, caseSensitive: iflags.caseSensitive, context: iflags.context, exclude: iflags.exclude, in: iflags.in, regex: iflags.regex });
             console.log(output.formatSearch(results, arg));
             break;
         }
@@ -2136,8 +2148,8 @@ function executeInteractiveCommand(index, command, arg, iflags = {}) {
         }
 
         case 'stats': {
-            const stats = index.getStats();
-            console.log(output.formatStats(stats));
+            const stats = index.getStats({ functions: iflags.functions });
+            console.log(output.formatStats(stats, { top: iflags.top }));
             break;
         }
 

package/core/output.js

@@ -1925,7 +1925,16 @@ function formatGraph(graph, options = {}) {
  */
 function formatSearch(results, term) {
     const totalMatches = results.reduce((sum, r) => sum + r.matches.length, 0);
-    if (totalMatches === 0) return `No matches found for "${term}"`;
+    if (totalMatches === 0) {
+        const meta = results.meta;
+        if (meta) {
+            const scope = meta.filesSkipped > 0
+                ? `Searched ${meta.filesScanned} of ${meta.totalFiles} files (${meta.filesSkipped} excluded by filters).`
+                : `Searched ${meta.filesScanned} files.`;
+            return `No matches found for "${term}". ${scope}`;
+        }
+        return `No matches found for "${term}"`;
+    }
 
     const lines = [];
     lines.push(`Found ${totalMatches} matches for "${term}" in ${results.length} files:`);
@@ -1969,7 +1978,7 @@ function formatFileExports(exports, filePath) {
 /**
  * Format stats command output
  */
-function formatStats(stats) {
+function formatStats(stats, options = {}) {
     const lines = [];
     lines.push('PROJECT STATISTICS');
     lines.push('═'.repeat(60));
@@ -1988,6 +1997,19 @@ function formatStats(stats) {
         lines.push(`  ${type}: ${count}`);
     }
 
+    if (stats.functions) {
+        const top = options.top || 30;
+        const shown = stats.functions.slice(0, top);
+        lines.push(`\nFunctions by line count (top ${shown.length} of ${stats.functions.length}):`);
+        for (const fn of shown) {
+            const loc = `${fn.file}:${fn.startLine}`;
+            lines.push(`  ${String(fn.lines).padStart(5)} lines  ${fn.name}  (${loc})`);
+        }
+        if (stats.functions.length > top) {
+            lines.push(`  ... ${stats.functions.length - top} more (use --top=N to show more)`);
+        }
+    }
+
     return lines.join('\n');
 }
 

package/core/project.js

@@ -4439,17 +4439,20 @@ class ProjectIndex {
         this._beginOp();
         try {
         const results = [];
-        // Escape the term to handle special regex characters
+        let filesScanned = 0;
+        let filesSkipped = 0;
         const regexFlags = options.caseSensitive ? 'g' : 'gi';
-        const regex = new RegExp(escapeRegExp(term), regexFlags);
+        const regex = options.regex ? new RegExp(term, regexFlags) : new RegExp(escapeRegExp(term), regexFlags);
 
         for (const [filePath, fileEntry] of this.files) {
             // Apply exclude/in filters
             if ((options.exclude && options.exclude.length > 0) || options.in) {
                 if (!this.matchesFilters(fileEntry.relativePath, { exclude: options.exclude, in: options.in })) {
+                    filesSkipped++;
                     continue;
                 }
             }
+            filesScanned++;
             try {
                 const content = this._readFile(filePath);
                 const lines = content.split('\n');
@@ -4462,7 +4465,7 @@ class ProjectIndex {
                         try {
                             const parser = getParser(language);
                             const { findMatchesWithASTFilter } = require('../languages/utils');
-                            const astMatches = findMatchesWithASTFilter(content, term, parser, { codeOnly: true });
+                            const astMatches = findMatchesWithASTFilter(content, term, parser, { codeOnly: true, regex: options.regex });
 
                             for (const m of astMatches) {
                                 const match = {
@@ -4542,6 +4545,7 @@ class ProjectIndex {
             }
         }
 
+        results.meta = { filesScanned, filesSkipped, totalFiles: this.files.size };
         return results;
         } finally { this._endOp(); }
     }
@@ -4553,7 +4557,7 @@ class ProjectIndex {
     /**
      * Get project statistics
      */
-    getStats() {
+    getStats(options = {}) {
         // Count total symbols (not just unique names)
         let totalSymbols = 0;
         for (const [name, symbols] of this.symbols) {
@@ -4588,6 +4592,27 @@ class ProjectIndex {
             }
         }
 
+        // Per-function line counts for complexity audits
+        if (options.functions) {
+            const functions = [];
+            for (const [name, symbols] of this.symbols) {
+                for (const sym of symbols) {
+                    if (sym.type === 'function' || sym.params !== undefined) {
+                        const lineCount = sym.endLine - sym.startLine + 1;
+                        const relativePath = sym.relativePath || (sym.file ? path.relative(this.root, sym.file) : '');
+                        functions.push({
+                            name: sym.className ? `${sym.className}.${sym.name}` : sym.name,
+                            file: relativePath,
+                            startLine: sym.startLine,
+                            lines: lineCount
+                        });
+                    }
+                }
+            }
+            functions.sort((a, b) => b.lines - a.lines);
+            stats.functions = functions;
+        }
+
         return stats;
     }
 

package/languages/utils.js

@@ -417,9 +417,8 @@ function findMatchesWithASTFilter(content, term, parser, options = {}) {
     const lines = content.split('\n');
     const matches = [];
 
-    // Escape special regex characters and create pattern
-    const escapedTerm = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const regex = new RegExp(escapedTerm, 'gi');
+    // Create search pattern — use raw regex when regex mode is enabled
+    const regex = options.regex ? new RegExp(term, 'gi') : new RegExp(term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
 
     lines.forEach((line, idx) => {
         const lineNum = idx + 1;

package/mcp/server.js

@@ -196,7 +196,7 @@ FINDING CODE:
 - find <name>: Locate definitions ranked by usage count. Supports glob patterns (e.g. find "handle*" or "_update*"). Use when you know the name but not the file.
 - usages <name>: See every usage organized by type: definitions, calls, imports, references. Complete picture of how something is used. Use code_only=true to skip comments/strings.
 - toc: Get a quick overview of a project you haven't seen before — file counts, line counts, function/class counts, entry points. Use detailed=true for full symbol listing.
-- search <term>: Plain text search (like grep, respects .gitignore). Supports context=N for surrounding lines, exclude/in for file filtering. Case-insensitive by default; set case_sensitive=true for exact case.
+- search <term>: Text search (like grep, respects .gitignore). Supports context=N for surrounding lines, exclude/in for file filtering. Case-insensitive by default; set case_sensitive=true for exact case. Set regex=true to use the term as a regex pattern (e.g. "\\d+" or "foo|bar").
 - tests <name>: Find test files covering a function, test case names, and how it's called in tests. Use before modifying or to find test patterns to follow.
 - deadcode: Find dead code: functions/classes with zero callers. Use during cleanup to identify safely deletable code. Excludes exported, decorated, and test symbols by default — use include_exported/include_decorated/include_tests to expand.
 
@@ -221,7 +221,7 @@ OTHER:
 - typedef <name>: Find type definitions matching a name: interfaces, enums, structs, traits, type aliases. See field shapes, required methods, or enum values.
 - stacktrace: Parse a stack trace, show source context per frame. Requires stack param. Handles JS, Python, Go, Rust, Java formats.
 - api: Public API surface of project or file: all exported/public symbols with signatures. Use to understand what a library exposes. Pass file to scope to one file. Python needs __all__; use toc instead.
-- stats: Quick project stats: file counts, symbol counts, lines of code by language and symbol type.`;
+- stats: Quick project stats: file counts, symbol counts, lines of code by language and symbol type. Use functions=true for per-function line counts sorted by size (complexity audit).`;
 
 server.registerTool(
     'ucn',
@@ -256,7 +256,9 @@ server.registerTool(
             calls_only: z.boolean().optional().describe('Only direct calls and test-case matches (tests command)'),
             max_lines: z.number().optional().describe('Max source lines for class (large classes show summary by default)'),
             direction: z.enum(['imports', 'importers', 'both']).optional().describe('Graph direction: imports (what this file uses), importers (who uses this file), both (default: both)'),
-            term: z.string().optional().describe('Search term (plain text, not regex)'),
+            term: z.string().optional().describe('Search term (plain text by default; set regex=true to use as regex pattern)'),
+            regex: z.boolean().optional().describe('Treat search term as a regex pattern (default: false, plain text)'),
+            functions: z.boolean().optional().describe('Include per-function line counts in stats output, sorted by size (complexity audit)'),
             add_param: z.string().optional().describe('Parameter name to add (plan command)'),
             remove_param: z.string().optional().describe('Parameter name to remove (plan command)'),
             rename_to: z.string().optional().describe('New function name (plan command)'),
@@ -276,7 +278,7 @@ server.registerTool(
                 include_exported, include_decorated, calls_only, max_lines,
                 direction, term, add_param, remove_param, rename_to,
                 default_value, stack, item, range, base, staged,
-                case_sensitive } = args;
+                case_sensitive, regex, functions } = args;
 
         try {
             switch (command) {
@@ -431,7 +433,8 @@ server.registerTool(
                     context: ctxLines || 0,
                     caseSensitive: case_sensitive || false,
                     exclude: searchExclude,
-                    in: inPath || undefined
+                    in: inPath || undefined,
+                    regex: regex || false
                 });
                 return toolResult(output.formatSearch(result, term));
             }
@@ -495,7 +498,8 @@ server.registerTool(
                     parts.push(note + output.formatFn(match, fnCode));
                 }
 
-                return toolResult(parts.join('\n\n'));
+                const separator = fnNames.length > 1 ? '\n\n' + '═'.repeat(60) + '\n\n' : '\n\n';
+                return toolResult(parts.join(separator));
             }
 
             case 'class': {
@@ -805,8 +809,8 @@ server.registerTool(
 
             case 'stats': {
                 const index = getIndex(project_dir);
-                const stats = index.getStats();
-                return toolResult(output.formatStats(stats));
+                const stats = index.getStats({ functions: functions || false });
+                return toolResult(output.formatStats(stats, { top: top || 30 }));
             }
 
             default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.7.11",
+  "version": "3.7.12",
   "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.",
   "main": "index.js",