ucn 3.8.23 → 3.8.25

package/core/execute.js

@@ -12,7 +12,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { addTestExclusions, pickBestDefinition } = require('./shared');
+const { addTestExclusions, pickBestDefinition, parseSymbolHandle, looksLikeHandle } = require('./shared');
 const { cleanHtmlScriptTags, detectLanguage } = require('./parser');
 const { renderExpandItem } = require('./expand-cache');
 
@@ -66,6 +66,8 @@ function splitClassMethod(name) {
  * part (explicit --class-name takes precedence over the class from dot notation).
  */
 function applyClassMethodSyntax(p) {
+    // Run handle normalization first — handles can be passed where a name is expected.
+    applyHandleSyntax(p);
     const split = splitClassMethod(p.name);
     if (split) {
         p.name = split.methodName;
@@ -73,6 +75,28 @@ function applyClassMethodSyntax(p) {
     }
 }
 
+/**
+ * If p.name is a stable handle (file:line[:name]), parse it and set p.name,
+ * p.file, p.line so downstream resolution targets the exact symbol. Idempotent.
+ *
+ * Why: lets multi-step workflows roundtrip without name disambiguation. A
+ * `find` result emits `lib/api.ts:42:handler`; piping that to `brief`/`impact`
+ * pins resolution to that exact definition even if 5 other `handler`s exist.
+ */
+function applyHandleSyntax(p) {
+    if (!p || !p.name) return;
+    if (!looksLikeHandle(p.name)) return;
+    const h = parseSymbolHandle(p.name);
+    if (!h) return;
+    // Pull name out of handle. If the handle has no name suffix, we need to
+    // recover it from the index — but at this layer we only have params.
+    // The downstream resolveSymbol path will look up by file+line if name is empty.
+    if (h.name) p.name = h.name;
+    // Only override p.file/p.line if they weren't explicitly set by the user
+    if (h.file && !p.file) p.file = h.file;
+    if (h.line && !p.line) p.line = h.line;
+}
+
 /** Normalize exclude to an array (accepts string CSV, array, or falsy). */
 function toExcludeArray(exclude) {
     if (!exclude) return [];
@@ -94,6 +118,7 @@ function buildCallerOptions(p) {
     return {
         file: p.file,
         className: p.className,
+        ...(p.line && { line: p.line }),
         includeMethods: p.includeMethods,
         includeUncertain: p.includeUncertain || false,
         includeTests: p.includeTests,
@@ -232,6 +257,8 @@ const HANDLERS = {
             all: p.all,
             maxCallers: num(p.top, undefined),
             maxCallees: num(p.top, undefined),
+            unreachableOnly: !!p.unreachableOnly,
+            git: !!p.git,
         });
         if (!result) {
             // Give better error if file/className filter is the problem
@@ -264,6 +291,7 @@ const HANDLERS = {
         if (classErr) return { ok: false, error: classErr };
         const result = index.context(p.name, {
             ...buildCallerOptions(p),
+            unreachableOnly: !!p.unreachableOnly,
         });
         if (!result) return { ok: false, error: `Symbol "${p.name}" not found.` };
         const tNote = truncationNote(index);
@@ -283,6 +311,13 @@ const HANDLERS = {
             className: p.className,
             exclude: toExcludeArray(p.exclude),
             top: num(p.top, undefined),
+            unreachableOnly: !!p.unreachableOnly,
+            // BUG-H3: pass through user-supplied flags. impact defaults to including
+            // method calls because "what breaks if I change this" should include
+            // every callable site, not just bare-name calls. User can disable with
+            // --no-include-methods.
+            ...(p.includeMethods !== undefined && { includeMethods: p.includeMethods }),
+            ...(p.includeUncertain !== undefined && { includeUncertain: p.includeUncertain }),
         });
         if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
         const tNote = truncationNote(index);
@@ -377,8 +412,25 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
-        const result = index.example(p.name, { file: p.file, className: p.className });
+        const result = index.example(p.name, {
+            file: p.file,
+            className: p.className,
+            diverse: !!p.diverse,
+            top: num(p.top, undefined),
+            // MEDIUM-8: thread includeTests so test-file callers are included
+            // when the user asks for them.
+            includeTests: !!p.includeTests,
+        });
         if (!result) return { ok: false, error: `No examples found for "${p.name}".` };
+        // MEDIUM-8: when no non-test examples found but test-file usages
+        // exist, return success with a note so the user knows to retry.
+        if (!result.best && result.excludedTestCalls > 0) {
+            return {
+                ok: true,
+                result,
+                note: `0 examples found (excluded ${result.excludedTestCalls} test-file usage${result.excludedTestCalls === 1 ? '' : 's'} — pass --include-tests to include them)`,
+            };
+        }
         return { ok: true, result };
     },
 
@@ -408,6 +460,46 @@ const HANDLERS = {
         return { ok: true, result, ...(combined && { note: combined }) };
     },
 
+    brief: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        const classErr = validateClassName(index, p.name, p.className);
+        if (classErr) return { ok: false, error: classErr };
+        const { brief } = require('./brief');
+        const result = brief(index, p.name, { file: p.file, className: p.className, git: !!p.git });
+        if (!result) return { ok: false, error: `Symbol "${p.name}" not found.` };
+        return { ok: true, result };
+    },
+
+    doctor: (index, p) => {
+        const { doctor } = require('./reporting');
+        const result = doctor(index, {
+            in: p.in,
+            file: p.file,
+            deep: !!p.deep,
+            sampleSize: num(p.limit, undefined),
+        });
+        return { ok: true, result };
+    },
+
+    check: (index, p) => {
+        const { check } = require('./check');
+        try {
+            const result = check(index, {
+                base: p.base || 'HEAD',
+                staged: !!p.staged,
+                file: p.file,
+                limit: num(p.limit, undefined),
+            });
+            return { ok: true, result };
+        } catch (e) {
+            return { ok: false, error: e && e.message ? e.message : String(e) };
+        }
+    },
+
     // ── Finding Code ────────────────────────────────────────────────────
 
     find: (index, p) => {
@@ -669,7 +761,17 @@ const HANDLERS = {
         const fileErr = checkFilePatternMatch(index, p.file);
         if (fileErr) return { ok: false, error: fileErr };
         const { detectEntrypoints } = require('./entrypoints');
-        const exclude = applyTestExclusions(p.exclude, p.includeTests);
+        // JAVA-2: tests ARE entry points (JUnit @Test, pytest fixtures,
+        // Rust #[test], etc.) — show them by default. Previously this command
+        // applied addTestExclusions() unconditionally, which stripped Java
+        // *Tests.java entries while letting Rust #[test] through (asymmetric).
+        // Now consistent: default = include test entries; user opts out via
+        // --exclude-tests (or --include-tests=false for back-compat).
+        const userExclude = Array.isArray(p.exclude)
+            ? p.exclude
+            : (p.exclude ? p.exclude.split(',').map(s => s.trim()).filter(Boolean) : []);
+        const wantsExcludeTests = p.excludeTests === true || p.includeTests === false;
+        const exclude = wantsExcludeTests ? addTestExclusions(userExclude) : userExclude;
         let result = detectEntrypoints(index, {
             type: p.type,
             framework: p.framework,
@@ -685,6 +787,99 @@ const HANDLERS = {
         return { ok: true, result, note };
     },
 
+    endpoints: (index, p) => {
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        // Minor polish: validate --method against known HTTP verbs to catch
+        // typos that would otherwise silently filter out everything.
+        // 'ALL' / 'USE' are downstream route labels that can be queried explicitly.
+        const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS', 'HEAD', 'ALL', 'USE']);
+        let normMethod = null;
+        if (p.method != null && String(p.method).trim() !== '') {
+            normMethod = String(p.method).trim().toUpperCase();
+            if (!HTTP_METHODS.has(normMethod)) {
+                return {
+                    ok: false,
+                    error: `Invalid --method value: "${p.method}". Expected one of ${[...HTTP_METHODS].join(', ')}.`,
+                };
+            }
+        }
+        const { endpoints } = require('./bridge');
+        // HIGH-2: --unmatched implies --bridge (we need bridges to know what's
+        // unmatched). Without bridges computed, we can't separate matched from
+        // unmatched on either side.
+        const wantUnmatched = !!p.unmatched;
+        const wantBridge = !!p.bridge || wantUnmatched;
+        const result = endpoints(index, {
+            bridge: wantBridge,
+            serverOnly: !!p.serverOnly,
+            clientOnly: !!p.clientOnly,
+            unmatched: wantUnmatched,
+            method: normMethod,
+            prefix: p.prefix || null,
+            showUncertain: !p.hideUncertain,
+        });
+        // Apply --file pattern as an additional filter on routes/requests
+        if (p.file) {
+            const sub = String(p.file);
+            result.routes = result.routes.filter(r => r.file.includes(sub));
+            result.requests = result.requests.filter(r => r.file.includes(sub));
+            result.bridges = result.bridges.filter(b =>
+                b.route.file.includes(sub) || b.request.file.includes(sub)
+            );
+            result.unmatchedRoutes = result.unmatchedRoutes.filter(r => r.file.includes(sub));
+            result.unmatchedRequests = result.unmatchedRequests.filter(r => r.file.includes(sub));
+        }
+        // Apply --exclude patterns to route/request files (deadcode-style boundary matching)
+        const exclude = toExcludeArray(p.exclude);
+        if (exclude.length > 0) {
+            const regexes = exclude.map(pat =>
+                new RegExp('(^|[/._-])' + pat + 's?([/._-]|$)', 'i'));
+            const matches = (file) => regexes.some(rx => rx.test(file));
+            result.routes = result.routes.filter(r => !matches(r.file));
+            result.requests = result.requests.filter(r => !matches(r.file));
+            result.bridges = result.bridges.filter(b => !matches(b.route.file) && !matches(b.request.file));
+            result.unmatchedRoutes = result.unmatchedRoutes.filter(r => !matches(r.file));
+            result.unmatchedRequests = result.unmatchedRequests.filter(r => !matches(r.file));
+        }
+        // Apply --limit
+        const limit = num(p.limit, undefined);
+        let note;
+        if (limit && limit > 0) {
+            const totalListed = result.routes.length + result.requests.length;
+            if (totalListed > limit) {
+                // Limit each list proportionally — but simpler: hard-cap each.
+                const halfLim = Math.max(1, Math.floor(limit / 2));
+                if (result.routes.length > halfLim) {
+                    result.routes = result.routes.slice(0, halfLim);
+                }
+                if (result.requests.length > halfLim) {
+                    result.requests = result.requests.slice(0, halfLim);
+                }
+                note = limitNote(limit, totalListed);
+            }
+        }
+        // Recompute meta after filtering
+        result.meta = {
+            totalRoutes: result.routes.length,
+            totalRequests: result.requests.length,
+            totalBridges: result.bridges.length,
+            unmatchedRoutes: result.unmatchedRoutes.length,
+            unmatchedRequests: result.unmatchedRequests.length,
+            byFramework: result.routes.reduce((acc, r) => {
+                acc[r.framework] = (acc[r.framework] || 0) + 1;
+                return acc;
+            }, {}),
+        };
+        // Pass display flags through to formatter via result properties.
+        // (HIGH-2: --unmatched implies --bridge for computation, but the
+        // formatter needs to know which mode the user ASKED for so it can
+        // suppress the "Matched" section in unmatched-only mode.)
+        result._bridge = wantBridge;
+        result._unmatched = wantUnmatched;
+        return { ok: true, result, note };
+    },
+
     // ── Extracting Code ─────────────────────────────────────────────────
 
     fn: (index, p) => {
@@ -909,6 +1104,9 @@ const HANDLERS = {
             direction: p.direction || 'both',
             maxDepth: num(p.depth, 2),
         });
+        if (result && result.error === 'invalid-direction') {
+            return { ok: false, error: result.message };
+        }
         const fileErr = checkFileError(result, p.file);
         if (fileErr) return { ok: false, error: fileErr };
         return { ok: true, result };
@@ -932,7 +1130,16 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
-        const result = index.verify(p.name, { file: p.file, className: p.className });
+        const result = index.verify(p.name, {
+            file: p.file,
+            className: p.className,
+            // BUG-H3: pass through user-supplied flags. Verify defaults to including
+            // method calls (current behavior) so call-arity checks reach all forms,
+            // including obj.method() invocations. User can disable with
+            // --no-include-methods.
+            ...(p.includeMethods !== undefined && { includeMethods: p.includeMethods }),
+            ...(p.includeUncertain !== undefined && { includeUncertain: p.includeUncertain }),
+        });
         return { ok: true, result };
     },
 
@@ -1017,10 +1224,69 @@ const HANDLERS = {
     },
 
     stats: (index, p) => {
+        // MEDIUM-7: validate `--top`. Previously non-numeric, zero, and
+        // negative values silently fell back to 10 — confusing when a typo
+        // hides a request to show MORE entries.
+        // BUG-2: reject 0 and negative explicitly — the rendering ("top 0 of
+        // 718 called: (no inbound calls detected)") was misleading because
+        // it implied no calls exist when the user simply asked for nothing.
+        let top;
+        let note;
+        if (p.top != null) {
+            const raw = String(p.top).trim();
+            const n = Number(raw);
+            if (raw === '' || isNaN(n) || !isFinite(n)) {
+                return {
+                    ok: false,
+                    error: `Invalid --top value: must be a positive integer (got "${p.top}")`,
+                };
+            }
+            if (!Number.isInteger(n)) {
+                return {
+                    ok: false,
+                    error: `Invalid --top value: must be an integer (got ${n})`,
+                };
+            }
+            if (n <= 0) {
+                return {
+                    ok: false,
+                    error: `Invalid --top value: must be a positive integer (got ${n})`,
+                };
+            }
+            if (n > 10000) {
+                top = 10000;
+                note = `--top capped at 10000 (requested ${n})`;
+            } else {
+                top = n;
+            }
+        }
         const result = index.getStats({
             functions: p.functions || false,
+            hot: p.hot || false,
+            top,
         });
-        return { ok: true, result };
+        return note ? { ok: true, result, note } : { ok: true, result };
+    },
+
+    auditAsync: (index, p) => {
+        if (p.file) {
+            const fileErr = checkFilePatternMatch(index, p.file);
+            if (fileErr) return { ok: false, error: fileErr };
+        }
+        let result = index.auditAsync({
+            file: p.file,
+            exclude: toExcludeArray(p.exclude),
+        });
+        // Apply limit to the issues array.
+        const limit = num(p.limit, undefined);
+        let note;
+        if (limit && limit > 0 && result && Array.isArray(result.issues) && result.issues.length > limit) {
+            note = limitNote(limit, result.issues.length);
+            result = { ...result, issues: result.issues.slice(0, limit) };
+        }
+        const tNote = truncationNote(index);
+        if (tNote) note = note ? `${note}\n${tNote}` : tNote;
+        return { ok: true, result, note };
     },
 
     // ── Expand (context drill-down) ──────────────────────────────────────
@@ -1060,10 +1326,43 @@ function execute(index, command, params = {}) {
         return { ok: false, error: `Unknown command: ${command}` };
     }
     try {
+        // Resolve name-less handles (e.g. `lib.js:42`) via index lookup before dispatch.
+        // Handles WITH a name suffix are handled later by applyClassMethodSyntax.
+        if (params && params.name && looksLikeHandle(params.name)) {
+            const h = parseSymbolHandle(params.name);
+            if (h && !h.name && h.file && h.line) {
+                const sym = lookupByLocation(index, h.file, h.line);
+                if (sym) {
+                    params.name = sym.name;
+                    if (!params.file) params.file = h.file;
+                    if (!params.line) params.line = h.line;
+                }
+            }
+        }
         return handler(index, params);
     } catch (e) {
         return { ok: false, error: e.message };
     }
 }
 
+/**
+ * Look up a symbol record by file path + start line. Used to recover a name
+ * from a name-less handle (`relativePath:line`). Returns the first matching
+ * symbol or null. Path matching is permissive (substring) so handles emitted
+ * with relative paths still resolve when callers pass partial paths.
+ */
+function lookupByLocation(index, file, line) {
+    if (!index || !index.symbols || !file || !line) return null;
+    for (const arr of index.symbols.values()) {
+        for (const sym of arr) {
+            if (sym.startLine !== line) continue;
+            const rp = sym.relativePath || '';
+            if (rp === file || rp.endsWith('/' + file) || file.endsWith('/' + rp) || rp.includes(file)) {
+                return sym;
+            }
+        }
+    }
+    return null;
+}
+
 module.exports = { execute };

package/core/git-enrich.js

@@ -0,0 +1,130 @@
+/**
+ * core/git-enrich.js — Optional git enrichment for about/brief output.
+ *
+ * Pure shell-out to `git log` — no parsing libraries, no LLM. Returns
+ * `{ available: false }` for any failure (not a repo, file untracked,
+ * git missing) so callers can render gracefully.
+ *
+ * Cached per (root, relPath) for the lifetime of the process — git history
+ * doesn't change mid-command, and `about` / `brief` may be invoked many
+ * times against the same files in interactive/MCP sessions.
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+// Module-level cache: `${projectRoot}::${relPath}` → enrichment object.
+// Process-lifetime is correct here — across-process invocations re-shell-out,
+// which is fine (git is fast enough), and within a process the cache prevents
+// hammering git for the same file when an agent runs `about` then `brief`.
+const _cache = new Map();
+
+const GIT_TIMEOUT_MS = 2000;
+
+/**
+ * Get git info for a file path inside a project.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @param {string} relativeFilePath - Relative path inside the project
+ * @returns {{ available: boolean, lastModified?: string, author?: string, recentChanges?: number, error?: string }}
+ */
+function getGitInfo(projectRoot, relativeFilePath) {
+    if (!projectRoot || !relativeFilePath) {
+        return { available: false, error: 'missing projectRoot or path' };
+    }
+    // Normalize to forward slashes for git on Windows
+    const relPath = relativeFilePath.split(path.sep).join('/');
+    const cacheKey = `${projectRoot}::${relPath}`;
+    if (_cache.has(cacheKey)) return _cache.get(cacheKey);
+
+    let info;
+    try {
+        // Last commit touching this file: ISO timestamp + author name.
+        // Use --follow to track renames, but only if the file exists in history.
+        // We capture stderr so we can classify failure modes (not-a-repo,
+        // file-not-tracked, timeout) instead of leaking the raw shell error
+        // to the caller (MEDIUM-9).
+        const lastLine = execFileSync(
+            'git',
+            ['log', '-1', '--format=%aI|%an', '--', relPath],
+            {
+                cwd: projectRoot,
+                encoding: 'utf-8',
+                timeout: GIT_TIMEOUT_MS,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            }
+        ).trim();
+
+        if (!lastLine) {
+            // File exists but no git history — likely untracked
+            info = { available: false, error: 'File not tracked' };
+        } else {
+            const [lastModified, author] = lastLine.split('|');
+
+            // Count of commits in the last 30 days that touched this file.
+            // We use a one-line --format and count rather than --oneline | wc -l
+            // to avoid platform shell differences.
+            const recentLines = execFileSync(
+                'git',
+                ['log', '--since=30 days ago', '--format=%H', '--', relPath],
+                {
+                    cwd: projectRoot,
+                    encoding: 'utf-8',
+                    timeout: GIT_TIMEOUT_MS,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                }
+            ).trim();
+            const recentChanges = recentLines === '' ? 0 : recentLines.split('\n').length;
+
+            info = {
+                available: true,
+                lastModified: lastModified || null,
+                author: author || null,
+                recentChanges,
+            };
+        }
+    } catch (e) {
+        // MEDIUM-9: never leak the raw shell command back to the user (which
+        // includes the path being queried — looks like a stack trace and is
+        // surface-level confusing in JSON output). Classify and translate.
+        info = { available: false, error: classifyGitError(e) };
+    }
+
+    _cache.set(cacheKey, info);
+    return info;
+}
+
+/**
+ * Translate a git execFileSync exception into a user-friendly error string.
+ * Inspects exit code, signal, and (when captured) stderr text to pick the
+ * right category. Falls back to a generic "Git unavailable" rather than
+ * leaking the underlying command — the caller renders this as JSON / text.
+ */
+function classifyGitError(e) {
+    if (!e) return 'Git unavailable';
+    // Timeout: child_process throws ENOENT-like errors with `signal: 'SIGTERM'`
+    // or `killed: true` when the timeout fires.
+    if (e.signal === 'SIGTERM' || e.killed === true) return 'Git timed out';
+    // git binary not installed
+    if (e.code === 'ENOENT') return 'Git not installed';
+    // Inspect stderr if captured
+    const stderr = e.stderr ? String(e.stderr) : '';
+    const lower = stderr.toLowerCase();
+    if (lower.includes('not a git repository')) return 'Not a git repository';
+    if (lower.includes("did not match any file") ||
+        lower.includes('pathspec') && lower.includes('did not match')) {
+        return 'File not tracked';
+    }
+    // Exit 128 commonly means "fatal" git error — we already caught the
+    // common cases above, so anything else is generic.
+    return 'Git unavailable';
+}
+
+/** Test helper: clear the in-process cache. */
+function _clearCache() {
+    _cache.clear();
+}
+
+module.exports = { getGitInfo, _clearCache };

package/core/graph.js

@@ -179,11 +179,18 @@ function fileExports(index, filePath, _visited) {
     const results = [];
     const exportedNames = new Set(fileEntry.exports);
 
+    // Python convention: when a module declares no `__all__`, every top-level
+    // non-`_` name is considered public. We don't want this in the underlying
+    // export list (deadcode would think everything is exported), so fileExports
+    // applies it locally for display.
+    const isPythonImplicit = fileEntry.language === 'python' && exportedNames.size === 0;
+
     for (const symbol of fileEntry.symbols) {
         const isExported = exportedNames.has(symbol.name) ||
             (symbol.modifiers && symbol.modifiers.includes('export')) ||
             (symbol.modifiers && symbol.modifiers.includes('public')) ||
-            (langTraits(fileEntry.language)?.exportVisibility === 'capitalization' && /^[A-Z]/.test(symbol.name));
+            (langTraits(fileEntry.language)?.exportVisibility === 'capitalization' && /^[A-Z]/.test(symbol.name)) ||
+            (isPythonImplicit && symbol.name && !symbol.name.startsWith('_') && !symbol.className && !symbol.isMethod);
 
         if (isExported) {
             results.push({
@@ -443,7 +450,22 @@ function api(index, filePath, options = {}) {
  * @returns {object} - Graph structure with root, nodes, edges
  */
 function graph(index, filePath, options = {}) {
-    const direction = options.direction || 'both';
+    // Normalize direction. Accept aliases (`in` ≡ importers, `out` ≡ imports),
+    // reject anything else with an explicit error so users don't get a silent
+    // empty-graph answer.
+    const rawDirection = options.direction || 'both';
+    const DIRECTION_ALIASES = {
+        'imports': 'imports', 'out': 'imports', 'outgoing': 'imports', 'downstream': 'imports',
+        'importers': 'importers', 'in': 'importers', 'incoming': 'importers', 'upstream': 'importers',
+        'both': 'both',
+    };
+    const direction = DIRECTION_ALIASES[rawDirection];
+    if (!direction) {
+        return {
+            error: 'invalid-direction',
+            message: `Unknown direction "${rawDirection}". Valid: imports/out/outgoing/downstream, importers/in/incoming/upstream, both.`,
+        };
+    }
     // Sanitize depth: use default for null/undefined, clamp negative to 0
     const rawDepth = options.maxDepth ?? 5;
     const maxDepth = Math.max(0, rawDepth);