ucn 3.8.25 → 4.0.0

package/languages/rust.js

@@ -10,7 +10,8 @@ const {
     traverseTreeCached,
     nodeToLocation,
     parseStructuredParams,
-    extractRustDocstring
+    extractRustDocstring,
+    visitNameNodes,
 } = require('./utils');
 const { PARSE_OPTIONS, safeParse } = require('./index');
 
@@ -44,6 +45,30 @@ function extractRustParams(paramsNode) {
     return params;
 }
 
+/**
+ * Base type name from a type-alias target (fix #208): SpannedString<Style>
+ * → SpannedString, module::Type → Type, &T → T. dyn/impl/tuple/fn shapes
+ * return null — not nominal method receivers.
+ */
+function aliasBaseTypeName(typeNode) {
+    if (!typeNode) return null;
+    if (typeNode.type === 'type_identifier') return typeNode.text;
+    if (typeNode.type === 'reference_type') {
+        for (let i = 0; i < typeNode.namedChildCount; i++) {
+            const r = aliasBaseTypeName(typeNode.namedChild(i));
+            if (r) return r;
+        }
+        return null;
+    }
+    if (typeNode.type === 'generic_type') {
+        return aliasBaseTypeName(typeNode.namedChild(0));
+    }
+    if (typeNode.type === 'scoped_type_identifier') {
+        return typeNode.childForFieldName('name')?.text || null;
+    }
+    return null;
+}
+
 /**
  * Extract visibility modifier
  */
@@ -492,6 +517,11 @@ function _processClass(node, types, processedRanges, lines, code) {
             const { startLine, endLine } = nodeToLocation(node, lines);
             const docstring = extractRustDocstring(lines, startLine);
             const visibility = extractVisibility(node.text);
+            // `pub type StyledString = SpannedString<Style>;` — the alias IS
+            // the aliased type (compiler identity). Record the base name so
+            // callers can treat alias-qualified receivers as the base type
+            // (fix #208 — cursive StyledString::plain).
+            const aliasOf = aliasBaseTypeName(node.childForFieldName('type'));
 
             types.push({
                 name: nameNode.text,
@@ -500,6 +530,7 @@ function _processClass(node, types, processedRanges, lines, code) {
                 type: 'type',
                 members: [],
                 modifiers: visibility ? [visibility] : [],
+                ...(aliasOf && { aliasOf }),
                 ...(docstring && { docstring })
             });
         }
@@ -912,6 +943,164 @@ function _findRustChainRootType(callNode) {
  * @param {object} parser - Tree-sitter parser instance
  * @returns {Array<{name: string, line: number, isMethod: boolean, receiver?: string, isMacro?: boolean}>}
  */
+/**
+ * Extract call-shaped token sequences from a macro body. Macro arguments are
+ * almost always ordinary expressions (assert_eq!, format!, vec!, write!), but
+ * tree-sitter parses them as a flat token_tree, so the regular call_expression
+ * handler never sees them. Recognized shapes (still AST token nodes, no text
+ * regex):  ident (…)  ·  recv . ident (…)  ·  Path :: ident (…)
+ * Emitted calls mirror the regular handlers' field contract and carry
+ * inMacro: true.
+ */
+function extractCallsFromTokenTree(tree, enclosingFunction, calls, getReceiverType) {
+    const children = [];
+    for (let i = 0; i < tree.childCount; i++) children.push(tree.child(i));
+    for (let i = 0; i < children.length; i++) {
+        const tok = children[i];
+        if (tok.type === 'token_tree') {
+            extractCallsFromTokenTree(tok, enclosingFunction, calls, getReceiverType);
+            continue;
+        }
+        if (tok.type !== 'identifier') continue;
+        const next = children[i + 1];
+        const prev = children[i - 1];
+        // $metavariable(...) — a macro fragment, not a named call
+        if (prev && prev.type === '$') continue;
+        // Nested macro invocation: name!(...)
+        if (next && next.type === '!' &&
+            children[i + 2] && children[i + 2].type === 'token_tree') {
+            calls.push({
+                name: tok.text,
+                line: tok.startPosition.row + 1,
+                isMethod: false,
+                isMacro: true,
+                inMacro: true,
+                enclosingFunction
+            });
+            continue;
+        }
+        if (!next || next.type !== 'token_tree' || !next.text.startsWith('(')) continue;
+        if (prev && prev.type === '::') {
+            // Path call: Type::func(...) / module::sub::func(...) — segments
+            // can be identifiers, primitives (char::from), or path keywords
+            const isSegment = (n) => n && ['identifier', 'primitive_type', 'self', 'super', 'crate'].includes(n.type);
+            const segments = [];
+            let j = i - 1;
+            while (j >= 1 && children[j].type === '::') {
+                let k = j - 1;
+                if (children[k] && children[k].type === '>') {
+                    // Turbofish: `Vec::<PatternSource>::new(...)` — angle
+                    // brackets do NOT group into token_trees, so skip the
+                    // <...> token run (nesting-aware) back to the matching
+                    // `<`, which the turbofish form introduces with `::`.
+                    // Without this the walk stopped at `>`, emitted a
+                    // receiver-less path call, and `Vec::<T>::new()` inside
+                    // assert_eq! scope-confirmed against every project `new`
+                    // (fix #222, ripgrep-seed-C-measured).
+                    let depth = 1;
+                    k--;
+                    while (k >= 0 && depth > 0) {
+                        if (children[k].type === '>') depth++;
+                        else if (children[k].type === '<') depth--;
+                        if (depth > 0) k--;
+                    }
+                    if (k < 1 || children[k - 1].type !== '::') break;
+                    k -= 2;
+                }
+                if (!isSegment(children[k])) break;
+                segments.unshift(children[k].text);
+                j = k - 1;
+            }
+            calls.push({
+                name: tok.text,
+                line: tok.startPosition.row + 1,
+                isMethod: segments.length > 0,
+                isPathCall: true,
+                receiver: segments.length > 0 ? segments.join('::') : undefined,
+                inMacro: true,
+                enclosingFunction
+            });
+        } else if (prev && prev.type === '.') {
+            // Method call: recv.method(...)
+            const recvTok = children[i - 2];
+            const receiver = recvTok && (recvTok.type === 'identifier' || recvTok.type === 'self')
+                ? recvTok.text : undefined;
+            // Literal receivers type as builtins inside macros too (fix #220,
+            // ripgrep-measured: assert_eq!(.., vec!["match:fg".parse()...]))
+            const litType = recvTok
+                ? ({ string_literal: 'str', raw_string_literal: 'str',
+                    char_literal: 'char', boolean_literal: 'bool' })[recvTok.type]
+                : undefined;
+            const receiverType = (receiver && receiver !== 'self' && getReceiverType)
+                ? getReceiverType(receiver) : litType;
+            calls.push({
+                name: tok.text,
+                line: tok.startPosition.row + 1,
+                isMethod: true,
+                receiver,
+                ...(receiverType && { receiverType }),
+                inMacro: true,
+                enclosingFunction
+            });
+        } else {
+            // Plain call: func(...) — includes enum-variant constructors
+            calls.push({
+                name: tok.text,
+                line: tok.startPosition.row + 1,
+                isMethod: false,
+                inMacro: true,
+                enclosingFunction
+            });
+        }
+    }
+}
+
+/**
+ * Variable receiving this call's result (fix #207 return-type flow):
+ *   let x = f(...);          → { assignedTo: 'x' }
+ *   let x = f(...)?;         → { assignedTo: 'x', unwrapped: true }
+ *   let x = f(...).unwrap(); → { assignedTo: 'x', unwrapped: true } (also .expect(...))
+ *   x = f(...);              → { assignedTo: 'x' }
+ * Value-transparent wrappers (`?`, .unwrap(), .expect(), .await) are walked
+ * through so the INNER call carries the target; the flow map then unwraps
+ * Result<T, _>/Option<T> from the producer's return annotation. `let mut x`
+ * works too — the pattern field is the plain identifier.
+ */
+function rustAssignmentTargetOf(callNode) {
+    let n = callNode;
+    let p = n.parent;
+    let unwrapped = false;
+    for (;;) {
+        if (!p) return undefined;
+        if (p.type === 'try_expression') { unwrapped = true; n = p; p = n.parent; continue; }
+        if (p.type === 'await_expression') { n = p; p = n.parent; continue; }
+        if (p.type === 'field_expression' &&
+            p.childForFieldName('value')?.id === n.id &&
+            ['unwrap', 'expect'].includes(p.childForFieldName('field')?.text) &&
+            p.parent?.type === 'call_expression' &&
+            p.parent.childForFieldName('function')?.id === p.id) {
+            unwrapped = true; n = p.parent; p = n.parent; continue;
+        }
+        break;
+    }
+    if (p.type === 'let_declaration') {
+        const value = p.childForFieldName('value');
+        const pattern = p.childForFieldName('pattern');
+        if (value && value.id === n.id && pattern?.type === 'identifier') {
+            return { assignedTo: pattern.text, ...(unwrapped && { unwrapped: true }) };
+        }
+        return undefined;
+    }
+    if (p.type === 'assignment_expression') {
+        const right = p.childForFieldName('right');
+        const left = p.childForFieldName('left');
+        if (right && right.id === n.id && left?.type === 'identifier') {
+            return { assignedTo: left.text, ...(unwrapped && { unwrapped: true }) };
+        }
+    }
+    return undefined;
+}
+
 function findCallsInCode(code, parser) {
     const tree = parseTree(parser, code);
     const calls = [];
@@ -1020,6 +1209,17 @@ function findCallsInCode(code, parser) {
         return undefined;
     };
 
+    // Walk up to the enclosing impl block's target type (impl<T> Foo<T> → Foo).
+    const findEnclosingImplType = (n) => {
+        for (let p = n.parent; p; p = p.parent) {
+            if (p.type === 'impl_item') {
+                const t = p.childForFieldName('type');
+                return (t && extractTypeName(t)) || undefined;
+            }
+        }
+        return undefined;
+    };
+
     traverseTree(tree.rootNode, (node) => {
         // Track function entry
         if (isFunctionNode(node)) {
@@ -1044,6 +1244,23 @@ function findCallsInCode(code, parser) {
 
             const enclosingFunction = getCurrentEnclosingFunction();
 
+            // Assignment target for return-type flow (fix #207): let args =
+            // parse_low_raw(...)? lets findCallers type args from the
+            // producer's declared return type at query time.
+            const assigned = rustAssignmentTargetOf(node);
+
+            // Call-site arg count for arity pruning (no spread syntax in Rust;
+            // UFCS `Type::method(&x, ...)` counts the explicit self — the
+            // pruning range accounts for the shift).
+            const argsNode = node.childForFieldName('arguments');
+            let argCount = 0;
+            if (argsNode) {
+                for (let i = 0; i < argsNode.namedChildCount; i++) {
+                    if (argsNode.namedChild(i).type === 'comment') continue;
+                    argCount++;
+                }
+            }
+
             if (funcNode.type === 'identifier') {
                 // Direct call: foo()
                 const firstArg = getFirstStringArg(node);
@@ -1051,6 +1268,9 @@ function findCallsInCode(code, parser) {
                     name: funcNode.text,
                     line: node.startPosition.row + 1,
                     isMethod: false,
+                    argCount,
+                    ...(assigned && { assignedTo: assigned.assignedTo }),
+                    ...(assigned?.unwrapped && { assignedUnwrap: true }),
                     enclosingFunction,
                     ...(firstArg && { firstStringArg: firstArg.value, firstStringArgInterp: firstArg.interp })
                 });
@@ -1076,7 +1296,63 @@ function findCallsInCode(code, parser) {
                             receiver = rootType;
                         }
                     }
-                    const receiverType = (receiver && receiver !== 'self') ? getReceiverType(receiver) : undefined;
+                    // fix #202: one-hop declared-field receivers — self.dent.path(),
+                    // low.sep.into_bytes() — with .clone() transparency (clone()
+                    // returns Self by stdlib convention). receiverRoot/Field/RootType
+                    // let findCallers hop to the field's declared type cross-file.
+                    let receiverRoot, receiverField, receiverRootType;
+                    if (!receiver) {
+                        let obj = valueNode;
+                        while (obj?.type === 'call_expression') {
+                            const innerFn = obj.childForFieldName('function');
+                            if (innerFn?.type === 'field_expression' &&
+                                innerFn.childForFieldName('field')?.text === 'clone') {
+                                obj = innerFn.childForFieldName('value');
+                            } else break;
+                        }
+                        if (obj?.type === 'field_expression') {
+                            const rootNode = obj.childForFieldName('value');
+                            const fldNode = obj.childForFieldName('field');
+                            if (fldNode?.type === 'field_identifier' && rootNode &&
+                                (rootNode.type === 'identifier' || rootNode.type === 'self')) {
+                                receiverRoot = rootNode.text;
+                                receiverField = fldNode.text;
+                                receiverRootType = rootNode.type === 'self'
+                                    ? findEnclosingImplType(node)
+                                    : getReceiverType(rootNode.text);
+                            }
+                        } else if (obj && obj !== valueNode &&
+                            (obj.type === 'identifier' || obj.type === 'self')) {
+                            // x.clone().m() — the receiver is effectively x
+                            receiver = obj.text;
+                        }
+                    }
+                    // Chained receiver (fix #220): the receiver IS a call —
+                    // self.as_u8().as_color() — record the producer so
+                    // findCallers can type it from the declared return.
+                    // Path producers (Config::load().x()) stay uncaptured
+                    // until a measured family justifies the path branch.
+                    let receiverCall, receiverCallIsMethod;
+                    if (!receiver && !receiverField && valueNode?.type === 'call_expression') {
+                        const prodFunc = valueNode.childForFieldName('function');
+                        if (prodFunc?.type === 'identifier') {
+                            receiverCall = prodFunc.text;
+                        } else if (prodFunc?.type === 'field_expression') {
+                            const pf = prodFunc.childForFieldName('field');
+                            if (pf) { receiverCall = pf.text; receiverCallIsMethod = true; }
+                        }
+                    }
+                    // Literal receivers carry their builtin type (fix #220,
+                    // ripgrep-measured): "match:fg:magenta".parse() is
+                    // str::parse, never a project method. Numeric literals
+                    // stay untyped (i32/u64/f64 ambiguity).
+                    const literalReceiverType = (!receiver && valueNode)
+                        ? ({ string_literal: 'str', raw_string_literal: 'str',
+                            char_literal: 'char', boolean_literal: 'bool' })[valueNode.type]
+                        : undefined;
+                    const receiverType = (receiver && receiver !== 'self')
+                        ? getReceiverType(receiver)
+                        : literalReceiverType;
                     const firstArg = getFirstStringArg(node);
                     // RUST-2: For chained calls like `a().b().parse::<T>().ok()`,
                     // each method should report the line where its OWN identifier
@@ -1089,6 +1365,13 @@ function findCallsInCode(code, parser) {
                         isMethod: true,
                         receiver,
                         ...(receiverType && { receiverType }),
+                        ...(receiverField && { receiverRoot, receiverField }),
+                        ...(receiverField && receiverRootType && { receiverRootType }),
+                        ...(receiverCall && { receiverCall }),
+                        ...(receiverCallIsMethod && { receiverCallIsMethod: true }),
+                        argCount,
+                        ...(assigned && { assignedTo: assigned.assignedTo }),
+                        ...(assigned?.unwrapped && { assignedUnwrap: true }),
                         enclosingFunction,
                         ...(firstArg && { firstStringArg: firstArg.value, firstStringArgInterp: firstArg.interp })
                     });
@@ -1100,12 +1383,20 @@ function findCallsInCode(code, parser) {
                 const segments = pathText.split('::');
                 const name = segments[segments.length - 1];
                 const firstArg = getFirstStringArg(node);
+                // Turbofish receivers (`Vec::<String>::new`) carry the type
+                // arguments as their own `::`-split segments — drop them so
+                // the receiver is the plain type/module path (fix #222).
+                const recvSegments = segments.slice(0, -1)
+                    .filter(s => !s.startsWith('<') && !s.endsWith('>'));
                 calls.push({
                     name: name,
                     line: node.startPosition.row + 1,
                     isMethod: segments.length > 1,
                     isPathCall: true,  // Distinguishes Type::func()/module::func() from obj.method()
-                    receiver: segments.length > 1 ? segments.slice(0, -1).join('::') : undefined,
+                    receiver: recvSegments.length > 0 ? recvSegments.join('::') : undefined,
+                    argCount,
+                    ...(assigned && { assignedTo: assigned.assignedTo }),
+                    ...(assigned?.unwrapped && { assignedUnwrap: true }),
                     enclosingFunction,
                     ...(firstArg && { firstStringArg: firstArg.value, firstStringArgInterp: firstArg.interp })
                 });
@@ -1124,17 +1415,27 @@ function findCallsInCode(code, parser) {
             const nameNode = node.childForFieldName('name');
             if (nameNode) {
                 let typeName = null;
+                let pathQualifier = null;
                 if (nameNode.type === 'type_identifier') {
                     typeName = nameNode.text;
                 } else if (nameNode.type === 'scoped_type_identifier') {
-                    // path::Foo or Enum::Variant — emit as the rightmost name.
+                    // path::Foo or Enum::Variant — emit as the rightmost name,
+                    // keeping the qualifier as receiver (fix #206): a
+                    // path-qualified type must not resolve to a same-file
+                    // binding of an unrelated same-name symbol.
                     const innerNameNode = nameNode.childForFieldName('name');
                     if (innerNameNode) {
                         typeName = innerNameNode.text;
+                        const pathNode = nameNode.childForFieldName('path');
+                        if (pathNode) {
+                            const segs = pathNode.text.split('::');
+                            pathQualifier = segs[segs.length - 1] || null;
+                        }
                     } else {
                         // Fallback: split by ::
                         const parts = nameNode.text.split('::');
                         typeName = parts[parts.length - 1];
+                        if (parts.length > 1) pathQualifier = parts[parts.length - 2] || null;
                     }
                 }
                 if (typeName) {
@@ -1144,6 +1445,7 @@ function findCallsInCode(code, parser) {
                         line: node.startPosition.row + 1,
                         isMethod: false,
                         isConstructor: true,
+                        ...(pathQualifier && { receiver: pathQualifier }),
                         enclosingFunction
                     });
                 }
@@ -1153,13 +1455,13 @@ function findCallsInCode(code, parser) {
         // Handle macro invocations: println!(), vec![]
         if (node.type === 'macro_invocation') {
             const macroNode = node.childForFieldName('macro');
+            const enclosingFunction = getCurrentEnclosingFunction();
             if (macroNode) {
                 let macroName = macroNode.text;
                 // Remove the trailing ! if present in the name
                 if (macroName.endsWith('!')) {
                     macroName = macroName.slice(0, -1);
                 }
-                const enclosingFunction = getCurrentEnclosingFunction();
                 calls.push({
                     name: macroName,
                     line: node.startPosition.row + 1,
@@ -1168,6 +1470,35 @@ function findCallsInCode(code, parser) {
                     enclosingFunction
                 });
             }
+            // Calls INSIDE the macro body: tree-sitter parses macro arguments
+            // as an unstructured token_tree, which hid every call written
+            // inside assert_eq!/format!/vec!/write! (measured: 175 unclaimed
+            // call lines on ripgrep — test assertions live in macros).
+            for (let i = 0; i < node.childCount; i++) {
+                const child = node.child(i);
+                if (child.type === 'token_tree') {
+                    extractCallsFromTokenTree(child, enclosingFunction, calls, getReceiverType);
+                }
+            }
+            return true;
+        }
+
+        // macro_rules! definitions: the transcriber token_tree holds concrete
+        // call templates (write!(stderr, $($tt)*) in messages.rs) — real call
+        // sites in every expansion. The matcher (token_tree_pattern) holds
+        // fragment specifiers, never calls — skipped.
+        if (node.type === 'macro_definition') {
+            const enclosingFunction = getCurrentEnclosingFunction();
+            for (let i = 0; i < node.namedChildCount; i++) {
+                const rule = node.namedChild(i);
+                if (rule.type !== 'macro_rule') continue;
+                for (let j = 0; j < rule.childCount; j++) {
+                    const part = rule.child(j);
+                    if (part.type === 'token_tree') {
+                        extractCallsFromTokenTree(part, enclosingFunction, calls, getReceiverType);
+                    }
+                }
+            }
             return true;
         }
 
@@ -1435,6 +1766,41 @@ function findExportsInCode(code, parser) {
     }
 
     traverseTreeCached(tree.rootNode, (node) => {
+        // Public renamed re-exports: `pub use foo::bar as baz;` (also nested in
+        // use lists: `pub use m::{a as b}`). name keeps the source symbol; alias
+        // carries the external name callers use. Plain (un-renamed) `pub use`
+        // re-exports are intentionally not emitted here — only renames feed the
+        // export-alias caller resolution.
+        if (node.type === 'use_declaration' && hasVisibility(node)) {
+            const line = node.startPosition.row + 1;
+            const collectAsClauses = (n) => {
+                if (n.type === 'use_as_clause') {
+                    const srcNode = n.namedChild(0);
+                    const aliasNode = n.namedChild(1);
+                    // Last path segment is the source symbol name (foo::bar -> bar)
+                    let local = null;
+                    if (srcNode) {
+                        if (srcNode.type === 'identifier' || srcNode.type === 'type_identifier') {
+                            local = srcNode.text;
+                        } else if (srcNode.type === 'scoped_identifier') {
+                            const nameField = srcNode.childForFieldName('name');
+                            local = nameField ? nameField.text : null;
+                        }
+                    }
+                    if (local && aliasNode && aliasNode.text !== local) {
+                        exports.push({
+                            name: local, type: 're-export', line,
+                            source: srcNode.text, alias: aliasNode.text,
+                        });
+                    }
+                    return;
+                }
+                for (let i = 0; i < n.namedChildCount; i++) collectAsClauses(n.namedChild(i));
+            };
+            collectAsClauses(node);
+            return true;
+        }
+
         // Public functions
         if (node.type === 'function_item' && hasVisibility(node)) {
             const nameNode = node.childForFieldName('name');
@@ -1563,7 +1929,7 @@ function findUsagesInCode(code, name, parser) {
     const tree = parseTree(parser, code);
     const usages = [];
 
-    traverseTreeCached(tree.rootNode, (node) => {
+    visitNameNodes(tree, code, name, (node) => {
         // Look for identifier, field_identifier (method names in obj.method() calls),
         // and type_identifier (type references in params, return types, struct expressions, etc.)
         const isIdentifier = node.type === 'identifier' || node.type === 'field_identifier' || node.type === 'type_identifier';
@@ -1598,11 +1964,14 @@ function findUsagesInCode(code, name, parser) {
                      parent.childForFieldName('function') === node) {
                 usageType = 'call';
             }
-            // Scoped call: Type::method() — identifier inside scoped_identifier inside call_expression
+            // Scoped call: Type::method() — only the LAST segment is the callee;
+            // the path qualifier (Type in Type::method()) is a type reference,
+            // not a call of Type
             else if (parent.type === 'scoped_identifier') {
                 const grandparent = parent.parent;
                 if (grandparent && grandparent.type === 'call_expression' &&
-                    grandparent.childForFieldName('function') === parent) {
+                    grandparent.childForFieldName('function') === parent &&
+                    parent.childForFieldName('name') === node) {
                     usageType = 'call';
                 }
             }

package/languages/utils.js

@@ -460,36 +460,56 @@ function parseJSDocTags(codeOrLines, startLine) {
     }
     const block = blockLines.join('\n');
 
-    // @param {Type} name  — capture balanced braces (no nested braces in JSDoc types in practice)
+    // @param {Type} name — balanced-brace scan so nested types survive
+    // (e.g. `{{ ok: boolean, error?: string }}` or `{Object<string, {x: number}>}`)
     const paramTypes = {};
     let any = false;
-    const paramRegex = /@param\s+\{([^}]+)\}\s+([A-Za-z_$][\w$]*)/g;
+    const paramTagRegex = /@param\s+/g;
     let m;
-    while ((m = paramRegex.exec(block)) !== null) {
-        const type = m[1].trim();
-        const name = m[2];
-        // Strip optional brackets if author wrote @param {Type} [name]; here we already excluded that
-        // but also handle @param {Type} [name=default] form by scanning a separate regex
-        paramTypes[name] = type;
-        any = true;
-    }
-    // Optional-bracket form: @param {Type} [name] or [name=default]
-    const paramOptRegex = /@param\s+\{([^}]+)\}\s+\[([A-Za-z_$][\w$]*)(?:\s*=[^\]]*)?\]/g;
-    while ((m = paramOptRegex.exec(block)) !== null) {
-        const type = m[1].trim();
-        const name = m[2];
-        if (!paramTypes[name]) paramTypes[name] = type;
+    while ((m = paramTagRegex.exec(block)) !== null) {
+        const braced = extractBracedType(block, m.index + m[0].length);
+        if (!braced) continue;
+        // Name follows the closing brace: plain `name` or optional `[name]` / `[name=default]`
+        const rest = block.slice(braced.endIdx);
+        const nameMatch = rest.match(/^\s+(?:\[([A-Za-z_$][\w$]*)(?:\s*=[^\]]*)?\]|([A-Za-z_$][\w$]*))/);
+        if (!nameMatch) continue;
+        const name = nameMatch[1] || nameMatch[2];
+        paramTypes[name] = braced.type.trim().replace(/\s+/g, ' ');
         any = true;
     }
 
     // @returns {Type} or @return {Type}
-    const retMatch = block.match(/@returns?\s+\{([^}]+)\}/);
+    const retTag = block.match(/@returns?\s+/);
+    const retBraced = retTag ? extractBracedType(block, retTag.index + retTag[0].length) : null;
     const result = {};
     if (any) result.paramTypes = paramTypes;
-    if (retMatch) result.returnType = retMatch[1].trim();
+    if (retBraced) result.returnType = retBraced.type.trim().replace(/\s+/g, ' ');
     return result;
 }
 
+/**
+ * Extract a balanced-brace type expression starting at an opening `{`.
+ * Returns the inner text (without the outer braces) and the index just past
+ * the matching closing brace, or null when text[openIdx] is not `{` or the
+ * braces never balance.
+ * @param {string} text
+ * @param {number} openIdx - index expected to hold the opening `{`
+ * @returns {{ type: string, endIdx: number }|null}
+ */
+function extractBracedType(text, openIdx) {
+    if (text[openIdx] !== '{') return null;
+    let depth = 0;
+    for (let k = openIdx; k < text.length; k++) {
+        const ch = text[k];
+        if (ch === '{') depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) return { type: text.slice(openIdx + 1, k), endIdx: k + 1 };
+        }
+    }
+    return null;
+}
+
 /**
  * Compute the final paramTypes/returnType for a function symbol.
  * Native AST types take precedence; JSDoc fills gaps.
@@ -708,6 +728,39 @@ function traverseTreeCached(rootNode, callback) {
     }
 }
 
+/**
+ * Visit the AST node covering each whole-word text occurrence of `name`.
+ *
+ * Equivalent to a full-tree walk whose callback filters on
+ * `node.text === name` token types — but O(occurrences) instead of
+ * O(nodes): the source string locates candidate offsets (indexOf + ASCII
+ * word-boundary pre-check), and descendantForIndex jumps straight to the
+ * deepest node spanning each. The callback receives the identifier-style
+ * token when the occurrence is code, or a string/comment/longer-identifier
+ * token otherwise — callers' existing type/text guards skip those, so
+ * false-positive candidates are safe and false negatives are impossible
+ * (a token equal to `name` cannot have identifier characters adjacent,
+ * or the token would extend past the name).
+ *
+ * node-tree-sitter indexes are UTF-16 code units, same as JS string
+ * offsets — unicode content needs no special handling.
+ */
+function visitNameNodes(tree, code, name, callback) {
+    const isWordCode = (c) =>
+        (c >= 48 && c <= 57) || (c >= 65 && c <= 90) ||
+        (c >= 97 && c <= 122) || c === 95 || c === 36; // [0-9A-Za-z_$]
+    const len = name.length;
+    let idx = code.indexOf(name);
+    while (idx !== -1) {
+        if ((idx === 0 || !isWordCode(code.charCodeAt(idx - 1))) &&
+            (idx + len >= code.length || !isWordCode(code.charCodeAt(idx + len)))) {
+            const node = tree.rootNode.descendantForIndex(idx);
+            if (node) callback(node);
+        }
+        idx = code.indexOf(name, idx + len);
+    }
+}
+
 /**
  * Clear the cached node list (call when the tree changes).
  */
@@ -900,6 +953,7 @@ function extractSprintfPrefix(callNode) {
 module.exports = {
     traverseTree,
     traverseTreeCached,
+    visitNameNodes,
     getCachedNodeList,
     clearNodeListCache,
     nodeToLocation,