ucn 5.3.7 → 5.4.0

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

@@ -126,7 +126,7 @@ answers:
 ucn find handleRequest --lines            # path:line:signature   # kind
 ucn show handleRequest --lines            # callers as path:line:text; unverified ones end in "\t# unverified: <reason>"
 ucn show handleRequest --lines --sections=callees
-ucn usages handleRequest --lines          # every literal-name line; non-call kinds tagged "# import" / "# definition"
+ucn usages handleRequest --lines          # every literal-name occurrence; non-call kinds tagged "# import" / "# definition"
 ucn search 'retry(' --lines               # grep -n output, code-aware scope
 ucn impact handleRequest --lines
 ucn source handleRequest --raw            # the code and nothing else, ready for an exact-string edit
@@ -136,9 +136,17 @@ ucn source src/server.js:40-80 --raw
 Records go to stdout; the `ACCOUNT` / `CONTRACT` lines, notes, and the
 same-name disambiguation go to stderr prefixed `# ` (MCP keeps them in the one
 text block, and `--raw` appends its note as one trailing `# ` line there).
+`usages` emits one record per occurrence, so a source line may repeat; deduplicate
+`path:line` values for line counts. Definition handles start at decorators when
+present, while usages point at token lines (`nameLine` identifies the declaration
+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
@@ -202,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

@@ -33,7 +33,7 @@ structural or code-only search.
 |---|---|
 | `repo` | Repository orientation. Select `summary,files,stats,health` with `--sections`; `--deep` includes readiness evidence. Skipped unsupported source is listed with a grep/language-tool handoff. |
 | `deps <file>` | File dependency graph. Use `--direction=imports\|importers\|both`, `--detailed`, or `--cycles`. Cycles distinguish eager edges from function-local, Python typing-guarded, and TypeScript type-only edges. Complete cycle groups remain visible when enumeration is capped. |
-| `api [file]` | Static exported/public surface for a project or file. |
+| `api [file]` | Static exported/public surface for a project or file. An exact file includes tests; broader scans exclude tests with a count. Use `--include-tests` to include them. |
 | `entrypoints` | Framework, route, task, test, and runtime entry points. |
 | `endpoints` | Server/client HTTP surface; `--bridge` adds advisory matching. |
 
@@ -49,6 +49,20 @@ structural or code-only search.
 
 Symbol-listing commands emit handles such as `src/api.ts:42:handler`. Pass the full handle to symbol commands. `path:line` also works. Handles prevent same-named definitions from being silently combined.
 
+Definition handles and source spans start at the first decorator or annotation when present; literal usages point at the actual token line. Use a symbol's `nameLine` (when present, otherwise `startLine`) to compare declaration tokens with usages.
+
+Structural `search --param` matches parameter names, types, and defaults; `--returns` matches return annotations. Both exclude AST comments and preserve string contents. `--unused` lists callable symbols without call edges, not safe-delete candidates; decorated runtime registrations may still appear. Its safety note and decorator tags are retained in `--lines` output. Use `deadcode` and `usages` before deletion.
+
+`repo` summary/stats `buildTime` is the duration of the last index build (discovery, parsing, and graphs), retained in the cache. It excludes cache loading/saving and query execution, so it is not command wall time; `buildTimeNote` states this boundary.
+
+`--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/cli/index.js

@@ -917,7 +917,8 @@ Commands:
   deps <file>                     File graph; --direction=imports|importers|both
     --detailed                     Include import declarations
   deps --cycles                   Report circular dependencies (no file target)
-  api [file]                      Project or file public API
+  api [file]                      Project or file public API (exact files include tests;
+                                  broader scans exclude tests unless --include-tests)
   check [symbol]                  Signature check; without symbol, precommit check
   plan <symbol>                   Preview rename or parameter edits
   entrypoints                     Runtime and framework entry points
@@ -933,7 +934,8 @@ Common flags:
   --base=REF --staged --no-cache --clear-cache [--all] --max-files=N --workers=N
   --max-chars=N (text output; default 10K targeted / 3K broad, ceiling 100K)
   --lines  find/usages/search/show/impact: grep -n shape, one path:line:text
-           record per line (tags after a tab: # unverified: <reason>, # import,
+           record per output line; usages may repeat a source line per occurrence
+           (tags after a tab: # unverified: <reason>, # import,
            # callee); accounting and notes go to stderr as "# " lines; exit 1
            when nothing matched; exit 2 on errors. No default result cap.
            show defaults to callers; --sections=callers,callees selects bands.

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

@@ -712,7 +712,9 @@ function clearAllCaches() {
 // copied bindings and qualified macro receivers; TS indexed array evidence.
 // 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.
-const CACHE_FORMAT_VERSION = 226;
+// v227: signature parameter/return text excludes AST comments in every language.
+// 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 };
         }
@@ -2330,7 +2333,7 @@ const HANDLERS = {
     },
 
     api: (index, p) => {
-        if (p.file) {
+        if (p.file && typeof index.resolveFilePathForQuery(p.file) !== 'string') {
             const fileErr = checkFilePatternMatch(index, p.file);
             if (fileErr) return { ok: false, error: fileErr };
         }
@@ -2346,7 +2349,7 @@ const HANDLERS = {
                 return { ok: false, error: `No files matched the 'in' directory filter '${p.in}'.` };
             }
         }
-        let result = index.api(p.file, { in: p.in });
+        let result = index.api(p.file, { in: p.in, includeTests: p.includeTests });
         if (p.file) {
             const fileErr = checkFileError(result, p.file, index);
             if (fileErr) return { ok: false, error: fileErr };
@@ -2374,6 +2377,10 @@ const HANDLERS = {
             }
             result = items;
         }
+        if (result.apiInfo?.excludedTestFiles > 0) {
+            const excluded = `${result.apiInfo.excludedTestFiles} test file(s) excluded from API; use --include-tests to include them, or name an exact file.`;
+            note = note ? `${note}\n${excluded}` : excluded;
+        }
         return { ok: true, result, note };
     },
 
@@ -2502,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)) {
@@ -2516,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/graph.js

@@ -564,6 +564,8 @@ function api(index, filePath, options = {}) {
     const results = [];
     let scopedFiles = 0;
     let pythonImplicitFiles = 0;
+    let excludedTestFiles = 0;
+    let explicitFile = false;
 
     let fileIterator;
     if (filePath) {
@@ -573,6 +575,7 @@ function api(index, filePath, options = {}) {
             const fileEntry = index.files.get(resolved);
             if (!fileEntry) return { error: 'file-not-found', filePath };
             fileIterator = [[resolved, fileEntry]];
+            explicitFile = true;
         } else {
             // Fall back to pattern filter (substring match on relative path)
             const matches = [];
@@ -596,7 +599,8 @@ function api(index, filePath, options = {}) {
         }
 
         // Skip test files by default (test classes aren't part of public API)
-        if (!options.includeTests && isTestFile(fileEntry.relativePath, fileEntry.language)) {
+        if (!explicitFile && !options.includeTests && isTestFile(fileEntry.relativePath, fileEntry.language)) {
+            excludedTestFiles++;
             continue;
         }
         scopedFiles++;
@@ -612,7 +616,7 @@ function api(index, filePath, options = {}) {
     results.sort((a, b) => codeUnitCompare(a.file, b.file) ||
         (a.startLine - b.startLine) || codeUnitCompare(a.name, b.name));
     Object.defineProperty(results, 'apiInfo', {
-        value: { scopedFiles, pythonImplicitFiles },
+        value: { scopedFiles, pythonImplicitFiles, excludedTestFiles },
         enumerable: false, writable: true, configurable: true,
     });
     return results;

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/doctor.js

@@ -33,7 +33,7 @@ function formatDoctor(result, options = {}) {
     // Cache state
     if (result.cache) {
         const state = result.cache.fresh === true ? 'fresh' : result.cache.fresh === false ? 'stale' : 'unknown';
-        const buildHint = result.cache.buildMs ? `, ${result.cache.buildMs}ms build` : '';
+        const buildHint = result.cache.buildMs ? `, ${result.cache.buildMs}ms last index build (excludes cache I/O and query execution)` : '';
         lines.push(`Cache: ${state}${buildHint}`);
     }
     if (result.commandTrust) {

package/core/output/lines.js

@@ -29,7 +29,8 @@ function record(pathLike, line, text, tag = '') {
     // Keep unusual filenames from becoming notes or extra physical records.
     let file = String(pathLike).replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t');
     if (file.startsWith('# ')) file = './' + file;
-    return `${file}:${line == null ? 0 : line}:${body}${tag ? `\t# ${tag}` : ''}`;
+    const tagText = String(tag || '').replace(/\s+/g, ' ').trim();
+    return `${file}:${line == null ? 0 : line}:${body}${tagText ? `\t# ${tagText}` : ''}`;
 }
 
 function commentLines(text) {
@@ -95,9 +96,14 @@ function searchRecords(result) {
     if (result && !Array.isArray(result) && Array.isArray(result.results)) {
         for (const item of result.results) {
             const text = item.params != null ? `${item.name}(${item.params})` : item.name;
-            out.push(record(item.file, item.line, text, item.kind || item.type));
+            const decorators = (item.decorators || []).map(d => `@${String(d).replace(/^@/, '')}`).join(', ');
+            const tag = [item.kind || item.type, decorators].filter(Boolean).join('; ');
+            out.push(record(item.file, item.line, text, tag));
         }
         const meta = result.meta;
+        if (meta?.query?.unused) {
+            notes.push(...commentLines(require('./search').unusedSearchNote()));
+        }
         if (meta && meta.totalMatched > meta.shown) {
             notes.push(`# ${meta.totalMatched - meta.shown} more match(es) (--limit=N / --all)`);
         }

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;
 }
@@ -424,6 +432,9 @@ function formatPublicJson(command, result, params = {}, execution = {}) {
         if (result.meta.truncatedMatches > 0) commandMeta.truncated = true;
         if (result.unsupportedMatches) commandMeta.unsupportedMatches = result.unsupportedMatches;
     }
+    if (command === 'api' && result?.apiInfo) {
+        commandMeta.apiInfo = result.apiInfo;
+    }
     if (command === 'entrypoints' && result?.filterInfo) {
         commandMeta.hiddenTestEntrypoints = result.filterInfo.hiddenTests;
         commandMeta.testsIncluded = result.filterInfo.testsIncluded;
@@ -471,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/output/reporting.js

@@ -125,7 +125,7 @@ function formatStats(stats, options = {}) {
         lines.push(`Files: ${stats.files}`);
     }
     lines.push(`Symbols: ${stats.symbols}`);
-    lines.push(`Build time: ${stats.buildTime}ms`);
+    lines.push(`Last index build: ${stats.buildTime}ms (excludes cache I/O and query execution; reused from cache)`);
 
     lines.push('\nBy Language:');
     for (const [lang, info] of Object.entries(stats.byLanguage)) {

package/core/output/search.js

@@ -87,6 +87,10 @@ function formatSearchJson(results, term) {
 /**
  * Format structural search results (index-based queries)
  */
+function unusedSearchNote(flag = '--unused') {
+    return `${flag} lists callable symbols with no resolved call edge; it does not assess type/field/reference liveness and is not safe-delete proof. Confirm with deadcode and usages.`;
+}
+
 function formatStructuralSearch(result, options = {}) {
     const { results, meta } = result;
     const lines = [];
@@ -106,7 +110,7 @@ function formatStructuralSearch(result, options = {}) {
     lines.push(`Structural search: ${queryStr}`);
     lines.push('═'.repeat(60));
     if (meta.query.unused) {
-        lines.push(`NOTE: ${options.unusedFlag || '--unused'} lists callable symbols with no resolved call edge; it does not assess type/field/reference liveness and is not safe-delete proof. Confirm with deadcode and usages.`);
+        lines.push(`NOTE: ${unusedSearchNote(options.unusedFlag)}`);
         lines.push('');
     }
 
@@ -447,6 +451,7 @@ function formatTestsJson(tests, name) {
 }
 
 module.exports = {
+    unusedSearchNote,
     formatSearch,
     formatSearchJson,
     formatStructuralSearch,

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/registry.js

@@ -143,7 +143,7 @@ const FLAG_APPLICABILITY = {
     impact:       ['name', 'file', 'exclude', 'className', 'line', 'includeMethods', 'top', 'unreachableOnly', 'compact', 'base', 'staged', 'limit', 'all', 'lines'],
     tests:        ['name', 'file', 'exclude', 'className', 'line', 'callsOnly', 'depth', 'includeMethods', 'all'],
     deps:         ['file', 'exclude', 'depth', 'direction', 'all', 'detailed', 'cycles'],
-    api:          ['file', 'in', 'limit'],
+    api:          ['file', 'in', 'limit', 'includeTests'],
     check:        ['name', 'file', 'className', 'line', 'includeMethods', 'base', 'staged', 'limit'],
     plan:         ['name', 'file', 'className', 'line', 'addParam', 'removeParam', 'renameTo', 'defaultValue'],
     repo:         ['file', 'exclude', 'top', 'limit', 'all', 'detailed', 'topLevel', 'in', 'functions', 'hot', 'deep', 'sections'],