code-auditor-mcp 4.1.0 → 5.0.1

package/dist/utils/astUtils.js

@@ -22,6 +22,10 @@ function findChildOfType(node, type) {
 /**
  * Find all nodes matching a predicate in the AST subtree.
  * Replacement for the old `findNodesByKind<T>(node, SyntaxKind)`.
+ *
+ * @param root - The root AST node to search within.
+ * @param predicate - Predicate that returns true for nodes to keep.
+ * @returns All nodes for which the predicate returns true.
  */
 export function findNodesByType(root, predicate) {
     return findNodes(root, predicate);
@@ -56,6 +60,10 @@ export { bridgeCalculateComplexity as calculateComplexity };
  * Extract import statements from an AST root node.
  * Uses tree-sitter import_statement structure:
  *   import_statement → import_clause? → (identifier | named_imports) → string
+ *
+ * @param root - The root AST node to search for import statements.
+ * @param sourceCode - The original source text for name extraction.
+ * @returns The list of extracted imports.
  */
 export function getImports(root, sourceCode) {
     const imports = [];
@@ -121,32 +129,34 @@ export function getImports(root, sourceCode) {
 /**
  * Extract export statements from an AST root node.
  * Uses tree-sitter export_statement structure.
+ *
+ * @param root - The root AST node to search for export statements.
+ * @param sourceCode - The original source text for name extraction.
+ * @returns The list of extracted exports.
  */
 export function getExports(root, sourceCode) {
     const exports = [];
     // export declarations: export { name1, name2 }
-    const exportNodes = findNodes(root, n => n.type === 'export_statement' || n.type === 'export_declaration');
+    const exportNodes = findNodes(root, n => n.type === 'export_statement');
     for (const node of exportNodes) {
         const { line } = bridgeGetLineAndColumn(node);
         // Check for type-only exports
         const isTypeOnly = hasModifier(node, 'type');
-        // export clause with named exports
+        // export clause with named exports (`export { a, b }`) — the `export_clause`
+        // holds `export_specifier` children directly (no `named_exports` node).
         const exportClause = findChildOfType(node, 'export_clause');
         if (exportClause) {
-            const namedExports = findChildOfType(exportClause, 'named_exports');
-            if (namedExports) {
-                for (const child of namedExports.children ?? []) {
-                    if (child.type !== 'export_specifier')
-                        continue;
-                    const ids = child.children?.filter(c => c.type === 'identifier') ?? [];
-                    if (ids.length > 0) {
-                        exports.push({
-                            name: getNodeText(ids[ids.length - 1], sourceCode),
-                            isDefault: false,
-                            isTypeOnly,
-                            line
-                        });
-                    }
+            for (const child of exportClause.children ?? []) {
+                if (child.type !== 'export_specifier')
+                    continue;
+                const ids = child.children?.filter(c => c.type === 'identifier') ?? [];
+                if (ids.length > 0) {
+                    exports.push({
+                        name: getNodeText(ids[ids.length - 1], sourceCode),
+                        isDefault: false,
+                        isTypeOnly,
+                        line
+                    });
                 }
             }
         }
@@ -191,6 +201,10 @@ export function findClasses(root) {
 // ---------------------------------------------------------------------------
 /**
  * Get AST node for inspection/debugging.
+ *
+ * @param node - The AST node to inspect.
+ * @param sourceCode - The original source text for text extraction.
+ * @returns A plain-object snapshot of the node and its children.
  */
 export function getASTNode(node, sourceCode) {
     return {
@@ -205,6 +219,11 @@ export function getASTNode(node, sourceCode) {
 /**
  * Check if a node has a specific decorator.
  * Tree-sitter parses decorators as `decorator` nodes.
+ *
+ * @param node - The AST node to search for decorators.
+ * @param decoratorName - The decorator name to match.
+ * @param sourceCode - The original source text for name extraction.
+ * @returns True if the node carries a matching decorator.
  */
 export function hasDecorator(node, decoratorName, sourceCode) {
     const decorators = findNodes(node, n => n.type === 'decorator');
@@ -231,6 +250,10 @@ export function hasDecorator(node, decoratorName, sourceCode) {
 /**
  * Get method names from a class declaration node.
  * Tree-sitter: class_declaration → class_body → method_definition / public_field_definition
+ *
+ * @param classNode - The class declaration node to inspect.
+ * @param sourceCode - The original source text for name extraction.
+ * @returns The names of the class's methods and public fields.
  */
 export function getClassMethods(classNode, sourceCode) {
     const methods = [];
@@ -253,6 +276,9 @@ export function getClassMethods(classNode, sourceCode) {
 /**
  * Count lines of code (excluding comments and empty lines).
  * Takes source text directly instead of ts.SourceFile.
+ *
+ * @param sourceCode - The source text to count lines in.
+ * @returns The number of non-comment, non-empty lines.
  */
 export function countLinesOfCode(sourceCode) {
     const lines = sourceCode.split('\n');
@@ -290,6 +316,9 @@ export function isAsyncFunction(node) {
 /**
  * Get parameter count for a function/method node.
  * Tree-sitter: formal_parameters → required_parameter / optional_parameter.
+ *
+ * @param node - The function or method node to inspect.
+ * @returns The number of declared parameters.
  */
 export function getParameterCount(node) {
     const params = findChildOfType(node, 'formal_parameters');
@@ -297,8 +326,7 @@ export function getParameterCount(node) {
         return 0;
     let count = 0;
     for (const child of params.children ?? []) {
-        if (child.type === 'required_parameter' || child.type === 'optional_parameter' ||
-            child.type === 'rest_parameter') {
+        if (child.type === 'required_parameter' || child.type === 'optional_parameter') {
             count++;
         }
     }
@@ -330,6 +358,9 @@ export function findInterfaces(root) {
 /**
  * Parse a TypeScript file and return an AST.
  * Uses the adapterBridge parseFile function.
+ *
+ * @param filePath - The path of the file to parse.
+ * @returns The parsed AST plus any parse errors.
  */
 export async function parseTypeScriptFile(filePath) {
     // Dynamic import to avoid circular dependency
@@ -350,6 +381,10 @@ export async function parseTypeScriptFile(filePath) {
 /**
  * Enhanced version of getImports that returns detailed ImportMapping[].
  * Uses tree-sitter import_statement traversal.
+ *
+ * @param root - The root AST node to search for import statements.
+ * @param sourceCode - The original source text for name extraction.
+ * @returns The detailed import mappings extracted from the file.
  */
 export function getImportsDetailed(root, sourceCode) {
     const imports = [];
@@ -426,10 +461,14 @@ export function getImportsDetailed(root, sourceCode) {
 /**
  * Get re-exports from a source file.
  * Tree-sitter: export_statement → string (module specifier).
+ *
+ * @param root - The root AST node to search for re-exports.
+ * @param sourceCode - The original source text for name extraction.
+ * @returns The list of re-exported names and their source modules.
  */
 export function getReExports(root, sourceCode) {
     const reExports = [];
-    const exportNodes = findNodes(root, n => n.type === 'export_statement' || n.type === 'export_declaration');
+    const exportNodes = findNodes(root, n => n.type === 'export_statement');
     for (const node of exportNodes) {
         // Check if there's a module specifier (export { x } from './y')
         const moduleNode = findChildOfType(node, 'string');
@@ -438,22 +477,19 @@ export function getReExports(root, sourceCode) {
         const moduleSpecifier = getNodeText(moduleNode, sourceCode).replace(/^["']|["']$/g, '');
         const exportClause = findChildOfType(node, 'export_clause');
         if (exportClause) {
-            const namedExports = findChildOfType(exportClause, 'named_exports');
-            if (namedExports) {
-                for (const child of namedExports.children ?? []) {
-                    if (child.type !== 'export_specifier')
-                        continue;
-                    const identifiers = child.children?.filter(c => c.type === 'identifier') ?? [];
-                    if (identifiers.length > 0) {
-                        const name = identifiers.length > 1
-                            ? getNodeText(identifiers[0], sourceCode)
-                            : getNodeText(identifiers[identifiers.length - 1], sourceCode);
-                        reExports.push({ name, module: moduleSpecifier });
-                    }
+            for (const child of exportClause.children ?? []) {
+                if (child.type !== 'export_specifier')
+                    continue;
+                const identifiers = child.children?.filter(c => c.type === 'identifier') ?? [];
+                if (identifiers.length > 0) {
+                    const name = identifiers.length > 1
+                        ? getNodeText(identifiers[0], sourceCode)
+                        : getNodeText(identifiers[identifiers.length - 1], sourceCode);
+                    reExports.push({ name, module: moduleSpecifier });
                 }
             }
         }
-        else if (!exportClause) {
+        else {
             // export * from './module' — no export clause
             reExports.push({ name: '*', module: moduleSpecifier });
         }
@@ -471,12 +507,12 @@ export function getReExports(root, sourceCode) {
  * | TS API check                       | Tree-sitter equivalent                 |
  * |------------------------------------|----------------------------------------|
  * | ts.isTypeNode(p)                   | p.type === 'type_annotation'           |
- * | ts.isTypeReferenceNode(p)          | p.type === 'type_reference'            |
- * | ts.isTypeQueryNode(p)              | p.type === 'typeof_expression'         |
- * | ts.isQualifiedName(p)              | p.type === 'qualified_name'            |
+ * | ts.isTypeReferenceNode(p)          | p.type === 'type_identifier'           |
+ * | ts.isTypeQueryNode(p)              | p.type === 'type_query'                |
+ * | ts.isQualifiedName(p)              | p.type === 'nested_type_identifier'    |
  * | ts.isExpressionWithTypeArguments(p)| p.type === 'generic_type'              |
  * | ts.isPropertyAccessExpression(p)   | p.type === 'member_expression'         |
- * | ts.isHeritageClause(p)             | p.type === 'heritage_clause'           |
+ * | ts.isHeritageClause(p)             | p.type === 'class_heritage'            |
  * | ts.isInterfaceDeclaration(p)       | p.type === 'interface_declaration'     |
  * | ts.isTypeAliasDeclaration(p)       | p.type === 'type_alias_declaration'    |
  * | ts.isClassDeclaration(p)           | p.type === 'class_declaration'         |
@@ -494,16 +530,16 @@ export function getReExports(root, sourceCode) {
  * | ts.isTypePredicateNode(p)          | p.type === 'type_predicate'            |
  * | ts.isMethodDeclaration(p)          | p.type === 'method_definition'         |
  * | ts.isMethodSignature(p)            | p.type === 'method_signature'          |
- * | ts.isPropertyDeclaration(p)        | p.type === 'class_property'            |
+ * | ts.isPropertyDeclaration(p)        | p.type === 'public_field_definition'   |
  * | ts.isPropertySignature(p)          | p.type === 'property_signature'        |
- * | ts.isGetAccessorDeclaration(p)     | p.type === 'get_accessor'              |
+ * | ts.isGetAccessorDeclaration(p)     | p.type === 'method_definition'         |
  * | ts.isFunctionDeclaration(p)        | p.type === 'function_declaration'      |
  * | ts.isArrowFunction(p)              | p.type === 'arrow_function'            |
  * | ts.isFunctionExpression(p)         | p.type === 'function_expression'       |
  * | ts.isParameter(p)                  | p.type === 'required_parameter'        |
  * | ts.isCallExpression(p)             | p.type === 'call_expression'           |
  * | ts.isNewExpression(p)              | p.type === 'new_expression'            |
- * | ts.isTaggedTemplateExpression(p)   | p.type === 'tagged_template_literal'   |
+ * | ts.isTaggedTemplateExpression(p)   | p.type === 'call_expression'           |
  * | ts.isImportDeclaration(p)          | p.type === 'import_statement'          |
  * | ts.isImportSpecifier(p)            | p.type === 'import_specifier'          |
  * | ts.isImportClause(p)               | p.type === 'import_clause'             |
@@ -523,8 +559,9 @@ export function getReExports(root, sourceCode) {
 const TYPE_NODE_TYPES = new Set([
     'type_annotation',
     'type_identifier',
+    'nested_identifier',
+    'nested_type_identifier',
     'generic_type',
-    'qualified_name',
     'union_type',
     'intersection_type',
     'conditional_type',
@@ -532,15 +569,14 @@ const TYPE_NODE_TYPES = new Set([
     'index_signature',
     'type_predicate',
     'predefined_type',
-    'string_type',
-    'number_type',
-    'boolean_type',
     'object_type',
     'array_type',
     'tuple_type',
     'function_type',
     'constructor_type',
-    'typeof_expression',
+    'type_query',
+    'extends_type_clause',
+    'implements_clause',
     'template_type',
     'literal_type',
     'lookup_type',
@@ -561,7 +597,17 @@ const DECLARATION_TYPES = new Set([
     'type_alias_declaration',
 ]);
 /** Set of node types that represent spreads */
-const SPREAD_TYPES = new Set(['spread_element', 'rest_parameter']);
+const SPREAD_TYPES = new Set(['spread_element']);
+/** Node types whose direct `type_annotation` child holds an identifier's type
+ *  position — parameters, property signatures, index signatures, and type
+ *  assertions. Collapsed into one generic check in isTypeOnlyUsage. */
+const DIRECT_TYPE_ANNOTATION_PARENTS = new Set([
+    'required_parameter',
+    'optional_parameter',
+    'property_signature',
+    'index_signature',
+    'type_assertion',
+]);
 /**
  * Recursively check if the identifier node is contained within the given type node.
  */
@@ -581,6 +627,73 @@ function isNodeInTypePosition(identifier, typeNode) {
     checkNode(typeNode);
     return found;
 }
+/**
+ * Return true when `identifier` sits inside the `type_arguments` node of
+ * `container` (e.g. `Array<SomeType>`). Shared by the direct generic-type
+ * position and the call/new/tagged-template type-argument positions.
+ */
+function isInTypeArguments(identifier, container) {
+    const typeArgs = findChildOfType(container, 'type_arguments');
+    if (!typeArgs)
+        return false;
+    for (const arg of typeArgs.children ?? []) {
+        if (isNodeInTypePosition(identifier, arg))
+            return true;
+    }
+    return false;
+}
+/**
+ * `function test<T extends SomeType>()` — the identifier is a type-parameter
+ * constraint. When a direct `type_annotation` constraint exists it is decisive
+ * (return its result, do not fall through to the secondary child scan).
+ */
+function isTypeParameterConstraintUsage(identifier, parent) {
+    if (parent.type !== 'type_parameter')
+        return false;
+    const constraint = findChildOfType(parent, 'type_annotation');
+    if (constraint) {
+        return isNodeInTypePosition(identifier, constraint);
+    }
+    for (const child of parent.children ?? []) {
+        if (child.type !== 'identifier' && child.type !== 'type_parameter') {
+            if (isNodeInTypePosition(identifier, child))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Mapped type (`{ [K in T]: ... }`) — the identifier is a mapped-type constraint
+ * or value type.
+ */
+function isMappedTypeUsage(identifier, parent) {
+    if (parent.type !== 'mapped_type_clause')
+        return false;
+    const typeParam = findChildOfType(parent, 'type_parameter');
+    if (typeParam) {
+        const constraint = findChildOfType(typeParam, 'type_annotation');
+        if (constraint && isNodeInTypePosition(identifier, constraint))
+            return true;
+    }
+    const typeAnnot = findChildOfType(parent, 'type_annotation');
+    if (typeAnnot && isNodeInTypePosition(identifier, typeAnnot))
+        return true;
+    return false;
+}
+/**
+ * Type positions reachable through the parent's own parent — type arguments on
+ * call/new/tagged-template expressions (tagged templates parse as
+ * `call_expression`).
+ */
+function isAncestorTypeUsage(identifier, parent) {
+    if (!parent.parent)
+        return false;
+    const grand = parent.parent;
+    if (grand.type === 'call_expression' || grand.type === 'new_expression') {
+        return isInTypeArguments(identifier, grand);
+    }
+    return false;
+}
 /**
  * Check if an identifier node is used only as a type.
  * Uses tree-sitter node type checks instead of TS API's `isTypeNode` etc.
@@ -590,85 +703,19 @@ function isTypeOnlyUsage(identifier) {
     if (!parent)
         return false;
     // Direct type position — parent is a type_annotation, type_reference, etc.
-    if (TYPE_NODE_TYPES.has(parent.type)) {
+    if (TYPE_NODE_TYPES.has(parent.type))
         return true;
-    }
     // Type query: `typeof X`
-    if (parent.type === 'typeof_expression') {
+    if (parent.type === 'type_query')
         return true;
-    }
-    // Qualified name in type position
-    if (parent.type === 'qualified_name' && parent.children?.[0] === identifier) {
-        return isTypeOnlyUsage(parent);
-    }
-    // Generic type arguments: `SomeType<X>` where X is the identifier
-    if (parent.type === 'generic_type' && parent.children?.[0] === identifier) {
-        const heritageClause = parent.parent;
-        if (heritageClause?.type === 'heritage_clause') {
-            const isExtends = hasModifier(heritageClause, 'extends');
-            if (isExtends) {
-                const interfaceNode = heritageClause.parent;
-                if (interfaceNode?.type === 'interface_declaration') {
-                    return true;
-                }
-            }
-        }
-    }
-    // `namespace.Type` in type position — check if left side is identifier
-    if (parent.type === 'member_expression' && parent.children?.[0] === identifier) {
-        const grandParent = parent.parent;
-        if (grandParent?.type === 'generic_type') {
-            const heritageClause = grandParent.parent;
-            if (heritageClause?.type === 'heritage_clause') {
-                const isExtends = hasModifier(heritageClause, 'extends');
-                if (isExtends) {
-                    const interfaceNode = heritageClause.parent;
-                    if (interfaceNode?.type === 'interface_declaration') {
-                        return true;
-                    }
-                }
-            }
-        }
-    }
     // Type alias: `type X = SomeType`
     if (parent.type === 'type_alias_declaration') {
         const typeAnnotation = findChildOfType(parent, 'type_annotation');
-        if (typeAnnotation) {
+        if (typeAnnotation)
             return isNodeInTypePosition(identifier, typeAnnotation);
-        }
-    }
-    // Class implements: `class X implements SomeType`
-    if (parent.type === 'class_declaration') {
-        for (const child of parent.children ?? []) {
-            if (child.type !== 'heritage_clause')
-                continue;
-            const isImplements = hasModifier(child, 'implements');
-            if (!isImplements)
-                continue;
-            for (const typeNode of child.children ?? []) {
-                if (typeNode === identifier)
-                    return true;
-                if (typeNode.type === 'member_expression' && typeNode.children?.[0] === identifier)
-                    return true;
-                if (typeNode.type === 'generic_type' && typeNode.children?.[0] === identifier)
-                    return true;
-            }
-        }
-    }
-    // Generic constraints: `function test<T extends SomeType>()`
-    if (parent.type === 'type_parameter') {
-        const constraint = findChildOfType(parent, 'type_annotation'); // or constraint
-        if (constraint) {
-            return isNodeInTypePosition(identifier, constraint);
-        }
-        // Also check for generic_type in constraint position
-        for (const child of parent.children ?? []) {
-            if (child.type !== 'identifier' && child.type !== 'type_parameter') {
-                if (isNodeInTypePosition(identifier, child))
-                    return true;
-            }
-        }
     }
+    if (isTypeParameterConstraintUsage(identifier, parent))
+        return true;
     // Type annotations in variable declarations: `const x: SomeType = ...`
     if (parent.type === 'variable_declarator') {
         const typeAnnot = findChildOfType(parent, 'type_annotation');
@@ -681,20 +728,17 @@ function isTypeOnlyUsage(identifier) {
         if (typeNode && isNodeInTypePosition(identifier, typeNode))
             return true;
     }
-    if (parent.type === 'type_assertion') {
-        const typeNode = findChildOfType(parent, 'type_annotation');
-        if (typeNode && isNodeInTypePosition(identifier, typeNode))
+    // Parameter / property / index-signature / type-assertion parents: a direct
+    // `type_annotation` child holds the type position.
+    if (DIRECT_TYPE_ANNOTATION_PARENTS.has(parent.type)) {
+        const typeAnnot = findChildOfType(parent, 'type_annotation');
+        if (typeAnnot && isNodeInTypePosition(identifier, typeAnnot))
             return true;
     }
     // Type parameters/arguments: `Array<SomeType>`, `Promise<SomeType>`
     if (parent.type === 'type_identifier' || parent.type === 'generic_type') {
-        const typeArgs = findChildOfType(parent, 'type_arguments');
-        if (typeArgs) {
-            for (const arg of typeArgs.children ?? []) {
-                if (isNodeInTypePosition(identifier, arg))
-                    return true;
-            }
-        }
+        if (isInTypeArguments(identifier, parent))
+            return true;
     }
     // Return type annotations: `function test(): SomeType`
     if (DECLARATION_TYPES.has(parent.type)) {
@@ -702,36 +746,8 @@ function isTypeOnlyUsage(identifier) {
         if (typeAnnot && isNodeInTypePosition(identifier, typeAnnot))
             return true;
     }
-    // Parameter type annotations: `function test(x: SomeType)`
-    if (parent.type === 'required_parameter' || parent.type === 'optional_parameter') {
-        const typeAnnot = findChildOfType(parent, 'type_annotation');
-        if (typeAnnot && isNodeInTypePosition(identifier, typeAnnot))
-            return true;
-    }
-    // Property type annotations: `{ prop: SomeType }` or `class { prop: SomeType }`
-    if (parent.type === 'property_signature' || parent.type === 'class_property') {
-        const typeAnnot = findChildOfType(parent, 'type_annotation');
-        if (typeAnnot && isNodeInTypePosition(identifier, typeAnnot))
-            return true;
-    }
-    // Index signature: `{ [key: string]: SomeType }`
-    if (parent.type === 'index_signature') {
-        const typeAnnot = findChildOfType(parent, 'type_annotation');
-        if (typeAnnot && isNodeInTypePosition(identifier, typeAnnot))
-            return true;
-    }
-    // Mapped type constraint or type
-    if (parent.type === 'mapped_type_clause') {
-        const typeParam = findChildOfType(parent, 'type_parameter');
-        if (typeParam) {
-            const constraint = findChildOfType(typeParam, 'type_annotation');
-            if (constraint && isNodeInTypePosition(identifier, constraint))
-                return true;
-        }
-        const typeAnnot = findChildOfType(parent, 'type_annotation');
-        if (typeAnnot && isNodeInTypePosition(identifier, typeAnnot))
-            return true;
-    }
+    if (isMappedTypeUsage(identifier, parent))
+        return true;
     // Conditional types: `T extends SomeType ? X : Y`
     if (parent.type === 'conditional_type') {
         for (const child of parent.children ?? []) {
@@ -752,225 +768,184 @@ function isTypeOnlyUsage(identifier) {
         if (annot && isNodeInTypePosition(identifier, annot))
             return true;
     }
-    // Walk up: if parent is itself in a type position, check further up
-    if (parent.parent) {
-        // Heritage clauses
-        if (parent.type === 'generic_type' && parent.parent.type === 'heritage_clause') {
-            return true;
+    if (isAncestorTypeUsage(identifier, parent))
+        return true;
+    return false;
+}
+/**
+ * Extract identifier usage to track which imports are used.
+ * Uses tree-sitter AST traversal with walkAST.
+ *
+ * @param root - The root AST node to walk.
+/**
+ * Record a single usage of an imported name in the usage map: increments the
+ * count, appends the line, and returns the (possibly freshly-created) entry so
+ * callers that classify the usage (type / reexport) can mutate it in place.
+ */
+function recordUsage(usageMap, name, node) {
+    const { line } = bridgeGetLineAndColumn(node);
+    const existing = usageMap.get(name) || {
+        usageType: 'direct',
+        usageCount: 0,
+        lineNumbers: [],
+    };
+    existing.usageCount++;
+    existing.lineNumbers.push(line);
+    usageMap.set(name, existing);
+    return existing;
+}
+/**
+ * Plain identifier references. Skips identifiers inside import declarations,
+ * and for member/subscript access counts only the leftmost (object) identifier.
+ * Classifies the usage as type-only or re-export where applicable.
+ */
+function recordIdentifierUsage(node, sourceCode, importNames, usageMap) {
+    const name = getNodeText(node, sourceCode);
+    if (!importNames.has(name))
+        return;
+    let shouldCount = true;
+    let p = node.parent;
+    while (p) {
+        if (p.type === 'import_statement' || p.type === 'import_specifier' ||
+            p.type === 'import_clause' || p.type === 'named_imports') {
+            shouldCount = false;
+            break;
         }
-        // Type arguments in call expressions: `func<SomeType>()`
-        if (parent.parent.type === 'call_expression') {
-            const typeArgs = findChildOfType(parent.parent, 'type_arguments');
-            if (typeArgs) {
-                for (const arg of typeArgs.children ?? []) {
-                    if (isNodeInTypePosition(identifier, arg))
-                        return true;
-                }
-            }
+        p = p.parent;
+    }
+    // For member expressions, only count the leftmost (object) identifier
+    if (shouldCount && node.parent?.type === 'member_expression') {
+        shouldCount = node.parent.children?.[0] === node;
+    }
+    // For subscript expressions (element access), only count expression side
+    if (shouldCount && node.parent?.type === 'subscript_expression') {
+        shouldCount = node.parent.children?.[0] === node;
+    }
+    if (!shouldCount)
+        return;
+    const existing = recordUsage(usageMap, name, node);
+    if (isTypeOnlyUsage(node)) {
+        existing.usageType = 'type';
+    }
+    else if (node.parent?.type === 'export_specifier') {
+        existing.usageType = 'reexport';
+    }
+}
+/**
+ * Spread elements (`...Imported`, rest params) whose spread expression is an
+ * imported identifier.
+ */
+function recordSpreadUsage(node, sourceCode, importNames, usageMap) {
+    const expr = node.children?.find(c => c.type !== '...');
+    if (expr?.type === 'identifier' && importNames.has(getNodeText(expr, sourceCode))) {
+        recordUsage(usageMap, getNodeText(expr, sourceCode), expr);
+    }
+}
+/**
+ * JSX elements (`<Button />`, `<Button.Primary />`) whose tag (or the leftmost
+ * member of the tag) is an imported identifier.
+ */
+function recordJsxUsage(node, sourceCode, importNames, usageMap) {
+    let tagNameNode;
+    if (node.type === 'jsx_element') {
+        const openTag = findChildOfType(node, 'jsx_opening_element');
+        if (openTag) {
+            tagNameNode = openTag.children?.find(c => c.type === 'identifier' || c.type === 'member_expression');
         }
-        // Type arguments in new expressions: `new Class<SomeType>()`
-        if (parent.parent.type === 'new_expression') {
-            const typeArgs = findChildOfType(parent.parent, 'type_arguments');
-            if (typeArgs) {
-                for (const arg of typeArgs.children ?? []) {
-                    if (isNodeInTypePosition(identifier, arg))
-                        return true;
-                }
-            }
+    }
+    else {
+        tagNameNode = node.children?.find(c => c.type === 'identifier' || c.type === 'member_expression');
+    }
+    if (!tagNameNode)
+        return;
+    if (tagNameNode.type === 'identifier' && importNames.has(getNodeText(tagNameNode, sourceCode))) {
+        recordUsage(usageMap, getNodeText(tagNameNode, sourceCode), tagNameNode);
+    }
+    else if (tagNameNode.type === 'member_expression') {
+        const leftmost = tagNameNode.children?.[0];
+        if (leftmost?.type === 'identifier' && importNames.has(getNodeText(leftmost, sourceCode))) {
+            recordUsage(usageMap, getNodeText(leftmost, sourceCode), leftmost);
         }
-        // Type arguments in tagged template expressions
-        if (parent.parent.type === 'tagged_template_literal') {
-            const typeArgs = findChildOfType(parent.parent, 'type_arguments');
-            if (typeArgs) {
-                for (const arg of typeArgs.children ?? []) {
-                    if (isNodeInTypePosition(identifier, arg))
-                        return true;
-                }
-            }
+    }
+}
+/**
+ * Decorators (`@withAuth`, `@Component()`): the decorator identifier, or the
+ * callee identifier of a call-expression decorator.
+ */
+function recordDecoratorUsage(node, sourceCode, importNames, usageMap) {
+    const id = findChildOfType(node, 'identifier');
+    if (id && importNames.has(getNodeText(id, sourceCode))) {
+        recordUsage(usageMap, getNodeText(id, sourceCode), id);
+    }
+    const callExpr = findChildOfType(node, 'call_expression');
+    if (callExpr) {
+        const callee = callExpr.children?.[0];
+        if (callee?.type === 'identifier' && importNames.has(getNodeText(callee, sourceCode))) {
+            recordUsage(usageMap, getNodeText(callee, sourceCode), callee);
         }
     }
-    return false;
+}
+/**
+ * Object-literal property assignments (`{ key: ImportedValue }`): the value
+ * identifier when it is an imported name.
+ */
+function recordPairUsage(node, sourceCode, importNames, usageMap) {
+    const key = node.children?.find(c => c.type === 'property_identifier');
+    const value = node.children?.find(c => c.type === 'identifier' && c !== key);
+    if (value && importNames.has(getNodeText(value, sourceCode))) {
+        recordUsage(usageMap, getNodeText(value, sourceCode), value);
+    }
+}
+/**
+ * Shorthand property assignments (`{ ComponentA }`): the identifier child that
+ * references the imported name.
+ */
+function recordShorthandUsage(node, sourceCode, importNames, usageMap) {
+    const ref = node.children?.find(c => c.type === 'identifier');
+    if (ref && importNames.has(getNodeText(ref, sourceCode))) {
+        recordUsage(usageMap, getNodeText(ref, sourceCode), ref);
+    }
+    else if (ref && importNames.has(getNodeText(ref, sourceCode))) {
+        // shorthand_property_identifier might itself be just text
+        recordUsage(usageMap, getNodeText(node, sourceCode), node);
+    }
+}
+/**
+ * Dispatch a single walked node to its usage recorder based on node type.
+ */
+function recordNodeUsage(node, sourceCode, importNames, usageMap) {
+    if (node.type === 'identifier') {
+        recordIdentifierUsage(node, sourceCode, importNames, usageMap);
+    }
+    else if (SPREAD_TYPES.has(node.type)) {
+        recordSpreadUsage(node, sourceCode, importNames, usageMap);
+    }
+    else if (node.type === 'jsx_element' || node.type === 'jsx_self_closing_element') {
+        recordJsxUsage(node, sourceCode, importNames, usageMap);
+    }
+    else if (node.type === 'decorator') {
+        recordDecoratorUsage(node, sourceCode, importNames, usageMap);
+    }
+    else if (node.type === 'pair') {
+        recordPairUsage(node, sourceCode, importNames, usageMap);
+    }
+    else if (node.type === 'shorthand_property_identifier') {
+        recordShorthandUsage(node, sourceCode, importNames, usageMap);
+    }
 }
 /**
  * Extract identifier usage to track which imports are used.
  * Uses tree-sitter AST traversal with walkAST.
+ *
+ * @param root - The root AST node to walk.
+ * @param sourceCode - The original source text for name extraction.
+ * @param importNames - Set of imported names to track usage for.
+ * @returns Map of imported name to its usage information.
  */
 export function extractIdentifierUsage(root, sourceCode, importNames) {
     const usageMap = new Map();
     walkAST(root, (node) => {
-        // --- identifiers ---
-        if (node.type === 'identifier') {
-            const name = getNodeText(node, sourceCode);
-            if (importNames.has(name)) {
-                let shouldCount = true;
-                // Skip if part of an import declaration
-                let p = node.parent;
-                while (p) {
-                    if (p.type === 'import_statement' || p.type === 'import_specifier' ||
-                        p.type === 'import_clause' || p.type === 'named_imports') {
-                        shouldCount = false;
-                        break;
-                    }
-                    p = p.parent;
-                }
-                // For member expressions, only count the leftmost (object) identifier
-                if (shouldCount && node.parent?.type === 'member_expression') {
-                    shouldCount = node.parent.children?.[0] === node;
-                }
-                // For subscript expressions (element access), only count expression side
-                if (shouldCount && node.parent?.type === 'subscript_expression') {
-                    shouldCount = node.parent.children?.[0] === node;
-                }
-                if (shouldCount) {
-                    const { line } = bridgeGetLineAndColumn(node);
-                    const existing = usageMap.get(name) || {
-                        usageType: 'direct',
-                        usageCount: 0,
-                        lineNumbers: [],
-                    };
-                    existing.usageCount++;
-                    existing.lineNumbers.push(line);
-                    if (isTypeOnlyUsage(node)) {
-                        existing.usageType = 'type';
-                    }
-                    else if (node.parent?.type === 'export_specifier') {
-                        existing.usageType = 'reexport';
-                    }
-                    usageMap.set(name, existing);
-                }
-            }
-        }
-        // --- spread elements ---
-        else if (SPREAD_TYPES.has(node.type)) {
-            const expr = node.children?.find(c => c.type !== '...');
-            if (expr?.type === 'identifier' && importNames.has(getNodeText(expr, sourceCode))) {
-                const { line } = bridgeGetLineAndColumn(expr);
-                const existing = usageMap.get(getNodeText(expr, sourceCode)) || {
-                    usageType: 'direct',
-                    usageCount: 0,
-                    lineNumbers: [],
-                };
-                existing.usageCount++;
-                existing.lineNumbers.push(line);
-                usageMap.set(getNodeText(expr, sourceCode), existing);
-            }
-        }
-        // --- JSX elements: <Button /> or <Button.Primary /> ---
-        else if (node.type === 'jsx_element' || node.type === 'jsx_self_closing_element') {
-            let tagNameNode;
-            if (node.type === 'jsx_element') {
-                const openTag = findChildOfType(node, 'open_tag');
-                if (openTag) {
-                    tagNameNode = openTag.children?.find(c => c.type === 'identifier' || c.type === 'member_expression');
-                }
-            }
-            else {
-                tagNameNode = node.children?.find(c => c.type === 'identifier' || c.type === 'member_expression');
-            }
-            if (tagNameNode) {
-                if (tagNameNode.type === 'identifier' && importNames.has(getNodeText(tagNameNode, sourceCode))) {
-                    const { line } = bridgeGetLineAndColumn(tagNameNode);
-                    const existing = usageMap.get(getNodeText(tagNameNode, sourceCode)) || {
-                        usageType: 'direct',
-                        usageCount: 0,
-                        lineNumbers: [],
-                    };
-                    existing.usageCount++;
-                    existing.lineNumbers.push(line);
-                    usageMap.set(getNodeText(tagNameNode, sourceCode), existing);
-                }
-                else if (tagNameNode.type === 'member_expression') {
-                    const leftmost = tagNameNode.children?.[0];
-                    if (leftmost?.type === 'identifier' && importNames.has(getNodeText(leftmost, sourceCode))) {
-                        const { line } = bridgeGetLineAndColumn(leftmost);
-                        const existing = usageMap.get(getNodeText(leftmost, sourceCode)) || {
-                            usageType: 'direct',
-                            usageCount: 0,
-                            lineNumbers: [],
-                        };
-                        existing.usageCount++;
-                        existing.lineNumbers.push(line);
-                        usageMap.set(getNodeText(leftmost, sourceCode), existing);
-                    }
-                }
-            }
-        }
-        // --- decorators: @withAuth ---
-        else if (node.type === 'decorator') {
-            // decorator → identifier (e.g., @deprecated)
-            const id = findChildOfType(node, 'identifier');
-            if (id && importNames.has(getNodeText(id, sourceCode))) {
-                const { line } = bridgeGetLineAndColumn(id);
-                const existing = usageMap.get(getNodeText(id, sourceCode)) || {
-                    usageType: 'direct',
-                    usageCount: 0,
-                    lineNumbers: [],
-                };
-                existing.usageCount++;
-                existing.lineNumbers.push(line);
-                usageMap.set(getNodeText(id, sourceCode), existing);
-            }
-            // decorator → call_expression → identifier (e.g., @Component())
-            const callExpr = findChildOfType(node, 'call_expression');
-            if (callExpr) {
-                const callee = callExpr.children?.[0];
-                if (callee?.type === 'identifier' && importNames.has(getNodeText(callee, sourceCode))) {
-                    const { line } = bridgeGetLineAndColumn(callee);
-                    const existing = usageMap.get(getNodeText(callee, sourceCode)) || {
-                        usageType: 'direct',
-                        usageCount: 0,
-                        lineNumbers: [],
-                    };
-                    existing.usageCount++;
-                    existing.lineNumbers.push(line);
-                    usageMap.set(getNodeText(callee, sourceCode), existing);
-                }
-            }
-        }
-        // --- Object literal property assignments: { key: ImportedValue } ---
-        else if (node.type === 'pair') {
-            const key = node.children?.find(c => c.type === 'property_identifier');
-            const value = node.children?.find(c => c.type === 'identifier' && c !== key);
-            if (value && importNames.has(getNodeText(value, sourceCode))) {
-                const { line } = bridgeGetLineAndColumn(value);
-                const existing = usageMap.get(getNodeText(value, sourceCode)) || {
-                    usageType: 'direct',
-                    usageCount: 0,
-                    lineNumbers: [],
-                };
-                existing.usageCount++;
-                existing.lineNumbers.push(line);
-                usageMap.set(getNodeText(value, sourceCode), existing);
-            }
-        }
-        // --- Shorthand property assignments: { ComponentA, ComponentB } ---
-        else if (node.type === 'shorthand_property_identifier') {
-            // The value node is a reference to an imported name
-            const ref = node.children?.find(c => c.type === 'identifier');
-            if (ref && importNames.has(getNodeText(ref, sourceCode))) {
-                const { line } = bridgeGetLineAndColumn(ref);
-                const existing = usageMap.get(getNodeText(ref, sourceCode)) || {
-                    usageType: 'direct',
-                    usageCount: 0,
-                    lineNumbers: [],
-                };
-                existing.usageCount++;
-                existing.lineNumbers.push(line);
-                usageMap.set(getNodeText(ref, sourceCode), existing);
-            }
-            else if (ref && importNames.has(getNodeText(ref, sourceCode))) {
-                // shorthand_property_identifier might itself be just text
-                const { line } = bridgeGetLineAndColumn(node);
-                const existing = usageMap.get(getNodeText(node, sourceCode)) || {
-                    usageType: 'direct',
-                    usageCount: 0,
-                    lineNumbers: [],
-                };
-                existing.usageCount++;
-                existing.lineNumbers.push(line);
-                usageMap.set(getNodeText(node, sourceCode), existing);
-            }
-        }
+        recordNodeUsage(node, sourceCode, importNames, usageMap);
     });
     return usageMap;
 }
@@ -980,6 +955,11 @@ export function extractIdentifierUsage(root, sourceCode, importNames) {
 /**
  * Check if a function name is defined locally in the file.
  * Uses tree-sitter instead of TS API.
+ *
+ * @param name - The function name to look for.
+ * @param root - The root AST node to search.
+ * @param sourceCode - The original source text for name extraction.
+ * @returns True if the name is declared locally.
  */
 export function isLocalFunction(name, root, sourceCode) {
     let found = false;
@@ -1017,6 +997,10 @@ export function isLocalFunction(name, root, sourceCode) {
 /**
  * Normalize a function call target for consistent naming.
  * No TypeScript dependency — pure string manipulation.
+ *
+ * @param callee - The callee name as written at the call site.
+ * @param filePath - The file path the call occurs in.
+ * @returns The normalized call target.
  */
 export function normalizeCallTarget(callee, filePath) {
     if (callee.includes('#') || callee.includes('.')) {
@@ -1034,6 +1018,10 @@ export function normalizeCallTarget(callee, filePath) {
  *
  * Note: the type parameter is retained only for backward compatibility with
  * the generic-based call pattern; tree-sitter uses string types, not SyntaxKind enums.
+ *
+ * @param root - The root AST node to search within.
+ * @param nodeType - The tree-sitter node type to match.
+ * @returns All matching AST nodes cast to the requested type.
  */
 export function findNodesByKind(root, nodeType) {
     return findNodes(root, n => n.type === nodeType);