ucn 3.8.22 → 3.8.25

package/core/project.js

@@ -77,6 +77,7 @@ class ProjectIndex {
             this._opContentCache = new Map();
             this._opUsagesCache = new Map();
             this._opCallsCountCache = new Map();
+            this._opEnclosingFnCache = new Map();
             this._opDepth = 0;
         }
         this._opDepth++;
@@ -84,10 +85,17 @@ class ProjectIndex {
 
     /** End a per-operation content cache scope (only clears when outermost scope ends) */
     _endOp() {
+        if (!this._opContentCache) return; // Mismatched call — no active operation
         if (--this._opDepth <= 0) {
             this._opContentCache = null;
             this._opUsagesCache = null;
             this._opCallsCountCache = null;
+            this._opEnclosingFnCache = null;
+            // Free cached file content from callsCache entries (retained during
+            // operation for _readFile caching, not needed between operations)
+            for (const entry of this.callsCache.values()) {
+                if (entry.content !== undefined) entry.content = undefined;
+            }
             this._opDepth = 0;
         }
     }
@@ -215,6 +223,9 @@ class ProjectIndex {
         // Always invalidate caches on rebuild
         this._completenessCache = null;
         this._attrTypeCache = null;
+        // Endpoints cache (server routes / client requests / bridges) becomes
+        // stale when files change; clear on every rebuild.
+        this._endpointsCache = null;
 
         let indexed = 0;
         let changed = 0;
@@ -395,6 +406,9 @@ class ProjectIndex {
                 params: item.params,
                 paramsStructured: item.paramsStructured,
                 returnType: item.returnType,
+                ...(item.paramTypes && { paramTypes: item.paramTypes }),
+                ...(item.isAsync && { isAsync: true }),
+                ...(item.isGenerator && { isGenerator: true }),
                 modifiers: item.modifiers,
                 docstring: item.docstring,
                 bindingId: `${fileEntry.relativePath}:${type}:${item.startLine}`,
@@ -409,6 +423,13 @@ class ProjectIndex {
                 ...(item.memberType && { memberType: item.memberType }),
                 ...(item.fieldType && { fieldType: item.fieldType }),
                 ...(item.decorators && item.decorators.length > 0 && { decorators: item.decorators }),
+                // Decorator/annotation/attribute argument capture for endpoints command:
+                // these fields hold the parsed first-string-arg of each route-style annotation.
+                // Only populated when at least one entry has a string-literal arg, keeping memory
+                // overhead minimal for non-route code.
+                ...(item.decoratorsWithArgs && item.decoratorsWithArgs.length > 0 && { decoratorsWithArgs: item.decoratorsWithArgs }),
+                ...(item.annotationsWithArgs && item.annotationsWithArgs.length > 0 && { annotationsWithArgs: item.annotationsWithArgs }),
+                ...(item.attributesWithArgs && item.attributesWithArgs.length > 0 && { attributesWithArgs: item.attributesWithArgs }),
                 ...(item.nameLine && { nameLine: item.nameLine }),
                 ...(item.traitImpl && { traitImpl: true }),
                 ...(item.isSignature && { isSignature: true })
@@ -474,14 +495,20 @@ class ProjectIndex {
             }
         }
 
-        // Invalidate cached call data for this file
+        // Incrementally update callee index before deleting cached calls
+        const oldCached = this.callsCache.get(filePath);
+        if (oldCached) {
+            this._removeFromCalleeIndex(filePath, oldCached.calls);
+        }
         this.callsCache.delete(filePath);
 
-        // Invalidate callee index (will be rebuilt lazily)
-        this.calleeIndex = null;
-
         // Invalidate attribute type cache for this file
         if (this._attrTypeCache) this._attrTypeCache.delete(filePath);
+
+        // Invalidate lazy Java file index (will be rebuilt on next use)
+        this._javaFileIndex = null;
+        // Endpoints cache is project-wide; safest to clear on any file removal.
+        this._endpointsCache = null;
     }
 
     /**
@@ -490,6 +517,61 @@ class ProjectIndex {
      */
     _buildDirIndex() { graphBuildModule.buildDirIndex(this); }
 
+    /**
+     * Add a file's calls to the callee index (name → Set<filePath>).
+     * Used by buildCalleeIndex (full build) and getCachedCalls (incremental update).
+     */
+    _addToCalleeIndex(filePath, calls) {
+        if (!this.calleeIndex || !calls) return;
+        for (const call of calls) {
+            const name = call.name;
+            if (!this.calleeIndex.has(name)) {
+                this.calleeIndex.set(name, new Set());
+            }
+            this.calleeIndex.get(name).add(filePath);
+            if (call.resolvedName && call.resolvedName !== name) {
+                if (!this.calleeIndex.has(call.resolvedName)) {
+                    this.calleeIndex.set(call.resolvedName, new Set());
+                }
+                this.calleeIndex.get(call.resolvedName).add(filePath);
+            }
+            if (call.resolvedNames) {
+                for (const rn of call.resolvedNames) {
+                    if (rn !== name) {
+                        if (!this.calleeIndex.has(rn)) {
+                            this.calleeIndex.set(rn, new Set());
+                        }
+                        this.calleeIndex.get(rn).add(filePath);
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * Remove a file's calls from the callee index.
+     * Used by removeFileSymbols for incremental updates instead of full invalidation.
+     */
+    _removeFromCalleeIndex(filePath, calls) {
+        if (!this.calleeIndex || !calls) return;
+        for (const call of calls) {
+            const removeName = (n) => {
+                const fileSet = this.calleeIndex.get(n);
+                if (fileSet) {
+                    fileSet.delete(filePath);
+                    if (fileSet.size === 0) this.calleeIndex.delete(n);
+                }
+            };
+            removeName(call.name);
+            if (call.resolvedName && call.resolvedName !== call.name) removeName(call.resolvedName);
+            if (call.resolvedNames) {
+                for (const rn of call.resolvedNames) {
+                    if (rn !== call.name) removeName(rn);
+                }
+            }
+        }
+    }
+
     /**
      * Build inverted call index: callee name -> Set<filePath>.
      * Built lazily on first findCallers call, from the calls cache.
@@ -497,37 +579,15 @@ class ProjectIndex {
      */
     buildCalleeIndex() {
         const { getCachedCalls } = require('./callers');
+        const { ensureCallsCacheLoaded } = require('./cache');
+        ensureCallsCacheLoaded(this);
         this.calleeIndex = new Map();
 
         for (const [filePath] of this.files) {
             // Fast path: use pre-populated callsCache (avoids stat per file)
             const cached = this.callsCache.get(filePath);
             const calls = cached ? cached.calls : getCachedCalls(this, filePath);
-            if (!calls) continue;
-            for (const call of calls) {
-                const name = call.name;
-                if (!this.calleeIndex.has(name)) {
-                    this.calleeIndex.set(name, new Set());
-                }
-                this.calleeIndex.get(name).add(filePath);
-                // Also index resolvedName and resolvedNames for alias resolution
-                if (call.resolvedName && call.resolvedName !== name) {
-                    if (!this.calleeIndex.has(call.resolvedName)) {
-                        this.calleeIndex.set(call.resolvedName, new Set());
-                    }
-                    this.calleeIndex.get(call.resolvedName).add(filePath);
-                }
-                if (call.resolvedNames) {
-                    for (const rn of call.resolvedNames) {
-                        if (rn !== name) {
-                            if (!this.calleeIndex.has(rn)) {
-                                this.calleeIndex.set(rn, new Set());
-                            }
-                            this.calleeIndex.get(rn).add(filePath);
-                        }
-                    }
-                }
-            }
+            this._addToCalleeIndex(filePath, calls);
         }
     }
 
@@ -548,6 +608,20 @@ class ProjectIndex {
      * Progressively strips trailing segments to find the class file.
      */
     _resolveJavaPackageImport(importModule, javaFileIndex) {
+        if (!javaFileIndex) {
+            // Lazy-build index to avoid O(N) fallback scan of all files
+            if (!this._javaFileIndex) {
+                this._javaFileIndex = new Map();
+                for (const [fp, fe] of this.files) {
+                    if (fe.language === 'java') {
+                        const name = path.basename(fp, '.java');
+                        if (!this._javaFileIndex.has(name)) this._javaFileIndex.set(name, []);
+                        this._javaFileIndex.get(name).push(fp);
+                    }
+                }
+            }
+            javaFileIndex = this._javaFileIndex;
+        }
         return graphBuildModule._resolveJavaPackageImport(this, importModule, javaFileIndex);
     }
 
@@ -582,7 +656,7 @@ class ProjectIndex {
             if (contextFile) {
                 const imports = this.importGraph.get(contextFile);
                 if (imports) {
-                    const imported = entries.find(e => imports.includes(e.file));
+                    const imported = entries.find(e => imports.has(e.file));
                     if (imported) return imported.parents;
                 }
             }
@@ -614,7 +688,7 @@ class ProjectIndex {
         if (contextFile) {
             const imports = this.importGraph.get(contextFile);
             if (imports) {
-                const imported = classSymbols.find(s => imports.includes(s.file));
+                const imported = classSymbols.find(s => imports.has(s.file));
                 if (imported) return imported.file;
             }
         }
@@ -769,15 +843,27 @@ class ProjectIndex {
             }
         }
 
+        // Filter by exact startLine when a handle was supplied. This pins
+        // the resolution to one specific definition — no ambiguity allowed.
+        if (options.line && Number.isFinite(options.line)) {
+            const filtered = definitions.filter(d => d.startLine === options.line);
+            if (filtered.length > 0) {
+                definitions = filtered;
+            }
+        }
+
         // Score each definition for selection
         const typeOrder = new Set(['class', 'struct', 'interface', 'type', 'impl']);
+        const { isTestPath } = require('./shared');
         const scored = definitions.map(d => {
             let score = 0;
             const rp = d.relativePath || '';
             // Prefer class/struct/interface types (+1000)
             if (typeOrder.has(d.type)) score += 1000;
-            // Deprioritize test files (-500)
-            if (isTestFile(rp, detectLanguage(d.file))) {
+            // BUG-M4: deprioritize test files (-500). Combine the filename-pattern
+            // detector with the path-segment detector so `about` agrees with `find`'s
+            // exclusion logic (e.g. `test/agent-benchmark.js` is treated as a test).
+            if (isTestFile(rp, detectLanguage(d.file)) || isTestPath(rp)) {
                 score -= 500;
             }
             // Deprioritize examples/docs/vendor directories (-300)
@@ -824,7 +910,7 @@ class ProjectIndex {
             for (const candidate of tiedCandidates) {
                 let importerCount = 0;
                 for (const [, importedFiles] of this.importGraph) {
-                    if (importedFiles.includes(candidate.def.file)) {
+                    if (importedFiles.has(candidate.def.file)) {
                         importerCount++;
                     }
                 }
@@ -899,8 +985,7 @@ class ProjectIndex {
             const hasFilters = options.exclude && options.exclude.length > 0;
 
             // Pre-compute which files can reference THIS specific definition
-            const importers = this.exportGraph.get(defFile) || [];
-            const importersSet = new Set(importers);
+            const importersSet = this.exportGraph.get(defFile) || new Set();
             const defEntry = this.files.get(defFile);
             const isDirectoryScope = langTraits(defEntry?.language)?.packageScope === 'directory';
             const defDir = isDirectoryScope ? path.dirname(defFile) : null;
@@ -963,7 +1048,7 @@ class ProjectIndex {
 
             // Count imports from import graph (files that import from defFile and use this name)
             let imports = 0;
-            for (const importer of importers) {
+            for (const importer of importersSet) {
                 const fe = this.files.get(importer);
                 if (!fe) continue;
                 if (hasFilters && !this.matchesFilters(fe.relativePath, { exclude: options.exclude })) continue;
@@ -1022,7 +1107,7 @@ class ProjectIndex {
 
         while (queue.length > 0) {
             const file = queue.pop();
-            const importersArr = this.exportGraph.get(file) || [];
+            const importersArr = this.exportGraph.get(file) || new Set();
             for (const importer of importersArr) {
                 if (!relevantFiles.has(importer)) {
                     relevantFiles.add(importer);
@@ -1306,7 +1391,10 @@ class ProjectIndex {
         }
         parts.push(def.name);
         if (def.params !== undefined) {
-            parts.push(`(${def.params})`);
+            // Prefer typed rendering when paramTypes/paramsStructured carry annotations
+            const { renderTypedParams } = require('./output/shared');
+            const typed = renderTypedParams(def);
+            parts.push(`(${typed != null ? typed : def.params})`);
         }
         if (def.returnType) {
             parts.push(`: ${def.returnType}`);
@@ -1548,6 +1636,15 @@ class ProjectIndex {
         const fileEntry = this.files.get(filePath);
         if (!fileEntry) return null;
 
+        // Per-operation cache: avoid rescanning symbols for same (file, line)
+        const cacheKey = filePath + '\0' + lineNum;
+        if (this._opEnclosingFnCache) {
+            const cached = this._opEnclosingFnCache.get(cacheKey);
+            if (cached !== undefined) {
+                return cached === null ? null : (returnSymbol ? cached : cached.name);
+            }
+        }
+
         let best = null;
         for (const symbol of fileEntry.symbols) {
             if (!NON_CALLABLE_TYPES.has(symbol.type) &&
@@ -1558,8 +1655,11 @@ class ProjectIndex {
                 }
             }
         }
-        if (!best) return null;
-        return returnSymbol ? best : best.name;
+
+        if (this._opEnclosingFnCache) {
+            this._opEnclosingFnCache.set(cacheKey, best);
+        }
+        return best ? (returnSymbol ? best : best.name) : null;
     }
 
     /** Get instance attribute types for a class in a file */
@@ -1868,8 +1968,14 @@ class ProjectIndex {
     /** Analyze a call site using AST for example scoring */
     _analyzeCallSiteAST(filePath, lineNum, funcName) { return verifyModule.analyzeCallSiteAST(this, filePath, lineNum, funcName); }
 
+    /** Analyze a call site's argument shape (used by `example --diverse`) */
+    _analyzeCallShape(filePath, lineNum, funcName) { return verifyModule.analyzeCallShape(this, filePath, lineNum, funcName); }
+
     /** Diff-based impact analysis: find which functions changed and who calls them */
     diffImpact(options) { return analysisModule.diffImpact(this, options); }
+
+    /** Audit async/await: find calls that are likely missing an `await`. */
+    auditAsync(options) { return analysisModule.auditAsync(this, options); }
 }
 
 const { parseDiff } = require('./analysis');

package/core/registry.js

@@ -15,17 +15,17 @@
 // Order: understanding, finding, extracting, file-deps, refactoring, other.
 const CANONICAL_COMMANDS = [
     // Understanding code
-    'about', 'context', 'impact', 'blast', 'smart', 'trace', 'reverseTrace', 'example', 'related',
+    'about', 'context', 'impact', 'blast', 'smart', 'trace', 'reverseTrace', 'example', 'related', 'brief',
     // Finding code
-    'find', 'usages', 'toc', 'search', 'tests', 'affectedTests', 'deadcode', 'entrypoints',
+    'find', 'usages', 'toc', 'search', 'tests', 'affectedTests', 'deadcode', 'entrypoints', 'endpoints',
     // Extracting code
     'fn', 'class', 'lines', 'expand',
     // File dependencies
     'imports', 'exporters', 'fileExports', 'graph', 'circularDeps',
     // Refactoring
-    'verify', 'plan', 'diffImpact',
+    'verify', 'plan', 'diffImpact', 'check',
     // Other
-    'typedef', 'stacktrace', 'api', 'stats',
+    'typedef', 'stacktrace', 'api', 'stats', 'doctor', 'auditAsync',
 ];
 
 // ============================================================================
@@ -47,6 +47,9 @@ const CLI_ALIASES = {
     'circular-deps':   'circularDeps',
     'circular':        'circularDeps',
     'cycles':          'circularDeps',
+    'audit-async':     'auditAsync',
+    // BUG-3: parity with other multi-word commands (circular-deps, reverse-trace, ...)
+    'entry-points':    'entrypoints',
 };
 
 // MCP uses snake_case for multi-word names.
@@ -56,6 +59,7 @@ const MCP_ALIASES = {
     'affected_tests': 'affectedTests',
     'reverse_trace':  'reverseTrace',
     'circular_deps':  'circularDeps',
+    'audit_async':    'auditAsync',
 };
 
 // ============================================================================
@@ -65,6 +69,7 @@ const MCP_ALIASES = {
 const PARAM_MAP = {
     project_dir:       'projectDir',
     include_tests:     'includeTests',
+    exclude_tests:     'excludeTests',
     include_methods:   'includeMethods',
     include_uncertain: 'includeUncertain',
     with_types:        'withTypes',
@@ -74,6 +79,7 @@ const PARAM_MAP = {
     include_decorated: 'includeDecorated',
     min_confidence:    'minConfidence',
     show_confidence:   'showConfidence',
+    hide_confidence:   'hideConfidence',
     calls_only:        'callsOnly',
     class_name:        'className',
     max_lines:         'maxLines',
@@ -85,6 +91,10 @@ const PARAM_MAP = {
     max_files:         'maxFiles',
     max_chars:         'maxChars',
     follow_symlinks:   'followSymlinks',
+    unreachable_only:  'unreachableOnly',
+    server_only:       'serverOnly',
+    client_only:       'clientOnly',
+    hide_uncertain:    'hideUncertain',
 };
 
 // ============================================================================
@@ -96,24 +106,26 @@ const PARAM_MAP = {
 // file* = file is the command subject (required), not a filter pattern.
 const FLAG_APPLICABILITY = {
     // Understanding code
-    about:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'includeTests', 'top', 'all', 'withTypes', 'minConfidence', 'showConfidence'],
-    context:      ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'minConfidence', 'showConfidence'],
-    impact:       ['name', 'file', 'exclude', 'className', 'top'],
+    about:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'includeTests', 'top', 'all', 'withTypes', 'minConfidence', 'showConfidence', 'unreachableOnly', 'compact', 'git'],
+    context:      ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'minConfidence', 'showConfidence', 'unreachableOnly', 'compact'],
+    impact:       ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'top', 'unreachableOnly', 'compact'],
     blast:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
     reverseTrace: ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
     smart:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'withTypes', 'minConfidence'],
     trace:        ['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
-    example:      ['name', 'file', 'className'],
+    example:      ['name', 'file', 'className', 'diverse', 'top', 'includeTests'],
     related:      ['name', 'file', 'className', 'top', 'all'],
+    brief:        ['name', 'file', 'className', 'git'],
     // Finding code
-    find:         ['name', 'file', 'exclude', 'className', 'includeTests', 'top', 'limit', 'exact', 'in', 'all', 'depth'],
-    usages:       ['name', 'file', 'exclude', 'className', 'includeTests', 'limit', 'codeOnly', 'context', 'in'],
+    find:         ['name', 'file', 'exclude', 'className', 'includeTests', 'top', 'limit', 'exact', 'in', 'all', 'depth', 'compact'],
+    usages:       ['name', 'file', 'exclude', 'className', 'includeTests', 'limit', 'codeOnly', 'context', 'in', 'compact'],
     toc:          ['file', 'exclude', 'top', 'limit', 'all', 'detailed', 'topLevel', 'in'],
     search:       ['term', 'file', 'exclude', 'includeTests', 'top', 'limit', 'codeOnly', 'caseSensitive', 'context', 'regex', 'in', 'type', 'param', 'receiver', 'returns', 'decorator', 'exported', 'unused'],
     tests:        ['name', 'file', 'exclude', 'className', 'callsOnly'],
     affectedTests:['name', 'file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'minConfidence'],
     deadcode:     ['file', 'exclude', 'includeTests', 'includeExported', 'includeDecorated', 'limit', 'in'],
-    entrypoints:  ['file', 'exclude', 'includeTests', 'limit', 'type', 'framework'],
+    entrypoints:  ['file', 'exclude', 'includeTests', 'excludeTests', 'limit', 'type', 'framework'],
+    endpoints:    ['file', 'exclude', 'limit', 'framework', 'bridge', 'serverOnly', 'clientOnly', 'unmatched', 'method', 'prefix', 'hideUncertain'],
     // Extracting code
     fn:           ['name', 'file', 'className', 'all'],
     class:        ['name', 'file', 'all', 'maxLines'],
@@ -126,21 +138,25 @@ const FLAG_APPLICABILITY = {
     graph:        ['file', 'depth', 'direction', 'all'],
     circularDeps: ['file', 'exclude'],
     // Refactoring
-    verify:       ['name', 'file', 'className'],
+    verify:       ['name', 'file', 'className', 'includeMethods', 'includeUncertain'],
     plan:         ['name', 'file', 'className', 'addParam', 'removeParam', 'renameTo', 'defaultValue'],
     diffImpact:   ['file', 'limit', 'base', 'staged', 'all'],
+    check:        ['file', 'base', 'staged', 'limit'],
     // Other
     typedef:      ['name', 'file', 'className', 'exact'],
     stacktrace:   ['stack'],
     api:          ['file', 'limit'],
-    stats:        ['functions', 'top'],
+    stats:        ['functions', 'hot', 'top'],
+    doctor:       ['file', 'in', 'limit', 'deep'],
+    auditAsync:   ['file', 'exclude', 'limit'],
 };
 
 // Commands whose output is project-wide — truncation means you need a filter, not more text.
 // Used by MCP server for tighter default output limits.
 const BROAD_COMMANDS = new Set([
-    'toc', 'entrypoints', 'diffImpact', 'affectedTests',
+    'toc', 'entrypoints', 'endpoints', 'diffImpact', 'affectedTests',
     'deadcode', 'usages', 'reverseTrace', 'circularDeps',
+    'doctor', 'check', 'auditAsync',
 ]);
 
 // Commands that can operate on a single file without a project index.