ucn 5.3.7 → 5.4.0

package/core/reporting.js

@@ -48,6 +48,7 @@ function getStats(index, options = {}) {
         files: scopedFiles.length,
         symbols: totalSymbols,  // Total symbol count, not unique names
         buildTime: index.buildTime,
+        buildTimeNote: 'Last index build, including discovery and graphs; excludes cache I/O and query execution. Reused when loading a cached index.',
         byLanguage: {},
         byType: {},
         ...(index.truncated && { truncated: index.truncated })
@@ -1044,6 +1045,7 @@ function orient(index, options = {}) {
         files: stats.files,
         symbols: stats.symbols,
         buildTime: stats.buildTime,
+        buildTimeNote: stats.buildTimeNote,
         byLanguage: stats.byLanguage,
         dirs,
         hot: {

package/core/search.js

@@ -727,6 +727,7 @@ function structuralSearch(index, options = {}) {
         // Auto-infer type: --receiver implies type=call
         const type = options.type || (receiver ? 'call' : undefined);
         const results = [];
+        const skippedTestFiles = new Set();
 
         // Validate type if provided
         if (type && !STRUCTURAL_TYPES.has(type)) {
@@ -753,7 +754,13 @@ function structuralSearch(index, options = {}) {
                 if (!rp.includes(options.file) && !rp.endsWith(options.file)) return false;
             }
             if ((options.exclude && options.exclude.length > 0) || options.in) {
-                if (!index.matchesFilters(fileEntry.relativePath, { exclude: options.exclude, in: options.in })) return false;
+                if (!index.matchesFilters(fileEntry.relativePath, { in: options.in })) return false;
+                if (!index.matchesFilters(fileEntry.relativePath, { exclude: options.exclude })) {
+                    if (options.testExclude && !index.matchesFilters(fileEntry.relativePath, { exclude: options.testExclude })) {
+                        skippedTestFiles.add(fileEntry.relativePath);
+                    }
+                    return false;
+                }
             }
             return true;
         };
@@ -883,7 +890,10 @@ function structuralSearch(index, options = {}) {
                         // expression position — never "unused" (the deadcode
                         // twin of the bodyScopedName audit skip).
                         if (def.bodyScopedName) continue;
-                        index.buildCalleeIndex();
+                        // buildCalleeIndex rebuilds the whole project. Reuse
+                        // the eagerly built (or cache-loaded) index, including
+                        // across every candidate in this operation.
+                        if (!index.calleeIndex) index.buildCalleeIndex();
                         // A name whose every call site is its own recursion
                         // has zero callers (fix #253c — the deadcode
                         // carve-out, applied here). Class-kind names are
@@ -975,6 +985,7 @@ function structuralSearch(index, options = {}) {
                 }).filter(([, v]) => v !== undefined && v !== null)),
                 totalMatched: total,
                 shown: results.length,
+                filesSkipped: skippedTestFiles.size,
                 ...(unused && {
                     unusedScope: 'callable-symbols-only',
                     unusedSafety: 'candidate-only; use deadcode before deletion',

package/core/shared.js

@@ -50,15 +50,22 @@ function codeUnitCompare(a, b) {
  * Path-based test heuristic — matches the same patterns as `find`'s exclusion
  * logic so that `about` and `find` agree on which files are de-emphasized.
  *
- * Triggers when any of `test|tests|spec|__tests__|__mocks__|fixture|mock`
- * appears as a path segment (with word boundaries on both sides).
+ * Uses language-specific filename conventions plus `test|tests|__tests__|__mocks__|fixture|mock`
+ * as path segments (with word boundaries on both sides). `spec` is a test
+ * marker only for languages whose test-file conventions include it.
  *
  * Complement to `isTestFile` (filename pattern check) — together they catch
  * both `foo.test.js` (filename) AND `test/agent-benchmark.js` (directory).
  */
 function isTestPath(rp) {
     if (!rp) return false;
-    return /(^|[/._-])(test|tests|spec|__tests__|__mocks__|fixture|mock)s?([/._-]|$)/i.test(rp);
+    const language = detectLanguage(rp);
+    const { langTraits } = require('../languages');
+    const specConvention = langTraits(language)?.testFileCandidates?.('sample', '')
+        .some(candidate => candidate.includes('.spec'));
+    return isTestFile(rp, language) ||
+        /(^|[/._-])(test|tests|__tests__|__mocks__|fixture|mock)s?([/._-]|$)/i.test(rp) ||
+        (!!specConvention && /(^|[/._-])specs?([/._-]|$)/i.test(rp));
 }
 
 /**
@@ -109,7 +116,9 @@ function pickBestDefinition(matches, opts = {}) {
  * Returns a new array with test patterns appended (deduplicating).
  */
 function addTestExclusions(exclude) {
-    const testPatterns = ['test', 'spec', '__tests__', '__mocks__', 'fixture', 'mock'];
+    // Keep automatic test classification distinct from explicit substring
+    // exclusions: --exclude=spec deliberately excludes Python specs too.
+    const testPatterns = ['test files'];
     const existing = new Set((exclude || []).map(e => e.toLowerCase()));
     const additions = testPatterns.filter(p => !existing.has(p));
     return [...(exclude || []), ...additions];

package/core/verify.js

@@ -808,6 +808,8 @@ function computePlanCallSites(index, name, def) {
             expression: (call.content || '').trim(),
             args: analysis.args,
             argCount: analysis.argCount,
+            ...(analysis.keywordArgNames && { keywordArgNames: analysis.keywordArgNames }),
+            ...(analysis.positionalCount != null && { positionalCount: analysis.positionalCount }),
             ...(c.calledAs && { calledAs: c.calledAs }),
         });
     }
@@ -2158,7 +2160,10 @@ function plan(index, name, options = {}) {
             } else if (options.defaultValue) {
                 suggestion = `Add argument: ${options.defaultValue} (no default parameter values in ${planFileEntry?.language || 'this language'})`;
             } else {
-                suggestion = `Add argument: ${options.addParam}`;
+                const keywordCall = langTraits(planLang)?.keywordArguments && site.keywordArgNames?.length > 0;
+                suggestion = keywordCall
+                    ? `Add keyword argument: ${options.addParam}=${options.addParam} (replace the right-hand value with the intended expression; keep existing keyword arguments)`
+                    : `Add argument: ${options.addParam}`;
             }
             changes.push({
                 file: site.file,

package/languages/c-family.js

@@ -13,6 +13,7 @@ const { typeOrigin } = require('./type-evidence');
 
 const {
     traverseTree,
+    nodeTextWithoutComments,
     traverseTreeCached,
     nodeToLocation,
     extractJSDocstring,
@@ -989,7 +990,7 @@ function paramTypeText(param, identity) {
     const defaultValue = param.childForFieldName('default_value');
     const end = defaultValue ? defaultValue.startIndex : param.endIndex;
     if (identity.nameNode.startIndex < base || identity.nameNode.endIndex > end) return null;
-    const text = param.text.slice(0, end - base);
+    const text = nodeTextWithoutComments(param).slice(0, end - base);
     const typeText = (text.slice(0, identity.nameNode.startIndex - base) +
         text.slice(identity.nameNode.endIndex - base))
         .replace(/\s+/g, ' ')
@@ -1014,10 +1015,10 @@ function structuredParams(paramsNode) {
         // their type text alone — the type must not double as both name and
         // annotation, and `void *` must not collapse into the `(void)` form.
         const info = {
-            name: identity.name || param.text.replace(/\s+/g, ' ').trim(),
+            name: identity.name || nodeTextWithoutComments(param).replace(/\s+/g, ' ').trim(),
         };
         if (typeNode && identity.name) {
-            info.type = paramTypeText(param, identity) || typeNode.text;
+            info.type = paramTypeText(param, identity) || nodeTextWithoutComments(typeNode);
         }
         if (param.type === 'optional_parameter_declaration') info.optional = true;
         let declaratorCursor = declarator;
@@ -1164,7 +1165,7 @@ function returnTypeOf(node) {
             const descriptor = (current.namedChildren || []).find(child =>
                 child.type === 'type_descriptor') || current.namedChild(0);
             const type = descriptor?.childForFieldName('type') || descriptor;
-            return type?.text || null;
+            return nodeTextWithoutComments(type) || null;
         }
         for (const child of current.namedChildren || []) {
             const found = findTrailing(child);
@@ -1193,7 +1194,7 @@ function returnTypeOf(node) {
         current = current.childForFieldName('declarator') ||
             (current.namedChildren || []).find(child => child.type.endsWith('_declarator'));
     }
-    return stars > 0 ? `${typeNode.text} ${'*'.repeat(stars)}` : typeNode.text;
+    return stars > 0 ? `${nodeTextWithoutComments(typeNode)} ${'*'.repeat(stars)}` : nodeTextWithoutComments(typeNode);
 }
 
 function memberFromNode(node, className, access, lines, mode) {
@@ -1209,7 +1210,7 @@ function memberFromNode(node, className, access, lines, mode) {
     if (isConstructor && identity.name.startsWith('~')) modifiers.push('destructor');
     return {
         name: identity.name,
-        params: paramsNode ? paramsNode.text.replace(/^\(|\)$/g, '').trim() : '...',
+        params: paramsNode ? nodeTextWithoutComments(paramsNode).replace(/^\(|\)$/g, '').trim() : '...',
         paramsStructured: structuredParams(paramsNode),
         returnType: isConstructor ? null :
             (identity.conversionType || returnTypeOf(node)),
@@ -1510,7 +1511,7 @@ function findFunctionsInTree(code, tree, mode, sourceLines = null) {
             : null;
         functions.push({
             name: identity.name,
-            params: paramsNode ? paramsNode.text.replace(/^\(|\)$/g, '').trim() : '...',
+            params: paramsNode ? nodeTextWithoutComments(paramsNode).replace(/^\(|\)$/g, '').trim() : '...',
             paramsStructured: structuredParams(paramsNode),
             returnType: isConstructor ? null :
                 (identity.conversionType || returnTypeOf(node)),
@@ -1800,7 +1801,7 @@ function findMacrosInTree(tree, lines, parser) {
             startLine,
             endLine,
             indent,
-            params: paramsNode ? paramsNode.text.replace(/^\(|\)$/g, '').trim() : undefined,
+            params: paramsNode ? nodeTextWithoutComments(paramsNode).replace(/^\(|\)$/g, '').trim() : undefined,
             paramsStructured: paramsNode
                 ? (paramsNode.namedChildren || [])
                     .filter(child => child.type === 'identifier')

package/languages/csharp.js

@@ -2,6 +2,7 @@
 
 const {
     traverseTree,
+    nodeTextWithoutComments,
     traverseTreeCached,
     nodeToLocation,
     extractJSDocstring,
@@ -127,7 +128,7 @@ function structuredParams(paramsNode) {
         if (nameNode) {
             recoveredParams.push({
                 name: nameNode.text,
-                ...(typeNode && { type: typeNode.text }),
+                ...(typeNode && { type: nodeTextWithoutComments(typeNode) }),
                 rest: true,
             });
         }
@@ -138,14 +139,14 @@ function structuredParams(paramsNode) {
         const typeNode = param.childForFieldName('type');
         if (!nameNode) continue;
         const info = { name: nameNode.text };
-        if (typeNode) info.type = typeNode.text;
+        if (typeNode) info.type = nodeTextWithoutComments(typeNode);
         if (modifiersOf(param).includes('this')) info.extensionReceiver = true;
         if (param.type === 'parameter_array') info.rest = true;
         const value = param.childForFieldName('value') ||
             param.namedChildren.find(child => child !== nameNode && child !== typeNode &&
-                !['attribute_list', 'modifier'].includes(child.type));
+                !['attribute_list', 'modifier', 'comment'].includes(child.type));
         if (value) {
-            info.default = value.text;
+            info.default = nodeTextWithoutComments(value);
             info.optional = true;
         }
         params.push(info);
@@ -208,9 +209,9 @@ function memberFromNode(node, className, lines) {
     const paramsStructured = structuredParams(paramsNode);
     return {
         name,
-        params: paramsNode ? paramsNode.text.replace(/^\(|\)$/g, '').trim() : '...',
+        params: paramsNode ? nodeTextWithoutComments(paramsNode).replace(/^\(|\)$/g, '').trim() : '...',
         paramsStructured,
-        returnType: isConstructor ? null : returnNode?.text || null,
+        returnType: isConstructor ? null : nodeTextWithoutComments(returnNode).trim() || null,
         startLine,
         endLine,
         indent,
@@ -263,9 +264,9 @@ function indexerMember(node, className, lines) {
     const { startLine, endLine, indent } = nodeToLocation(node, lines);
     return {
         name: 'this[]',
-        params: paramsNode ? paramsNode.text.replace(/^\[|\]$/g, '').trim() : '...',
+        params: paramsNode ? nodeTextWithoutComments(paramsNode).replace(/^\[|\]$/g, '').trim() : '...',
         paramsStructured: structuredParams(paramsNode),
-        returnType: typeNode?.text || null,
+        returnType: nodeTextWithoutComments(typeNode).trim() || null,
         startLine,
         endLine,
         indent,
@@ -495,9 +496,9 @@ function findFunctions(code, parser) {
         const modifiers = modifiersOf(node);
         functions.push({
             name: nameNode.text,
-            params: paramsNode ? paramsNode.text.replace(/^\(|\)$/g, '').trim() : '...',
+            params: paramsNode ? nodeTextWithoutComments(paramsNode).replace(/^\(|\)$/g, '').trim() : '...',
             paramsStructured: structuredParams(paramsNode),
-            returnType: returnNode?.text || null,
+            returnType: nodeTextWithoutComments(returnNode).trim() || null,
             startLine,
             endLine,
             indent,

package/languages/go.js

@@ -10,6 +10,7 @@ const { ReceiverTypeMap, typeOrigin } = require('./type-evidence');
 
 const {
     traverseTree,
+    nodeTextWithoutComments,
     traverseTreeCached,
     nodeToLocation,
     parseStructuredParams,
@@ -29,7 +30,7 @@ function parseTree(parser, code) {
 function extractReturnType(node) {
     const resultNode = node.childForFieldName('result');
     if (resultNode) {
-        return resultNode.text.trim() || null;
+        return nodeTextWithoutComments(resultNode).trim() || null;
     }
     return null;
 }
@@ -39,7 +40,7 @@ function extractReturnedFunctionResult(node) {
     const resultNode = node.childForFieldName('result');
     if (resultNode?.type !== 'function_type') return null;
     const innerResult = resultNode.childForFieldName('result');
-    return innerResult?.text.trim() || null;
+    return nodeTextWithoutComments(innerResult).trim() || null;
 }
 
 /**
@@ -51,7 +52,7 @@ function extractGoParams(paramsNode) {
     // unknown signatures in JSON output (fix #238; the shared
     // utils.extractParams already had this fix).
     if (!paramsNode) return '...';
-    const text = paramsNode.text;
+    const text = nodeTextWithoutComments(paramsNode);
     return text.replace(/^\(|\)$/g, '').trim();
 }
 
@@ -115,7 +116,7 @@ function _processFunction(node, functions, processedRanges, lines) {
                 indent,
                 modifiers: isExported ? ['export'] : [],
                 isFunctionVariable: true,
-                ...(resultNode?.text.trim() && { returnType: resultNode.text.trim() }),
+                ...(resultNode && { returnType: nodeTextWithoutComments(resultNode).trim() || null }),
             });
         }
         return true;
@@ -491,11 +492,11 @@ function extractInterfaceMembers(interfaceNode, codeOrLines) {
                 } else if (sub.type === 'parameter_list') {
                     hasParams = true;
                     if (!paramsText) {
-                        paramsText = sub.text.slice(1, -1); // strip parens
+                        paramsText = nodeTextWithoutComments(sub).slice(1, -1); // strip parens
                         paramsNode = sub;
                     } else {
                         // Second parameter_list is the return type tuple
-                        returnType = sub.text;
+                        returnType = nodeTextWithoutComments(sub);
                     }
                 }
             }
@@ -514,7 +515,7 @@ function extractInterfaceMembers(interfaceNode, codeOrLines) {
                 for (let j = 0; j < child.namedChildCount; j++) {
                     const sub = child.namedChild(j);
                     if (returnTypeNodes.has(sub.type) && sub.text !== nameText) {
-                        returnType = sub.text;
+                        returnType = nodeTextWithoutComments(sub);
                     }
                 }
             }

package/languages/index.js

@@ -144,6 +144,7 @@ const LANGUAGES = {
         traits: {
             ...STRUCTURAL_TRAITS,
             selfParam: ['this'],
+            storedPromises: true,
             testFileCandidates: (base, ext) => [`${base}.test${ext}`, `${base}.spec${ext}`, `${base}.test.ts`, `${base}.test.js`, `${base}.spec.ts`, `${base}.spec.js`],
             testDirs: ['__tests__'],
         },
@@ -157,6 +158,7 @@ const LANGUAGES = {
         traits: {
             ...STRUCTURAL_TRAITS,
             selfParam: ['this'],
+            storedPromises: true,
             testFileCandidates: (base, ext) => [`${base}.test${ext}`, `${base}.spec${ext}`, `${base}.test.ts`, `${base}.test.js`, `${base}.spec.ts`, `${base}.spec.js`],
             testDirs: ['__tests__'],
         },
@@ -170,6 +172,7 @@ const LANGUAGES = {
         traits: {
             ...STRUCTURAL_TRAITS,
             selfParam: ['this'],
+            storedPromises: true,
             testFileCandidates: (base, ext) => [`${base}.test${ext}`, `${base}.spec${ext}`, `${base}.test.ts`, `${base}.test.js`, `${base}.spec.ts`, `${base}.spec.js`],
             testDirs: ['__tests__'],
         },
@@ -324,6 +327,7 @@ const LANGUAGES = {
         traits: {
             ...STRUCTURAL_TRAITS,
             selfParam: ['this'],
+            storedPromises: true,
             testFileCandidates: (base, ext) => [`${base}.test${ext}`, `${base}.spec${ext}`],
         },
     }

package/languages/java.js

@@ -10,6 +10,7 @@ const { ReceiverTypeMap, typeOrigin } = require('./type-evidence');
 
 const {
     traverseTree,
+    nodeTextWithoutComments,
     traverseTreeCached,
     nodeToLocation,
     parseStructuredParams,
@@ -32,7 +33,7 @@ function extractJavaParams(paramsNode) {
     // unknown signatures in JSON output (fix #241; go/rust got this in #238,
     // the shared utils.extractParams already had it).
     if (!paramsNode) return '...';
-    const text = paramsNode.text;
+    const text = nodeTextWithoutComments(paramsNode);
     let params = text.replace(/^\(|\)$/g, '').trim();
     return params;
 }
@@ -201,7 +202,7 @@ function stripJavaString(text) {
 function extractReturnType(node) {
     const typeNode = node.childForFieldName('type');
     if (typeNode) {
-        return typeNode.text;
+        return nodeTextWithoutComments(typeNode);
     }
     return null;
 }

package/languages/javascript.js

@@ -10,6 +10,7 @@ const { ReceiverTypeMap, typeOrigin } = require('./type-evidence');
 
 const {
     traverseTree,
+    nodeTextWithoutComments,
     traverseTreeCached,
     nodeToLocation,
     extractParams,
@@ -34,7 +35,7 @@ function parseTree(parser, code) {
 function extractReturnType(node) {
     const returnTypeNode = node.childForFieldName('return_type');
     if (returnTypeNode) {
-        let text = returnTypeNode.text.trim();
+        let text = nodeTextWithoutComments(returnTypeNode).trim();
         if (text.startsWith(':')) {
             text = text.slice(1).trim();
         }

package/languages/python.js

@@ -10,6 +10,7 @@ const { ReceiverTypeMap, typeOrigin } = require('./type-evidence');
 
 const {
     traverseTree,
+    nodeTextWithoutComments,
     traverseTreeCached,
     nodeToLocation,
     parseStructuredParams,
@@ -32,7 +33,7 @@ function parseTree(parser, code) {
 function extractReturnType(node) {
     const returnTypeNode = node.childForFieldName('return_type');
     if (returnTypeNode) {
-        let text = returnTypeNode.text.trim();
+        let text = nodeTextWithoutComments(returnTypeNode).trim();
         if (text.startsWith('->')) {
             text = text.slice(2).trim();
         }
@@ -129,7 +130,7 @@ function extractPythonParams(paramsNode) {
     // unknown signatures in JSON output (fix #241; go/rust got this in #238,
     // the shared utils.extractParams already had it).
     if (!paramsNode) return '...';
-    const text = paramsNode.text;
+    const text = nodeTextWithoutComments(paramsNode);
     let params = text.replace(/^\(|\)$/g, '').trim();
     return params;
 }
@@ -2804,7 +2805,14 @@ function findCallsInCode(code, parser) {
             const argsNode = node.childForFieldName('arguments');
             if (argsNode) {
                 for (let i = 0; i < argsNode.namedChildCount; i++) {
-                    const arg = argsNode.namedChild(i);
+                    const rawArg = argsNode.namedChild(i);
+                    const arg = rawArg.type === 'keyword_argument'
+                        ? rawArg.childForFieldName('value') : rawArg;
+                    if (!arg) continue;
+                    // Bare keyword values already belong to the reference
+                    // inventory/rename path; only extend the member-value
+                    // callback model to match its positional counterpart.
+                    if (rawArg.type === 'keyword_argument' && arg.type !== 'attribute') continue;
                     if (arg.type === 'identifier' && !PYTHON_SKIP.has(arg.text) && !nonCallableNames.has(arg.text)) {
                         calls.push({
                             name: arg.text,

package/languages/rust.js

@@ -10,6 +10,7 @@ const { ReceiverTypeMap, typeOrigin } = require('./type-evidence');
 
 const {
     traverseTree,
+    nodeTextWithoutComments,
     traverseTreeCached,
     nodeToLocation,
     parseStructuredParams,
@@ -128,7 +129,7 @@ function declarationTrees(code, parser) {
 function extractReturnType(node) {
     const returnTypeNode = node.childForFieldName('return_type');
     if (returnTypeNode) {
-        let text = returnTypeNode.text.trim();
+        let text = nodeTextWithoutComments(returnTypeNode).trim();
         if (text.startsWith('->')) {
             text = text.slice(2).trim();
         }
@@ -198,7 +199,7 @@ function extractRustParams(paramsNode) {
     // unknown signatures in JSON output (fix #238; the shared
     // utils.extractParams already had this fix).
     if (!paramsNode) return '...';
-    const text = paramsNode.text;
+    const text = nodeTextWithoutComments(paramsNode);
     return text.replace(/^\(|\)$/g, '').trim();
 }