ucn 3.7.15 → 3.7.17

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

@@ -99,6 +99,12 @@ ucn deadcode --exclude=test         # Skip test files (most useful)
 | Preview a rename or param change | `ucn plan <name> --rename-to=new_name` | Shows what would change without doing it |
 | File-level dependency tree | `ucn graph <file> --depth=1` | Visual import tree. Setting `--depth=N` expands all children. Can be noisy — use depth=1 for large projects. For function-level flow, use `trace` instead |
 | Find which tests cover a function | `ucn tests <name>` | Test files and test function names |
+| Extract specific lines from a file | `ucn lines --file=<file> --range=10-20` | Pull a line range without reading the whole file |
+| Find type definitions | `ucn typedef <name>` | Interfaces, enums, structs, traits, type aliases |
+| See a project's public API | `ucn api` or `ucn api --file=<file>` | All exported/public symbols with signatures |
+| Drill into context results | `ucn expand <N>` | Show source code for item N from a previous `context` call |
+| Best usage example of a function | `ucn example <name>` | Finds and scores the best call site with surrounding context |
+| Debug a stack trace | `ucn stacktrace --stack="<trace>"` | Parses stack frames and shows source context per frame |
 
 ## Command Format
 
@@ -126,9 +132,20 @@ ucn [target] <command> [name] [--flags]
 | `--base=<ref>` | Git ref for diff-impact (default: HEAD) |
 | `--staged` | Analyze staged changes (diff-impact) |
 | `--no-cache` | Force re-index after editing files |
+| `--clear-cache` | Delete cached index entirely before running |
 | `--context=N` | Lines of surrounding context in `usages`/`search` output |
 | `--no-regex` | Force plain text search (regex is default) |
 | `--functions` | Show per-function line counts in `stats` (complexity audit) |
+| `--json` | Machine-readable JSON output (wrapped in `{meta, data}`) |
+| `--code-only` | Exclude matches in comments and strings (`search`/`usages`) |
+| `--with-types` | Include related type definitions in `smart`/`about` output |
+| `--detailed` | Show full symbol listing per file in `toc` |
+| `--top=N` | Limit result count (default: 10 for most commands) |
+| `--case-sensitive` | Case-sensitive text search (default: case-insensitive) |
+| `--exact` | Exact name match only in `find`/`typedef` (no substring) |
+| `--include-uncertain` | Include ambiguous/uncertain matches in `context`/`smart`/`about` |
+| `--include-exported` | Include exported symbols in `deadcode` results |
+| `--include-decorated` | Include decorated/annotated symbols in `deadcode` results |
 
 ## Workflow Integration
 

package/core/output.js

@@ -1920,6 +1920,20 @@ function formatGraph(graph, options = {}) {
     return lines.join('\n');
 }
 
+/**
+ * Detect common double-escaping patterns in regex search terms.
+ * When MCP/JSON transport is involved, agents often write \\.  when they mean \. (literal dot).
+ * Returns a hint string if double-escaping is suspected, empty string otherwise.
+ */
+function detectDoubleEscaping(term) {
+    // Look for \\. \\d \\w \\s \\b \\D \\W \\S \\B \\( \\) \\[ \\] — common double-escaped sequences
+    const doubleEscaped = term.match(/\\\\[.dDwWsSbB()\[\]*+?^${}|]/g);
+    if (!doubleEscaped) return '';
+    const examples = [...new Set(doubleEscaped)].slice(0, 3);
+    const fixed = examples.map(e => e.slice(1)); // remove one backslash
+    return `\nHint: Pattern contains ${examples.join(', ')} which matches literal backslash(es). If you meant ${fixed.join(', ')}, use a single backslash (MCP/JSON parameters are already raw strings).`;
+}
+
 /**
  * Format search command output
  */
@@ -1933,15 +1947,17 @@ function formatSearch(results, term) {
     if (totalMatches === 0) {
         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}${fallbackNote}`;
+                ? `Searched ${meta.filesScanned} of ${meta.totalFiles} file${meta.totalFiles === 1 ? '' : 's'} (${meta.filesSkipped} excluded by filters).`
+                : `Searched ${meta.filesScanned} file${meta.filesScanned === 1 ? '' : 's'}.`;
+            const escapingHint = detectDoubleEscaping(term);
+            return `No matches found for "${term}". ${scope}${fallbackNote}${escapingHint}`;
         }
         return `No matches found for "${term}"${fallbackNote}`;
     }
 
     const lines = [];
-    lines.push(`Found ${totalMatches} matches for "${term}" in ${results.length} files:`);
+    const fileWord = results.length === 1 ? 'file' : 'files';
+    lines.push(`Found ${totalMatches} match${totalMatches === 1 ? '' : 'es'} for "${term}" in ${results.length} ${fileWord}:`);
     if (fallbackNote) lines.push(fallbackNote.trim());
     lines.push('═'.repeat(60));
 
@@ -2358,6 +2374,7 @@ module.exports = {
     formatClass,
     formatGraph,
     formatSearch,
+    detectDoubleEscaping,
     formatFileExports,
     formatStats,
 

package/mcp/server.js

@@ -268,7 +268,9 @@ server.registerTool(
             range: z.string().optional().describe('Line range to extract, e.g. "10-20" or "15" (lines command)'),
             base: z.string().optional().describe('Git ref to diff against (default: HEAD). E.g. "HEAD~3", "main", a commit SHA'),
             staged: z.boolean().optional().describe('Analyze staged changes (diff_impact command)'),
-            case_sensitive: z.boolean().optional().describe('Case-sensitive search (default: false, case-insensitive)')
+            case_sensitive: z.boolean().optional().describe('Case-sensitive search (default: false, case-insensitive)'),
+            all: z.boolean().optional().describe('Show all results (expand truncated sections). Applies to about, toc, related, trace, and others.'),
+            top_level: z.boolean().optional().describe('Show only top-level functions in toc (exclude nested/indented)')
         })
     },
     async (args) => {
@@ -278,7 +280,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, regex, functions } = args;
+                case_sensitive, regex, functions, all, top_level } = args;
 
         try {
             switch (command) {
@@ -291,9 +293,9 @@ server.registerTool(
                 const err = requireName(name);
                 if (err) return err;
                 const index = getIndex(project_dir);
-                const result = index.about(name, { file, exclude: parseExclude(exclude), withTypes: with_types || false, includeMethods: include_methods ?? undefined, maxCallers: top, maxCallees: top });
+                const result = index.about(name, { file, exclude: parseExclude(exclude), withTypes: with_types || false, includeMethods: include_methods ?? undefined, includeUncertain: include_uncertain || false, all: all || false, maxCallers: top, maxCallees: top });
                 return toolResult(output.formatAbout(result, {
-                    allHint: 'Repeat with top set higher to show all.',
+                    allHint: 'Repeat with all=true to show all.',
                     methodsHint: 'Note: obj.method() callers/callees excluded. Use include_methods=true to include them.'
                 }));
             }
@@ -378,12 +380,12 @@ server.registerTool(
                 const err = requireName(name);
                 if (err) return err;
                 const index = getIndex(project_dir);
-                const result = index.related(name, { file, top, all: top !== undefined });
+                const result = index.related(name, { file, top, all: all || false });
                 if (!result) return toolResult(`Symbol "${name}" not found.`);
                 return toolResult(output.formatRelated(result, {
-                    showAll: top !== undefined,
+                    showAll: all || false,
                     top,
-                    allHint: 'Repeat with top set higher to show all.'
+                    allHint: 'Repeat with all=true to show all.'
                 }));
             }
 
@@ -416,7 +418,7 @@ server.registerTool(
 
             case 'toc': {
                 const index = getIndex(project_dir);
-                const toc = index.getToc({ detailed: detailed || false, top });
+                const toc = index.getToc({ detailed: detailed || false, topLevel: top_level || false, all: all || false, top });
                 return toolResult(output.formatToc(toc, {
                     topHint: 'Set top=N or use detailed=false for compact view.'
                 }));
@@ -728,7 +730,7 @@ server.registerTool(
                 if (result?.error === 'file-not-found') return toolError(`File not found in project: ${file}`);
                 if (result?.error === 'file-ambiguous') return toolError(`Ambiguous file "${file}". Candidates:\n${result.candidates.map(c => '  ' + c).join('\n')}`);
                 return toolResult(output.formatGraph(result, {
-                    showAll: depth !== undefined,
+                    showAll: all || depth !== undefined,
                     file,
                     depthHint: 'Set depth parameter for deeper graph.',
                     allHint: 'Set depth to expand all children.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.7.15",
+  "version": "3.7.17",
   "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",