ucn 5.3.7 → 5.3.8

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,6 +136,12 @@ 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

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,14 @@ 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.
+
 ## 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/cache.js

@@ -712,7 +712,8 @@ 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.
+const CACHE_FORMAT_VERSION = 227;
 const USAGE_CACHE_FILE = 'usage-results.json';
 
 /**

package/core/execute.js

@@ -2330,7 +2330,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 +2346,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 +2374,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 };
     },
 

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/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

@@ -424,6 +424,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;

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/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'],

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

@@ -883,7 +883,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

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/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;
 }

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();
 }
 

package/languages/utils.js

@@ -54,11 +54,32 @@ function extractParams(paramsNode) {
     // functions that actually take zero arguments. Empty → '' so callers can
     // render `main()` cleanly.
     if (!paramsNode) return '...';
-    const text = paramsNode.text;
+    const text = nodeTextWithoutComments(paramsNode);
     const stripped = text.replace(/^\(|\)$/g, '').trim();
     return stripped;  // '' for empty params, '...' only when paramsNode missing
 }
 
+/**
+ * Signature text without AST comment nodes. Keep source offsets/line breaks
+ * intact for declarator slicing, and preserve strings (including forward
+ * annotations and defaults containing comment-like text) verbatim.
+ */
+function nodeTextWithoutComments(node) {
+    if (!node) return '';
+    const text = node.text;
+    const parts = [];
+    let offset = 0;
+    traverseTree(node, child => {
+        if (child.type !== 'comment' && !child.type.endsWith('_comment')) return true;
+        const start = child.startIndex - node.startIndex;
+        const end = child.endIndex - node.startIndex;
+        parts.push(text.slice(offset, start), text.slice(start, end).replace(/[^\r\n]/g, ' '));
+        offset = end;
+        return false;
+    });
+    return parts.length ? parts.join('') + text.slice(offset) : text;
+}
+
 /**
  * Parse parameters into structured format
  * @param {object} paramsNode - Tree-sitter parameters node
@@ -140,7 +161,7 @@ function parseStructuredParams(paramsNode, language) {
 
 function parseJSParam(param, info) {
     if (param.type === 'identifier') {
-        info.name = param.text;
+        info.name = nodeTextWithoutComments(param);
     } else if (param.type === 'required_parameter' || param.type === 'optional_parameter') {
         const patternNode = param.childForFieldName('pattern');
         const typeNode = param.childForFieldName('type');
@@ -148,18 +169,18 @@ function parseJSParam(param, info) {
             // Check if pattern is a rest_pattern (e.g., ...args inside required_parameter)
             if (patternNode.type === 'rest_pattern') {
                 const innerName = patternNode.namedChild(0);
-                info.name = innerName ? innerName.text : patternNode.text.replace(/^\.\.\./, '');
+                info.name = innerName ? nodeTextWithoutComments(innerName) : nodeTextWithoutComments(patternNode).replace(/^\.\.\./, '');
                 info.rest = true;
             } else {
-                info.name = patternNode.text;
+                info.name = nodeTextWithoutComments(patternNode);
             }
         }
-        if (typeNode) info.type = typeNode.text.replace(/^:\s*/, '');
+        if (typeNode) info.type = nodeTextWithoutComments(typeNode).replace(/^:\s*/, '');
         if (param.type === 'optional_parameter') info.optional = true;
         // Check for default value (e.g., priority: number = 1)
         const valueNode = param.childForFieldName('value');
         if (valueNode) {
-            info.default = valueNode.text;
+            info.default = nodeTextWithoutComments(valueNode);
             info.optional = true;
         } else if (!info.rest) {
             // Also check for bare number/string/etc. children as defaults.
@@ -170,14 +191,14 @@ function parseJSParam(param, info) {
             // wrecking expectedArgs.min and the signature display).
             const NON_DEFAULT_PARAM_CHILDREN = new Set([
                 'identifier', 'type_annotation', 'rest_pattern',
-                'accessibility_modifier', 'override_modifier', 'readonly', 'decorator',
+                'accessibility_modifier', 'override_modifier', 'readonly', 'decorator', 'comment',
             ]);
             for (let i = 0; i < param.namedChildCount; i++) {
                 const child = param.namedChild(i);
                 if (child !== patternNode && child !== (typeNode && typeNode.parent === param ? typeNode : null) &&
                     !NON_DEFAULT_PARAM_CHILDREN.has(child.type)) {
                     // This is likely a default value node
-                    info.default = child.text;
+                    info.default = nodeTextWithoutComments(child);
                     info.optional = true;
                     break;
                 }
@@ -186,27 +207,27 @@ function parseJSParam(param, info) {
     } else if (param.type === 'rest_parameter' || param.type === 'rest_pattern') {
         // rest_parameter = TypeScript, rest_pattern = JavaScript
         const patternNode = param.childForFieldName('pattern') || param.namedChild(0);
-        if (patternNode) info.name = patternNode.text;
+        if (patternNode) info.name = nodeTextWithoutComments(patternNode);
         info.rest = true;
     } else if (param.type === 'assignment_pattern') {
         const leftNode = param.childForFieldName('left');
         const rightNode = param.childForFieldName('right');
-        if (leftNode) info.name = leftNode.text;
-        if (rightNode) info.default = rightNode.text;
+        if (leftNode) info.name = nodeTextWithoutComments(leftNode);
+        if (rightNode) info.default = nodeTextWithoutComments(rightNode);
     } else if (param.type === 'object_pattern' || param.type === 'array_pattern') {
         // Destructured params: { name, value } or [a, b]
-        info.name = param.text;
+        info.name = nodeTextWithoutComments(param);
     }
 }
 
 function parsePythonParam(param, info) {
     if (param.type === 'identifier') {
-        info.name = param.text;
+        info.name = nodeTextWithoutComments(param);
     } else if (param.type === 'typed_parameter') {
         const nameNode = param.namedChild(0);
         const typeNode = param.childForFieldName('type');
-        if (nameNode) info.name = nameNode.text;
-        if (typeNode) info.type = typeNode.text;
+        if (nameNode) info.name = nodeTextWithoutComments(nameNode);
+        if (typeNode) info.type = nodeTextWithoutComments(typeNode);
         // Python wraps annotated splats in typed_parameter, with the actual
         // `*args` / `**kwargs` node as its first named child. Treating those
         // as ordinary required parameters makes every short call look broken.
@@ -218,12 +239,12 @@ function parsePythonParam(param, info) {
         const nameNode = param.childForFieldName('name');
         const valueNode = param.childForFieldName('value');
         const typeNode = param.childForFieldName('type');
-        if (nameNode) info.name = nameNode.text;
-        if (valueNode) info.default = valueNode.text;
-        if (typeNode) info.type = typeNode.text;
+        if (nameNode) info.name = nodeTextWithoutComments(nameNode);
+        if (valueNode) info.default = nodeTextWithoutComments(valueNode);
+        if (typeNode) info.type = nodeTextWithoutComments(typeNode);
         info.optional = true;
     } else if (param.type === 'list_splat_pattern' || param.type === 'dictionary_splat_pattern') {
-        info.name = param.text;
+        info.name = nodeTextWithoutComments(param);
         info.rest = true;
     }
 }
@@ -237,11 +258,11 @@ function parseGoParam(param, info) {
         for (let i = 0; i < param.namedChildCount; i++) {
             const child = param.namedChild(i);
             if (child && child.type === 'identifier') {
-                names.push(child.text);
+                names.push(nodeTextWithoutComments(child));
             }
         }
         if (names.length > 0) info.name = names[0];
-        if (typeNode) info.type = typeNode.text;
+        if (typeNode) info.type = nodeTextWithoutComments(typeNode);
         // Interface method declarations commonly omit parameter names:
         // `Match(*http.Request, *RouteMatch) bool`. These are still two real
         // signature slots. Dropping them made verify/plan see zero arguments
@@ -249,7 +270,7 @@ function parseGoParam(param, info) {
         // slot. Preserve the authored type as the display token while marking
         // it unnamed so signature consumers can distinguish it from a name.
         if (names.length === 0 && typeNode) {
-            info.name = typeNode.text;
+            info.name = nodeTextWithoutComments(typeNode);
             info.unnamed = true;
             delete info.type;
         }
@@ -261,9 +282,9 @@ function parseGoParam(param, info) {
         // Go variadic: `args ...int`
         const nameNode = param.childForFieldName('name');
         const typeNode = param.childForFieldName('type');
-        if (nameNode) info.name = nameNode.text;
+        if (nameNode) info.name = nodeTextWithoutComments(nameNode);
         else info.name = '...';
-        if (typeNode) info.type = '...' + typeNode.text;
+        if (typeNode) info.type = '...' + nodeTextWithoutComments(typeNode);
         info.rest = true;
     }
 }
@@ -272,10 +293,10 @@ function parseRustParam(param, info) {
     if (param.type === 'parameter') {
         const patternNode = param.childForFieldName('pattern');
         const typeNode = param.childForFieldName('type');
-        if (patternNode) info.name = patternNode.text;
-        if (typeNode) info.type = typeNode.text;
+        if (patternNode) info.name = nodeTextWithoutComments(patternNode);
+        if (typeNode) info.type = nodeTextWithoutComments(typeNode);
     } else if (param.type === 'self_parameter') {
-        info.name = param.text;
+        info.name = nodeTextWithoutComments(param);
     }
 }
 
@@ -294,8 +315,8 @@ function parseJavaParam(param, info) {
                 }
             }
         }
-        if (nameNode) info.name = nameNode.text;
-        if (typeNode) info.type = typeNode.text;
+        if (nameNode) info.name = nodeTextWithoutComments(nameNode);
+        if (typeNode) info.type = nodeTextWithoutComments(typeNode);
         if (param.type === 'spread_parameter') info.rest = true;
     }
 }
@@ -1051,6 +1072,7 @@ function sameNode(a, b) {
 }
 
 module.exports = {
+    nodeTextWithoutComments,
     sameNode,
     traverseTree,
     traverseTreeCached,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "5.3.7",
+  "version": "5.3.8",
   "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.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.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",