@vybestack/llxprt-code-tools 0.10.0-nightly.260613.1adad3b34

package/dist/src/tools/structural-analysis.js

@@ -0,0 +1,1089 @@
+/**
+ * Multi-hop AST-based code analysis tool.
+ * Analyzes code relationships: call graphs, type hierarchies, symbol references,
+ * module dependencies, and exports using @ast-grep/napi.
+ *
+ * This is name-based (not type-resolved) analysis. See overview.md for limitations.
+ *
+ * @plan PLAN-20260211-ASTGREP.P07
+ */
+/* eslint-disable complexity, sonarjs/cognitive-complexity, max-lines -- Phase 5: legacy core boundary retained while larger decomposition continues. */
+import * as path from 'node:path';
+import { promises as fs } from 'node:fs';
+import FastGlob from 'fast-glob';
+import { BaseDeclarativeTool, BaseToolInvocation, Kind, } from './tools.js';
+import { makeRelative } from '../utils/paths.js';
+import { parse, getAstLanguage, LANGUAGE_MAP, } from '../utils/ast-grep-utils.js';
+const VALID_MODES = [
+    'callers',
+    'callees',
+    'definitions',
+    'hierarchy',
+    'references',
+    'dependencies',
+    'exports',
+];
+const DEFAULT_DEPTH = 1;
+const MAX_DEPTH = 5;
+const DEFAULT_MAX_NODES = 50;
+class StructuralAnalysisInvocation extends BaseToolInvocation {
+    host;
+    constructor(host, params, messageBus) {
+        super(params, messageBus);
+        this.host = host;
+    }
+    getDescription() {
+        const { mode, symbol } = this.params;
+        if (symbol)
+            return `${mode}: ${symbol}`;
+        return `${mode} analysis`;
+    }
+    makeError(message) {
+        return { llmContent: message, returnDisplay: message };
+    }
+    formatResult(analysisResult) {
+        const llmContent = JSON.stringify(analysisResult, null, 2);
+        const mode = analysisResult.mode;
+        const symbol = analysisResult.symbol ? ` for ${analysisResult.symbol}` : '';
+        const displayMessage = `${mode} analysis${symbol} complete${analysisResult.truncated ? ' (truncated)' : ''}`;
+        return {
+            llmContent,
+            returnDisplay: displayMessage,
+            metadata: analysisResult,
+        };
+    }
+    validateAndResolveParams() {
+        const { mode, language, symbol, depth, maxNodes, target, reverse } = this.params;
+        if (!VALID_MODES.includes(mode)) {
+            return this.makeError(`Error: Invalid mode "${mode}". Valid modes: ${VALID_MODES.join(', ')}`);
+        }
+        if (!language) {
+            return this.makeError('Error: `language` parameter is required.');
+        }
+        const resolvedLang = getAstLanguage(language);
+        if (!resolvedLang) {
+            return this.makeError(`Error: Unrecognized language "${language}". Supported: ${Object.keys(LANGUAGE_MAP).join(', ')}`);
+        }
+        const targetDir = this.host.getTargetDir();
+        let searchPath = this.params.path ?? target ?? targetDir;
+        if (!path.isAbsolute(searchPath)) {
+            searchPath = path.resolve(targetDir, searchPath);
+        }
+        const normalizedTarget = targetDir.endsWith(path.sep)
+            ? targetDir
+            : targetDir + path.sep;
+        if (searchPath !== targetDir && !searchPath.startsWith(normalizedTarget)) {
+            return this.makeError('Error: Path resolves outside the workspace root.');
+        }
+        const symbolModes = [
+            'callers',
+            'callees',
+            'definitions',
+            'hierarchy',
+            'references',
+        ];
+        if (symbolModes.includes(mode) && !symbol) {
+            return this.makeError(`Error: \`symbol\` parameter is required for "${mode}" mode.`);
+        }
+        return {
+            mode,
+            resolvedLang,
+            searchPath,
+            targetDir,
+            symbol,
+            depth: Math.min(depth ?? DEFAULT_DEPTH, MAX_DEPTH),
+            maxNodes: maxNodes ?? DEFAULT_MAX_NODES,
+            reverse: reverse === true,
+        };
+    }
+    async dispatchMode(mode, resolvedLang, searchPath, targetDir, symbol, effectiveDepth, effectiveMaxNodes, reverse, signal) {
+        switch (mode) {
+            case 'definitions':
+                return this.executeDefinitions(symbol, resolvedLang, searchPath, targetDir, signal);
+            case 'hierarchy':
+                return this.executeHierarchy(symbol, resolvedLang, searchPath, targetDir, signal);
+            case 'callers':
+                return this.executeCallers(symbol, resolvedLang, searchPath, targetDir, effectiveDepth, effectiveMaxNodes, signal);
+            case 'callees':
+                return this.executeCallees(symbol, resolvedLang, searchPath, targetDir, effectiveDepth, effectiveMaxNodes, signal);
+            case 'references':
+                return this.executeReferences(symbol, resolvedLang, searchPath, targetDir, signal);
+            case 'dependencies':
+                return this.executeDependencies(searchPath, resolvedLang, targetDir, reverse, signal);
+            case 'exports':
+                return this.executeExports(searchPath, resolvedLang, targetDir, signal);
+            default:
+                throw new Error(`Mode "${mode}" is not implemented.`);
+        }
+    }
+    async execute(signal) {
+        const params = this.validateAndResolveParams();
+        if ('llmContent' in params)
+            return params;
+        const { mode, resolvedLang, searchPath, targetDir, symbol, depth: effectiveDepth, maxNodes: effectiveMaxNodes, reverse, } = params;
+        try {
+            const analysisResult = await this.dispatchMode(mode, resolvedLang, searchPath, targetDir, symbol, effectiveDepth, effectiveMaxNodes, reverse, signal);
+            return this.formatResult(analysisResult);
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.endsWith('is not implemented.')) {
+                return this.makeError(`Error: ${err.message}`);
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            return this.makeError(`Error in ${mode}: ${msg}`);
+        }
+    }
+    async getFiles(searchPath, lang) {
+        const stat = await fs.stat(searchPath).catch(() => null);
+        if (stat !== null && stat.isFile() === true) {
+            return [searchPath];
+        }
+        const extensions = this.getExtensionsForLanguage(lang);
+        return FastGlob(extensions.map((ext) => `**/*.${ext}`), {
+            cwd: searchPath,
+            absolute: true,
+            dot: false,
+            ignore: ['**/node_modules/**', '**/.git/**'],
+        });
+    }
+    getExtensionsForLanguage(lang) {
+        const exts = [];
+        for (const [ext, mapped] of Object.entries(LANGUAGE_MAP)) {
+            if (mapped === lang)
+                exts.push(ext);
+        }
+        return exts.length > 0 ? exts : ['*'];
+    }
+    escapeRegex(s) {
+        // eslint-disable-next-line sonarjs/regular-expr -- Static regex reviewed for lint hardening; behavior preserved.
+        return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    /**
+     * AST node kinds that represent function-like containers.
+     * Used for callers mode to find the scope a call lives in.
+     */
+    static FUNCTION_CONTAINER_KINDS = new Set([
+        'method_definition',
+        'function_declaration',
+        'arrow_function',
+    ]);
+    /**
+     * Extract a name from a function-like container node.
+     * - method_definition: first property_identifier child
+     * - function_declaration: first identifier child
+     * - arrow_function: name from parent variable_declarator's identifier
+     */
+    getContainerName(node) {
+        const kind = String(node.kind());
+        if (kind === 'method_definition') {
+            const nameNode = node
+                .children()
+                .find((c) => String(c.kind()) === 'property_identifier');
+            return nameNode?.text() ?? null;
+        }
+        if (kind === 'function_declaration') {
+            const nameNode = node
+                .children()
+                .find((c) => String(c.kind()) === 'identifier');
+            return nameNode?.text() ?? null;
+        }
+        if (kind === 'arrow_function') {
+            // Walk up to variable_declarator → get its identifier
+            const parent = node.parent();
+            if (parent && String(parent.kind()) === 'variable_declarator') {
+                const nameNode = parent
+                    .children()
+                    .find((c) => String(c.kind()) === 'identifier');
+                return nameNode?.text() ?? null;
+            }
+            return null;
+        }
+        return null;
+    }
+    async parseFile(filePath, lang) {
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const result = parse(lang, content);
+            return { root: result.root(), content };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Extracts the function/method name from a call_expression node.
+     * Handles: `foo()` → "foo", `obj.bar()` → "bar", `a.b.c()` → "c"
+     */
+    extractCalleeName(callNode) {
+        const children = callNode.children();
+        if (children.length === 0)
+            return null;
+        const callee = children[0]; // first child of call_expression is the callee
+        const kind = String(callee.kind());
+        if (kind === 'identifier') {
+            return callee.text();
+        }
+        if (kind === 'member_expression') {
+            // Last property_identifier child is the method name
+            const props = callee
+                .children()
+                .filter((c) => String(c.kind()) === 'property_identifier');
+            if (props.length > 0) {
+                return props[props.length - 1].text();
+            }
+        }
+        return null;
+    }
+    // ===== DEFINITIONS =====
+    searchDefinitionPatterns(parsed, symbol, relPath, definitions) {
+        const patterns = [
+            { pat: `${symbol}($$$PARAMS) { $$$BODY }`, kind: 'method' },
+            { pat: `function ${symbol}($$$PARAMS) { $$$BODY }`, kind: 'function' },
+            { pat: `class ${symbol} { $$$BODY }`, kind: 'class' },
+            { pat: `class ${symbol} extends $PARENT { $$$BODY }`, kind: 'class' },
+        ];
+        for (const { pat, kind } of patterns) {
+            try {
+                const matches = parsed.root.findAll(pat);
+                for (const m of matches) {
+                    const range = m.range();
+                    definitions.push({
+                        file: relPath,
+                        line: range.start.line + 1,
+                        kind,
+                        text: m.text().substring(0, 200),
+                    });
+                }
+            }
+            catch {
+                // Pattern may not be valid for all languages
+            }
+        }
+    }
+    searchDeclarationRules(parsed, symbol, relPath, definitions) {
+        try {
+            const ruleMatches = parsed.root.findAll({
+                rule: {
+                    any: [
+                        {
+                            kind: 'class_declaration',
+                            has: {
+                                kind: 'type_identifier',
+                                regex: `^${this.escapeRegex(symbol)}$`,
+                            },
+                        },
+                        {
+                            kind: 'interface_declaration',
+                            has: {
+                                kind: 'type_identifier',
+                                regex: `^${this.escapeRegex(symbol)}$`,
+                            },
+                        },
+                        {
+                            kind: 'type_alias_declaration',
+                            has: {
+                                kind: 'type_identifier',
+                                regex: `^${this.escapeRegex(symbol)}$`,
+                            },
+                        },
+                    ],
+                },
+            });
+            for (const m of ruleMatches) {
+                const range = m.range();
+                const exists = definitions.some((d) => d.file === relPath && d.line === range.start.line + 1);
+                if (!exists) {
+                    definitions.push({
+                        file: relPath,
+                        line: range.start.line + 1,
+                        kind: String(m.kind()),
+                        text: m.text().substring(0, 200),
+                    });
+                }
+            }
+        }
+        catch {
+            // Rule may not apply
+        }
+    }
+    async executeDefinitions(symbol, lang, searchPath, workspaceRoot, signal) {
+        const files = await this.getFiles(searchPath, lang);
+        const definitions = [];
+        // eslint-disable-next-line sonarjs/too-many-break-or-continue-in-loop -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+        for (const file of files) {
+            if (signal.aborted)
+                break;
+            const parsed = await this.parseFile(file, lang);
+            if (!parsed)
+                continue;
+            const relPath = makeRelative(file, workspaceRoot);
+            this.searchDefinitionPatterns(parsed, symbol, relPath, definitions);
+            this.searchDeclarationRules(parsed, symbol, relPath, definitions);
+        }
+        return {
+            mode: 'definitions',
+            symbol,
+            truncated: false,
+            results: definitions,
+        };
+    }
+    // ===== HIERARCHY =====
+    findSymbolParents(parsed, symbol, extendsParent, implementsInterfaces) {
+        try {
+            const extendsMatches = parsed.root.findAll(`class ${symbol} extends $PARENT { $$$BODY }`);
+            for (const m of extendsMatches) {
+                const parent = m.getMatch('PARENT');
+                if (parent)
+                    extendsParent.push(parent.text());
+            }
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            const implMatches = parsed.root.findAll(`class ${symbol} implements $IFACE { $$$BODY }`);
+            for (const m of implMatches) {
+                const iface = m.getMatch('IFACE');
+                if (iface)
+                    implementsInterfaces.push(iface.text());
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    findSymbolChildren(parsed, symbol, relPath, extendedBy, implementedBy) {
+        try {
+            const childMatches = parsed.root.findAll(`class $NAME extends ${symbol} { $$$BODY }`);
+            for (const m of childMatches) {
+                const name = m.getMatch('NAME');
+                if (name) {
+                    extendedBy.push({
+                        name: name.text(),
+                        file: relPath,
+                        line: m.range().start.line + 1,
+                    });
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            const implByMatches = parsed.root.findAll(`class $NAME implements ${symbol} { $$$BODY }`);
+            for (const m of implByMatches) {
+                const name = m.getMatch('NAME');
+                if (name) {
+                    implementedBy.push({
+                        name: name.text(),
+                        file: relPath,
+                        line: m.range().start.line + 1,
+                    });
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    async executeHierarchy(symbol, lang, searchPath, workspaceRoot, signal) {
+        const files = await this.getFiles(searchPath, lang);
+        const extendsParent = [];
+        const implementsInterfaces = [];
+        const extendedBy = [];
+        const implementedBy = [];
+        // eslint-disable-next-line sonarjs/too-many-break-or-continue-in-loop -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+        for (const file of files) {
+            if (signal.aborted)
+                break;
+            const parsed = await this.parseFile(file, lang);
+            if (!parsed)
+                continue;
+            const relPath = makeRelative(file, workspaceRoot);
+            this.findSymbolParents(parsed, symbol, extendsParent, implementsInterfaces);
+            this.findSymbolChildren(parsed, symbol, relPath, extendedBy, implementedBy);
+        }
+        return {
+            mode: 'hierarchy',
+            symbol,
+            truncated: false,
+            results: {
+                extends: extendsParent,
+                implements: implementsInterfaces,
+                extendedBy,
+                implementedBy,
+            },
+        };
+    }
+    // ===== CALLERS =====
+    // @plan PLAN-20260211-ASTGREP.P09
+    findFunctionContainer(node) {
+        let container = node.parent();
+        while (container &&
+            !StructuralAnalysisInvocation.FUNCTION_CONTAINER_KINDS.has(String(container.kind()))) {
+            container = container.parent();
+        }
+        return container;
+    }
+    getViaContext(callNode) {
+        let node = callNode;
+        let parentNode = node.parent();
+        while (parentNode) {
+            const parentKind = String(parentNode.kind());
+            if (parentKind.includes('statement') ||
+                StructuralAnalysisInvocation.FUNCTION_CONTAINER_KINDS.has(parentKind)) {
+                break;
+            }
+            node = parentNode;
+            parentNode = node.parent();
+        }
+        return node.text().trim().substring(0, 200);
+    }
+    buildCallerEntry(callNode, sym, relPath, visited, via) {
+        const container = this.findFunctionContainer(callNode);
+        if (container === null) {
+            return undefined;
+        }
+        const methodName = this.getContainerName(container);
+        if (methodName === null || methodName === '' || methodName === sym) {
+            return undefined;
+        }
+        const key = `${methodName}@${relPath}`;
+        if (visited.has(key)) {
+            return undefined;
+        }
+        visited.add(key);
+        return {
+            method: methodName,
+            file: relPath,
+            line: container.range().start.line + 1,
+            via: via ?? this.getViaContext(callNode),
+        };
+    }
+    findMemberCallCallers(parsed, sym, relPath, visited, ctx) {
+        const results = [];
+        try {
+            const memberCalls = parsed.root.findAll({
+                rule: {
+                    kind: 'member_expression',
+                    has: {
+                        kind: 'property_identifier',
+                        regex: `^${this.escapeRegex(sym)}$`,
+                    },
+                },
+            });
+            for (const callNode of memberCalls) {
+                if (ctx.nodesVisited >= ctx.maxNodes) {
+                    ctx.truncated = true;
+                    break;
+                }
+                const entry = this.buildCallerEntry(callNode, sym, relPath, visited);
+                if (entry !== undefined) {
+                    ctx.nodesVisited++;
+                    results.push(entry);
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        return results;
+    }
+    findDirectCallCallers(parsed, sym, relPath, visited, ctx) {
+        const results = [];
+        try {
+            const directCallNodes = parsed.root.findAll(`${sym}($$$ARGS)`);
+            for (const callNode of directCallNodes) {
+                const entry = this.buildCallerEntry(callNode, sym, relPath, visited, `${sym}(...)`);
+                if (entry !== undefined) {
+                    ctx.nodesVisited++;
+                    results.push(entry);
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        return results;
+    }
+    async findCallersOfFile(file, lang, sym, workspaceRoot, visited, ctx) {
+        if (ctx.signal.aborted || ctx.nodesVisited >= ctx.maxNodes)
+            return [];
+        const parsed = await this.parseFile(file, lang);
+        if (!parsed)
+            return [];
+        const relPath = makeRelative(file, workspaceRoot);
+        const memberResults = this.findMemberCallCallers(parsed, sym, relPath, visited, ctx);
+        const directResults = this.findDirectCallCallers(parsed, sym, relPath, visited, ctx);
+        return [...memberResults, ...directResults];
+    }
+    async executeCallers(symbol, lang, searchPath, workspaceRoot, depth, maxNodes, signal) {
+        const files = await this.getFiles(searchPath, lang);
+        const visited = new Set();
+        let nodesVisited = 0;
+        let truncated = false;
+        const findCallersOf = async (sym, currentDepth) => {
+            if (currentDepth <= 0 || nodesVisited >= maxNodes || signal.aborted) {
+                if (nodesVisited >= maxNodes)
+                    truncated = true;
+                return [];
+            }
+            const callers = [];
+            const ctx = { nodesVisited, maxNodes, truncated, signal };
+            const syncTraversalState = () => {
+                nodesVisited = ctx.nodesVisited;
+                truncated = ctx.truncated;
+            };
+            // eslint-disable-next-line sonarjs/too-many-break-or-continue-in-loop -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+            for (const file of files) {
+                const fileResults = await this.findCallersOfFile(file, lang, sym, workspaceRoot, visited, ctx);
+                for (const r of fileResults) {
+                    const entry = {
+                        method: r.method,
+                        file: r.file,
+                        line: r.line,
+                        via: r.via,
+                    };
+                    if (currentDepth > 1 && ctx.nodesVisited < maxNodes) {
+                        syncTraversalState();
+                        entry.callers = await findCallersOf(r.method, currentDepth - 1);
+                        ctx.nodesVisited = nodesVisited;
+                        ctx.truncated = truncated;
+                    }
+                    callers.push(entry);
+                }
+            }
+            nodesVisited = ctx.nodesVisited;
+            truncated = ctx.truncated;
+            return callers;
+        };
+        const results = await findCallersOf(symbol, depth);
+        return {
+            mode: 'callers',
+            symbol,
+            truncated,
+            results,
+        };
+    }
+    // ===== CALLEES =====
+    // @plan PLAN-20260211-ASTGREP.P09
+    deduplicateCallRanges(callMatches) {
+        const ranges = callMatches.map((c) => ({
+            node: c,
+            start: c.range().start.index,
+            end: c.range().end.index,
+        }));
+        ranges.sort((a, b) => a.start - b.start !== 0 ? a.start - b.start : b.end - a.end);
+        const outermost = [];
+        for (const r of ranges) {
+            const isContained = outermost.some((o) => r.start >= o.start && r.end <= o.end);
+            if (!isContained)
+                outermost.push(r);
+        }
+        return outermost;
+    }
+    async findCalleesOfFile(file, lang, sym, workspaceRoot, visited, ctx) {
+        if (ctx.nodesVisited >= ctx.maxNodes)
+            return [];
+        const parsed = await this.parseFile(file, lang);
+        if (!parsed)
+            return [];
+        const relPath = makeRelative(file, workspaceRoot);
+        const results = [];
+        try {
+            const methodMatches = parsed.root.findAll({
+                rule: {
+                    kind: 'method_definition',
+                    has: {
+                        kind: 'property_identifier',
+                        regex: `^${this.escapeRegex(sym)}$`,
+                    },
+                },
+            });
+            for (const methodNode of methodMatches) {
+                const callMatches = methodNode.findAll({
+                    rule: { kind: 'call_expression' },
+                });
+                const outermost = this.deduplicateCallRanges(callMatches);
+                for (const { node } of outermost) {
+                    const callText = node.text().substring(0, 200);
+                    const key = `${callText}@${relPath}`;
+                    // eslint-disable-next-line sonarjs/nested-control-flow -- Dedup check inside nested iteration over AST matches
+                    if (visited.has(key))
+                        continue;
+                    visited.add(key);
+                    ctx.nodesVisited++;
+                    results.push({
+                        text: callText,
+                        file: relPath,
+                        line: node.range().start.line + 1,
+                        calleeNode: node,
+                    });
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        return results;
+    }
+    async executeCallees(symbol, lang, searchPath, workspaceRoot, depth, maxNodes, signal) {
+        const files = await this.getFiles(searchPath, lang);
+        const visited = new Set();
+        let nodesVisited = 0;
+        let truncated = false;
+        const findCalleesOf = async (sym, currentDepth) => {
+            if (currentDepth <= 0 || nodesVisited >= maxNodes || signal.aborted) {
+                if (nodesVisited >= maxNodes)
+                    truncated = true;
+                return [];
+            }
+            const callees = [];
+            const ctx = { nodesVisited, maxNodes };
+            for (const file of files) {
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- Signal may be aborted asynchronously between recursive calls while scanning files.
+                if (signal.aborted)
+                    break;
+                const calleeResults = await this.findCalleesOfFile(file, lang, sym, workspaceRoot, visited, ctx);
+                for (const r of calleeResults) {
+                    const entry = {
+                        text: r.text,
+                        file: r.file,
+                        line: r.line,
+                    };
+                    const calleeName = r.calleeNode
+                        ? this.extractCalleeName(r.calleeNode)
+                        : null;
+                    if (currentDepth > 1 &&
+                        ctx.nodesVisited < maxNodes &&
+                        calleeName &&
+                        calleeName !== sym) {
+                        nodesVisited = ctx.nodesVisited;
+                        entry.callees = await findCalleesOf(calleeName, currentDepth - 1);
+                        ctx.nodesVisited = nodesVisited;
+                    }
+                    callees.push(entry);
+                }
+            }
+            nodesVisited = ctx.nodesVisited;
+            return callees;
+        };
+        const results = await findCalleesOf(symbol, depth);
+        return {
+            mode: 'callees',
+            symbol,
+            truncated,
+            results,
+        };
+    }
+    // ===== REFERENCES =====
+    // @plan PLAN-20260211-ASTGREP.P10
+    searchDirectCallReferences(parsed, symbol, relPath, addResult) {
+        try {
+            const memberCalls = parsed.root.findAll(`$OBJ.${symbol}($$$ARGS)`);
+            for (const m of memberCalls) {
+                addResult('Direct calls', relPath, m.range().start.line + 1, m.text());
+            }
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            const standaloneCalls = parsed.root.findAll(`${symbol}($$$ARGS)`);
+            for (const m of standaloneCalls) {
+                addResult('Direct calls', relPath, m.range().start.line + 1, m.text());
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    searchInstantiationReferences(parsed, symbol, relPath, addResult) {
+        try {
+            const news = parsed.root.findAll(`new ${symbol}($$$ARGS)`);
+            for (const m of news) {
+                addResult('Instantiations', relPath, m.range().start.line + 1, m.text());
+            }
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            const lowerSymbol = symbol.charAt(0).toLowerCase() + symbol.slice(1);
+            const instanceCalls = parsed.root.findAll({
+                rule: {
+                    kind: 'call_expression',
+                    has: {
+                        kind: 'member_expression',
+                        has: {
+                            kind: 'identifier',
+                            regex: `(?i)${this.escapeRegex(lowerSymbol)}|${this.escapeRegex(symbol)}`,
+                        },
+                    },
+                },
+            });
+            for (const m of instanceCalls) {
+                addResult('Instance method calls (heuristic)', relPath, m.range().start.line + 1, m.text());
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    searchTypeAndHeritageReferences(parsed, symbol, relPath, addResult) {
+        try {
+            const typeRefs = parsed.root.findAll({
+                rule: {
+                    kind: 'type_annotation',
+                    has: {
+                        kind: 'type_identifier',
+                        regex: `^${this.escapeRegex(symbol)}$`,
+                    },
+                },
+            });
+            for (const m of typeRefs) {
+                addResult('Type annotations', relPath, m.range().start.line + 1, m.text());
+            }
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            const heritage = parsed.root.findAll(`class $NAME extends ${symbol} { $$$BODY }`);
+            for (const m of heritage) {
+                addResult('Extends/Implements', relPath, m.range().start.line + 1, `class ${m.getMatch('NAME')?.text()} extends ${symbol}`);
+            }
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            const implHeritage = parsed.root.findAll(`class $NAME implements ${symbol} { $$$BODY }`);
+            for (const m of implHeritage) {
+                addResult('Extends/Implements', relPath, m.range().start.line + 1, `class ${m.getMatch('NAME')?.text()} implements ${symbol}`);
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    searchImportReferences(parsed, symbol, relPath, addResult) {
+        try {
+            const imports = parsed.root.findAll({
+                rule: {
+                    kind: 'import_specifier',
+                    has: { kind: 'identifier', regex: `^${this.escapeRegex(symbol)}$` },
+                },
+            });
+            for (const m of imports) {
+                addResult('Imports', relPath, m.range().start.line + 1, m.text());
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    async executeReferences(symbol, lang, searchPath, workspaceRoot, signal) {
+        const files = await this.getFiles(searchPath, lang);
+        const categories = {
+            'Direct calls': [],
+            'Instance method calls (heuristic)': [],
+            Instantiations: [],
+            'Type annotations': [],
+            'Extends/Implements': [],
+            Imports: [],
+        };
+        const seen = new Set();
+        const addResult = (category, file, line, text) => {
+            const key = `${category}:${file}:${line}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            categories[category].push({ file, line, text: text.substring(0, 200) });
+        };
+        // eslint-disable-next-line sonarjs/too-many-break-or-continue-in-loop -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+        for (const file of files) {
+            if (signal.aborted)
+                break;
+            const parsed = await this.parseFile(file, lang);
+            if (!parsed)
+                continue;
+            const relPath = makeRelative(file, workspaceRoot);
+            this.searchDirectCallReferences(parsed, symbol, relPath, addResult);
+            this.searchInstantiationReferences(parsed, symbol, relPath, addResult);
+            this.searchTypeAndHeritageReferences(parsed, symbol, relPath, addResult);
+            this.searchImportReferences(parsed, symbol, relPath, addResult);
+        }
+        const counts = {};
+        for (const [cat, items] of Object.entries(categories)) {
+            counts[cat] = items.length;
+        }
+        return {
+            mode: 'references',
+            symbol,
+            truncated: false,
+            results: { categories, counts },
+        };
+    }
+    // ===== DEPENDENCIES =====
+    // @plan PLAN-20260211-ASTGREP.P10
+    collectNamedAndDefaultImports(parsed, relPath, imports) {
+        try {
+            const named = parsed.root.findAll(`import { $$$NAMES } from $SOURCE`);
+            for (const m of named) {
+                const src = m.getMatch('SOURCE');
+                if (src) {
+                    imports.push({
+                        file: relPath,
+                        line: m.range().start.line + 1,
+                        source: src.text().replace(/['"]/g, ''),
+                        kind: 'named',
+                    });
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            const defaults = parsed.root.findAll(`import $DEFAULT from $SOURCE`);
+            for (const m of defaults) {
+                const src = m.getMatch('SOURCE');
+                if (src) {
+                    imports.push({
+                        file: relPath,
+                        line: m.range().start.line + 1,
+                        source: src.text().replace(/['"]/g, ''),
+                        kind: 'default',
+                    });
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    collectDynamicAndReexports(parsed, relPath, imports) {
+        try {
+            const dynamic = parsed.root.findAll({
+                rule: {
+                    kind: 'call_expression',
+                    has: { kind: 'import' },
+                },
+            });
+            for (const m of dynamic) {
+                imports.push({
+                    file: relPath,
+                    line: m.range().start.line + 1,
+                    source: m.text(),
+                    kind: 'dynamic',
+                });
+            }
+        }
+        catch {
+            /* skip */
+        }
+        try {
+            const reexports = parsed.root.findAll({
+                rule: {
+                    kind: 'export_statement',
+                    has: { kind: 'string', regex: '.' },
+                },
+            });
+            for (const m of reexports) {
+                if (m.text().includes('from')) {
+                    imports.push({
+                        file: relPath,
+                        line: m.range().start.line + 1,
+                        source: m.text().substring(0, 200),
+                        kind: 'reexport',
+                    });
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    collectFileImports(parsed, relPath, imports) {
+        this.collectNamedAndDefaultImports(parsed, relPath, imports);
+        this.collectDynamicAndReexports(parsed, relPath, imports);
+    }
+    async findReverseImports(searchPath, workspaceRoot, lang, signal) {
+        const reverseImports = [];
+        const allFiles = await this.getFiles(workspaceRoot, lang);
+        const targetRel = makeRelative(searchPath, workspaceRoot);
+        const targetBasename = path.basename(searchPath).replace(/\.\w+$/, '');
+        // eslint-disable-next-line sonarjs/too-many-break-or-continue-in-loop -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+        for (const file of allFiles) {
+            if (signal.aborted)
+                break;
+            const parsed = await this.parseFile(file, lang);
+            if (!parsed)
+                continue;
+            const relPath = makeRelative(file, workspaceRoot);
+            if (relPath === targetRel)
+                continue;
+            const content = parsed.content || '';
+            if (content.includes(targetBasename)) {
+                reverseImports.push(...this.collectImportMatches(parsed, relPath, targetBasename));
+            }
+        }
+        return reverseImports;
+    }
+    collectImportMatches(parsed, relPath, targetBasename) {
+        const imports = [];
+        try {
+            const allImports = parsed.root.findAll({
+                rule: { kind: 'import_statement' },
+            });
+            for (const m of allImports) {
+                const text = m.text();
+                if (text.includes(targetBasename)) {
+                    imports.push({
+                        file: relPath,
+                        line: m.range().start.line + 1,
+                        source: text.substring(0, 200),
+                        kind: 'import',
+                    });
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+        return imports;
+    }
+    async executeDependencies(searchPath, lang, workspaceRoot, reverse, signal) {
+        const files = await this.getFiles(searchPath, lang);
+        const imports = [];
+        // eslint-disable-next-line sonarjs/too-many-break-or-continue-in-loop -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+        for (const file of files) {
+            if (signal.aborted)
+                break;
+            const parsed = await this.parseFile(file, lang);
+            if (!parsed)
+                continue;
+            const relPath = makeRelative(file, workspaceRoot);
+            this.collectFileImports(parsed, relPath, imports);
+        }
+        const reverseImports = reverse
+            ? await this.findReverseImports(searchPath, workspaceRoot, lang, signal)
+            : [];
+        return {
+            mode: 'dependencies',
+            truncated: false,
+            results: {
+                imports,
+                reverseImports: reverse ? reverseImports : undefined,
+            },
+        };
+    }
+    // ===== EXPORTS =====
+    // @plan PLAN-20260211-ASTGREP.P10
+    async executeExports(searchPath, lang, workspaceRoot, signal) {
+        const files = await this.getFiles(searchPath, lang);
+        const exports = [];
+        // eslint-disable-next-line sonarjs/too-many-break-or-continue-in-loop -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+        for (const file of files) {
+            if (signal.aborted)
+                break;
+            const parsed = await this.parseFile(file, lang);
+            if (!parsed)
+                continue;
+            const relPath = makeRelative(file, workspaceRoot);
+            try {
+                const exportNodes = parsed.root.findAll({
+                    rule: { kind: 'export_statement' },
+                });
+                for (const m of exportNodes) {
+                    const text = m.text();
+                    let kind = 'export';
+                    // eslint-disable-next-line sonarjs/nested-control-flow -- Existing structure is intentionally preserved; refactoring this boundary is outside the lint slice.
+                    if (/^export\s+default\b/.test(text))
+                        kind = 'default';
+                    else if (text.includes('class'))
+                        kind = 'class';
+                    else if (text.includes('function'))
+                        kind = 'function';
+                    else if (text.includes('const') ||
+                        text.includes('let') ||
+                        text.includes('var'))
+                        kind = 'const';
+                    else if (text.includes('interface'))
+                        kind = 'interface';
+                    else if (text.includes('type '))
+                        kind = 'type';
+                    else if (text.includes('from'))
+                        kind = 'reexport';
+                    exports.push({
+                        file: relPath,
+                        line: m.range().start.line + 1,
+                        text: text.substring(0, 200),
+                        kind,
+                    });
+                }
+            }
+            catch {
+                /* skip */
+            }
+        }
+        return {
+            mode: 'exports',
+            truncated: false,
+            results: exports,
+        };
+    }
+}
+export class StructuralAnalysisTool extends BaseDeclarativeTool {
+    host;
+    static Name = 'structural_analysis';
+    constructor(host) {
+        super(StructuralAnalysisTool.Name, 'StructuralAnalysis', 'Performs multi-hop AST-based code analysis: call graphs, type hierarchies, symbol references, ' +
+            'module dependencies, and exports. This is name-based (not type-resolved) analysis. ' +
+            'Use for understanding code relationships. Unlike ast_grep (single-query), this chains multiple queries.', Kind.Search, {
+            properties: {
+                mode: {
+                    description: `Analysis mode: ${VALID_MODES.join(', ')}`,
+                    type: 'string',
+                    enum: [...VALID_MODES],
+                },
+                language: {
+                    description: 'Programming language (e.g., typescript, python)',
+                    type: 'string',
+                },
+                path: {
+                    description: 'Directory to search. Defaults to workspace root.',
+                    type: 'string',
+                },
+                symbol: {
+                    description: 'Symbol name for callers/callees/definitions/hierarchy/references modes.',
+                    type: 'string',
+                },
+                depth: {
+                    description: 'Recursion depth for callers/callees. Default 1, max 5.',
+                    type: 'number',
+                },
+                maxNodes: {
+                    description: 'Max symbols to visit during recursive traversal. Default 50.',
+                    type: 'number',
+                },
+                target: {
+                    description: 'File/directory for dependencies/exports modes.',
+                    type: 'string',
+                },
+                reverse: {
+                    description: 'For dependencies mode: also find what imports the target.',
+                    type: 'boolean',
+                },
+            },
+            required: ['mode', 'language'],
+            type: 'object',
+        });
+        this.host = host;
+    }
+    createInvocation(params, messageBus) {
+        return new StructuralAnalysisInvocation(this.host, params, messageBus);
+    }
+}
+//# sourceMappingURL=structural-analysis.js.map