ucn 3.7.4 → 3.7.5

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/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 '';
         }
     }
@@ -2354,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 {
@@ -2368,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';
                             }
@@ -4409,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.');
@@ -465,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');
@@ -490,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');
@@ -542,13 +573,8 @@ server.registerTool(
                     return toolError('Line range is required (e.g. "10-20" or "15").');
                 }
                 const index = getIndex(project_dir);
-                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}`);
-                }
+                const resolved = resolveAndValidatePath(index, file);
+                if (typeof resolved !== 'string') return resolved; // toolError response
                 const filePath = resolved;
 
                 const parts = range.split('-');
@@ -631,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');
@@ -732,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',

package/package.json

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

@@ -411,6 +411,59 @@ const tests = [
         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
+    },
 ];
 
 // ============================================================================

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');