ucn 5.3.8 → 5.4.0

package/.claude/skills/ucn/SKILL.md

@@ -143,8 +143,10 @@ token when it differs from `startLine`). Structural `search --unused` keeps its
 safety note and decorator tags in shell output; runtime registrations can appear
 and zero call edges do not prove a symbol is safe to delete.
 `--lines` lists the whole band without default row/character caps, so pipe through
-`grep -v '# unverified'` for the confirmed tier or `cut -d: -f1 | sort | uniq -c`
-for callers per file. Nothing to list prints nothing and exits 1, grep's
+`grep -v '# unverified'` for the confirmed tier. To count distinct source lines
+per file, use `cut -d: -f1,2 | sort -u | cut -d: -f1 | sort | uniq -c`;
+counting raw usage records can count a source line more than once.
+Nothing to list prints nothing and exits 1, grep's
 contract; errors exit 2. Explicit `--top`/`--limit` still apply and disclose
 omissions. `show --lines` accepts only callers/callees sections; target-less
 `impact --lines` lists Git-diff callers with per-target accounting. Closing a
@@ -208,6 +210,30 @@ The selection note discloses that approximation. `find`, text `search`,
 (structural `search`: 50). Use an explicit `--limit=N` to request more;
 `usages` and `--lines` have no default row cap.
 
+Automatic test filtering follows the language's conventions: Python `spec.py`
+and `chart_spec.py` are production paths; `test_*.py`, `*_test.py`, and test
+directories remain test paths. Structural search discloses hidden test files,
+including empty results; `--include-tests` gives the full indexed inventory.
+Explicit `--exclude=spec` still means the requested path exclusion.
+
+Public JSON source `file` fields are relative to `meta.pathBase` (the absolute
+project root). Dependency edge paths use the same base. Both absolute and
+relative indexed-file handles are accepted. Definition handles retain their
+decorator span; use `nameLine` for the name token rather than joining usages
+to a handle's start line.
+
+Callable references passed to another function remain visible when a project
+method or function could be their target. An ordinary attribute read with no
+callable member candidate stays a non-call reference in ACCOUNT and `usages`.
+The caller model includes callback dependencies; it does not prove that the
+receiving function invokes every passed callable.
+
+`audit-async` checks recognized async producers. In JS/TS/HTML it also checks
+captured promises used in arithmetic, conditions, or resolved-value member
+access within the same lexical scope. Awaiting, returning, promise handlers,
+reassignment, and shadowed bindings are distinguished. It is a bounded AST
+audit, not a compiler-wide proof that every missing await has been found.
+
 For `plan --rename-to`, the selected declaration is only the starting point.
 When the index proves the relationship, the rename unit closes over
 overload/signature groups, base and override declarations, Rust trait slots,

package/.claude/skills/ucn/references/commands.md

@@ -57,6 +57,12 @@ Structural `search --param` matches parameter names, types, and defaults; `--ret
 
 `--lines` writes one record per output line. `usages` records occurrences, so multiple tokens on the same source line can produce repeated `path:line` values. Deduplicate those values when counting source lines.
 
+Public JSON source paths (`file`, caller files, dependency roots and edges) are project-relative, with the absolute base in `meta.pathBase`. Project roots and external paths remain absolute. Indexed absolute handles are accepted as well as relative handles.
+
+Default test exclusions follow language conventions. Python `spec.py` and `*_spec.py` are included; `test_*.py`, `*_test.py`, and test directories are excluded. Structural search reports hidden test-file counts, including on empty results. `--include-tests` disables these defaults; explicit `--exclude` patterns still apply.
+
+`audit-async` checks recognized async producers, including captured JS/TS/HTML promises used as resolved values in the same lexical scope. Promise returns and handlers are valid; alias flow and unknown receivers require compiler/type-checker review.
+
 ## Common flags
 
 | Flag | Meaning |

package/core/account.js

@@ -301,6 +301,10 @@ function classifyGroundLines(index, name, groundSet, claimedKeys) {
         const callLines = new Set();
         if (Array.isArray(cachedCalls)) {
             for (const c of cachedCalls) {
+                // Unclaimed callback/type references have no invocation
+                // syntax. Let the usage AST classify them as references;
+                // merely entering the candidate cache is not a call fact.
+                if (c.isFunctionReference || c.isTypeReference) continue;
                 if (c.name === name || c.resolvedName === name ||
                     (c.resolvedNames && c.resolvedNames.includes(name))) {
                     callLines.add(c.line);

package/core/analysis.js

@@ -2656,6 +2656,78 @@ const _ASYNCIO_CONSUMER_FNS = new Set([
     'gather', 'create_task', 'ensure_future', 'wait', 'as_completed',
 ]);
 
+// Follow a captured JS promise within its lexical scope, looking only for
+// operations that require its resolved value. Passing/returning/awaiting the
+// promise and its own methods are valid. Reassignment stops the inference;
+// nested functions and shadowing blocks cannot borrow the outer binding.
+function storedPromiseMisuse(call, functionNodes) {
+    const { sameNode } = require('../languages/utils');
+    let value = call;
+    while (value.parent?.type === 'parenthesized_expression') value = value.parent;
+    const assignment = value.parent;
+    if (!assignment || !['variable_declarator', 'assignment_expression'].includes(assignment.type)) return null;
+    const binding = assignment.childForFieldName(assignment.type === 'variable_declarator' ? 'name' : 'left');
+    if (binding?.type !== 'identifier') return null;
+    let scope = assignment.parent;
+    while (scope && scope.type !== 'statement_block' && !functionNodes.has(scope.type)) scope = scope.parent;
+    if (!scope) return null;
+    const name = binding.text;
+    const promiseMembers = new Set(['then', 'catch', 'finally', 'constructor',
+        'toString', 'toLocaleString', 'valueOf', 'hasOwnProperty', 'isPrototypeOf', 'propertyIsEnumerable']);
+    let stopped = false;
+    let misuse = null;
+    const namesBinding = node => !!node && ((['identifier', 'shorthand_property_identifier_pattern'].includes(node.type) && node.text === name) ||
+        node.namedChildren.some(namesBinding));
+    const shadows = block => (block.namedChildren || []).some(statement =>
+        ['lexical_declaration', 'variable_declaration'].includes(statement.type) &&
+        statement.namedChildren.some(decl => namesBinding(decl.childForFieldName('name'))));
+    const visit = node => {
+        if (stopped || misuse || node.endIndex <= call.endIndex) return;
+        if (functionNodes.has(node.type)) return;
+        if (!sameNode(node, scope) && node.type === 'statement_block' && shadows(node)) return;
+        if (node.type === 'catch_clause' && namesBinding(node.childForFieldName('parameter'))) return;
+        if (node.type === 'for_statement' && shadows(node)) return;
+        if (node.type === 'for_in_statement' && namesBinding(node.childForFieldName('left'))) {
+            // A declared loop variable shadows; an undeclared one overwrites
+            // the promise, so later uses cannot inherit its earlier type.
+            if (!node.children.some(child => ['let', 'const'].includes(child.type))) stopped = true;
+            return;
+        }
+        if (node.type === 'assignment_expression' && !sameNode(node, assignment) && node.childForFieldName('left')?.text === name) {
+            const right = node.childForFieldName('right');
+            if (right) visit(right);
+            stopped = true;
+            return;
+        }
+        if (node.type === 'identifier' && node.text === name && node.startIndex >= call.endIndex) {
+            let use = node;
+            while (use.parent?.type === 'parenthesized_expression') use = use.parent;
+            const parent = use.parent;
+            if (parent?.type === 'member_expression' && sameNode(parent.childForFieldName('object'), use)) {
+                const property = parent.childForFieldName('property');
+                if (property && !promiseMembers.has(property.text)) misuse = node;
+            } else if (parent?.type === 'subscript_expression' && sameNode(parent.childForFieldName('object'), use)) {
+                misuse = node;
+            } else if (parent?.type === 'binary_expression') {
+                const operator = parent.childForFieldName('operator')?.text;
+                if (['+', '-', '*', '/', '%', '**', '<', '>', '<=', '>=', '|', '&', '^', '<<', '>>', '>>>'].includes(operator)) misuse = node;
+            } else if (parent?.type === 'unary_expression' && ['+', '-', '~'].includes(parent.childForFieldName('operator')?.text)) {
+                misuse = node;
+            } else if (parent && ['update_expression', 'augmented_assignment_expression'].includes(parent.type)) {
+                misuse = node;
+            } else if (parent && ['if_statement', 'while_statement', 'do_statement', 'ternary_expression'].includes(parent.type) &&
+                sameNode(parent.childForFieldName('condition'), use)) {
+                misuse = node;
+            }
+        }
+        for (const child of node.namedChildren || []) visit(child);
+    };
+    // A function root's body is the scan scope, never its parameters.
+    visit(scope.type === 'statement_block' ? scope : scope.childForFieldName('body') || scope);
+    return misuse ? { line: misuse.startPosition.row + 1, variable: name,
+        originLine: call.startPosition.row + 1, reason: 'stored-promise-used-as-value' } : null;
+}
+
 /**
  * Run an async/await audit across the project.
  *
@@ -3012,6 +3084,10 @@ function auditAsync(index, options = {}) {
                                         let current = node.parent;
                                         let awaitDepth = 0;
                                         while (current && awaitDepth++ < 5) {
+                                            if (current.type === 'parenthesized_expression') {
+                                                current = current.parent;
+                                                continue;
+                                            }
                                             if (current.type === 'await_expression' ||
                                                 current.type === 'await') {
                                                 awaited = true;
@@ -3034,12 +3110,15 @@ function auditAsync(index, options = {}) {
                                             }
                                             break;
                                         }
-                                        if (!awaited && !isFireAndForget(node, language)) {
+                                        const storedMisuse = !awaited && langTraits(language)?.storedPromises
+                                            ? storedPromiseMisuse(node, FN_NODE_TYPES) : null;
+                                        if (storedMisuse || (!awaited && !isFireAndForget(node, language))) {
                                             issues.push({
                                                 file: fileEntry.relativePath || filePath,
                                                 line,
                                                 callerName: enclosing.name,
                                                 calleeName,
+                                                ...(storedMisuse || {}),
                                             });
                                         }
                                     }

package/core/cache.js

@@ -713,7 +713,8 @@ function clearAllCaches() {
 // v225 (fix #357): Rust `use path::name as local` bindings record the original name with a paired `renames` alias.
 // v226: bundled/minified filename exclusions are disclosed in discoveryIssues.
 // v227: signature parameter/return text excludes AST comments in every language.
-const CACHE_FORMAT_VERSION = 227;
+// v228: Python keyword arguments retain the same callable-reference facts as positional arguments.
+const CACHE_FORMAT_VERSION = 228;
 const USAGE_CACHE_FILE = 'usage-results.json';
 
 /**

package/core/callers.js

@@ -291,6 +291,22 @@ function _javaConstructorDisposition(index, filePath, fileEntry, call, targetDef
     return 'unknown';
 }
 
+// A structural member passed as a value is not invocation syntax. Keep it
+// in the callback model only when a project member can actually be callable;
+// an unrelated standalone function's spelling is not such evidence. Module
+// members remain eligible because modules can export standalone functions.
+function isDataMemberReference(fileEntry, call, definitions) {
+    if (!call.isFunctionReference || !call.isMethod || call.receiverIsModule ||
+        call.receiverModuleSpecifier || langTraits(fileEntry?.language)?.typeSystem !== 'structural') return false;
+    if (_structuralModuleBindings(fileEntry, call).length > 0) return false;
+    return !definitions.some(def => !NON_CALLABLE_TYPES.has(def.type) &&
+        // A typed Python descriptor read really invokes its getter; retain
+        // that existing proof path. An untyped property spelling belongs to
+        // the separate property-access inventory, never the call band.
+        (!require('./accessors').isAccessorDefinition(def) || call.receiverType) &&
+        (def.className || def.receiver));
+}
+
 /**
  * Find all call sites that invoke the named symbol.
  *
@@ -697,6 +713,7 @@ function findCallers(index, name, options = {}) {
                 langTraits(fileEntry.language)?.typeSystem === 'structural';
 
             for (let call of calls) {
+                if (isDataMemberReference(fileEntry, call, options.targetDefinitions || definitions)) continue;
                 // fix #353: C# `Beta.Helper.Widget()` — the parser records a
                 // field hop rooted at `this` (Beta is no local). When the
                 // prefix names a project NAMESPACE that declares the last
@@ -5444,7 +5461,8 @@ function findCallees(index, definition, options = {}) {
         // to this definition's source range. Nested closures deliberately
         // remain in the slice and retain the existing inner-symbol rules.
         const calls = _callsInDefinitionRange(index, def.file, allCalls,
-            def.startLine, def.endLine);
+            def.startLine, def.endLine).filter(call => !isDataMemberReference(
+                index.files.get(def.file), call, index.symbols.get(call.name) || []));
         // The reachability walk uses the legacy (non-accounting) path and most
         // entry/test symbols contain no calls. Avoid constructing receiver,
         // overload, and flow machinery for an empty source range. Contract
@@ -5545,7 +5563,8 @@ function findCallees(index, definition, options = {}) {
             if (!entry) {
                 const defs = index.symbols.get(call.name) || [];
                 const owners = defs.filter(s => !NON_CALLABLE_TYPES.has(s.type)).length;
-                entry = { name: call.name, reason, callCount: 0, sites: [], ownerCount: owners, ...meta };
+                entry = { name: call.name, reason, callCount: 0, sites: [], ownerCount: owners,
+                    ...(call.isFunctionReference && { functionReference: true }), ...meta };
                 unverifiedCallees.set(key, entry);
             }
             entry.callCount++;

package/core/execute.js

@@ -1462,6 +1462,7 @@ const HANDLERS = {
                 unused: p.unused || false,
                 caseSensitive: p.caseSensitive || false,
                 exclude,
+                testExclude: p.includeTests ? undefined : ['test files'],
                 in: p.in,
                 file: p.file,
                 top: topVal || (p.lines ? undefined : 50),
@@ -1470,13 +1471,15 @@ const HANDLERS = {
             const unsupported = (!p.regex && (p.term || p.name))
                 ? require('./account').scanUnsupportedFiles(index, p.term || p.name)
                 : null;
-            let note;
+            let note = result.meta.filesSkipped > 0
+                ? `${result.meta.filesSkipped} test file(s) hidden by default (--include-tests).`
+                : undefined;
             if (unsupported?.lines > 0) {
                 Object.defineProperty(result, 'unsupportedMatches', {
                     value: unsupported,
                     enumerable: false, writable: true, configurable: true,
                 });
-                note = `${unsupported.lines} matching line(s) in ${unsupported.fileCount} unsupported-language file(s) were not structurally analyzed; verify with grep/ripgrep.`;
+                note = combineNotes([note, `${unsupported.lines} matching line(s) in ${unsupported.fileCount} unsupported-language file(s) were not structurally analyzed; verify with grep/ripgrep.`]);
             }
             return { ok: true, result, structural: true, note };
         }
@@ -2506,6 +2509,18 @@ function execute(index, command, params = {}) {
             const validationError = validatePublicParams(command, params);
             if (validationError) return { ok: false, error: validationError };
         }
+        // Public JSON paths and pasted stack frames may be absolute. Resolve
+        // only indexed files, then use the same relative scope as our handles.
+        const relativeIndexedFile = file => {
+            if (!file || !path.isAbsolute(file)) return file;
+            const resolved = index.resolveFilePathForQuery(file);
+            return typeof resolved === 'string' ? index.files.get(resolved).relativePath : file;
+        };
+        if (params.file) params.file = relativeIndexedFile(params.file);
+        const absoluteHandle = params.name && parseSymbolHandle(params.name);
+        if (absoluteHandle && path.isAbsolute(absoluteHandle.file)) {
+            params.name = relativeIndexedFile(absoluteHandle.file) + params.name.slice(absoluteHandle.file.length);
+        }
         // 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)) {
@@ -2520,6 +2535,7 @@ function execute(index, command, params = {}) {
             }
         }
         const response = handler(index, params);
+        response.projectRoot = index.root;
         const bundled = (index.discoveryIssues || []).filter(issue => issue.reason === 'bundled');
         if (bundled.length > 0) {
             const files = bundled.slice(0, 5).map(issue => issue.relativePath).join(', ');

package/core/output/analysis.js

@@ -205,7 +205,7 @@ function formatCalleeAccountLine(acct) {
 function unverifiedCalleeLines(entries, compact) {
     if (!entries || entries.length === 0) return [];
     const lines = [];
-    lines.push(`${compact ? '' : '\n'}CALLEES — UNVERIFIED (${entries.length}) — call syntax, receiver/binding unresolved:`);
+    lines.push(`${compact ? '' : '\n'}CALLEES — UNVERIFIED (${entries.length}) — call or callable-reference syntax, receiver/binding unresolved:`);
     for (const u of entries) {
         const owners = u.ownerCount > 1 ? ` (${u.ownerCount} owners)` : '';
         const sites = u.sites && u.sites.length > 0 ? ` L${u.sites.join(',L')}` : '';
@@ -461,7 +461,7 @@ function formatContext(ctx, options = {}) {
 
         const typeUnverified = ctx.unverifiedCallers || [];
         if (typeUnverified.length > 0) {
-            lines.push(`\nCALLERS — UNVERIFIED (${typeUnverified.length}) — call syntax, no binding/receiver evidence:`);
+            lines.push(`\nCALLERS — UNVERIFIED (${typeUnverified.length}) — call or callable-reference syntax, no binding/receiver evidence:`);
             formatAmbiguityCandidates(lines, ctx.ambiguityCandidates);
             const cap = 10;
             let shown = 0;
@@ -688,7 +688,7 @@ function formatContext(ctx, options = {}) {
     // Actionable ambiguity: call syntax without enough identity evidence.
     // Always visible and capped at 10 one-liners unless --all.
     if (actionableUnverified.length > 0) {
-        lines.push(`${compact ? '' : '\n'}CALLERS — UNVERIFIED (${actionableUnverified.length}) — call syntax, no binding/receiver evidence:`);
+        lines.push(`${compact ? '' : '\n'}CALLERS — UNVERIFIED (${actionableUnverified.length}) — call or callable-reference syntax, no binding/receiver evidence:`);
         formatAmbiguityCandidates(lines, ctx.ambiguityCandidates);
         const cap = (ctx.meta && ctx.meta.all) ? Infinity : 10;
         let shown = 0;
@@ -927,7 +927,7 @@ function formatImpact(impact, options = {}) {
 
     // Unverified tier: visible, capped at 10 one-liners
     if (impactUnverified.length > 0) {
-        lines.push(`${compact ? '' : '\n'}UNVERIFIED CALL SITES (${impactUnverified.length}) — call syntax, no binding/receiver evidence:`);
+        lines.push(`${compact ? '' : '\n'}UNVERIFIED CALL SITES (${impactUnverified.length}) — call or callable-reference syntax, no binding/receiver evidence:`);
         const cap = 10;
         for (const site of impactUnverified.slice(0, cap)) {
             const caller = site.callerName ? ` [${site.callerName}]` : '';
@@ -1085,7 +1085,7 @@ function formatAbout(about, options = {}) {
     const aboutUnverified = about.callers.unverified;
     if (aboutUnverified && aboutUnverified.total > 0) {
         lines.push('');
-        lines.push(`CALLERS — UNVERIFIED (${aboutUnverified.total}) — call syntax, no binding/receiver evidence:`);
+        lines.push(`CALLERS — UNVERIFIED (${aboutUnverified.total}) — call or callable-reference syntax, no binding/receiver evidence:`);
         for (const u of aboutUnverified.top) {
             const caller = u.callerName ? ` [${u.callerName}]` : '';
             const reason = u.reason ? ` (${unverifiedReasonLabel(u)})` : '';

package/core/output/public.js

@@ -40,12 +40,20 @@ function appendNote(text, note) {
 }
 
 /** Canonicalize object keys so JSON bytes do not depend on index provenance. */
-function canonicalJsonValue(value) {
-    if (Array.isArray(value)) return value.map(canonicalJsonValue);
+function canonicalJsonValue(value, root, field = undefined) {
+    if (Array.isArray(value)) return value.map(item => canonicalJsonValue(item, root, field));
+    if (root && typeof value === 'string' &&
+        ['file', 'filePath', 'callerFile', 'definitionFile', 'resolved', 'path', 'targetFile', 'from', 'to', 'root', 'files'].includes(field)) {
+        const path = require('path');
+        if (path.isAbsolute(value)) {
+            const relative = path.relative(root, value);
+            if (relative && relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative)) return relative;
+        }
+    }
     if (!value || typeof value !== 'object') return value;
     const canonical = {};
     for (const key of Object.keys(value).sort()) {
-        canonical[key] = canonicalJsonValue(provenanceReplacer(key, value[key]));
+        canonical[key] = canonicalJsonValue(provenanceReplacer(key, value[key]), root, key);
     }
     return canonical;
 }
@@ -474,12 +482,13 @@ function formatPublicJson(command, result, params = {}, execution = {}) {
             ...(data && data.ok === false && { ok: false }),
             ...(modeOf(command, result) && { mode: modeOf(command, result) }),
             contract: contractMeta(command),
+            ...(execution.projectRoot && { pathBase: execution.projectRoot }),
             ...commandMeta,
             ...(execution.note && { note: execution.note }),
         },
         data,
     };
-    return JSON.stringify(canonicalJsonValue(envelope), null, 2);
+    return JSON.stringify(canonicalJsonValue(envelope, execution.projectRoot), null, 2);
 }
 
 module.exports = {

package/core/output/refactoring.js

@@ -522,7 +522,10 @@ function formatAuditAsync(result) {
         lines.push(`${file} (${fileIssues.length})`);
         for (const issue of fileIssues) {
             const caller = issue.callerName ? ` [${issue.callerName}]` : '';
-            lines.push(`  :${issue.line}${caller}  ${issue.calleeName}() — async, not awaited`);
+            const detail = issue.reason === 'stored-promise-used-as-value'
+                ? `${issue.variable} used as a resolved value; promise from ${issue.calleeName}() at line ${issue.originLine}`
+                : `${issue.calleeName}() — async, not awaited`;
+            lines.push(`  :${issue.line}${caller}  ${detail}`);
         }
     }
     return lines.join('\n');

package/core/project.js

@@ -1105,6 +1105,11 @@ class ProjectIndex {
             const lowerPath = filePath.toLowerCase();
             for (const pattern of filters.exclude) {
                 const lowerPattern = pattern.toLowerCase();
+                if (lowerPattern === 'test files') {
+                    const rp = path.isAbsolute(filePath) ? path.relative(this.root, filePath) : filePath;
+                    if (require('./shared').isTestPath(rp)) return false;
+                    continue;
+                }
                 let regex = this._excludeRegexCache?.get(lowerPattern);
                 if (!regex) {
                     const escaped = lowerPattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

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;
         };
@@ -978,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/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/python.js

@@ -2805,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "5.3.8",
+  "version": "5.4.0",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Auditable AST code intelligence for AI agents: 18 task-oriented commands through one MCP tool, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java, C, C++, C#, and HTML.",
   "main": "index.js",
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "version": "node scripts/sync-server-version.js && git add server.json",
-    "test": "node --test test/audit-5.3.7.test.js test/audit-5.3.6.test.js test/evidence-provenance.test.js test/provenance-unit.test.js test/shell-output.test.js test/parser-unit.test.js test/integration.test.js test/cache.test.js test/formatter.test.js test/interactive.test.js test/feature.test.js test/regression-js.test.js test/regression-py.test.js test/regression-go.test.js test/regression-java.test.js test/regression-rust.test.js test/regression-c-family.test.js test/regression-cross.test.js test/regression-mcp.test.js test/mcp-protocol.test.js test/mcp-sdk-compat.test.js test/dependency-security.test.js test/regression-parser.test.js test/regression-commands.test.js test/regression-fixes.test.js test/regression-bugfixes.test.js test/release-surface-regressions.test.js test/prerelease-audit.test.js test/release-readiness-audit.test.js test/cross-language.test.js test/accuracy.test.js test/command-coverage.test.js test/perf-optimizations.test.js test/performance-gate-policy.test.js test/oracle-gate-policy.test.js test/outcome-policy.test.js test/consistency-eval.test.js test/agent-public-surface-benchmark.test.js test/command-contracts.test.js test/language-adapter.test.js test/systematic-test.js test/mcp-edge-cases.js test/conservation.test.js test/parity-test.js test/trust-matrix.test.js",
+    "test": "node --test test/audit-5.3.8.test.js test/audit-5.3.7.test.js test/audit-5.3.6.test.js test/evidence-provenance.test.js test/provenance-unit.test.js test/shell-output.test.js test/parser-unit.test.js test/integration.test.js test/cache.test.js test/formatter.test.js test/interactive.test.js test/feature.test.js test/regression-js.test.js test/regression-py.test.js test/regression-go.test.js test/regression-java.test.js test/regression-rust.test.js test/regression-c-family.test.js test/regression-cross.test.js test/regression-mcp.test.js test/mcp-protocol.test.js test/mcp-sdk-compat.test.js test/dependency-security.test.js test/regression-parser.test.js test/regression-commands.test.js test/regression-fixes.test.js test/regression-bugfixes.test.js test/release-surface-regressions.test.js test/prerelease-audit.test.js test/release-readiness-audit.test.js test/cross-language.test.js test/accuracy.test.js test/command-coverage.test.js test/perf-optimizations.test.js test/performance-gate-policy.test.js test/oracle-gate-policy.test.js test/outcome-policy.test.js test/consistency-eval.test.js test/agent-public-surface-benchmark.test.js test/command-contracts.test.js test/language-adapter.test.js test/systematic-test.js test/mcp-edge-cases.js test/conservation.test.js test/parity-test.js test/trust-matrix.test.js",
     "benchmark:agent": "node test/agent-public-surface-benchmark.js",
     "benchmark:agent:gate": "node test/agent-public-surface-benchmark.js --gate",
     "benchmark:agent:legacy": "node test/agent-understanding-benchmark.js",