ucn 3.7.3 → 3.7.5

package/README.md

@@ -4,9 +4,37 @@ UCN gives AI agents call-graph-level understanding of code. Instead of reading e
 
 Designed for large codebases where agents waste context on reading large files. UCN's surgical output means agents spend tokens on reasoning, not on ingesting thousands of lines to find three callers, discourages agents from cutting corners, as without UCN, agents working with large codebases tend to skip parts of the code structure, assuming they have "enough data".
 
+Everything runs locally on your machine and nothing leaves your project.
+
 ---
 
-## Three Ways to it: ucn mcp, ucn skill, ucn cli 
+## What UCN does
+
+Precise answers without reading files.
+
+```
+  TASK                                    COMMAND
+  ─────────────────────                   ─────────────────────
+
+  Pull one function from                  $ ucn fn handleRequest
+  a 2000-line file                        → 20 lines, just that function
+
+  Who calls this? Will they               $ ucn impact handleRequest
+  break if I change it?                   → 8 call sites, with arguments
+
+  What happens when                       $ ucn trace main --depth=3
+  main() runs?                            → full call tree, no file reads
+
+  What can I safely delete?               $ ucn deadcode
+                                          → unused functions, AST-verified
+
+  What depends on this file               $ ucn graph src/routes.ts
+  before I move it?                       → imports and importers tree
+```
+
+---
+
+## Three Ways to it: ucn mcp, ucn skill, ucn cli
 
 ```
   ┌──────────────────────────────────────────────────────────────────────┐
@@ -15,7 +43,7 @@ Designed for large codebases where agents waste context on reading large files.
   │      $ ucn about myFunc     Works standalone, no agent required.     │
   │                                                                      │
   │   2. MCP Server             Any MCP-compatible AI agent connects     │
-  │      $ ucn --mcp            and gets 28 tools automatically.         │
+  │      $ ucn --mcp            and gets 28 commands automatically.         │
   │                                                                      │
   │   3. Agent Skill            Drop-in skill for Claude Code and        │
   │      /ucn about myFunc      OpenAI Codex CLI. No server needed.      │
@@ -66,7 +94,7 @@ AI agents working with code typically do this:
                           ▼
                  ┌───────────────────┐
                  │   UCN MCP Server  │
-                 │   28 tools        │
+                 │   28 commands     │
                  │   runs locally    │
                  └────────┬──────────┘
                           │
@@ -78,8 +106,6 @@ AI agents working with code typically do this:
         └─────────────────────────────────────┘
 ```
 
-No cloud. No API keys. Parses locally, stays local.
-
 ---
 
 ## Before and after UCN
@@ -88,7 +114,7 @@ No cloud. No API keys. Parses locally, stays local.
   WITHOUT UCN                              WITH UCN
   ──────────────────────                   ──────────────────────
 
-  grep "processOrder"                      ucn_impact "processOrder"
+  grep "processOrder"                      ucn impact "processOrder"
        │                                        │
        ▼                                        ▼
   34 matches, mostly noise                 8 call sites, grouped by file,
@@ -97,7 +123,7 @@ No cloud. No API keys. Parses locally, stays local.
   read service.ts  (800 lines)                  │
        │                                        │
        ▼                                        │
-  read handler.ts  (600 lines)             ucn_smart "processOrder"
+  read handler.ts  (600 lines)             ucn smart "processOrder"
        │                                        │
        ▼                                        ▼
   read batch.ts    (400 lines)             function + all dependencies
@@ -126,7 +152,7 @@ After editing code, before committing:
   WITHOUT UCN                              WITH UCN
   ──────────────────────                   ──────────────────────
 
-  git diff                                 ucn_diff_impact
+  git diff                                 ucn diff_impact
        │                                        │
        ▼                                        ▼
   see changed lines, but which             13 modified functions
@@ -137,7 +163,7 @@ After editing code, before committing:
   to function boundaries                   Each function shown with:
        │                                     • which lines changed
        ▼                                     • every downstream caller
-  ucn_impact on each function                • caller context
+  ucn impact on each function                • caller context
   you identified (repeat 5-10x)                 │
        │                                        ▼
        ▼                                   Done. Full blast radius.
@@ -169,7 +195,7 @@ After editing code, before committing:
 
 
   ┌─────────────────────────────────────────────────────────────────┐
-  │  ucn_context "processOrder"                                     │
+  │  ucn context "processOrder"                                     │
   │                                                                 │
   │    Callers:                                                     │
   │      handleCheckout    src/api/checkout.ts:45                   │
@@ -515,38 +541,40 @@ ucn toc                                   # Project overview
 
 ---
 
-## All 28 UCN tools
+## All 28 Commands
+
+All commands are accessible through a single `ucn` MCP tool with a `command` parameter.
 
 ```
   UNDERSTAND                          MODIFY SAFELY
   ─────────────────────               ─────────────────────
-  ucn_about     everything in one     ucn_impact      all call sites
+  about         everything in one     impact          all call sites
                 call: definition,                     with arguments
                 callers, callees,
-                tests, source         ucn_diff_impact what changed in a
+                tests, source         diff_impact     what changed in a
                                                       git diff + who
-  ucn_context   callers + callees                     calls it
+  context       callers + callees                     calls it
                 (quick overview)
-                                      ucn_verify      check all sites
-  ucn_smart     function + helpers                    match signature
+                                      verify          check all sites
+  smart         function + helpers                    match signature
                 expanded inline
-                                      ucn_plan        preview a refactor
-  ucn_trace     call tree — map                       before doing it
+                                      plan            preview a refactor
+  trace         call tree — map                       before doing it
                 a whole pipeline
 
 
   FIND & NAVIGATE                     ARCHITECTURE
   ─────────────────────               ─────────────────────
-  ucn_find      locate definitions    ucn_imports     file dependencies
-  ucn_usages    all occurrences       ucn_exporters   who depends on it
-  ucn_fn        extract a function    ucn_graph       dependency tree
-  ucn_class     extract a class       ucn_related     sibling functions
-  ucn_toc       project overview      ucn_tests       find tests
-  ucn_deadcode  unused functions      ucn_stacktrace  error trace context
-  ucn_search    text search           ucn_api         public API surface
-  ucn_example   best usage example    ucn_typedef     type definitions
-  ucn_lines     extract line range    ucn_file_exports file's exports
-  ucn_expand    drill into context    ucn_stats       project size stats
+  find          locate definitions    imports         file dependencies
+  usages        all occurrences       exporters       who depends on it
+  fn            extract a function    graph           dependency tree
+  class         extract a class       related         sibling functions
+  toc           project overview      tests           find tests
+  deadcode      unused functions      stacktrace      error trace context
+  search        text search           api             public API surface
+  example       best usage example    typedef         type definitions
+  lines         extract line range    file_exports    file's exports
+  expand        drill into context    stats           project size stats
 ```
 
 ---

package/cli/index.js

@@ -1819,14 +1819,21 @@ Commands:
   about <name>           Everything about a symbol
   usages <name>          All usages grouped by type
   context <name>         Callers + callees
+  expand <N>             Show code for item N from context
   smart <name>           Function + dependencies
   impact <name>          What breaks if changed
   trace <name>           Call tree
+  example <name>         Best usage example
+  related <name>         Sibling functions
   imports <file>         What file imports
   exporters <file>       Who imports file
   tests <name>           Find tests
   search <term>          Text search
   typedef <name>         Find type definitions
+  deadcode               Find unused functions/classes
+  verify <name>          Check call sites match signature
+  plan <name>            Preview refactoring
+  stacktrace <text>      Parse a stack trace
   api                    Show public symbols
   diff-impact            What changed and who's affected
   stats                  Index statistics
@@ -1913,7 +1920,7 @@ function executeInteractiveCommand(index, command, arg) {
                 console.log('Usage: context <name>');
                 return;
             }
-            const ctx = index.context(arg, { includeUncertain: flags.includeUncertain });
+            const ctx = index.context(arg, { includeUncertain: flags.includeUncertain, includeMethods: flags.includeMethods });
             if (!ctx) {
                 console.log(`Symbol "${arg}" not found.`);
             } else {
@@ -2036,6 +2043,100 @@ function executeInteractiveCommand(index, command, arg) {
             break;
         }
 
+        case 'expand': {
+            if (!arg) {
+                console.log('Usage: expand <number>');
+                return;
+            }
+            const expandNum = parseInt(arg, 10);
+            if (isNaN(expandNum)) {
+                console.log(`Invalid item number: "${arg}"`);
+                return;
+            }
+            const cached = loadExpandableItems(index.root);
+            if (!cached || !cached.items || cached.items.length === 0) {
+                console.log('No expandable items. Run context first.');
+                return;
+            }
+            const expandMatch = cached.items.find(i => i.num === expandNum);
+            if (!expandMatch) {
+                console.log(`Item ${expandNum} not found. Available: 1-${cached.items.length}`);
+                return;
+            }
+            printExpandedItem(expandMatch, cached.root || index.root);
+            break;
+        }
+
+        case 'deadcode': {
+            const deadResult = index.deadcode({
+                includeExported: flags.includeExported,
+                includeDecorated: flags.includeDecorated,
+                includeTests: flags.includeTests
+            });
+            console.log(output.formatDeadcode(deadResult));
+            break;
+        }
+
+        case 'related': {
+            if (!arg) {
+                console.log('Usage: related <name>');
+                return;
+            }
+            const relResult = index.related(arg, { file: flags.file });
+            console.log(output.formatRelated(relResult));
+            break;
+        }
+
+        case 'example': {
+            if (!arg) {
+                console.log('Usage: example <name>');
+                return;
+            }
+            console.log(output.formatExample(index.example(arg), arg));
+            break;
+        }
+
+        case 'plan': {
+            if (!arg) {
+                console.log('Usage: plan <name> [--add-param=x] [--remove-param=x] [--rename-to=x]');
+                return;
+            }
+            if (!flags.addParam && !flags.removeParam && !flags.renameTo) {
+                console.log('Plan requires an operation: --add-param, --remove-param, or --rename-to');
+                return;
+            }
+            const planResult = index.plan(arg, {
+                addParam: flags.addParam,
+                removeParam: flags.removeParam,
+                renameTo: flags.renameTo,
+                defaultValue: flags.defaultValue,
+                file: flags.file
+            });
+            console.log(output.formatPlan(planResult));
+            break;
+        }
+
+        case 'verify': {
+            if (!arg) {
+                console.log('Usage: verify <name>');
+                return;
+            }
+            const verifyResult = index.verify(arg, { file: flags.file });
+            console.log(output.formatVerify(verifyResult));
+            break;
+        }
+
+        case 'stacktrace':
+        case 'stack': {
+            if (!arg) {
+                console.log('Usage: stacktrace <stack text>');
+                return;
+            }
+            const stackResult = index.parseStackTrace(arg);
+            console.log(output.formatStackTrace(stackResult));
+            break;
+        }
+
         default:
             console.log(`Unknown command: ${command}. Type "help" for available commands.`);
     }

package/core/output.js

@@ -829,7 +829,7 @@ function formatRelated(related, options = {}) {
     // Same file
     let relatedTruncated = false;
     if (related.sameFile.length > 0) {
-        const maxSameFile = options.showAll ? Infinity : 8;
+        const maxSameFile = options.top || (options.showAll ? Infinity : 8);
         lines.push(`SAME FILE (${related.sameFile.length}):`);
         for (const f of related.sameFile.slice(0, maxSameFile)) {
             const params = f.params ? `(${f.params})` : '';

package/core/project.js

@@ -1412,7 +1412,8 @@ class ProjectIndex {
                     });
                 }
             } catch (e) {
-                // Skip files that can't be processed
+                // Expected: minified files exceed tree-sitter buffer, binary files fail to parse.
+                // These are not actionable errors — silently skip.
             }
         }
 
@@ -1848,6 +1849,8 @@ class ProjectIndex {
 
             return result;
         } catch (e) {
+            // Expected: file read/parse failures (minified, binary, buffer exceeded).
+            // Return empty callees rather than crashing the entire query.
             return [];
         }
     }
@@ -1956,6 +1959,8 @@ class ProjectIndex {
             cleanHtmlScriptTags(extracted, detectLanguage(symbol.file));
             return extracted.join('\n');
         } catch (e) {
+            // Expected: file may have been deleted or become unreadable since indexing.
+            // Return empty string rather than crashing.
             return '';
         }
     }
@@ -2188,18 +2193,12 @@ class ProjectIndex {
      * @returns {Array} Imports with resolved paths
      */
     imports(filePath) {
-        const normalizedPath = path.isAbsolute(filePath)
-            ? filePath
-            : path.join(this.root, filePath);
+        const resolved = this.resolveFilePathForQuery(filePath);
+        if (typeof resolved !== 'string') return resolved;
 
+        const normalizedPath = resolved;
         const fileEntry = this.files.get(normalizedPath);
         if (!fileEntry) {
-            // Try to find by relative path
-            for (const [absPath, entry] of this.files) {
-                if (entry.relativePath === filePath || absPath.endsWith(filePath)) {
-                    return this.imports(absPath);
-                }
-            }
             return { error: 'file-not-found', filePath };
         }
 
@@ -2275,24 +2274,10 @@ class ProjectIndex {
      * @returns {Array} Files that import this file
      */
     exporters(filePath) {
-        const normalizedPath = path.isAbsolute(filePath)
-            ? filePath
-            : path.join(this.root, filePath);
+        const resolved = this.resolveFilePathForQuery(filePath);
+        if (typeof resolved !== 'string') return resolved;
 
-        // Try to find the file
-        let targetPath = normalizedPath;
-        if (!this.files.has(normalizedPath)) {
-            for (const [absPath, entry] of this.files) {
-                if (entry.relativePath === filePath || absPath.endsWith(filePath)) {
-                    targetPath = absPath;
-                    break;
-                }
-            }
-        }
-
-        if (!this.files.has(targetPath)) {
-            return { error: 'file-not-found', filePath };
-        }
+        const targetPath = resolved;
 
         const importers = this.exportGraph.get(targetPath) || [];
 
@@ -2374,6 +2359,9 @@ class ProjectIndex {
         // Note: no 'g' flag - we only need to test for presence per line
         // The 'i' flag is kept for case-insensitive matching
         const regex = new RegExp('\\b' + escapeRegExp(searchTerm) + '\\b', 'i');
+        // Pre-compile patterns used inside per-line loop
+        const callPattern = new RegExp(escapeRegExp(searchTerm) + '\\s*\\(');
+        const strPattern = new RegExp("['\"`]" + escapeRegExp(searchTerm) + "['\"`]");
 
         for (const { path: testPath, entry } of testFiles) {
             try {
@@ -2388,12 +2376,11 @@ class ProjectIndex {
                             matchType = 'test-case';
                         } else if (/\b(import|require|from)\b/.test(line)) {
                             matchType = 'import';
-                        } else if (new RegExp(searchTerm + '\\s*\\(').test(line)) {
+                        } else if (callPattern.test(line)) {
                             matchType = 'call';
                         }
                         // Detect if the match is inside a string literal (e.g., 'parseFile' or "parseFile")
                         if (matchType === 'reference' || matchType === 'call') {
-                            const strPattern = new RegExp("['\"`]" + escapeRegExp(searchTerm) + "['\"`]");
                             if (strPattern.test(line)) {
                                 matchType = 'string-ref';
                             }
@@ -2432,7 +2419,18 @@ class ProjectIndex {
     api(filePath, options = {}) {
         const results = [];
 
-        for (const [absPath, fileEntry] of (filePath ? [[this.findFile(filePath), this.files.get(this.findFile(filePath))]] : this.files.entries())) {
+        let fileIterator;
+        if (filePath) {
+            const resolved = this.resolveFilePathForQuery(filePath);
+            if (typeof resolved !== 'string') return resolved;
+            const fileEntry = this.files.get(resolved);
+            if (!fileEntry) return { error: 'file-not-found', filePath };
+            fileIterator = [[resolved, fileEntry]];
+        } else {
+            fileIterator = this.files.entries();
+        }
+
+        for (const [absPath, fileEntry] of fileIterator) {
             if (!fileEntry) continue;
 
             // Skip test files by default (test classes aren't part of public API)
@@ -2487,9 +2485,12 @@ class ProjectIndex {
     }
 
     /**
-     * Find a file by path (supports partial paths)
+     * Resolve a file path query to an indexed file (with ambiguity detection)
+     * @param {string} filePath - File path to resolve
+     * @returns {string|{error: string, filePath: string, candidates?: string[]}}
      */
-    findFile(filePath) {
+    resolveFilePathForQuery(filePath) {
+        // 1. Exact absolute/relative path match
         const normalizedPath = path.isAbsolute(filePath)
             ? filePath
             : path.join(this.root, filePath);
@@ -2498,13 +2499,34 @@ class ProjectIndex {
             return normalizedPath;
         }
 
-        // Try partial match
+        // 2. Collect ALL suffix/partial candidates
+        const candidates = [];
         for (const [absPath, entry] of this.files) {
-            if (entry.relativePath === filePath || absPath.endsWith(filePath)) {
-                return absPath;
+            if (entry.relativePath === filePath || absPath.endsWith('/' + filePath)) {
+                candidates.push(absPath);
             }
         }
 
+        if (candidates.length === 0) {
+            return { error: 'file-not-found', filePath };
+        }
+        if (candidates.length === 1) {
+            return candidates[0];
+        }
+        return {
+            error: 'file-ambiguous',
+            filePath,
+            candidates: candidates.map(c => this.files.get(c)?.relativePath || path.relative(this.root, c))
+        };
+    }
+
+    /**
+     * Find a file by path (supports partial paths)
+     * Backward-compatible wrapper — returns null on error.
+     */
+    findFile(filePath) {
+        const result = this.resolveFilePathForQuery(filePath);
+        if (typeof result === 'string') return result;
         return null;
     }
 
@@ -2514,11 +2536,10 @@ class ProjectIndex {
      * @returns {Array} Exported symbols from that file
      */
     fileExports(filePath) {
-        const absPath = this.findFile(filePath);
-        if (!absPath) {
-            return { error: 'file-not-found', filePath };
-        }
+        const resolved = this.resolveFilePathForQuery(filePath);
+        if (typeof resolved !== 'string') return resolved;
 
+        const absPath = resolved;
         const fileEntry = this.files.get(absPath);
         if (!fileEntry) {
             return [];
@@ -2960,24 +2981,10 @@ class ProjectIndex {
         const rawDepth = options.maxDepth ?? 5;
         const maxDepth = Math.max(0, rawDepth);
 
-        const absPath = path.isAbsolute(filePath)
-            ? filePath
-            : path.resolve(this.root, filePath);
-
-        // Try to find file if not exact match
-        let targetPath = absPath;
-        if (!this.files.has(absPath)) {
-            for (const [p, entry] of this.files) {
-                if (entry.relativePath === filePath || p.endsWith(filePath)) {
-                    targetPath = p;
-                    break;
-                }
-            }
-        }
+        const resolved = this.resolveFilePathForQuery(filePath);
+        if (typeof resolved !== 'string') return resolved;
 
-        if (!this.files.has(targetPath)) {
-            return { error: 'file-not-found', filePath };
-        }
+        const targetPath = resolved;
 
         const buildSubgraph = (dir) => {
             const visited = new Set();
@@ -3176,7 +3183,8 @@ class ProjectIndex {
         }
         // Sort by number of shared parts
         related.similarNames.sort((a, b) => b.sharedParts.length - a.sharedParts.length);
-        if (!options.all) related.similarNames = related.similarNames.slice(0, 10);
+        const similarLimit = options.top || (options.all ? Infinity : 10);
+        if (related.similarNames.length > similarLimit) related.similarNames = related.similarNames.slice(0, similarLimit);
 
         // 3. Shared callers - functions called by the same callers
         const myCallers = new Set(this.findCallers(name).map(c => c.callerName).filter(Boolean));
@@ -3194,7 +3202,7 @@ class ProjectIndex {
                 }
             }
             // Sort by shared caller count
-            const maxShared = options.all ? Infinity : 5;
+            const maxShared = options.top || (options.all ? Infinity : 5);
             const sorted = Array.from(callerCounts.entries())
                 .sort((a, b) => b[1] - a[1])
                 .slice(0, maxShared);
@@ -3230,7 +3238,7 @@ class ProjectIndex {
                 // Sort by shared callee count
                 const sorted = Array.from(calleeCounts.entries())
                     .sort((a, b) => b[1] - a[1])
-                    .slice(0, options.all ? Infinity : 5);
+                    .slice(0, options.top || (options.all ? Infinity : 5));
                 for (const [symName, count] of sorted) {
                     const sym = this.symbols.get(symName)?.[0];
                     if (sym) {
@@ -4408,7 +4416,8 @@ class ProjectIndex {
                     });
                 }
             } catch (e) {
-                // Skip unreadable files
+                // Expected: binary/minified files fail to read or parse.
+                // These are not actionable errors — silently skip.
             }
         }
 

package/mcp/server.js

@@ -158,6 +158,31 @@ function toolError(message) {
     return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
 }
 
+/**
+ * Resolve a file path via index and validate it's within the project root.
+ * Returns the resolved absolute path string, or a toolError response.
+ */
+function resolveAndValidatePath(index, file) {
+    const resolved = index.resolveFilePathForQuery(file);
+    if (typeof resolved !== 'string') {
+        if (resolved.error === 'file-ambiguous') {
+            return toolError(`Ambiguous file "${file}". Candidates:\n${resolved.candidates.map(c => '  ' + c).join('\n')}`);
+        }
+        return toolError(`File not found: ${file}`);
+    }
+    // Path boundary check: ensure resolved path is within the project root
+    try {
+        const realPath = fs.realpathSync(resolved);
+        const realRoot = fs.realpathSync(index.root);
+        if (realPath !== realRoot && !realPath.startsWith(realRoot + path.sep)) {
+            return toolError(`File is outside project root: ${file}`);
+        }
+    } catch (e) {
+        return toolError(`Cannot resolve file path: ${file}`);
+    }
+    return resolved;
+}
+
 function requireName(name) {
     if (!name || !name.trim()) {
         return toolError('Symbol name is required.');
@@ -371,9 +396,10 @@ server.registerTool(
                 const err = requireName(name);
                 if (err) return err;
                 const index = getIndex(project_dir);
-                const result = index.related(name, { file, all: top !== undefined });
+                const result = index.related(name, { file, top, all: top !== undefined });
                 return toolResult(output.formatRelated(result, {
                     showAll: top !== undefined,
+                    top,
                     allHint: 'Repeat with top set higher to show all.'
                 }));
             }
@@ -464,6 +490,9 @@ server.registerTool(
                 }
 
                 const match = matches.length > 1 ? pickBestDefinition(matches) : matches[0];
+                // Validate file is within project root
+                const fnPathCheck = resolveAndValidatePath(index, match.relativePath || path.relative(index.root, match.file));
+                if (typeof fnPathCheck !== 'string') return fnPathCheck;
                 const code = fs.readFileSync(match.file, 'utf-8');
                 const codeLines = code.split('\n');
                 const fnCode = codeLines.slice(match.startLine - 1, match.endLine).join('\n');
@@ -489,6 +518,9 @@ server.registerTool(
                 }
 
                 const match = matches.length > 1 ? pickBestDefinition(matches) : matches[0];
+                // Validate file is within project root
+                const clsPathCheck = resolveAndValidatePath(index, match.relativePath || path.relative(index.root, match.file));
+                if (typeof clsPathCheck !== 'string') return clsPathCheck;
 
                 const code = fs.readFileSync(match.file, 'utf-8');
                 const codeLines = code.split('\n');
@@ -499,6 +531,10 @@ server.registerTool(
                     note = `Note: Found ${matches.length} definitions for "${name}". Showing ${match.relativePath}:${match.startLine}. Use file parameter to disambiguate.\n\n`;
                 }
 
+                if (max_lines !== undefined && (!Number.isInteger(max_lines) || max_lines < 1)) {
+                    return toolError(`Invalid max_lines: ${max_lines}. Must be a positive integer.`);
+                }
+
                 const classLineCount = match.endLine - match.startLine + 1;
 
                 // Large class: show summary by default, truncated source with max_lines
@@ -537,10 +573,9 @@ server.registerTool(
                     return toolError('Line range is required (e.g. "10-20" or "15").');
                 }
                 const index = getIndex(project_dir);
-                const filePath = index.findFile(file);
-                if (!filePath) {
-                    return toolError(`File not found: ${file}`);
-                }
+                const resolved = resolveAndValidatePath(index, file);
+                if (typeof resolved !== 'string') return resolved; // toolError response
+                const filePath = resolved;
 
                 const parts = range.split('-');
                 const start = parseInt(parts[0], 10);
@@ -552,12 +587,18 @@ server.registerTool(
                 if (start < 1) {
                     return toolError(`Invalid start line: ${start}. Line numbers must be >= 1`);
                 }
+                if (end < 1) {
+                    return toolError(`Invalid end line: ${end}. Line numbers must be >= 1`);
+                }
+                if (end < start) {
+                    return toolError(`Invalid range: end line (${end}) must be >= start line (${start})`);
+                }
 
                 const content = fs.readFileSync(filePath, 'utf-8');
                 const fileLines = content.split('\n');
 
-                const startLine = Math.min(start, end);
-                const endLine = Math.max(start, end);
+                const startLine = start;
+                const endLine = end;
 
                 if (startLine > fileLines.length) {
                     return toolError(`Line ${startLine} is out of bounds. File has ${fileLines.length} lines.`);
@@ -616,6 +657,16 @@ server.registerTool(
                 if (!filePath || !fs.existsSync(filePath)) {
                     return toolError(`Cannot locate file for ${match.name}`);
                 }
+                // Validate file is within project root
+                try {
+                    const realPath = fs.realpathSync(filePath);
+                    const realRoot = fs.realpathSync(index.root);
+                    if (realPath !== realRoot && !realPath.startsWith(realRoot + path.sep)) {
+                        return toolError(`File is outside project root: ${match.name}`);
+                    }
+                } catch (e) {
+                    return toolError(`Cannot resolve file path for ${match.name}`);
+                }
 
                 const content = fs.readFileSync(filePath, 'utf-8');
                 const fileLines = content.split('\n');
@@ -645,6 +696,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const result = index.imports(file);
                 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.formatImports(result, file));
             }
 
@@ -655,6 +707,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const result = index.exporters(file);
                 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.formatExporters(result, file));
             }
 
@@ -665,6 +718,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const result = index.fileExports(file);
                 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.formatFileExports(result, file));
             }
 
@@ -675,6 +729,7 @@ server.registerTool(
                 const index = getIndex(project_dir);
                 const result = index.graph(file, { direction: direction || 'both', maxDepth: depth ?? 2 });
                 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,
                     file,
@@ -713,6 +768,10 @@ server.registerTool(
             }
 
             case 'diff_impact': {
+                // Validate git ref format to prevent argument injection
+                if (base && !/^[a-zA-Z0-9._\-~\/^@{}:]+$/.test(base)) {
+                    return toolError(`Invalid git ref format: ${base}`);
+                }
                 const index = getIndex(project_dir);
                 const result = index.diffImpact({
                     base: base || 'HEAD',
@@ -745,8 +804,10 @@ server.registerTool(
 
             case 'api': {
                 const index = getIndex(project_dir);
-                const symbols = index.api(file || undefined);
-                return toolResult(output.formatApi(symbols, file || '.'));
+                const result = index.api(file || undefined);
+                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.formatApi(result, file || '.'));
             }
 
             case 'stats': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "3.7.3",
+  "version": "3.7.5",
   "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",
   "bin": {

package/test/mcp-edge-cases.js

@@ -358,6 +358,112 @@ const tests = [
         desc: 'lines - extract lines 1-5 from discovery.js',
         args: { command: 'lines', project_dir: PROJECT_DIR, file: 'core/discovery.js', range: '1-5' }
     },
+
+    // ========================================================================
+    // Correctness Assertions
+    // ========================================================================
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'api(file=nonexistent) returns isError',
+        args: { command: 'api', project_dir: PROJECT_DIR, file: 'nonexistent/path/to/file.js' },
+        assert: (res, text, isError) => isError === true || 'Expected isError: true for nonexistent file'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'api(file=nonexistent) message contains "not found"',
+        args: { command: 'api', project_dir: PROJECT_DIR, file: 'nonexistent.js' },
+        assert: (res, text, isError) => (isError && /not found/i.test(text)) || 'Expected file-not-found error message'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'lines(range="5-0") returns validation error',
+        args: { command: 'lines', project_dir: PROJECT_DIR, file: 'core/discovery.js', range: '5-0' },
+        assert: (res, text, isError) => isError === true || 'Expected isError: true for invalid range'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'class(max_lines=-1) returns validation error',
+        args: { command: 'class', project_dir: PROJECT_DIR, name: 'ProjectIndex', max_lines: -1 },
+        assert: (res, text, isError) => isError === true || 'Expected isError: true for negative max_lines'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'lines - unique partial file resolves successfully',
+        args: { command: 'lines', project_dir: PROJECT_DIR, file: 'core/discovery.js', range: '1-3' },
+        assert: (res, text, isError) => isError === false || 'Expected success for unique partial file'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'file_exports(file=utils.js) returns ambiguity error',
+        args: { command: 'file_exports', project_dir: PROJECT_DIR, file: 'utils.js' },
+        assert: (res, text, isError) => (isError && /ambiguous/i.test(text)) || 'Expected file-ambiguous error for utils.js'
+    },
+    {
+        category: 'Correctness',
+        tool: 'ucn',
+        desc: 'imports(file=utils.js) returns ambiguity error',
+        args: { command: 'imports', project_dir: PROJECT_DIR, file: 'utils.js' },
+        assert: (res, text, isError) => (isError && /ambiguous/i.test(text)) || 'Expected file-ambiguous error for utils.js'
+    },
+
+    // ========================================================================
+    // CATEGORY 3: Security (path traversal, argument injection)
+    // ========================================================================
+    {
+        category: 'Security',
+        tool: 'ucn',
+        desc: 'lines rejects path traversal (../../../../etc/passwd)',
+        args: { command: 'lines', project_dir: PROJECT_DIR, file: '../../../../etc/passwd', range: '1-5' },
+        assert: (res, text, isError) => (isError && (/not found/i.test(text) || /outside project/i.test(text))) || 'Expected error for path traversal'
+    },
+    {
+        category: 'Security',
+        tool: 'ucn',
+        desc: 'lines rejects path traversal (../../other-project/secret.js)',
+        args: { command: 'lines', project_dir: PROJECT_DIR, file: '../../other-project/secret.js', range: '1-5' },
+        assert: (res, text, isError) => (isError && (/not found/i.test(text) || /outside project/i.test(text))) || 'Expected error for path traversal'
+    },
+    {
+        category: 'Security',
+        tool: 'ucn',
+        desc: 'lines works with valid file',
+        args: { command: 'lines', project_dir: PROJECT_DIR, file: 'core/discovery.js', range: '1-3' },
+        assert: (res, text, isError) => (!isError && text.length > 0) || 'Expected valid output for core/discovery.js'
+    },
+    {
+        category: 'Security',
+        tool: 'ucn',
+        desc: 'diff_impact rejects --config argument injection',
+        args: { command: 'diff_impact', project_dir: PROJECT_DIR, base: '--config=malicious' },
+        assert: (res, text, isError) => (isError && /invalid git ref/i.test(text)) || 'Expected error for argument injection in base'
+    },
+    {
+        category: 'Security',
+        tool: 'ucn',
+        desc: 'diff_impact rejects -o flag injection',
+        args: { command: 'diff_impact', project_dir: PROJECT_DIR, base: '-o /tmp/evil' },
+        assert: (res, text, isError) => (isError && /invalid git ref/i.test(text)) || 'Expected error for flag injection in base'
+    },
+    {
+        category: 'Security',
+        tool: 'ucn',
+        desc: 'diff_impact accepts valid ref HEAD~3',
+        args: { command: 'diff_impact', project_dir: PROJECT_DIR, base: 'HEAD~3' },
+        assert: (res, text, isError) => true  // Should not error on valid ref format
+    },
+    {
+        category: 'Security',
+        tool: 'ucn',
+        desc: 'diff_impact accepts valid ref origin/main',
+        args: { command: 'diff_impact', project_dir: PROJECT_DIR, base: 'origin/main' },
+        assert: (res, text, isError) => true  // Should not error on valid ref format
+    },
 ];
 
 // ============================================================================
@@ -406,6 +512,15 @@ async function run() {
                 const preview = text.substring(0, 120).replace(/\n/g, '\\n');
                 status = 'PASS';
                 detail = `${isError ? 'ERROR response' : 'OK'}: "${preview}" (${elapsed}ms)`;
+
+                // Run assertion if provided
+                if (t.assert && status === 'PASS') {
+                    const assertResult = t.assert(res, text, isError);
+                    if (assertResult !== true) {
+                        status = 'FAIL';
+                        detail = `ASSERTION: ${assertResult} (${elapsed}ms)`;
+                    }
+                }
             } else {
                 status = 'PASS';
                 detail = `Empty result (${elapsed}ms)`;

package/test/parser.test.js

@@ -13025,5 +13025,59 @@ it('FIX 99 — parseDiff handles quoted paths with special characters', () => {
         'Literal backslash-n in filename must be preserved, not converted to newline');
 });
 
+// ============================================================================
+// Interactive Mode Tests (Fix #100 — missing commands)
+// ============================================================================
+
+describe('Interactive Mode', () => {
+    const { execFileSync } = require('child_process');
+    const cliPath = path.join(__dirname, '..', 'cli', 'index.js');
+
+    it('supports all commands without errors', () => {
+        // Test each previously-missing command by piping into interactive mode
+        // Each should not crash and should produce some output (not "Unknown command")
+        const commands = [
+            'deadcode',
+            'related processData',
+            'example processData',
+            'verify processData',
+            'expand 1',  // Will say "no expandable items" but won't crash
+        ];
+
+        const input = commands.join('\n') + '\nquit\n';
+
+        const result = execFileSync('node', [cliPath, '--interactive', '.'], {
+            input,
+            encoding: 'utf-8',
+            cwd: path.join(__dirname, '..'),
+            timeout: 30000,
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+
+        // Verify no "Unknown command" errors for the previously-missing commands
+        assert.ok(!result.includes('Unknown command: deadcode'), 'deadcode should be recognized in interactive mode');
+        assert.ok(!result.includes('Unknown command: related'), 'related should be recognized in interactive mode');
+        assert.ok(!result.includes('Unknown command: example'), 'example should be recognized in interactive mode');
+        assert.ok(!result.includes('Unknown command: verify'), 'verify should be recognized in interactive mode');
+        assert.ok(!result.includes('Unknown command: expand'), 'expand should be recognized in interactive mode');
+    });
+
+    it('help lists all commands', () => {
+        const result = execFileSync('node', [cliPath, '--interactive', '.'], {
+            input: 'help\nquit\n',
+            encoding: 'utf-8',
+            cwd: path.join(__dirname, '..'),
+            timeout: 30000,
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+
+        // Verify the help text includes all commands (including newly added ones)
+        const expectedCommands = ['expand', 'deadcode', 'related', 'example', 'verify', 'plan', 'stacktrace'];
+        for (const cmd of expectedCommands) {
+            assert.ok(result.includes(cmd), `Interactive help should list "${cmd}"`);
+        }
+    });
+});
+
 console.log('UCN v3 Test Suite');
 console.log('Run with: node --test test/parser.test.js');