code-auditor-mcp 3.4.12 → 3.4.13

package/dist/languages/typescript/TreeSitterTypeScriptAdapter.js

@@ -3,8 +3,17 @@
  *
  * Uses web-tree-sitter WASM parsers behind the adapter seam — no TypeScript compiler API.
  * Supports .ts, .tsx, .js, and .jsx files.
+ *
+ * The adapter is split across a leaf-first inheritance chain (Spec-33
+ * interface-segregation): each link contributes a cohesive slice of the
+ * adapter so no single class exceeds the SOLID class-size threshold.
+ * Ancestors hold the tree-traversal, extraction, and scope-resolution
+ * primitives; descendants compose them into the public LanguageAdapter
+ * surface. The mutually-recursive cross-function safety cluster is
+ * co-located in TsSafetyAnalysis (TypeScript forbids a base class calling a
+ * subclass method, so those must live in one class).
  */
-import { getParser } from '../tree-sitter/parser.js';
+import { getParser, parseWithRecovery } from '../tree-sitter/parser.js';
 import { toASTNode, toSourceLocation } from '../tree-sitter/converter.js';
 // ---------------------------------------------------------------------------
 // Source code storage
@@ -14,316 +23,28 @@ import { toASTNode, toSourceLocation } from '../tree-sitter/converter.js';
  * can recover the original source text.
  */
 const sourceCodeMap = new WeakMap();
+/**
+ * A sentinel ASTNode standing in for a provably-constant string.  Used when
+ * binding `.map()` callback element parameters (which iterate a static array)
+ * during cross-function safety analysis: the element is unknown but its value
+ * is constrained to the array's compile-time elements, so it is safe to embed
+ * in a SQL fragment the same way a literal is.
+ */
+const SAFE_STRING_NODE = {
+    type: 'string',
+    range: [-1, -1],
+    location: { start: { line: 0, column: 0 }, end: { line: 0, column: 0 } },
+    raw: {
+        type: 'string',
+        text: "''",
+        startIndex: -1,
+        endIndex: -1,
+    },
+};
 // ---------------------------------------------------------------------------
-// Adapter implementation
+// Traversal + primitive helpers
 // ---------------------------------------------------------------------------
-export class TreeSitterTypeScriptAdapter {
-    name = 'typescript';
-    fileExtensions = ['.ts', '.tsx', '.js', '.jsx'];
-    // -- File detection -------------------------------------------------------
-    supportsFile(filePath) {
-        return this.fileExtensions.some((ext) => filePath.endsWith(ext));
-    }
-    // -- Parsing --------------------------------------------------------------
-    async parse(filePath, content) {
-        const isTsx = filePath.endsWith('.tsx') || filePath.endsWith('.jsx');
-        const lang = isTsx ? 'tsx' : filePath.endsWith('.go') ? 'go' : 'typescript';
-        const parser = getParser(lang, isTsx);
-        const tree = parser.parse(content);
-        if (!tree)
-            throw new Error(`Failed to parse file: ${filePath}`);
-        const errors = [];
-        // Collect ERROR nodes as parse errors
-        this.collectErrors(tree.rootNode, errors);
-        const root = toASTNode(tree.rootNode, undefined, lang);
-        const ast = {
-            root,
-            language: lang,
-            filePath,
-            errors,
-        };
-        sourceCodeMap.set(ast, content);
-        return ast;
-    }
-    // -- AST Navigation -------------------------------------------------------
-    findNodes(ast, pattern) {
-        const results = [];
-        this.walk(ast.root, (node) => {
-            if (this.matchesPattern(node, pattern)) {
-                results.push(node);
-            }
-        });
-        return results;
-    }
-    getParent(node) {
-        return node.parent ?? null;
-    }
-    getChildren(node) {
-        return node.children ?? [];
-    }
-    getSiblings(node) {
-        if (!node.parent?.children)
-            return [];
-        return node.parent.children.filter((c) => c !== node);
-    }
-    // -- Node Information -----------------------------------------------------
-    getNodeType(node) {
-        return node.type;
-    }
-    getNodeText(node, sourceCode) {
-        return sourceCode.slice(node.range[0], node.range[1]);
-    }
-    getNodeName(node) {
-        const syntaxNode = node.raw;
-        return this.extractName(syntaxNode);
-    }
-    getNodeLocation(node) {
-        return node.location;
-    }
-    // -- Language-Specific Extraction -----------------------------------------
-    extractFunctions(ast) {
-        const sourceCode = sourceCodeMap.get(ast) ?? '';
-        const functions = [];
-        this.walk(ast.root, (node) => {
-            const syntaxNode = node.raw;
-            const type = syntaxNode.type;
-            if (type === 'function_declaration' ||
-                type === 'generator_function_declaration' ||
-                type === 'function_expression' ||
-                type === 'arrow_function' ||
-                type === 'method_definition') {
-                const fn = this.buildFunctionInfo(syntaxNode, sourceCode);
-                if (fn)
-                    functions.push(fn);
-            }
-        });
-        return functions;
-    }
-    extractClasses(ast) {
-        const sourceCode = sourceCodeMap.get(ast) ?? '';
-        const classes = [];
-        this.walk(ast.root, (node) => {
-            const syntaxNode = node.raw;
-            if (syntaxNode.type === 'class_declaration') {
-                const cls = this.buildClassInfo(syntaxNode, sourceCode);
-                if (cls)
-                    classes.push(cls);
-            }
-        });
-        return classes;
-    }
-    extractImports(ast) {
-        const sourceCode = sourceCodeMap.get(ast) ?? '';
-        const imports = [];
-        this.walk(ast.root, (node) => {
-            const syntaxNode = node.raw;
-            if (syntaxNode.type === 'import_statement') {
-                const imp = this.buildImportInfo(syntaxNode, sourceCode);
-                if (imp)
-                    imports.push(imp);
-            }
-        });
-        return imports;
-    }
-    extractExports(ast) {
-        const sourceCode = sourceCodeMap.get(ast) ?? '';
-        const exports = [];
-        this.walk(ast.root, (node) => {
-            const syntaxNode = node.raw;
-            if (syntaxNode.type === 'export_statement') {
-                const ex = this.buildExportInfo(syntaxNode, sourceCode);
-                if (ex)
-                    exports.push(ex);
-            }
-        });
-        return exports;
-    }
-    // -- Pattern Matching Helpers ---------------------------------------------
-    isClass(node) {
-        const type = node.raw.type;
-        return type === 'class_declaration' || type === 'class_expression';
-    }
-    isFunction(node) {
-        const type = node.raw.type;
-        return (type === 'function_declaration' ||
-            type === 'function_expression' ||
-            type === 'arrow_function' ||
-            type === 'generator_function_declaration' ||
-            type === 'generator_function_expression');
-    }
-    isMethod(node) {
-        return node.raw.type === 'method_definition';
-    }
-    isInterface(node) {
-        return node.raw.type === 'interface_declaration';
-    }
-    isImport(node) {
-        return node.raw.type === 'import_statement';
-    }
-    isExport(node) {
-        return node.raw.type === 'export_statement';
-    }
-    isLoop(node) {
-        const type = node.raw.type;
-        return (type === 'for_statement' ||
-            type === 'for_in_statement' ||
-            type === 'while_statement' ||
-            type === 'do_statement');
-    }
-    isConditional(node) {
-        const type = node.raw.type;
-        return (type === 'if_statement' ||
-            type === 'switch_statement' ||
-            type === 'ternary_expression' ||
-            type === 'switch_case');
-    }
-    isVariableDeclaration(node) {
-        const type = node.raw.type;
-        return (type === 'variable_declaration' ||
-            type === 'lexical_declaration' ||
-            type === 'variable_declarator');
-    }
-    // -- Advanced Features ----------------------------------------------------
-    getTypeInfo(node) {
-        const syntaxNode = node.raw;
-        return this.extractTypeAnnotation(syntaxNode);
-    }
-    getDocumentation(node) {
-        const syntaxNode = node.raw;
-        return this.extractDocumentation(syntaxNode);
-    }
-    getComplexity(node) {
-        const syntaxNode = node.raw;
-        return this.calculateCyclomaticComplexity(syntaxNode);
-    }
-    // -- Optional: Interfaces -------------------------------------------------
-    extractInterfaces(ast) {
-        const sourceCode = sourceCodeMap.get(ast) ?? '';
-        const interfaces = [];
-        this.walk(ast.root, (node) => {
-            const syntaxNode = node.raw;
-            if (syntaxNode.type === 'interface_declaration') {
-                const iface = this.buildInterfaceInfo(syntaxNode, sourceCode);
-                if (iface)
-                    interfaces.push(iface);
-            }
-        });
-        return interfaces;
-    }
-    // -- Optional: Raw imports (static, dynamic, require) ----------------------
-    extractRawImports(_filePath, content) {
-        const results = [];
-        const parser = getParser('typescript');
-        const tree = parser.parse(content);
-        if (!tree)
-            return results;
-        // Static imports
-        this.walkRaw(tree.rootNode, (node) => {
-            if (node.type === 'import_statement') {
-                const source = this.getChildByType(node, 'string');
-                if (source) {
-                    const specifier = source.text.slice(1, -1); // strip quotes
-                    results.push({
-                        moduleSpecifier: specifier,
-                        isStatic: true,
-                        isDynamic: false,
-                        isRequire: false,
-                        line: source.startPosition.row,
-                    });
-                }
-            }
-            // Dynamic import(): import('...')
-            if (node.type === 'call_expression') {
-                const fn = node.firstChild;
-                if (fn?.type === 'import') {
-                    const args = this.getChildByType(node, 'arguments');
-                    if (args) {
-                        const strNode = this.findFirstNamedChild(args, 'string');
-                        if (strNode) {
-                            const specifier = strNode.text.slice(1, -1);
-                            results.push({
-                                moduleSpecifier: specifier,
-                                isStatic: false,
-                                isDynamic: true,
-                                isRequire: false,
-                                line: strNode.startPosition.row,
-                            });
-                        }
-                    }
-                }
-                // require('...')
-                if (fn?.type === 'identifier' && fn.text === 'require') {
-                    const args = this.getChildByType(node, 'arguments');
-                    if (args) {
-                        const strNode = this.findFirstNamedChild(args, 'string');
-                        if (strNode) {
-                            const specifier = strNode.text.slice(1, -1);
-                            results.push({
-                                moduleSpecifier: specifier,
-                                isStatic: false,
-                                isDynamic: false,
-                                isRequire: true,
-                                line: strNode.startPosition.row,
-                            });
-                        }
-                    }
-                }
-            }
-        });
-        return results;
-    }
-    // -- Optional: Exported symbol names --------------------------------------
-    extractExportedSymbols(ast) {
-        const symbols = [];
-        this.walk(ast.root, (astNode) => {
-            const node = astNode.raw;
-            if (node.type === 'export_statement') {
-                // export function foo / export class Foo / export const x
-                const declaration = this.findFirstNamedChild(node, [
-                    'function_declaration',
-                    'class_declaration',
-                    'lexical_declaration',
-                    'variable_declaration',
-                    'interface_declaration',
-                    'type_alias_declaration',
-                    'enum_declaration',
-                ]);
-                if (declaration) {
-                    const name = this.extractName(declaration);
-                    if (name) {
-                        symbols.push({ name, line: declaration.startPosition.row });
-                        return;
-                    }
-                }
-                // export { foo, bar } or export { default }
-                const clause = this.getChildByType(node, 'export_clause');
-                if (clause) {
-                    for (const child of clause.namedChildren) {
-                        if (child.type === 'export_specifier') {
-                            const nameNode = this.getChildByType(child, 'identifier');
-                            if (nameNode) {
-                                symbols.push({
-                                    name: nameNode.text,
-                                    line: nameNode.startPosition.row,
-                                });
-                            }
-                        }
-                    }
-                }
-                // export default <expression>
-                if (node.childForFieldName?.('value')) {
-                    symbols.push({
-                        name: 'default',
-                        line: node.startPosition.row,
-                    });
-                }
-            }
-        });
-        return symbols;
-    }
-    // ---------------------------------------------------------------------------
-    // Internal helpers
-    // ---------------------------------------------------------------------------
+class TsTraversalHelpers {
     /** Walk all ASTNodes in a tree (depth-first). */
     walk(node, visitor) {
         visitor(node);
@@ -353,93 +74,164 @@ export class TreeSitterTypeScriptAdapter {
             this.collectErrors(child, errors);
         }
     }
-    /** Match an ASTNode against a NodePattern. */
-    matchesPattern(node, pattern) {
-        const syntaxNode = node.raw;
-        // type matching
-        if (pattern.type !== undefined) {
-            const types = Array.isArray(pattern.type) ? pattern.type : [pattern.type];
-            if (!types.includes(syntaxNode.type))
-                return false;
+    /** Find first child of node matching one of the given types. */
+    getChildByType(node, type) {
+        for (const child of node.children) {
+            if (child.type === type)
+                return child;
         }
-        // name matching
-        if (pattern.name !== undefined) {
-            const nodeName = this.extractName(syntaxNode);
-            if (nodeName === null)
-                return false;
-            if (typeof pattern.name === 'string') {
-                if (nodeName !== pattern.name)
-                    return false;
-            }
-            else if (pattern.name instanceof RegExp) {
-                if (!pattern.name.test(nodeName))
-                    return false;
-            }
+        return null;
+    }
+    /** Find the first named child matching one of the given types. */
+    findFirstNamedChild(node, types) {
+        const typeSet = Array.isArray(types) ? new Set(types) : new Set([types]);
+        for (const child of node.namedChildren) {
+            if (typeSet.has(child.type))
+                return child;
         }
-        // hasChild matching
-        if (pattern.hasChild !== undefined) {
-            const childNodes = node.children ?? [];
-            const hasMatch = childNodes.some((c) => this.matchesPattern(c, pattern.hasChild));
-            if (!hasMatch)
-                return false;
+        return null;
+    }
+    /** Check if node has a direct child (named or anonymous) with the given text. */
+    hasChild(node, text) {
+        for (const child of node.children) {
+            if (child.text === text || child.type === text)
+                return true;
         }
-        // hasParent matching
-        if (pattern.hasParent !== undefined) {
-            if (!node.parent)
-                return false;
-            if (!this.matchesPattern(node.parent, pattern.hasParent))
-                return false;
+        return false;
+    }
+    /** Get the operator text from a binary expression node. */
+    getOperator(node) {
+        for (const child of node.children) {
+            if (!child.isNamed &&
+                ['&&', '||', '+', '-', '*', '/', '%', '===', '!==', '==', '!='].includes(child.type)) {
+                return child.type;
+            }
         }
-        // custom predicate
-        if (pattern.custom !== undefined) {
-            if (!pattern.custom(node))
-                return false;
+        return null;
+    }
+    /** Check if a node has an `async` modifier keyword. */
+    hasModifier(node, modifier) {
+        for (const child of node.children) {
+            if (!child.isNamed && child.type === modifier)
+                return true;
+            // tree-sitter may represent modifiers as named decorator/modifier nodes
+            if (child.isNamed &&
+                (child.type === modifier ||
+                    child.type === 'accessibility_modifier' ||
+                    child.type === 'override_modifier' ||
+                    child.type === 'readonly' ||
+                    child.type === 'static' ||
+                    child.type === 'abstract')) {
+                if (child.text === modifier)
+                    return true;
+            }
         }
-        return true;
+        return false;
+    }
+    /** Check if a node is under an export_statement. */
+    isNodeExported(node) {
+        const parent = node.parent;
+        if (parent?.type === 'export_statement')
+            return true;
+        // Also check for `export` keyword on the node itself (TS module syntax)
+        for (const child of node.children) {
+            if (!child.isNamed && child.type === 'export')
+                return true;
+        }
+        return false;
+    }
+    extractParameters(node, sourceCode) {
+        const params = [];
+        const formalParams = node.childForFieldName?.('parameters');
+        if (!formalParams)
+            return params;
+        for (const child of formalParams.namedChildren) {
+            if (child.type === 'required_parameter' || child.type === 'optional_parameter') {
+                const paramNode = child.childForFieldName?.('pattern');
+                const name = paramNode?.text ?? child.firstNamedChild?.text;
+                const isOptional = child.type === 'optional_parameter';
+                const typeNode = child.childForFieldName?.('type');
+                let defaultValue;
+                // Check for a default value
+                const valueNode = child.childForFieldName?.('value');
+                if (valueNode) {
+                    defaultValue = valueNode.text;
+                }
+                if (name) {
+                    params.push({
+                        name,
+                        type: typeNode?.text.replace(/^:\s*/, ''),
+                        optional: isOptional,
+                        defaultValue,
+                    });
+                }
+            }
+        }
+        return params;
+    }
+    /** Extract ordered parameter names from a function node. */
+    getParamNames(fnNode) {
+        const raw = fnNode.raw;
+        const paramsNode = raw.childForFieldName?.('parameters');
+        if (!paramsNode)
+            return [];
+        const names = [];
+        for (const child of paramsNode.namedChildren) {
+            if (child.type === 'identifier') {
+                names.push(child.text);
+                continue;
+            }
+            const pattern = child.childForFieldName?.('pattern');
+            if (pattern && pattern.type === 'identifier') {
+                names.push(pattern.text);
+                continue;
+            }
+            for (const c of child.namedChildren) {
+                if (c.type === 'identifier') {
+                    names.push(c.text);
+                    break;
+                }
+            }
+        }
+        return names;
+    }
+    /** Wrap a raw tree-sitter node into a detached ASTNode for local analysis. */
+    wrapRaw(raw) {
+        if (!raw)
+            return null;
+        return toASTNode(raw, undefined, 'typescript');
     }
+    /** Return the ASTNodes for a call expression's arguments. */
+    getCallArgASTNodes(callNode) {
+        const raw = callNode.raw;
+        const argsNode = raw.childForFieldName?.('arguments');
+        if (!argsNode)
+            return [];
+        return argsNode.namedChildren.map((c) => this.wrapRaw(c));
+    }
+}
+// ---------------------------------------------------------------------------
+// Name / type / documentation extraction
+// ---------------------------------------------------------------------------
+class TsNameDocumentation extends TsTraversalHelpers {
     /** Extract the name/identifier from a tree-sitter TreeSitterNode. */
     extractName(node) {
         switch (node.type) {
             case 'function_declaration':
             case 'generator_function_declaration':
             case 'class_declaration':
+            case 'abstract_class_declaration':
             case 'interface_declaration':
             case 'enum_declaration':
-            case 'type_alias_declaration': {
-                const nameNode = node.childForFieldName?.('name');
-                if (nameNode)
-                    return nameNode.text;
-                // Fallback: find first identifier child
-                for (const child of node.namedChildren) {
-                    if (child.type === 'identifier' || child.type === 'type_identifier') {
-                        return child.text;
-                    }
-                }
-                return null;
-            }
+            case 'type_alias_declaration':
+                return this.resolveNameField(node, ['identifier', 'type_identifier']);
             case 'method_definition':
-            case 'public_field_definition': {
-                const nameNode = node.childForFieldName?.('name');
-                if (nameNode)
-                    return nameNode.text;
-                // property_identifier or string
-                for (const child of node.namedChildren) {
-                    if (child.type === 'property_identifier' ||
-                        child.type === 'string') {
-                        return child.text.replace(/^["']|["']$/g, '');
-                    }
-                }
-                return null;
-            }
-            case 'variable_declarator': {
-                const nameNode = node.childForFieldName?.('name');
-                if (nameNode)
-                    return nameNode.text;
-                return null;
-            }
+            case 'public_field_definition':
+                return this.resolveNameField(node, ['property_identifier', 'string']);
+            case 'variable_declarator':
+                return this.resolveNameField(node, []);
             case 'lexical_declaration':
             case 'variable_declaration': {
-                // Find the declarator child and extract its name
                 for (const child of node.namedChildren) {
                     if (child.type === 'variable_declarator') {
                         return this.extractName(child);
@@ -448,24 +240,15 @@ export class TreeSitterTypeScriptAdapter {
                 return null;
             }
             case 'arrow_function': {
-                // Check if assigned to a variable: const foo = () => {}
                 const parent = node.parent;
-                if (parent?.type === 'variable_declarator') {
-                    return this.extractName(parent);
-                }
-                return null;
+                return parent?.type === 'variable_declarator' ? this.extractName(parent) : null;
             }
             case 'function_expression': {
-                // Might have a name: const foo = function bar() {}
                 const nameNode = node.childForFieldName?.('name');
                 if (nameNode)
                     return nameNode.text;
-                // Check if assigned to a variable
                 const parent = node.parent;
-                if (parent?.type === 'variable_declarator') {
-                    return this.extractName(parent);
-                }
-                return null;
+                return parent?.type === 'variable_declarator' ? this.extractName(parent) : null;
             }
             case 'property_identifier':
                 return node.text;
@@ -475,6 +258,21 @@ export class TreeSitterTypeScriptAdapter {
                 return null;
         }
     }
+    /** Return `node`'s `name` field text, else the first named child whose type
+     *  is in `fallbackTypes` (stripping quotes from `string` children). */
+    resolveNameField(node, fallbackTypes) {
+        const nameNode = node.childForFieldName?.('name');
+        if (nameNode)
+            return nameNode.text;
+        for (const child of node.namedChildren) {
+            if (fallbackTypes.includes(child.type)) {
+                return child.type === 'string'
+                    ? child.text.replace(/^["']|["']$/g, '')
+                    : child.text;
+            }
+        }
+        return null;
+    }
     /** Extract a type annotation string from a node. */
     extractTypeAnnotation(node) {
         // Function return type
@@ -538,37 +336,36 @@ export class TreeSitterTypeScriptAdapter {
             const text = comments.join('\n').trim();
             return this.cleanCommentText(text);
         }
-        // When the immediate parent is a wrapper like `export_statement`, it won't
-        // contain comment nodes — the JSDoc lives at the grandparent (program) level
-        // as a sibling of the wrapper. Ascend and check for an adjacent comment.
-        // Adjacency guard prevents misattributing file-level comments: only a
-        // comment whose end row is immediately before the wrapper's start row
-        // (no blank line gap) is treated as JSDoc for the function inside.
-        if (parent.type === 'export_statement' && parent.parent) {
-            const gpSiblings = parent.parent.children;
-            let parentIndex = -1;
-            for (let i = 0; i < gpSiblings.length; i++) {
-                if (gpSiblings[i].equals(parent)) {
-                    parentIndex = i;
-                    break;
-                }
+        // When the parent is `export_statement`, the JSDoc lives at the grandparent
+        // (program) level as a sibling of the wrapper — ascend and look for it.
+        return this.findExportStatementDoc(parent);
+    }
+    /** When `parent` is an `export_statement`, find an adjacent /** JSDoc comment
+     *  at the grandparent level. Adjacency guard (comment ends on line L, wrapper
+     *  starts on L+1) prevents misattributing file-level comments. */
+    findExportStatementDoc(parent) {
+        if (parent.type !== 'export_statement' || !parent.parent)
+            return null;
+        const gpSiblings = parent.parent.children;
+        let parentIndex = -1;
+        for (let i = 0; i < gpSiblings.length; i++) {
+            if (gpSiblings[i].equals(parent)) {
+                parentIndex = i;
+                break;
             }
-            if (parentIndex > 0) {
-                // Look backwards from the export_statement in the grandparent's children
-                for (let i = parentIndex - 1; i >= 0; i--) {
-                    const sibling = gpSiblings[i];
-                    if (sibling.type === 'comment' && sibling.text.trimStart().startsWith('/**')) {
-                        // Only attribute if comment is adjacent — no blank line gap.
-                        // Adjacent: comment ends on line L, export_statement starts on L+1.
-                        if (sibling.endPosition.row + 1 === parent.startPosition.row) {
-                            return this.cleanCommentText(sibling.text);
-                        }
-                        break; // Found a comment but not adjacent — stop looking
-                    }
-                    else if (sibling.isNamed) {
-                        break; // Stop at named siblings
-                    }
+        }
+        if (parentIndex <= 0)
+            return null;
+        for (let i = parentIndex - 1; i >= 0; i--) {
+            const sibling = gpSiblings[i];
+            if (sibling.type === 'comment' && sibling.text.trimStart().startsWith('/**')) {
+                if (sibling.endPosition.row + 1 === parent.startPosition.row) {
+                    return this.cleanCommentText(sibling.text);
                 }
+                break; // Found a comment but not adjacent — stop looking
+            }
+            else if (sibling.isNamed) {
+                break; // Stop at named siblings
             }
         }
         return null;
@@ -623,17 +420,55 @@ export class TreeSitterTypeScriptAdapter {
         });
         return complexity;
     }
-    /** Get the operator text from a binary expression node. */
-    getOperator(node) {
-        for (const child of node.children) {
-            if (!child.isNamed &&
-                ['&&', '||', '+', '-', '*', '/', '%', '===', '!==', '==', '!='].includes(child.type)) {
-                return child.type;
+    /** Match an ASTNode against a NodePattern. */
+    matchesPattern(node, pattern) {
+        const syntaxNode = node.raw;
+        // type matching
+        if (pattern.type !== undefined) {
+            const types = Array.isArray(pattern.type) ? pattern.type : [pattern.type];
+            if (!types.includes(syntaxNode.type))
+                return false;
+        }
+        // name matching
+        if (pattern.name !== undefined) {
+            const nodeName = this.extractName(syntaxNode);
+            if (nodeName === null)
+                return false;
+            if (typeof pattern.name === 'string') {
+                if (nodeName !== pattern.name)
+                    return false;
+            }
+            else if (pattern.name instanceof RegExp) {
+                if (!pattern.name.test(nodeName))
+                    return false;
             }
         }
-        return null;
+        // hasChild matching
+        if (pattern.hasChild !== undefined) {
+            const childNodes = node.children ?? [];
+            const hasMatch = childNodes.some((c) => this.matchesPattern(c, pattern.hasChild));
+            if (!hasMatch)
+                return false;
+        }
+        // hasParent matching
+        if (pattern.hasParent !== undefined) {
+            if (!node.parent)
+                return false;
+            if (!this.matchesPattern(node.parent, pattern.hasParent))
+                return false;
+        }
+        // custom predicate
+        if (pattern.custom !== undefined) {
+            if (!pattern.custom(node))
+                return false;
+        }
+        return true;
     }
-    // -- Extraction helpers ----------------------------------------------------
+}
+// ---------------------------------------------------------------------------
+// Extraction builders (functions, classes, imports, exports, interfaces)
+// ---------------------------------------------------------------------------
+class TsExtraction extends TsNameDocumentation {
     buildFunctionInfo(node, sourceCode) {
         const name = this.extractName(node);
         if (name === null && node.type !== 'arrow_function')
@@ -679,28 +514,10 @@ export class TreeSitterTypeScriptAdapter {
         if (implementsClause) {
             implementsList = implementsClause.namedChildren.map((c) => c.text);
         }
-        // Extract methods
         const classBody = node.childForFieldName?.('body');
-        const methods = [];
-        const properties = [];
-        if (classBody) {
-            for (const member of classBody.namedChildren) {
-                if (member.type === 'method_definition') {
-                    const fnInfo = this.buildFunctionInfo(member, sourceCode);
-                    if (fnInfo) {
-                        fnInfo.className = name;
-                        fnInfo.isMethod = true;
-                        methods.push(fnInfo);
-                    }
-                }
-                else if (member.type === 'public_field_definition' ||
-                    member.type === 'field_definition') {
-                    const propInfo = this.buildPropertyInfo(member);
-                    if (propInfo)
-                        properties.push(propInfo);
-                }
-            }
-        }
+        const { methods, properties } = classBody
+            ? this.buildClassMembers(classBody, sourceCode, name)
+            : { methods: [], properties: [] };
         return {
             name,
             location: toSourceLocation(node),
@@ -713,6 +530,28 @@ export class TreeSitterTypeScriptAdapter {
             jsDoc: jsDoc ?? undefined,
         };
     }
+    /** Build method/property lists from a class body's members. */
+    buildClassMembers(classBody, sourceCode, className) {
+        const methods = [];
+        const properties = [];
+        for (const member of classBody.namedChildren) {
+            if (member.type === 'method_definition') {
+                const fnInfo = this.buildFunctionInfo(member, sourceCode);
+                if (fnInfo) {
+                    fnInfo.className = className;
+                    fnInfo.isMethod = true;
+                    methods.push(fnInfo);
+                }
+            }
+            else if (member.type === 'public_field_definition' ||
+                member.type === 'field_definition') {
+                const propInfo = this.buildPropertyInfo(member);
+                if (propInfo)
+                    properties.push(propInfo);
+            }
+        }
+        return { methods, properties };
+    }
     buildPropertyInfo(node) {
         const name = this.extractName(node);
         if (!name)
@@ -742,90 +581,77 @@ export class TreeSitterTypeScriptAdapter {
             return null;
         const source = sourceNode.text.slice(1, -1); // strip quotes
         const specifiers = [];
-        // import defaultExport from 'module'
-        // import * as namespace from 'module'
-        // import { named } from 'module'
-        //
-        // Tree-sitter nests named imports inside import_clause -> named_imports,
-        // so we walk into import_clause children recursively.
-        const collectSpecifiers = (child) => {
-            if (child.type === 'import_specifier') {
-                const nameNode = child.childForFieldName?.('name');
-                const aliasNode = child.childForFieldName?.('alias');
-                if (nameNode) {
-                    specifiers.push({
-                        name: nameNode.text,
-                        alias: aliasNode?.text,
-                        isDefault: false,
-                        isNamespace: false,
-                    });
-                }
+        for (const child of node.namedChildren) {
+            this.collectImportSpecifiers(child, specifiers);
+        }
+        return {
+            source,
+            specifiers,
+            location: toSourceLocation(node),
+        };
+    }
+    /** Recursively collect import specifiers (default / named / namespace).
+     *  Tree-sitter nests named imports inside import_clause -> named_imports. */
+    collectImportSpecifiers(child, specifiers) {
+        if (child.type === 'import_specifier') {
+            const nameNode = child.childForFieldName?.('name');
+            const aliasNode = child.childForFieldName?.('alias');
+            if (nameNode) {
+                specifiers.push({
+                    name: nameNode.text,
+                    alias: aliasNode?.text,
+                    isDefault: false,
+                    isNamespace: false,
+                });
             }
-            else if (child.type === 'namespace_import') {
-                const nameNode = child.childForFieldName?.('name');
-                if (nameNode) {
-                    specifiers.push({
-                        name: nameNode.text,
-                        isDefault: false,
-                        isNamespace: true,
-                    });
-                }
+        }
+        else if (child.type === 'namespace_import') {
+            const nameNode = child.childForFieldName?.('name');
+            if (nameNode) {
+                specifiers.push({
+                    name: nameNode.text,
+                    isDefault: false,
+                    isNamespace: true,
+                });
             }
-            else if (child.type === 'import') {
-                // default import: `import foo from '...'`
-                const nameNode = node.childForFieldName?.('name');
-                if (nameNode) {
+        }
+        else if (child.type === 'import_clause') {
+            // Default import: `import foo from '...'` — import_clause children include
+            // an identifier for the default binding and optionally named_imports for
+            // mixed imports (`import foo, { bar }`).
+            for (const grandchild of child.namedChildren) {
+                if (grandchild.type === 'identifier') {
                     specifiers.push({
-                        name: nameNode.text,
+                        name: grandchild.text,
                         isDefault: true,
                         isNamespace: false,
                     });
                 }
-            }
-            else {
-                // Recurse into containers: import_clause, named_imports
-                for (const grandchild of child.namedChildren) {
-                    collectSpecifiers(grandchild);
+                else {
+                    this.collectImportSpecifiers(grandchild, specifiers);
                 }
             }
-        };
-        for (const child of node.namedChildren) {
-            collectSpecifiers(child);
         }
-        return {
-            source,
-            specifiers,
-            location: toSourceLocation(node),
-        };
+        else {
+            // Recurse into containers: import_clause, named_imports
+            for (const grandchild of child.namedChildren) {
+                this.collectImportSpecifiers(grandchild, specifiers);
+            }
+        }
     }
     buildExportInfo(node, _sourceCode) {
         // export default <expression>
         const isDefault = this.hasChild(node, 'default');
-        // export { foo, bar } [from '...']
-        const clause = node.childForFieldName?.('clause');
-        if (clause?.type === 'export_clause') {
-            const sourceNode = node.childForFieldName?.('source');
-            const exports = [];
-            for (const spec of clause.namedChildren) {
-                if (spec.type === 'export_specifier') {
-                    const nameNode = spec.childForFieldName?.('name');
-                    if (nameNode) {
-                        exports.push({
-                            name: nameNode.text,
-                            location: toSourceLocation(nameNode),
-                            isDefault: false,
-                            source: sourceNode?.text.slice(1, -1),
-                        });
-                    }
-                }
-            }
-            // Return first (handled by caller iterating export_statement nodes)
-            return exports[0] ?? null;
-        }
+        // export { foo, bar } [from '...'] — return the first named export
+        // (caller iterates export_statement nodes).
+        const named = this.buildNamedExport(node);
+        if (named)
+            return named;
         // export function/class/const/let/var name
         const declaration = this.findFirstNamedChild(node, [
             'function_declaration',
             'class_declaration',
+            'abstract_class_declaration',
             'lexical_declaration',
             'variable_declaration',
         ]);
@@ -853,6 +679,27 @@ export class TreeSitterTypeScriptAdapter {
         }
         return null;
     }
+    /** Build the ExportInfo for an `export { a, b } [from '...']` statement. */
+    buildNamedExport(node) {
+        const clause = node.childForFieldName?.('clause');
+        if (clause?.type !== 'export_clause')
+            return null;
+        const sourceNode = node.childForFieldName?.('source');
+        for (const spec of clause.namedChildren) {
+            if (spec.type === 'export_specifier') {
+                const nameNode = spec.childForFieldName?.('name');
+                if (nameNode) {
+                    return {
+                        name: nameNode.text,
+                        location: toSourceLocation(nameNode),
+                        isDefault: false,
+                        source: sourceNode?.text.slice(1, -1),
+                    };
+                }
+            }
+        }
+        return null;
+    }
     buildInterfaceInfo(node, _sourceCode) {
         const name = this.extractName(node);
         if (!name)
@@ -866,31 +713,9 @@ export class TreeSitterTypeScriptAdapter {
         }
         // Members
         const body = node.childForFieldName?.('body');
-        const members = [];
-        if (body) {
-            for (const member of body.namedChildren) {
-                if (member.type === 'method_signature') {
-                    const memberName = member.childForFieldName?.('name')?.text;
-                    if (memberName) {
-                        members.push({
-                            name: memberName,
-                            type: 'method',
-                            location: toSourceLocation(member),
-                        });
-                    }
-                }
-                else if (member.type === 'property_signature') {
-                    const memberName = member.childForFieldName?.('name')?.text;
-                    if (memberName) {
-                        members.push({
-                            name: memberName,
-                            type: 'property',
-                            location: toSourceLocation(member),
-                        });
-                    }
-                }
-            }
-        }
+        const members = body
+            ? this.buildInterfaceMembers(body)
+            : [];
         return {
             name,
             location: toSourceLocation(node),
@@ -899,414 +724,350 @@ export class TreeSitterTypeScriptAdapter {
             isExported,
         };
     }
-    // -- Parameter extraction --------------------------------------------------
-    extractParameters(node, sourceCode) {
-        const params = [];
-        const formalParams = node.childForFieldName?.('parameters');
-        if (!formalParams)
-            return params;
-        for (const child of formalParams.namedChildren) {
-            if (child.type === 'required_parameter' || child.type === 'optional_parameter') {
-                const paramNode = child.childForFieldName?.('pattern');
-                const name = paramNode?.text ?? child.firstNamedChild?.text;
-                const isOptional = child.type === 'optional_parameter';
-                const typeNode = child.childForFieldName?.('type');
-                let defaultValue;
-                // Check for a default value
-                const valueNode = child.childForFieldName?.('value');
-                if (valueNode) {
-                    defaultValue = valueNode.text;
-                }
-                if (name) {
-                    params.push({
-                        name,
-                        type: typeNode?.text.replace(/^:\s*/, ''),
-                        optional: isOptional,
-                        defaultValue,
+    /** Build method/property member descriptors from an interface body. */
+    buildInterfaceMembers(body) {
+        const members = [];
+        for (const member of body.namedChildren) {
+            if (member.type === 'method_signature' || member.type === 'property_signature') {
+                const memberName = member.childForFieldName?.('name')?.text;
+                if (memberName) {
+                    members.push({
+                        name: memberName,
+                        type: member.type === 'method_signature' ? 'method' : 'property',
+                        location: toSourceLocation(member),
                     });
                 }
             }
         }
-        return params;
-    }
-    // -- Context helpers -------------------------------------------------------
-    /** Check if a node has an `async` modifier keyword. */
-    hasModifier(node, modifier) {
-        for (const child of node.children) {
-            if (!child.isNamed && child.type === modifier)
-                return true;
-            // tree-sitter may represent modifiers as named decorator/modifier nodes
-            if (child.isNamed &&
-                (child.type === modifier ||
-                    child.type === 'accessibility_modifier' ||
-                    child.type === 'override_modifier' ||
-                    child.type === 'readonly' ||
-                    child.type === 'static' ||
-                    child.type === 'abstract')) {
-                if (child.text === modifier)
-                    return true;
-            }
-        }
-        return false;
-    }
-    /** Check if a node is under an export_statement. */
-    isNodeExported(node) {
-        const parent = node.parent;
-        if (parent?.type === 'export_statement')
-            return true;
-        // Also check for `export` keyword on the node itself (TS module syntax)
-        for (const child of node.children) {
-            if (!child.isNamed && child.type === 'export')
-                return true;
-        }
-        return false;
+        return members;
     }
     /** Get the enclosing class name for a method. */
     getEnclosingClassName(node) {
         let current = node.parent;
         while (current) {
-            if (current.type === 'class_declaration') {
+            if (current.type === 'class_declaration' || current.type === 'abstract_class_declaration') {
                 return this.extractName(current) ?? undefined;
             }
             current = current.parent ?? null;
         }
         return undefined;
     }
-    // -- Tree traversal helpers ------------------------------------------------
-    /** Find first child of node matching one of the given types. */
-    getChildByType(node, type) {
-        for (const child of node.children) {
-            if (child.type === type)
-                return child;
-        }
-        return null;
-    }
-    /** Find the first named child matching one of the given types. */
-    findFirstNamedChild(node, types) {
-        const typeSet = Array.isArray(types) ? new Set(types) : new Set([types]);
-        for (const child of node.namedChildren) {
-            if (typeSet.has(child.type))
-                return child;
-        }
-        return null;
-    }
-    /** Check if node has a direct child (named or anonymous) with the given text. */
-    hasChild(node, text) {
-        for (const child of node.children) {
-            if (child.text === text || child.type === text)
-                return true;
-        }
-        return false;
-    }
-    // -- String Construction Capabilities (v3.4.7) ----------------------------
-    /**
-     * Returns true when the node is a dynamically-constructed string in TS/JS:
-     * - template_string with template_substitution children
-     * - binary_expression with + operator (string concatenation)
-     * - call_expression with .concat() method
-     *   String-like identifiers and plain string literals are never dynamic.
-     */
-    isDynamicStringConstruction(node) {
-        const type = node.raw.type;
-        if (type === 'template_string') {
-            // template_string is dynamic only if it has template_substitution children
-            for (const child of node.children ?? []) {
-                if (child.raw.type === 'template_substitution') {
-                    return true;
-                }
-            }
-            return false;
-        }
-        if (type === 'binary_expression') {
-            // Check for string concatenation: operands include a string literal
-            const children = node.children ?? [];
-            const hasStringLiteral = children.some(c => c.raw.type === 'string');
-            return hasStringLiteral;
-        }
-        if (type === 'call_expression') {
-            // Check for .concat() calls
-            const text = node.raw.text;
-            if (text.includes('.concat(') || text.includes('?.concat('))
-                return true;
-            // Recurse into arguments: query(binaryExpression) where the argument
-            // itself is a dynamic string construction.
-            for (const child of node.children ?? []) {
-                if (child.raw.type === 'arguments') {
-                    for (const arg of child.children ?? []) {
-                        const argType = arg.raw.type;
-                        if (argType === '(' || argType === ')' || argType === ',')
-                            continue;
-                        if (this.isDynamicStringConstruction(arg))
-                            return true;
-                    }
-                }
-            }
-            return false;
-        }
-        return false;
-    }
-    /**
-     * Extracts dynamic sub-parts from a string construction node.
-     * Returns template_substitution text for template literals,
-     * non-string-literal operands for binary expressions,
-     * and non-literal arguments for concat calls.
-     */
-    getDynamicParts(node, sourceCode) {
-        const type = node.raw.type;
-        const parts = [];
-        // For call_expressions (other than .concat), walk into the first
-        // argument that is itself a dynamic string construction.
-        if (type === 'call_expression') {
-            const text = node.raw.text;
-            // .concat() handled below
-            if (!text.includes('.concat(') && !text.includes('?.concat(')) {
-                for (const child of node.children ?? []) {
-                    if (child.raw.type === 'arguments') {
-                        for (const arg of child.children ?? []) {
-                            const argType = arg.raw.type;
-                            if (argType === '(' || argType === ')' || argType === ',')
-                                continue;
-                            if (this.isDynamicStringConstruction(arg)) {
-                                return this.getDynamicParts(arg, sourceCode);
-                            }
-                        }
-                    }
-                }
+    /** Collect static imports, dynamic `import()`, and `require()` calls. */
+    collectRawImport(node, results) {
+        if (node.type === 'import_statement') {
+            const source = this.getChildByType(node, 'string');
+            if (source) {
+                results.push({
+                    moduleSpecifier: source.text.slice(1, -1), // strip quotes
+                    isStatic: true,
+                    isDynamic: false,
+                    isRequire: false,
+                    line: source.startPosition.row,
+                });
             }
         }
-        if (type === 'template_string') {
-            for (const child of node.children ?? []) {
-                if (child.raw.type === 'template_substitution') {
-                    const text = sourceCode.slice(child.range[0], child.range[1]);
-                    // Strip the ${ } wrapper to get the inner identifier/expression
-                    // tree-sitter: template_substitution text includes ${ and }
-                    const inner = text.startsWith('${') ? text.slice(2, -1).trim() : text;
-                    const isId = /^[$\p{L}_][\p{L}\p{N}_$]*$/u.test(inner);
-                    // Extract the actual identifier node from inside the template_substitution
-                    // (tree-sitter nests it as: ${ <identifier> }), so resolveLocalConstant
-                    // can use its range to extract the raw name.
-                    let idNode;
-                    if (isId) {
-                        for (const subChild of child.children ?? []) {
-                            const subType = subChild.raw.type;
-                            if (subType === 'identifier') {
-                                idNode = subChild;
-                                break;
-                            }
-                        }
-                    }
-                    parts.push({ text: inner, isIdentifier: isId, node: idNode ?? (isId ? child : undefined) });
-                }
-            }
-            return parts;
-        }
-        if (type === 'binary_expression') {
-            for (const child of node.children ?? []) {
-                const childType = child.raw.type;
-                if (childType !== 'string' && childType !== '+' && childType !== 'template_string') {
-                    const text = sourceCode.slice(child.range[0], child.range[1]);
-                    const isId = /^[$\p{L}_][\p{L}\p{N}_$]*$/u.test(text.trim());
-                    parts.push({ text: text.trim(), isIdentifier: isId, node: isId ? child : undefined });
-                }
+        if (node.type === 'call_expression') {
+            const fn = node.firstChild;
+            if (fn?.type === 'import') {
+                this.pushCallImport(node, results, /* isRequire */ false);
             }
-            return parts;
-        }
-        if (type === 'call_expression') {
-            // .concat() — arguments after the first are dynamic
-            for (const child of node.children ?? []) {
-                if (child.raw.type === 'arguments') {
-                    for (const arg of child.children ?? []) {
-                        const argType = arg.raw.type;
-                        if (argType !== '(' && argType !== ')' && argType !== ',') {
-                            const text = arg.raw.text.trim();
-                            const isId = /^[$\p{L}_][\p{L}\p{N}_$]*$/u.test(text);
-                            parts.push({ text, isIdentifier: isId, node: isId ? arg : undefined });
-                        }
-                    }
-                }
+            else if (fn?.type === 'identifier' && fn.text === 'require') {
+                this.pushCallImport(node, results, /* isRequire */ true);
             }
-            return parts;
         }
-        return parts;
     }
-    /**
-     * Resolves a local const/let/var declaration for an identifier node.
-     * Searches within the enclosing function scope for the declaration site.
-     * Returns null when the identifier is a parameter, complex expression,
-     * or cannot be statically resolved.
-     */
-    resolveLocalConstant(identifierNode, ast, sourceCode) {
-        const idName = sourceCode.slice(identifierNode.range[0], identifierNode.range[1]).trim();
-        if (!idName)
-            return null;
-        // Find the enclosing function or file scope.  First search within
-        // the enclosing function; if not found, fall back to the program-level
-        // (module) scope — constants declared at module level are accessible
-        // inside any function in that module.
-        const enclosing = this.findEnclosingScope(identifierNode, ast);
-        const scopeRoot = enclosing ?? ast.root;
-        let declNode = this.findDeclarationInScope(scopeRoot, idName);
-        // If the enclosing scope is a function (not the program) and we didn't
-        // find the declaration there, also search the program-level scope.
-        if (!declNode && enclosing && enclosing !== ast.root) {
-            declNode = this.findDeclarationInScope(ast.root, idName);
-        }
-        // If still not found in local declarations, check if the identifier
-        // is imported (import { X } from … or import X from …).  Imported
-        // symbols are compile-time constants — they're resolved at link time,
-        // not at runtime, so user input cannot reach them via import bindings.
-        if (!declNode) {
-            const importResult = this.resolveImportConstant(idName, ast);
-            if (importResult)
-                return importResult;
-            // tree-sitter-typescript (v0.x) parses both "for…in" and "for…of"
-            // as `for_in_statement`.  The loop variable is a bare `identifier`
-            // child — NOT wrapped in `variable_declarator` / `lexical_declaration`.
-            // Walk up from the identifier to a `for_in_statement` and trace
-            // through the iterable to determine static-ness.
-            //   const TABLES = ["a", "b"];
-            //   for (const table of TABLES) { … `${table}` … }
-            const idRaw = identifierNode.raw;
-            let tsCurrent = idRaw.parent;
-            while (tsCurrent) {
-                if (tsCurrent.type === 'for_in_statement') {
-                    const left = tsCurrent.childForFieldName?.('left');
-                    if (left && left.text === idName) {
-                        const right = tsCurrent.childForFieldName?.('right');
-                        if (right && right.type === 'identifier') {
-                            const iterName = right.text;
-                            let iterDecl = this.findDeclarationInScope(scopeRoot, iterName);
-                            if (!iterDecl && enclosing && enclosing !== ast.root) {
-                                iterDecl = this.findDeclarationInScope(ast.root, iterName);
-                            }
-                            if (iterDecl) {
-                                const iterRaw = iterDecl.raw;
-                                const iterValue = iterRaw.childForFieldName?.('value');
-                                const iterLine = iterDecl.location.start.line;
-                                const iterReassigned = this.hasReassignment(scopeRoot, iterName, iterLine)
-                                    || (enclosing && enclosing !== ast.root ? this.hasReassignment(ast.root, iterName, iterLine) : false);
-                                if (!iterReassigned && this.isStaticValueNode(iterValue)) {
-                                    const initText = iterValue ? sourceCode.slice(iterValue.startIndex, iterValue.endIndex).trim() : '';
-                                    return { initText, isStatic: true, declLine: iterDecl.location.start.line };
-                                }
-                            }
-                        }
-                    }
-                    break;
-                }
-                tsCurrent = tsCurrent.parent;
-            }
-            return null;
-        }
-        // Extract value from AST (handles multiline declarations that the old
-        // regex missed — `.` doesn't match `\n` so `.+?` truncated at newlines).
-        const raw = declNode.raw;
-        const valueNode = raw.childForFieldName?.('value');
-        const declLine = declNode.location.start.line;
-        // Check for reassignment after declaration
-        const reassigned = this.hasReassignment(scopeRoot, idName, declLine);
-        // Determine if static by inspecting the value node's AST type.  String
-        // literals and substitution-free template strings are compile-time constants
-        // regardless of whether they contain `?` placeholders — SQL fragment
-        // constants (WHERE clauses, column lists) are just as static as
-        // parameterised query strings.
-        let isStatic = !reassigned && this.isStaticValueNode(valueNode);
-        // For-of / for-in loop variables: the declarator has no `value` field
-        // (the iterable is on the for-statement's `right` child).  Trace the
-        // iterable to see if all possible loop values are known constants.
-        //   const TABLES = ["a", "b"];
-        //   for (const table of TABLES) { … `${table}` … }
-        if (!isStatic && !valueNode) {
-            const forParent = this.findEnclosingForStatement(declNode);
-            if (forParent) {
-                const forRaw = forParent.raw;
-                const iterable = forRaw.childForFieldName?.('right');
-                if (iterable && iterable.type === 'identifier') {
-                    const iterName = iterable.text;
-                    let iterDecl = this.findDeclarationInScope(scopeRoot, iterName);
-                    if (!iterDecl && enclosing && enclosing !== ast.root) {
-                        iterDecl = this.findDeclarationInScope(ast.root, iterName);
-                    }
-                    if (iterDecl) {
-                        const iterRaw = iterDecl.raw;
-                        const iterValue = iterRaw.childForFieldName?.('value');
-                        const iterLine = iterDecl.location.start.line;
-                        const iterReassigned = this.hasReassignment(scopeRoot, iterName, iterLine)
-                            || (enclosing && enclosing !== ast.root ? this.hasReassignment(ast.root, iterName, iterLine) : false);
-                        if (!iterReassigned && this.isStaticValueNode(iterValue)) {
-                            isStatic = true;
-                        }
-                    }
-                }
+    /** Push a `import('...')` or `require('...')` record for a call expression. */
+    pushCallImport(node, results, isRequire) {
+        const args = this.getChildByType(node, 'arguments');
+        const strNode = args ? this.findFirstNamedChild(args, 'string') : null;
+        if (!strNode)
+            return;
+        results.push({
+            moduleSpecifier: strNode.text.slice(1, -1),
+            isStatic: false,
+            isDynamic: !isRequire,
+            isRequire,
+            line: strNode.startPosition.row,
+        });
+    }
+    /** Collect the exported symbol(s) declared by a single `export_statement`. */
+    collectExportedSymbol(node, symbols) {
+        // export function foo / export class Foo / export const x
+        const declaration = this.findFirstNamedChild(node, [
+            'function_declaration',
+            'class_declaration',
+            'abstract_class_declaration',
+            'lexical_declaration',
+            'variable_declaration',
+            'interface_declaration',
+            'type_alias_declaration',
+            'enum_declaration',
+        ]);
+        if (declaration) {
+            const name = this.extractName(declaration);
+            if (name) {
+                symbols.push({ name, line: declaration.startPosition.row });
+                return;
             }
         }
-        // When the value is a simple identifier (e.g. `table` ← `tables`),
-        // trace through to the linked declaration.  This handles patterns like:
-        //   const TABLES = ["a", "b"];
-        //   for (const table of TABLES) { … `${table}` … }
-        // where the variable's value is known at compile time because the
-        // iterable is a constant array.
-        if (!isStatic && valueNode && valueNode.type === 'identifier') {
-            const linkedName = valueNode.text;
-            if (linkedName && linkedName !== idName) {
-                let linkedDecl = this.findDeclarationInScope(scopeRoot, linkedName);
-                if (!linkedDecl && enclosing && enclosing !== ast.root) {
-                    linkedDecl = this.findDeclarationInScope(ast.root, linkedName);
-                }
-                if (linkedDecl) {
-                    const linkedRaw = linkedDecl.raw;
-                    const linkedValue = linkedRaw.childForFieldName?.('value');
-                    const linkedLine = linkedDecl.location.start.line;
-                    const linkedReassigned = this.hasReassignment(scopeRoot, linkedName, linkedLine)
-                        || (enclosing && enclosing !== ast.root ? this.hasReassignment(ast.root, linkedName, linkedLine) : false);
-                    if (!linkedReassigned && this.isStaticValueNode(linkedValue)) {
-                        isStatic = true;
+        // export { foo, bar } or export { default }
+        const clause = this.getChildByType(node, 'export_clause');
+        if (clause) {
+            for (const child of clause.namedChildren) {
+                if (child.type === 'export_specifier') {
+                    const nameNode = this.getChildByType(child, 'identifier');
+                    if (nameNode) {
+                        symbols.push({ name: nameNode.text, line: nameNode.startPosition.row });
                     }
                 }
             }
         }
-        // Extract init text from the value node; fall back to the full declaration.
-        let initText;
-        if (valueNode) {
-            initText = sourceCode.slice(valueNode.startIndex, valueNode.endIndex).trim();
-        }
-        else {
-            // No initializer node — try regex as a last resort.
-            const declText = sourceCode.slice(declNode.range[0], declNode.range[1]);
-            const declMatch = declText.match(/^(?:const|let|var)\s+(\w+)\s*=\s*(.+?);?\s*$|^(\w+)\s*=\s*(.+?);?\s*$/s);
-            initText = declMatch
-                ? (declMatch[2] ?? declMatch[4]).replace(/;\s*$/, '').trim()
-                : '';
+        // export default <expression>
+        if (node.childForFieldName?.('value')) {
+            symbols.push({ name: 'default', line: node.startPosition.row });
         }
-        return { initText, isStatic, declLine };
     }
-    /** Determine whether a tree-sitter value node represents a static (compile-time
-     *  constant) expression — no variables, function calls, or runtime evaluation. */
-    isStaticValueNode(node) {
-        if (!node)
-            return false;
-        const type = node.type;
-        // Literals that are trivially compile-time constants.
-        if (type === 'string')
-            return true;
-        if (type === 'number')
-            return true;
-        if (type === 'true' || type === 'false' || type === 'null' || type === 'undefined')
-            return true;
-        // Template strings: static only when they contain no ${…} substitutions.
-        if (type === 'template_string') {
-            for (let i = 0; i < node.childCount; i++) {
+}
+// ---------------------------------------------------------------------------
+// Public LanguageAdapter surface: parsing, navigation, extraction
+// ---------------------------------------------------------------------------
+class TsPublicApi extends TsExtraction {
+    name = 'typescript';
+    fileExtensions = ['.ts', '.tsx', '.js', '.jsx'];
+    supportsFile(filePath) {
+        return this.fileExtensions.some((ext) => filePath.endsWith(ext));
+    }
+    async parse(filePath, content) {
+        const isTsx = filePath.endsWith('.tsx') || filePath.endsWith('.jsx');
+        const lang = isTsx ? 'tsx' : filePath.endsWith('.go') ? 'go' : 'typescript';
+        const tree = await parseWithRecovery(lang, isTsx, content);
+        if (!tree)
+            throw new Error(`Failed to parse file: ${filePath}`);
+        const errors = [];
+        // Collect ERROR nodes as parse errors
+        this.collectErrors(tree.rootNode, errors);
+        const root = toASTNode(tree.rootNode, undefined, lang);
+        const ast = {
+            root,
+            language: lang,
+            filePath,
+            errors,
+            dispose: () => tree.delete(),
+        };
+        sourceCodeMap.set(ast, content);
+        return ast;
+    }
+    findNodes(ast, pattern) {
+        const results = [];
+        this.walk(ast.root, (node) => {
+            if (this.matchesPattern(node, pattern)) {
+                results.push(node);
+            }
+        });
+        return results;
+    }
+    getParent(node) {
+        return node.parent ?? null;
+    }
+    getChildren(node) {
+        return node.children ?? [];
+    }
+    getSiblings(node) {
+        if (!node.parent?.children)
+            return [];
+        return node.parent.children.filter((c) => c !== node);
+    }
+    getNodeType(node) {
+        return node.type;
+    }
+    getNodeText(node, sourceCode) {
+        return sourceCode.slice(node.range[0], node.range[1]);
+    }
+    getNodeName(node) {
+        const syntaxNode = node.raw;
+        return this.extractName(syntaxNode);
+    }
+    getNodeLocation(node) {
+        return node.location;
+    }
+    extractFunctions(ast) {
+        const sourceCode = sourceCodeMap.get(ast) ?? '';
+        const functions = [];
+        this.walk(ast.root, (node) => {
+            const syntaxNode = node.raw;
+            const type = syntaxNode.type;
+            if (type === 'function_declaration' ||
+                type === 'generator_function_declaration' ||
+                type === 'function_expression' ||
+                type === 'arrow_function' ||
+                type === 'method_definition') {
+                const fn = this.buildFunctionInfo(syntaxNode, sourceCode);
+                if (fn)
+                    functions.push(fn);
+            }
+        });
+        return functions;
+    }
+    extractClasses(ast) {
+        const sourceCode = sourceCodeMap.get(ast) ?? '';
+        const classes = [];
+        this.walk(ast.root, (node) => {
+            const syntaxNode = node.raw;
+            if (syntaxNode.type === 'class_declaration' || syntaxNode.type === 'abstract_class_declaration') {
+                const cls = this.buildClassInfo(syntaxNode, sourceCode);
+                if (cls)
+                    classes.push(cls);
+            }
+        });
+        return classes;
+    }
+    extractImports(ast) {
+        const sourceCode = sourceCodeMap.get(ast) ?? '';
+        const imports = [];
+        this.walk(ast.root, (node) => {
+            const syntaxNode = node.raw;
+            if (syntaxNode.type === 'import_statement') {
+                const imp = this.buildImportInfo(syntaxNode, sourceCode);
+                if (imp)
+                    imports.push(imp);
+            }
+        });
+        return imports;
+    }
+    extractExports(ast) {
+        const sourceCode = sourceCodeMap.get(ast) ?? '';
+        const exports = [];
+        this.walk(ast.root, (node) => {
+            const syntaxNode = node.raw;
+            if (syntaxNode.type === 'export_statement') {
+                const ex = this.buildExportInfo(syntaxNode, sourceCode);
+                if (ex)
+                    exports.push(ex);
+            }
+        });
+        return exports;
+    }
+}
+// ---------------------------------------------------------------------------
+// Node predicates + advanced + optional capabilities
+// ---------------------------------------------------------------------------
+class TsPredicatesOptional extends TsPublicApi {
+    isClass(node) {
+        const type = node.raw.type;
+        return type === 'class_declaration' || type === 'abstract_class_declaration' || type === 'class_expression';
+    }
+    isFunction(node) {
+        const type = node.raw.type;
+        return (type === 'function_declaration' ||
+            type === 'function_expression' ||
+            type === 'arrow_function' ||
+            type === 'generator_function_declaration' ||
+            type === 'generator_function_expression');
+    }
+    isMethod(node) {
+        return node.raw.type === 'method_definition';
+    }
+    isInterface(node) {
+        return node.raw.type === 'interface_declaration';
+    }
+    isImport(node) {
+        return node.raw.type === 'import_statement';
+    }
+    isExport(node) {
+        return node.raw.type === 'export_statement';
+    }
+    isLoop(node) {
+        const type = node.raw.type;
+        return (type === 'for_statement' ||
+            type === 'for_in_statement' ||
+            type === 'while_statement' ||
+            type === 'do_statement');
+    }
+    isConditional(node) {
+        const type = node.raw.type;
+        return (type === 'if_statement' ||
+            type === 'switch_statement' ||
+            type === 'ternary_expression' ||
+            type === 'switch_case');
+    }
+    isVariableDeclaration(node) {
+        const type = node.raw.type;
+        return (type === 'variable_declaration' ||
+            type === 'lexical_declaration' ||
+            type === 'variable_declarator');
+    }
+    getTypeInfo(node) {
+        const syntaxNode = node.raw;
+        return this.extractTypeAnnotation(syntaxNode);
+    }
+    getDocumentation(node) {
+        const syntaxNode = node.raw;
+        return this.extractDocumentation(syntaxNode);
+    }
+    getComplexity(node) {
+        const syntaxNode = node.raw;
+        return this.calculateCyclomaticComplexity(syntaxNode);
+    }
+    extractInterfaces(ast) {
+        const sourceCode = sourceCodeMap.get(ast) ?? '';
+        const interfaces = [];
+        this.walk(ast.root, (node) => {
+            const syntaxNode = node.raw;
+            if (syntaxNode.type === 'interface_declaration') {
+                const iface = this.buildInterfaceInfo(syntaxNode, sourceCode);
+                if (iface)
+                    interfaces.push(iface);
+            }
+        });
+        return interfaces;
+    }
+    extractRawImports(_filePath, content) {
+        const results = [];
+        const parser = getParser('typescript');
+        const tree = parser.parse(content);
+        if (!tree)
+            return results;
+        this.walkRaw(tree.rootNode, (node) => this.collectRawImport(node, results));
+        return results;
+    }
+    extractExportedSymbols(ast) {
+        const symbols = [];
+        this.walk(ast.root, (astNode) => {
+            const node = astNode.raw;
+            if (node.type === 'export_statement')
+                this.collectExportedSymbol(node, symbols);
+        });
+        return symbols;
+    }
+}
+// ---------------------------------------------------------------------------
+// Scope + static-value resolution
+// ---------------------------------------------------------------------------
+class TsScopeStatic extends TsPredicatesOptional {
+    /** Determine whether a tree-sitter value node represents a static (compile-time
+     *  constant) expression — no variables, function calls, or runtime evaluation. */
+    isStaticValueNode(node) {
+        if (!node)
+            return false;
+        const type = node.type;
+        // Literals that are trivially compile-time constants.
+        if (type === 'string')
+            return true;
+        if (type === 'number')
+            return true;
+        if (type === 'true' || type === 'false' || type === 'null' || type === 'undefined')
+            return true;
+        // Template strings: static only when they contain no ${…} substitutions.
+        if (type === 'template_string') {
+            for (let i = 0; i < node.childCount; i++) {
                 const child = node.child(i);
                 if (child && child.type === 'template_substitution')
                     return false;
             }
             return true;
         }
-        // Array literals: static when all elements are compile-time constants.
-        // This enables tracing through patterns like:
-        //   const TABLES = ["a", "b"];
-        //   for (const t of TABLES) { … `${t}` … }
-        // where every possible value of `t` is known at compile time.
+        // Array literals are static when every element is a compile-time constant
+        // (enables tracing `for (const t of TABLES)` over a static column list).
         if (type === 'array') {
             for (let i = 0; i < node.childCount; i++) {
                 const child = node.child(i);
@@ -1318,6 +1079,14 @@ export class TreeSitterTypeScriptAdapter {
             }
             return true;
         }
+        // Type assertions (`[...] as const`, `x as T`, `x satisfies T`) wrap an inner
+        // expression without changing its runtime value — unwrap and judge that.
+        if (type === 'as_expression' ||
+            type === 'type_assertion' ||
+            type === 'satisfies_expression' ||
+            type === 'non_null_expression') {
+            return this.isStaticValueNode(node.namedChild(0));
+        }
         // Everything else (identifiers, call expressions, binary expressions,
         // object literals, regexes, etc.) is conservatively treated as non-static.
         return false;
@@ -1421,14 +1190,18 @@ export class TreeSitterTypeScriptAdapter {
             declLine: r.declLine,
         };
     }
-    /** Check if identifier targetName is reassigned in scope after declLine. */
+    /** Check if identifier targetName is reassigned in scope after declLine.
+     *  Handles both plain assignment (`x = …`) and augmented assignment
+     *  (`x += …`, `x -= …`, etc.) — the latter accumulates into a string the
+     *  same way `x = x + …` does, so a variable built up with `+=` is just as
+     *  runtime-dependent as one reassigned with `=`. */
     hasReassignment(scopeRoot, targetName, declLine) {
         let found = false;
         this.walk(scopeRoot, (astNode) => {
             if (found)
                 return;
             const t = astNode.raw.type;
-            if (t === 'assignment_expression') {
+            if (t === 'assignment_expression' || t === 'augmented_assignment_expression') {
                 if (astNode.location.start.line < declLine)
                     return;
                 const raw = astNode.raw;
@@ -1440,20 +1213,743 @@ export class TreeSitterTypeScriptAdapter {
         });
         return found;
     }
-    /** Helper: extract text of arguments from a call_expression node. */
-    getCallArguments(node) {
-        const args = [];
+    /** Find a function declaration (named or arrow-assigned) by name in the file. */
+    findFunctionDeclaration(name, ast) {
+        let result = null;
+        this.walk(ast.root, (node) => {
+            if (result)
+                return;
+            const raw = node.raw;
+            const t = raw.type;
+            if (t === 'function_declaration' || t === 'generator_function_declaration') {
+                const nameNode = raw.childForFieldName?.('name');
+                if (nameNode && nameNode.text === name)
+                    result = node;
+            }
+            else if (t === 'variable_declarator') {
+                const nameNode = raw.childForFieldName?.('name');
+                const valueNode = raw.childForFieldName?.('value');
+                if (nameNode && nameNode.type === 'identifier' && nameNode.text === name
+                    && valueNode && ['arrow_function', 'function_expression', 'function'].includes(valueNode.type)) {
+                    result = this.wrapRaw(valueNode);
+                }
+            }
+        });
+        return result;
+    }
+    /** Extract a function's name (named functions and arrow-function assignments). */
+    getFunctionName(node) {
+        const raw = node.raw;
+        const t = raw.type;
+        if (t === 'function_declaration' || t === 'generator_function_declaration'
+            || t === 'function_expression' || t === 'method_definition') {
+            const nameNode = raw.childForFieldName?.('name');
+            if (nameNode && nameNode.text)
+                return nameNode.text;
+        }
+        if (t === 'arrow_function') {
+            const parent = node.parent;
+            if (parent) {
+                const pRaw = parent.raw;
+                if (pRaw.type === 'variable_declarator') {
+                    const nameNode = pRaw.childForFieldName?.('name');
+                    if (nameNode && nameNode.type === 'identifier')
+                        return nameNode.text;
+                }
+            }
+        }
+        return null;
+    }
+    /** Find all call sites of a named function in the file. */
+    findCallSites(fnName, ast) {
+        const sites = [];
+        this.walk(ast.root, (node) => {
+            const raw = node.raw;
+            if (raw.type !== 'call_expression')
+                return;
+            const fn = raw.childForFieldName?.('function');
+            if (fn && fn.type === 'identifier' && fn.text === fnName)
+                sites.push(node);
+        });
+        return sites;
+    }
+}
+// ---------------------------------------------------------------------------
+// Dynamic string construction + local-constant resolution
+// ---------------------------------------------------------------------------
+class TsDynamicStringConstruction extends TsScopeStatic {
+    /**
+     * Returns true when the node is a dynamically-constructed string in TS/JS:
+     * - template_string with template_substitution children
+     * - binary_expression with + operator (string concatenation)
+     * - call_expression with .concat() method
+     *   String-like identifiers and plain string literals are never dynamic.
+     */
+    isDynamicStringConstruction(node) {
+        const type = node.raw.type;
+        if (type === 'template_string') {
+            // template_string is dynamic only if it has template_substitution children
+            for (const child of node.children ?? []) {
+                if (child.raw.type === 'template_substitution') {
+                    return true;
+                }
+            }
+            return false;
+        }
+        if (type === 'binary_expression') {
+            // Check for string concatenation: operands include a string literal
+            const children = node.children ?? [];
+            const hasStringLiteral = children.some(c => c.raw.type === 'string');
+            return hasStringLiteral;
+        }
+        if (type === 'call_expression') {
+            // Check for .concat() calls
+            const text = node.raw.text;
+            if (text.includes('.concat(') || text.includes('?.concat('))
+                return true;
+            // Recurse into arguments: query(binaryExpression) where the argument
+            // itself is a dynamic string construction.
+            for (const child of node.children ?? []) {
+                if (child.raw.type === 'arguments') {
+                    for (const arg of child.children ?? []) {
+                        const argType = arg.raw.type;
+                        if (argType === '(' || argType === ')' || argType === ',')
+                            continue;
+                        if (this.isDynamicStringConstruction(arg))
+                            return true;
+                    }
+                }
+            }
+            return false;
+        }
+        return false;
+    }
+    /**
+     * Extracts dynamic sub-parts from a string construction node.
+     * Returns template_substitution text for template literals,
+     * non-string-literal operands for binary expressions,
+     * and non-literal arguments for concat calls.
+     */
+    getDynamicParts(node, sourceCode) {
+        const type = node.raw.type;
+        if (type === 'call_expression') {
+            const nested = this.getNestedDynamicCallParts(node, sourceCode);
+            if (nested)
+                return nested;
+            return this.getCallArgParts(node);
+        }
+        if (type === 'template_string')
+            return this.getTemplateStringParts(node, sourceCode);
+        if (type === 'binary_expression')
+            return this.getBinaryExpressionParts(node, sourceCode);
+        return [];
+    }
+    /** For a non-`.concat()` call, recurse into the first argument that is itself
+     *  a dynamic string construction; null when there is none (or it's .concat). */
+    getNestedDynamicCallParts(node, sourceCode) {
+        const text = node.raw.text;
+        if (text.includes('.concat(') || text.includes('?.concat('))
+            return null;
         for (const child of node.children ?? []) {
-            if (child.raw.type === 'arguments') {
-                for (const arg of child.children ?? []) {
-                    const argType = arg.raw.type;
-                    if (argType !== '(' && argType !== ')' && argType !== ',') {
-                        args.push(arg.raw.text);
+            if (child.raw.type !== 'arguments')
+                continue;
+            for (const arg of child.children ?? []) {
+                const argType = arg.raw.type;
+                if (argType === '(' || argType === ')' || argType === ',')
+                    continue;
+                if (this.isDynamicStringConstruction(arg)) {
+                    return this.getDynamicParts(arg, sourceCode);
+                }
+            }
+        }
+        return null;
+    }
+    /** `.concat()` (or a call with no nested dynamic arg): every argument is dynamic. */
+    getCallArgParts(node) {
+        const parts = [];
+        for (const child of node.children ?? []) {
+            if (child.raw.type !== 'arguments')
+                continue;
+            for (const arg of child.children ?? []) {
+                const argType = arg.raw.type;
+                if (argType === '(' || argType === ')' || argType === ',')
+                    continue;
+                const text = arg.raw.text.trim();
+                const isId = /^[$\p{L}_][\p{L}\p{N}_$]*$/u.test(text);
+                parts.push({ text, isIdentifier: isId, node: arg });
+            }
+        }
+        return parts;
+    }
+    /** Dynamic parts from a template string's `${…}` substitutions. */
+    getTemplateStringParts(node, sourceCode) {
+        const parts = [];
+        for (const child of node.children ?? []) {
+            if (child.raw.type !== 'template_substitution')
+                continue;
+            const text = sourceCode.slice(child.range[0], child.range[1]);
+            // Strip the ${ } wrapper to get the inner identifier/expression.
+            const inner = text.startsWith('${') ? text.slice(2, -1).trim() : text;
+            const isId = /^[$\p{L}_][\p{L}\p{N}_$]*$/u.test(inner);
+            // The expression inside ${…} is the single named child; attach it for
+            // isSafeInterpolation() cross-function safety checks.
+            let exprNode;
+            for (const subChild of child.children ?? []) {
+                if (subChild.raw.type !== 'template_substitution') {
+                    exprNode = subChild;
+                    break;
+                }
+            }
+            parts.push({ text: inner, isIdentifier: isId, node: exprNode ?? child });
+        }
+        return parts;
+    }
+    /** Dynamic parts from a `+`-concatenation of strings and expressions. */
+    getBinaryExpressionParts(node, sourceCode) {
+        const parts = [];
+        for (const child of node.children ?? []) {
+            const childType = child.raw.type;
+            if (childType === 'string' || childType === '+' || childType === 'template_string')
+                continue;
+            const text = sourceCode.slice(child.range[0], child.range[1]);
+            const isId = /^[$\p{L}_][\p{L}\p{N}_$]*$/u.test(text.trim());
+            parts.push({ text: text.trim(), isIdentifier: isId, node: child });
+        }
+        return parts;
+    }
+}
+class TsConstantResolution extends TsDynamicStringConstruction {
+    /**
+     * Resolves a local const/let/var declaration for an identifier node.
+     * Searches within the enclosing function scope for the declaration site.
+     * Returns null when the identifier is a parameter, complex expression,
+     * or cannot be statically resolved.
+     */
+    resolveLocalConstant(identifierNode, ast, sourceCode) {
+        const idName = sourceCode.slice(identifierNode.range[0], identifierNode.range[1]).trim();
+        if (!idName)
+            return null;
+        // Enclosing function/file scope, falling back to the module scope for
+        // module-level constants.
+        const enclosing = this.findEnclosingScope(identifierNode, ast);
+        const scopeRoot = enclosing ?? ast.root;
+        const scope = { scopeRoot, enclosing, ast };
+        const resolved = this.resolveDeclarationOrConstant(identifierNode, idName, sourceCode, scope);
+        if (resolved.constant)
+            return resolved.constant;
+        const declNode = resolved.declNode;
+        if (!declNode)
+            return null;
+        return this.resolveFromDeclaration(declNode, idName, sourceCode, scope);
+    }
+    /** Determine static-ness and init text from a resolved declaration node.
+     *
+     *  "Static" means the value is a compile-time constant that is never
+     *  reassigned.  String literals and substitution-free template strings are
+     *  constants regardless of `?` placeholders — SQL fragment constants (WHERE
+     *  clauses, column lists) are as static as parameterised query strings.
+     *
+     *  The value is extracted from the AST rather than regex so that multiline
+     *  declarations survive (`.` doesn't match `\n`). */
+    resolveFromDeclaration(declNode, idName, sourceCode, scope) {
+        const { scopeRoot, enclosing, ast } = scope;
+        const raw = declNode.raw;
+        const valueNode = raw.childForFieldName?.('value');
+        const declLine = declNode.location.start.line;
+        const reassigned = this.hasReassignment(scopeRoot, idName, declLine);
+        let isStatic = !reassigned && this.isStaticValueNode(valueNode);
+        // For-of / for-in loop variables: the declarator has no `value` field
+        // (the iterable is on the for-statement's `right` child).  Trace the
+        // iterable to see if all possible loop values are known constants.
+        if (!isStatic && !valueNode && this.traceForOfLoopVariable(declNode, scopeRoot, enclosing, ast)) {
+            isStatic = true;
+        }
+        // Value is a simple identifier (e.g. `table` ← `tables`): trace through to
+        // the linked declaration (handles `for (const table of TABLES)` where the
+        // iterable is a compile-time constant array).
+        if (!isStatic && valueNode?.type === 'identifier' && this.traceLinkedIdentifier(valueNode, idName, scope)) {
+            isStatic = true;
+        }
+        const initText = this.extractInitText(valueNode, declNode, sourceCode);
+        return { initText, isStatic, declLine };
+    }
+    /** Resolve `idName` to a declaration in the enclosing scope (falling back to
+     *  the program-level scope), or — when no local declaration exists — to an
+     *  imported constant or a `for…in`/`for…of` loop variable.  Returns either a
+     *  declaration node or a fully resolved constant. */
+    resolveDeclarationOrConstant(identifierNode, idName, sourceCode, scope) {
+        const { scopeRoot, enclosing, ast } = scope;
+        let declNode = this.findDeclarationInScope(scopeRoot, idName);
+        // If the enclosing scope is a function (not the program) and we didn't
+        // find the declaration there, also search the program-level scope.
+        if (!declNode && enclosing && enclosing !== ast.root) {
+            declNode = this.findDeclarationInScope(ast.root, idName);
+        }
+        if (declNode)
+            return { declNode, constant: null };
+        // Not in local declarations — imported symbols are compile-time constants
+        // resolved at link time, not runtime, so user input cannot reach them via
+        // import bindings.
+        const importResult = this.resolveImportConstant(idName, ast);
+        if (importResult)
+            return { declNode: null, constant: importResult };
+        // tree-sitter-typescript (v0.x) parses both "for…in" and "for…of" as
+        // `for_in_statement`; the loop variable is a bare identifier child.
+        const forInResult = this.traceForInLoopVariable(identifierNode, idName, sourceCode, scope);
+        if (forInResult)
+            return { declNode: null, constant: forInResult };
+        return { declNode: null, constant: null };
+    }
+    /** Trace a `for…in`/`for…of` loop variable whose identifier appears directly
+     *  under a `for_in_statement` `left` child.  tree-sitter-typescript (v0.x)
+     *  parses both loop forms as `for_in_statement`; the loop variable is a bare
+     *  `identifier` child — NOT wrapped in `variable_declarator` /
+     *  `lexical_declaration`.  Walk up from the identifier to a `for_in_statement`
+     *  and trace through the iterable to determine static-ness.
+     *    const TABLES = ["a", "b"];
+     *    for (const table of TABLES) { … `${table}` … }
+     */
+    traceForInLoopVariable(identifierNode, idName, sourceCode, scope) {
+        const { scopeRoot, enclosing, ast } = scope;
+        const idRaw = identifierNode.raw;
+        let tsCurrent = idRaw.parent;
+        while (tsCurrent) {
+            if (tsCurrent.type === 'for_in_statement') {
+                const left = tsCurrent.childForFieldName?.('left');
+                if (left && left.text === idName) {
+                    const right = tsCurrent.childForFieldName?.('right');
+                    if (right && right.type === 'identifier') {
+                        const iterName = right.text;
+                        let iterDecl = this.findDeclarationInScope(scopeRoot, iterName);
+                        if (!iterDecl && enclosing && enclosing !== ast.root) {
+                            iterDecl = this.findDeclarationInScope(ast.root, iterName);
+                        }
+                        if (iterDecl) {
+                            const iterRaw = iterDecl.raw;
+                            const iterValue = iterRaw.childForFieldName?.('value');
+                            const iterLine = iterDecl.location.start.line;
+                            const iterReassigned = this.hasReassignment(scopeRoot, iterName, iterLine)
+                                || (enclosing && enclosing !== ast.root ? this.hasReassignment(ast.root, iterName, iterLine) : false);
+                            if (!iterReassigned && this.isStaticValueNode(iterValue)) {
+                                const initText = iterValue ? sourceCode.slice(iterValue.startIndex, iterValue.endIndex).trim() : '';
+                                return { initText, isStatic: true, declLine: iterDecl.location.start.line };
+                            }
+                        }
                     }
                 }
+                break;
+            }
+            tsCurrent = tsCurrent.parent;
+        }
+        return null;
+    }
+    /** Trace a for-of / for-in loop variable whose declarator has no `value` field
+     *  (the iterable is on the for-statement's `right` child).  Returns true when
+     *  all possible loop values are known compile-time constants. */
+    traceForOfLoopVariable(declNode, scopeRoot, enclosing, ast) {
+        const forParent = this.findEnclosingForStatement(declNode);
+        if (!forParent)
+            return false;
+        const forRaw = forParent.raw;
+        const iterable = forRaw.childForFieldName?.('right');
+        if (!iterable || iterable.type !== 'identifier')
+            return false;
+        const iterName = iterable.text;
+        let iterDecl = this.findDeclarationInScope(scopeRoot, iterName);
+        if (!iterDecl && enclosing && enclosing !== ast.root) {
+            iterDecl = this.findDeclarationInScope(ast.root, iterName);
+        }
+        if (!iterDecl)
+            return false;
+        const iterRaw = iterDecl.raw;
+        const iterValue = iterRaw.childForFieldName?.('value');
+        const iterLine = iterDecl.location.start.line;
+        const iterReassigned = this.hasReassignment(scopeRoot, iterName, iterLine)
+            || (enclosing && enclosing !== ast.root ? this.hasReassignment(ast.root, iterName, iterLine) : false);
+        return !iterReassigned && this.isStaticValueNode(iterValue);
+    }
+    /** Trace an identifier value (e.g. `table` ← `tables`) to its linked
+     *  declaration.  Returns true when the linked initializer is a static
+     *  constant and is never reassigned. */
+    traceLinkedIdentifier(valueNode, idName, scope) {
+        const { scopeRoot, enclosing, ast } = scope;
+        const linkedName = valueNode.text;
+        if (!linkedName || linkedName === idName)
+            return false;
+        let linkedDecl = this.findDeclarationInScope(scopeRoot, linkedName);
+        if (!linkedDecl && enclosing && enclosing !== ast.root) {
+            linkedDecl = this.findDeclarationInScope(ast.root, linkedName);
+        }
+        if (!linkedDecl)
+            return false;
+        const linkedRaw = linkedDecl.raw;
+        const linkedValue = linkedRaw.childForFieldName?.('value');
+        const linkedLine = linkedDecl.location.start.line;
+        const linkedReassigned = this.hasReassignment(scopeRoot, linkedName, linkedLine)
+            || (enclosing && enclosing !== ast.root ? this.hasReassignment(ast.root, linkedName, linkedLine) : false);
+        return !linkedReassigned && this.isStaticValueNode(linkedValue);
+    }
+    /** Extract the initializer text from a declaration: the value node when
+     *  present, otherwise a regex fallback over the full declaration text. */
+    extractInitText(valueNode, declNode, sourceCode) {
+        if (valueNode) {
+            return sourceCode.slice(valueNode.startIndex, valueNode.endIndex).trim();
+        }
+        // No initializer node — try regex as a last resort.
+        const declText = sourceCode.slice(declNode.range[0], declNode.range[1]);
+        const declMatch = declText.match(/^(?:const|let|var)\s+(\w+)\s*=\s*(.+?);?\s*$|^(\w+)\s*=\s*(.+?);?\s*$/s);
+        return declMatch
+            ? (declMatch[2] ?? declMatch[4]).replace(/;\s*$/, '').trim()
+            : '';
+    }
+    /** True when the identifier names the enclosing function's parameter AND a
+     *  guard call (assert/validate/check/ensure/guard-prefixed) is invoked on it
+     *  before its use.  Guards throw on invalid input, so a parameter that has
+     *  passed one cannot carry unvalidated attacker data past the check. */
+    isGuardValidatedParameter(identifierNode, ast) {
+        const idRaw = identifierNode.raw;
+        const paramName = idRaw.text;
+        const enclosing = this.findEnclosingScope(identifierNode, ast);
+        if (!enclosing || enclosing === ast.root)
+            return false;
+        if (!this.getParamNames(enclosing).includes(paramName))
+            return false;
+        let guarded = false;
+        this.walk(enclosing, (node) => {
+            if (guarded)
+                return;
+            const raw = node.raw;
+            if (raw.type !== 'call_expression')
+                return;
+            const fn = raw.childForFieldName?.('function');
+            if (!fn)
+                return;
+            let calleeName = null;
+            if (fn.type === 'identifier')
+                calleeName = fn.text;
+            else if (fn.type === 'member_expression') {
+                calleeName = fn.childForFieldName?.('property')?.text ?? null;
+            }
+            if (!calleeName)
+                return;
+            if (!/^(assert|validate|check|ensure|guard)([A-Z_]|$)/i.test(calleeName))
+                return;
+            const argsNode = raw.childForFieldName?.('arguments');
+            const first = argsNode?.namedChildren[0] ?? null;
+            if (first && first.type === 'identifier' && first.text === paramName
+                && raw.startIndex < idRaw.startIndex) {
+                guarded = true;
+            }
+        });
+        return guarded;
+    }
+}
+class TsSafetyAnalysis extends TsConstantResolution {
+    /** Public entry point (LanguageAdapter.isSafeInterpolation). */
+    isSafeInterpolation(node, ast, sourceCode) {
+        return this.isSafeExpression(node, {
+            ast,
+            sourceCode,
+            seen: new Set(),
+            seenFns: new Set(),
+            paramMap: new Map(),
+        });
+    }
+    /** Recursive safety check against the traversal context in `ctx`. */
+    isSafeExpression(node, ctx) {
+        if (!node)
+            return false;
+        if (node === SAFE_STRING_NODE)
+            return true;
+        const raw = node.raw;
+        // `seen` is path-based (added on entry, removed on exit) and keyed by the
+        // node's unique `id` — NOT `startIndex`, which collides between an
+        // expression and its leading operand (a `binary_expression` and its left
+        // string share a start offset).  Path-based semantics let a shared value
+        // (one literal bound to two parameters) be re-checked via sibling branches
+        // while still breaking true cycles (a node in its own ancestor chain).
+        const key = raw.id;
+        if (ctx.seen.has(key))
+            return false;
+        ctx.seen.add(key);
+        const result = this.evaluateSafeExpression(node, raw, ctx);
+        ctx.seen.delete(key);
+        return result;
+    }
+    /** Evaluate a single expression node's safety, dispatching on its AST type. */
+    evaluateSafeExpression(node, raw, ctx) {
+        // Structural nodes (wrappers, binary, ternary) recurse into children.
+        const structural = this.evaluateStructuralExpression(node, raw, ctx);
+        if (structural !== null)
+            return structural;
+        switch (raw.type) {
+            case 'string':
+            case 'number':
+            case 'true':
+            case 'false':
+            case 'null':
+            case 'undefined':
+            case 'regex':
+                return true;
+            case 'identifier':
+                return this.isSafeIdentifier(node, ctx);
+            case 'template_string':
+                return this.isSafeTemplateString(node, ctx);
+            case 'array':
+                return this.isSafeArray(node, ctx);
+            case 'call_expression':
+                return this.isSafeCallExpression(node, ctx);
+            // member_expression, object/class literals, await/async, etc. — a value we
+            // cannot prove safe.  Conservative: stay flagged.
+            default:
+                return false;
+        }
+    }
+    /** Handle structural nodes that recurse into child expressions (parenthesized
+     *  wrappers, type casts/assertions, ternaries, binary ops).  Returns `null`
+     *  when the node is not structural, so the caller can fall through to the
+     *  leaf switch. */
+    evaluateStructuralExpression(node, raw, ctx) {
+        switch (raw.type) {
+            case 'parenthesized_expression': {
+                const inner = (node.children ?? []).find((c) => !['(', ')'].includes(c.raw.type));
+                return this.isSafeExpression(inner ?? null, ctx);
+            }
+            case 'as_expression':
+            case 'type_assertion':
+            case 'satisfies_expression':
+            case 'non_null_expression': {
+                const inner = raw.namedChild?.(0);
+                return this.isSafeExpression(this.wrapRaw(inner), ctx);
+            }
+            case 'ternary_expression': {
+                const consequence = raw.childForFieldName?.('consequence');
+                const alternative = raw.childForFieldName?.('alternative');
+                return this.isSafeExpression(this.wrapRaw(consequence), ctx)
+                    && this.isSafeExpression(this.wrapRaw(alternative), ctx);
+            }
+            case 'binary_expression': {
+                const left = raw.childForFieldName?.('left');
+                const right = raw.childForFieldName?.('right');
+                return this.isSafeExpression(this.wrapRaw(left), ctx)
+                    && this.isSafeExpression(this.wrapRaw(right), ctx);
+            }
+            default:
+                return null;
+        }
+    }
+    /** Identifier safety: a bound parameter, compile-time constant, or validated
+     *  parameter at all call sites. */
+    isSafeIdentifier(node, ctx) {
+        const name = node.raw.text;
+        // A parameter bound at the current call site — recurse into its value.
+        if (ctx.paramMap.has(name)) {
+            return this.isSafeExpression(ctx.paramMap.get(name) ?? null, ctx);
+        }
+        // Compile-time constant (string/number/static array/imported symbol).
+        const resolved = this.resolveLocalConstant(node, ctx.ast, ctx.sourceCode);
+        if (resolved && resolved.isStatic) {
+            return true;
+        }
+        if (this.isDeclarationValueSafe(node, ctx)) {
+            return true;
+        }
+        if (this.isGuardValidatedParameter(node, ctx.ast)) {
+            return true;
+        }
+        if (this.isParamSafeAtAllCallSites(node, ctx)) {
+            return true;
+        }
+        return false;
+    }
+    /** A template string is safe only if every `${…}` substitution is safe. */
+    isSafeTemplateString(node, ctx) {
+        for (const child of node.children ?? []) {
+            const ct = child.raw.type;
+            if (ct !== 'template_substitution')
+                continue;
+            const inner = (child.children ?? []).find((c) => c.raw.type !== 'template_substitution') ?? child;
+            if (!this.isSafeExpression(inner, ctx)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** An array literal is safe only if every element is safe. */
+    isSafeArray(node, ctx) {
+        for (const child of node.children ?? []) {
+            const ct = child.raw.type;
+            if (ct === ',' || ct === '[' || ct === ']')
+                continue;
+            if (!this.isSafeExpression(child, ctx)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Decide whether a call expression is provably safe to embed in SQL. */
+    isSafeCallExpression(node, ctx) {
+        const raw = node.raw;
+        const fnNode = raw.childForFieldName?.('function');
+        if (!fnNode)
+            return false;
+        // NOTE: manual quote-escaping (`x.replace(/'/g, "''")`) is deliberately NOT
+        // treated as a sanitizer here — see the module-level comment above.  It
+        // covers only the single-quote case and would otherwise bless a real
+        // vulnerability.
+        // 1. Static-array `.map().join()` chain (e.g. `FLAGS.map((c) => \`a.${c}\`).join(", ")`).
+        if (this.isSafeMapJoin(node, ctx))
+            return true;
+        // 2. Local function call with a safe body and safe call sites.
+        if (this.isLocalFunctionCallSafe(node, ctx))
+            return true;
+        return false;
+    }
+    /** True when the node is `.join(...)` over `.map(...)` of a static array whose
+     *  callback body is safe for every element. */
+    isSafeMapJoin(node, ctx) {
+        const raw = node.raw;
+        const fnNode = raw.childForFieldName?.('function');
+        if (!fnNode || fnNode.type !== 'member_expression')
+            return false;
+        const joinProp = fnNode.childForFieldName?.('property');
+        const joinObj = fnNode.childForFieldName?.('object');
+        if (!joinProp || !joinObj || joinProp.text !== 'join')
+            return false;
+        if (joinObj.type !== 'call_expression')
+            return false;
+        const mapFn = joinObj.childForFieldName?.('function');
+        const mapArgs = joinObj.childForFieldName?.('arguments');
+        if (!mapFn || mapFn.type !== 'member_expression')
+            return false;
+        const mapProp = mapFn.childForFieldName?.('property');
+        const mapObj = mapFn.childForFieldName?.('object');
+        if (!mapProp || !mapObj || mapProp.text !== 'map')
+            return false;
+        // The array being mapped must itself be provably safe (static array/const).
+        if (!this.isSafeExpression(this.wrapRaw(mapObj), ctx))
+            return false;
+        // The callback must be safe for any element — bind its first parameter to a
+        // compile-time string sentinel and check the callback body.
+        const callback = mapArgs?.namedChildren[0] ?? null;
+        if (!callback || !['arrow_function', 'function_expression', 'function'].includes(callback.type))
+            return false;
+        const cbParams = this.getParamNames(this.wrapRaw(callback));
+        if (cbParams.length === 0)
+            return false;
+        const bound = new Map(ctx.paramMap);
+        bound.set(cbParams[0], SAFE_STRING_NODE);
+        return this.isBodySafeUnderParams(this.wrapRaw(callback), { ...ctx, paramMap: bound });
+    }
+    /** True when the node is a call to a local (in-file) function whose body is
+     *  safe under the values passed at this call site. */
+    isLocalFunctionCallSafe(node, ctx) {
+        const raw = node.raw;
+        const fnNode = raw.childForFieldName?.('function');
+        if (!fnNode || fnNode.type !== 'identifier')
+            return false;
+        const calleeName = fnNode.text;
+        if (!calleeName || ctx.seenFns.has(calleeName))
+            return false;
+        ctx.seenFns.add(calleeName);
+        const decl = this.findFunctionDeclaration(calleeName, ctx.ast);
+        if (!decl)
+            return false;
+        const paramNames = this.getParamNames(decl);
+        const argNodes = this.getCallArgASTNodes(node);
+        const bound = new Map(ctx.paramMap);
+        paramNames.forEach((p, i) => bound.set(p, argNodes[i] ?? null));
+        return this.isBodySafeUnderParams(decl, { ...ctx, paramMap: bound });
+    }
+    /** Check a function's body returns only safe values, under the `paramMap`
+     *  already bound in `ctx` to the values passed at the call site. */
+    isBodySafeUnderParams(fnNode, ctx) {
+        const raw = fnNode.raw;
+        const body = raw.childForFieldName?.('body');
+        if (!body)
+            return false;
+        if (body.type === 'statement_block') {
+            const returns = [];
+            const collect = (n) => {
+                if (n.type === 'return_statement')
+                    returns.push(n);
+                for (const c of n.namedChildren)
+                    collect(c);
+            };
+            collect(body);
+            if (returns.length === 0)
+                return false;
+            for (const r of returns) {
+                const expr = r.namedChildren.find((c) => c.type !== 'return_statement') ?? null;
+                if (!expr)
+                    return false;
+                if (!this.isSafeExpression(this.wrapRaw(expr), ctx))
+                    return false;
             }
+            return true;
+        }
+        // Arrow-function expression body (no braces).
+        return this.isSafeExpression(this.wrapRaw(body), ctx);
+    }
+    /** True when the identifier names the enclosing function's parameter AND every
+     *  in-file call site of that function passes a provably-safe value for that
+     *  parameter position. */
+    isParamSafeAtAllCallSites(identifierNode, ctx) {
+        const idRaw = identifierNode.raw;
+        const paramName = idRaw.text;
+        const enclosing = this.findEnclosingScope(identifierNode, ctx.ast);
+        if (!enclosing || enclosing === ctx.ast.root)
+            return false;
+        const paramNames = this.getParamNames(enclosing);
+        const paramIndex = paramNames.indexOf(paramName);
+        if (paramIndex < 0)
+            return false;
+        const fnName = this.getFunctionName(enclosing);
+        if (!fnName)
+            return false;
+        const callSites = this.findCallSites(fnName, ctx.ast);
+        if (callSites.length === 0)
+            return false;
+        for (const site of callSites) {
+            const arg = this.getCallArgASTNodes(site)[paramIndex];
+            if (!arg)
+                return false;
+            if (!this.isSafeExpression(arg, { ...ctx, paramMap: new Map() }))
+                return false;
         }
-        return args;
+        return true;
     }
+    /** True when the identifier names a local variable whose initializer is a
+     *  provably-safe expression and which is never reassigned. */
+    isDeclarationValueSafe(identifierNode, ctx) {
+        const idRaw = identifierNode.raw;
+        const name = idRaw.text;
+        const enclosing = this.findEnclosingScope(identifierNode, ctx.ast);
+        const scopeRoot = enclosing ?? ctx.ast.root;
+        let declNode = this.findDeclarationInScope(scopeRoot, name);
+        if (!declNode && enclosing && enclosing !== ctx.ast.root) {
+            declNode = this.findDeclarationInScope(ctx.ast.root, name);
+        }
+        if (!declNode)
+            return false;
+        const declLine = declNode.location.start.line;
+        const reassigned = this.hasReassignment(scopeRoot, name, declLine)
+            || (enclosing && enclosing !== ctx.ast.root ? this.hasReassignment(ctx.ast.root, name, declLine) : false);
+        if (reassigned)
+            return false;
+        const declRaw = declNode.raw;
+        const valueRaw = declRaw.childForFieldName?.('value');
+        if (!valueRaw)
+            return false;
+        return this.isSafeExpression(this.wrapRaw(valueRaw), ctx);
+    }
+}
+// ---------------------------------------------------------------------------
+// Adapter (composes the slices above)
+// ---------------------------------------------------------------------------
+/**
+ * Tree sitter type script adapter.
+ */
+export class TreeSitterTypeScriptAdapter extends TsSafetyAnalysis {
 }
 //# sourceMappingURL=TreeSitterTypeScriptAdapter.js.map