ucn 3.7.18 → 3.7.19

package/core/execute.js

@@ -0,0 +1,376 @@
+/**
+ * Shared Command Executor — single dispatch for CLI, MCP, and interactive mode.
+ *
+ * Handles: input validation, exclude normalization, test exclusion, index calls.
+ * Does NOT handle: output formatting, expand caching, file I/O commands.
+ *
+ * Each handler returns { ok: true, result } or { ok: false, error }.
+ * Adapters handle formatting and surface-specific concerns.
+ */
+
+'use strict';
+
+const { addTestExclusions } = require('./shared');
+
+// Commands handled directly by adapters (not in HANDLERS below).
+// fn, class, lines need raw file content / line-range logic.
+// expand needs per-session cache state that differs by surface.
+const ADAPTER_ONLY_COMMANDS = new Set(['fn', 'class', 'lines', 'expand']);
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+function requireName(name) {
+    if (!name || (typeof name === 'string' && !name.trim())) {
+        return 'Symbol name is required.';
+    }
+    return null;
+}
+
+function requireFile(file) {
+    if (!file || (typeof file === 'string' && !file.trim())) {
+        return 'File parameter is required.';
+    }
+    return null;
+}
+
+function requireTerm(term) {
+    if (!term || (typeof term === 'string' && !term.trim())) {
+        return 'Search term is required.';
+    }
+    return null;
+}
+
+/** Normalize exclude to an array (accepts string CSV, array, or falsy). */
+function toExcludeArray(exclude) {
+    if (!exclude) return [];
+    if (Array.isArray(exclude)) return exclude;
+    return exclude.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/** Apply test exclusions unless includeTests is set. */
+function applyTestExclusions(exclude, includeTests) {
+    const arr = toExcludeArray(exclude);
+    return includeTests ? arr : addTestExclusions(arr);
+}
+
+/** Check if a file-based result has a file error. */
+function checkFileError(result, file) {
+    if (!result) return null;
+    if (result.error === 'file-not-found') {
+        return `File not found in project: ${file}`;
+    }
+    if (result.error === 'file-ambiguous') {
+        const candidates = result.candidates ? result.candidates.map(c => '  ' + c).join('\n') : '';
+        return `Ambiguous file "${file}". Candidates:\n${candidates}`;
+    }
+    return null;
+}
+
+/** Parse a number param (handles string from CLI, number from MCP). */
+function num(val, fallback) {
+    if (val == null) return fallback;
+    const n = Number(val);
+    return isNaN(n) ? fallback : n;
+}
+
+// ============================================================================
+// COMMAND HANDLERS
+// ============================================================================
+
+const HANDLERS = {
+
+    // ── Understanding Code ──────────────────────────────────────────────
+
+    about: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const result = index.about(p.name, {
+            withTypes: p.withTypes || false,
+            file: p.file,
+            all: p.all,
+            includeMethods: p.includeMethods,
+            includeUncertain: p.includeUncertain || false,
+            exclude: toExcludeArray(p.exclude),
+            maxCallers: num(p.top, undefined),
+            maxCallees: num(p.top, undefined),
+        });
+        return { ok: true, result };
+    },
+
+    context: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const result = index.context(p.name, {
+            includeMethods: p.includeMethods,
+            includeUncertain: p.includeUncertain || false,
+            file: p.file,
+            exclude: toExcludeArray(p.exclude),
+        });
+        if (!result) return { ok: false, error: `Symbol "${p.name}" not found.` };
+        return { ok: true, result };
+    },
+
+    impact: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const result = index.impact(p.name, {
+            file: p.file,
+            exclude: toExcludeArray(p.exclude),
+        });
+        return { ok: true, result };
+    },
+
+    smart: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const result = index.smart(p.name, {
+            file: p.file,
+            withTypes: p.withTypes || false,
+            includeMethods: p.includeMethods,
+            includeUncertain: p.includeUncertain || false,
+        });
+        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
+        return { ok: true, result };
+    },
+
+    trace: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const depthVal = num(p.depth, undefined);
+        const result = index.trace(p.name, {
+            depth: depthVal ?? 3,
+            file: p.file,
+            all: p.all || depthVal !== undefined,
+            includeMethods: p.includeMethods,
+            includeUncertain: p.includeUncertain || false,
+        });
+        return { ok: true, result };
+    },
+
+    example: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const result = index.example(p.name);
+        return { ok: true, result };
+    },
+
+    related: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const result = index.related(p.name, {
+            file: p.file,
+            top: num(p.top, undefined),
+            all: p.all,
+        });
+        return { ok: true, result };
+    },
+
+    // ── Finding Code ────────────────────────────────────────────────────
+
+    find: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const exclude = applyTestExclusions(p.exclude, p.includeTests);
+        const result = index.find(p.name, {
+            file: p.file,
+            exact: p.exact || false,
+            exclude,
+            in: p.in,
+        });
+        return { ok: true, result };
+    },
+
+    usages: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const exclude = applyTestExclusions(p.exclude, p.includeTests);
+        const result = index.usages(p.name, {
+            codeOnly: p.codeOnly || false,
+            context: num(p.context, 0),
+            exclude,
+            in: p.in,
+        });
+        return { ok: true, result };
+    },
+
+    toc: (index, p) => {
+        const result = index.getToc({
+            detailed: p.detailed,
+            topLevel: p.topLevel,
+            all: p.all,
+            top: num(p.top, undefined),
+        });
+        return { ok: true, result };
+    },
+
+    search: (index, p) => {
+        const err = requireTerm(p.term);
+        if (err) return { ok: false, error: err };
+        const exclude = applyTestExclusions(p.exclude, p.includeTests);
+        const result = index.search(p.term, {
+            codeOnly: p.codeOnly || false,
+            context: num(p.context, 0),
+            caseSensitive: p.caseSensitive || false,
+            exclude,
+            in: p.in,
+            regex: p.regex,
+        });
+        return { ok: true, result };
+    },
+
+    tests: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const result = index.tests(p.name, {
+            callsOnly: p.callsOnly || false,
+        });
+        return { ok: true, result };
+    },
+
+    deadcode: (index, p) => {
+        const result = index.deadcode({
+            includeExported: p.includeExported || false,
+            includeDecorated: p.includeDecorated || false,
+            includeTests: p.includeTests || false,
+            exclude: toExcludeArray(p.exclude),
+            in: p.in,
+        });
+        return { ok: true, result };
+    },
+
+    // ── File Dependencies ───────────────────────────────────────────────
+
+    imports: (index, p) => {
+        const err = requireFile(p.file);
+        if (err) return { ok: false, error: err };
+        const result = index.imports(p.file);
+        const fileErr = checkFileError(result, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        return { ok: true, result };
+    },
+
+    exporters: (index, p) => {
+        const err = requireFile(p.file);
+        if (err) return { ok: false, error: err };
+        const result = index.exporters(p.file);
+        const fileErr = checkFileError(result, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        return { ok: true, result };
+    },
+
+    fileExports: (index, p) => {
+        const err = requireFile(p.file);
+        if (err) return { ok: false, error: err };
+        const result = index.fileExports(p.file);
+        const fileErr = checkFileError(result, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        return { ok: true, result };
+    },
+
+    graph: (index, p) => {
+        const err = requireFile(p.file);
+        if (err) return { ok: false, error: err };
+        const result = index.graph(p.file, {
+            direction: p.direction || 'both',
+            maxDepth: num(p.depth, 2),
+        });
+        const fileErr = checkFileError(result, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        return { ok: true, result };
+    },
+
+    // ── Refactoring ─────────────────────────────────────────────────────
+
+    verify: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const result = index.verify(p.name, { file: p.file });
+        return { ok: true, result };
+    },
+
+    plan: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        if (!p.addParam && !p.removeParam && !p.renameTo) {
+            return { ok: false, error: 'Plan requires an operation: add_param, remove_param, or rename_to.' };
+        }
+        const result = index.plan(p.name, {
+            addParam: p.addParam,
+            removeParam: p.removeParam,
+            renameTo: p.renameTo,
+            defaultValue: p.defaultValue,
+            file: p.file,
+        });
+        return { ok: true, result };
+    },
+
+    diffImpact: (index, p) => {
+        const result = index.diffImpact({
+            base: p.base || 'HEAD',
+            staged: p.staged || false,
+            file: p.file,
+        });
+        return { ok: true, result };
+    },
+
+    // ── Other ───────────────────────────────────────────────────────────
+
+    typedef: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const result = index.typedef(p.name, { exact: p.exact || false });
+        return { ok: true, result };
+    },
+
+    stacktrace: (index, p) => {
+        if (!p.stack || (typeof p.stack === 'string' && !p.stack.trim())) {
+            return { ok: false, error: 'Stack trace text is required.' };
+        }
+        const result = index.parseStackTrace(p.stack);
+        return { ok: true, result };
+    },
+
+    api: (index, p) => {
+        const result = index.api(p.file);
+        if (p.file) {
+            const fileErr = checkFileError(result, p.file);
+            if (fileErr) return { ok: false, error: fileErr };
+        }
+        return { ok: true, result };
+    },
+
+    stats: (index, p) => {
+        const result = index.getStats({
+            functions: p.functions || false,
+        });
+        return { ok: true, result };
+    },
+};
+
+// ============================================================================
+// MAIN DISPATCH
+// ============================================================================
+
+/**
+ * Execute a UCN command.
+ *
+ * @param {object} index - Built ProjectIndex instance
+ * @param {string} command - Canonical command name (camelCase)
+ * @param {object} params - Normalized parameters
+ * @returns {{ ok: boolean, result?: any, error?: string }}
+ */
+function execute(index, command, params = {}) {
+    const handler = HANDLERS[command];
+    if (!handler) {
+        return { ok: false, error: `Unknown command: ${command}` };
+    }
+    try {
+        return handler(index, params);
+    } catch (e) {
+        return { ok: false, error: e.message };
+    }
+}
+
+module.exports = { execute, ADAPTER_ONLY_COMMANDS };

package/core/expand-cache.js

@@ -0,0 +1,162 @@
+/**
+ * Shared expand cache for context → expand workflow.
+ *
+ * Used by MCP server (in-memory, multi-symbol) and interactive mode (in-memory, session-scoped).
+ * CLI one-shot mode uses file-based persistence instead (separate processes).
+ *
+ * LRU eviction keeps memory bounded. Cache entries are keyed by project:symbol:file
+ * to support multiple concurrent context results per project.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+class ExpandCache {
+    /**
+     * @param {object} [opts]
+     * @param {number} [opts.maxSize=50] - Maximum cached context results
+     */
+    constructor({ maxSize = 50 } = {}) {
+        this.entries = new Map();     // cacheKey → { items, root, symbolName, usedAt }
+        this.lastKey = new Map();     // projectRoot → most recent cacheKey
+        this.maxSize = maxSize;
+    }
+
+    /**
+     * Save expandable items from a context result.
+     *
+     * @param {string} root - Project root path
+     * @param {string} name - Symbol name from the context call
+     * @param {string} [file] - Optional file filter used in the context call
+     * @param {Array} items - Expandable items from formatContext()
+     */
+    save(root, name, file, items) {
+        if (!items || items.length === 0) return;
+
+        const key = `${root}:${name}:${file || ''}`;
+
+        // LRU eviction if at capacity
+        if (this.entries.size >= this.maxSize && !this.entries.has(key)) {
+            let oldestKey = null;
+            let oldestTime = Infinity;
+            for (const [k, v] of this.entries) {
+                if ((v.usedAt || 0) < oldestTime) {
+                    oldestTime = v.usedAt || 0;
+                    oldestKey = k;
+                }
+            }
+            if (oldestKey) this.entries.delete(oldestKey);
+        }
+
+        this.entries.set(key, { items, root, symbolName: name, usedAt: Date.now() });
+        this.lastKey.set(root, key);
+    }
+
+    /**
+     * Look up an expandable item by number.
+     * Tries the most recent context for the project first, then falls back to all entries.
+     *
+     * @param {string} root - Project root path
+     * @param {number} itemNum - Item number to find
+     * @returns {{ match: object|null, itemCount: number, symbolName: string|null }}
+     */
+    lookup(root, itemNum) {
+        // Try most recent context for this project
+        const recentKey = this.lastKey.get(root);
+        const recent = recentKey ? this.entries.get(recentKey) : null;
+
+        if (recent && recent.items) {
+            recent.usedAt = Date.now();
+            const match = recent.items.find(i => i.num === itemNum);
+            if (match) {
+                return { match, itemCount: recent.items.length, symbolName: recent.symbolName };
+            }
+        }
+
+        // Fallback: scan all entries for this project
+        let maxCount = recent?.items?.length || 0;
+        for (const [, cached] of this.entries) {
+            if (cached.root === root && cached.items) {
+                cached.usedAt = Date.now();
+                maxCount = Math.max(maxCount, cached.items.length);
+                const found = cached.items.find(i => i.num === itemNum);
+                if (found) {
+                    return { match: found, itemCount: maxCount, symbolName: cached.symbolName };
+                }
+            }
+        }
+
+        return {
+            match: null,
+            itemCount: maxCount,
+            symbolName: recent?.symbolName || null
+        };
+    }
+
+    /**
+     * Clear all expand cache entries for a project root.
+     * Called when the project index is rebuilt (entries become stale).
+     *
+     * @param {string} root - Project root path
+     */
+    clearForRoot(root) {
+        for (const [key, cached] of this.entries) {
+            if (cached.root === root) this.entries.delete(key);
+        }
+        this.lastKey.delete(root);
+    }
+
+    /** Number of cached entries. */
+    get size() {
+        return this.entries.size;
+    }
+}
+
+/**
+ * Render an expand match to text lines.
+ * Shared by MCP and interactive mode to avoid duplicated rendering logic.
+ *
+ * @param {object} match - Expandable item from formatContext()
+ * @param {string} root - Project root path
+ * @param {object} [opts]
+ * @param {boolean} [opts.validateRoot=false] - Validate file is within project root (MCP security)
+ * @returns {{ ok: boolean, text?: string, error?: string }}
+ */
+function renderExpandItem(match, root, { validateRoot = false } = {}) {
+    const filePath = match.file || (root && match.relativePath ? path.join(root, match.relativePath) : null);
+    if (!filePath || !fs.existsSync(filePath)) {
+        return { ok: false, error: `Cannot locate file for ${match.name}` };
+    }
+
+    if (validateRoot && root) {
+        try {
+            const realPath = fs.realpathSync(filePath);
+            const realRoot = fs.realpathSync(root);
+            if (realPath !== realRoot && !realPath.startsWith(realRoot + path.sep)) {
+                return { ok: false, error: `File is outside project root: ${match.name}` };
+            }
+        } catch (e) {
+            return { ok: false, error: `Cannot resolve file path for ${match.name}` };
+        }
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const fileLines = content.split('\n');
+    const startLine = match.startLine || match.line || 1;
+    const endLine = match.endLine || startLine + 20;
+
+    const lines = [];
+    lines.push(`[${match.num}] ${match.name} (${match.type})`);
+    lines.push(`${match.relativePath}:${startLine}-${endLine}`);
+    lines.push('\u2550'.repeat(60));
+
+    for (let i = startLine - 1; i < Math.min(endLine, fileLines.length); i++) {
+        lines.push(fileLines[i]);
+    }
+
+    return { ok: true, text: lines.join('\n') };
+}
+
+module.exports = { ExpandCache, renderExpandItem };

package/core/project.js

@@ -12,7 +12,7 @@ const { execSync, execFileSync } = require('child_process');
 const { expandGlob, findProjectRoot, detectProjectPattern, isTestFile, parseGitignore, DEFAULT_IGNORES } = require('./discovery');
 const { extractImports, extractExports, resolveImport } = require('./imports');
 const { parse, parseFile, cleanHtmlScriptTags } = require('./parser');
-const { detectLanguage, getParser, getLanguageModule, PARSE_OPTIONS, safeParse } = require('../languages');
+const { detectLanguage, getParser, getLanguageModule, safeParse } = require('../languages');
 const { getTokenTypeAtPosition } = require('../languages/utils');
 
 // Read UCN version for cache invalidation
@@ -1510,7 +1510,7 @@ class ProjectIndex {
                 return false;
             }
 
-            const tree = parser.parse(content, undefined, PARSE_OPTIONS);
+            const tree = safeParse(parser, content);
 
             // Find all occurrences of name in the line
             const nameRegex = new RegExp('(?<![a-zA-Z0-9_$])' + escapeRegExp(name) + '(?![a-zA-Z0-9_$])', 'g');
@@ -2116,7 +2116,7 @@ class ProjectIndex {
                 return false;
             }
 
-            const tree = parser.parse(content, undefined, PARSE_OPTIONS);
+            const tree = safeParse(parser, content);
             const tokenType = getTokenTypeAtPosition(tree.rootNode, lineNum, column);
             return tokenType === 'comment' || tokenType === 'string';
         } catch (e) {
@@ -2788,12 +2788,12 @@ class ProjectIndex {
                     if (blocks.length === 0 && !htmlModule.extractEventHandlerCalls) continue;
                     if (blocks.length > 0) {
                         const virtualJS = htmlModule.buildVirtualJSContent(content, blocks);
-                        tree = jsParser.parse(virtualJS, undefined, PARSE_OPTIONS);
+                        tree = safeParse(jsParser, virtualJS);
                     }
                 } else {
                     const parser = getParser(language);
                     if (!parser) continue;
-                    tree = parser.parse(content, undefined, PARSE_OPTIONS);
+                    tree = safeParse(parser, content);
                 }
 
                 // Collect all identifiers from this file in one pass
@@ -5005,7 +5005,7 @@ class ProjectIndex {
 
             const parser = getParser(language);
             const content = this._readFile(filePath);
-            const tree = parser.parse(content, undefined, PARSE_OPTIONS);
+            const tree = safeParse(parser, content);
 
             const row = lineNum - 1;
             const node = tree.rootNode.descendantForPosition({ row, column: 0 });
@@ -5067,6 +5067,11 @@ class ProjectIndex {
         try {
         const { base = 'HEAD', staged = false, file } = options;
 
+        // Validate base ref format to prevent argument injection
+        if (base && !/^[a-zA-Z0-9._\-~\/^@{}:]+$/.test(base)) {
+            throw new Error(`Invalid git ref format: ${base}`);
+        }
+
         // Verify git repo
         let gitRoot;
         try {