lsp-intelligence 0.1.2 → 0.2.0

package/dist/search/types.js

@@ -0,0 +1,11 @@
+// ============================================================================
+// Query IR — the parsed representation of a user's search query
+// ============================================================================
+/**
+ * Deduplication key for candidates.
+ * Uses match identity, not just symbol name.
+ */
+export function candidateKey(c) {
+    return `${c.candidateType}:${c.filePath}:${c.line}:${c.column ?? 0}:${c.matchedIdentifier ?? c.symbol ?? ''}`;
+}
+//# sourceMappingURL=types.js.map

package/dist/search/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/search/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,gEAAgE;AAChE,+EAA+E;AAwF/E;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,CAAgB;IAC3C,OAAO,GAAG,CAAC,CAAC,aAAa,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,iBAAiB,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;AAChH,CAAC"}

package/dist/tools/composites/apiGuard.d.ts

@@ -0,0 +1 @@
+export declare const apiGuard: import("../registry.js").ToolDef;

package/dist/tools/composites/apiGuard.js

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+import * as fs from 'fs';
+import * as path from 'path';
+import { defineTool } from '../registry.js';
+import { relativePath, uriToPath, getPackageName } from '../../engine/positions.js';
+import { parseSource } from '../../ast/parseFile.js';
+import { extractExportDeclarations } from '../../ast/extractExportDeclarations.js';
+import { diffExportDeclarations } from '../../ast/diffDeclarationShapes.js';
+import { getMergeBase } from '../../git/getMergeBase.js';
+import { getChangedFiles } from '../../git/getChangedFiles.js';
+import { getBaseFileContent } from '../../git/getBaseFileContent.js';
+import { LspError, LspErrorCode, DEFAULT_TIMEOUTS, SKIP_DIRS } from '../../engine/types.js';
+// --- Helper: collect all TS files under a dir ---
+function collectTsFiles(dir, max) {
+    const files = [];
+    const walk = (d, depth) => {
+        if (depth > 6 || files.length >= max)
+            return;
+        try {
+            for (const entry of fs.readdirSync(d)) {
+                if (SKIP_DIRS.has(entry))
+                    continue;
+                const full = path.join(d, entry);
+                if (fs.statSync(full).isDirectory())
+                    walk(full, depth + 1);
+                else if ((entry.endsWith('.ts') || entry.endsWith('.tsx')) && !entry.endsWith('.d.ts')) {
+                    files.push(full);
+                }
+            }
+        }
+        catch { }
+    };
+    walk(dir, 0);
+    return files;
+}
+export const apiGuard = defineTool({
+    name: 'api_guard',
+    description: 'Detect public API contract changes: what exports changed, how they changed structurally, who consumes them, and the semver impact. Use before merging to catch accidental breaking changes.',
+    schema: z.object({
+        base: z.string().optional().describe('Git base ref. Defaults to merge-base with main.'),
+        scope: z.enum(['changed', 'all']).default('changed').describe('"changed" = only diff-modified files, "all" = scan all source files'),
+        symbol: z.string().optional().describe('Optional: narrow to a specific export name'),
+        file_path: z.string().optional().describe('Optional: narrow to a specific file'),
+    }),
+    async handler(params, engine) {
+        if (!engine.gitAvailable && params.scope === 'changed') {
+            throw new LspError(LspErrorCode.GIT_UNAVAILABLE, 'Git required for scope "changed". Use scope "all" instead.');
+        }
+        const timeout = DEFAULT_TIMEOUTS.composite;
+        const warnings = [];
+        let astUsed = false;
+        // Step 0: Resolve base ref
+        const base = engine.gitAvailable ? getMergeBase(engine.workspaceRoot, params.base) : undefined;
+        // Step 1: Get files in scope
+        let scopeFiles;
+        if (params.file_path) {
+            scopeFiles = [params.file_path];
+        }
+        else if (params.scope === 'changed' && base) {
+            scopeFiles = getChangedFiles(engine.workspaceRoot, base);
+        }
+        else {
+            scopeFiles = collectTsFiles(engine.workspaceRoot, 500);
+        }
+        if (scopeFiles.length === 0) {
+            return { summary: { exportsChecked: 0, changedExports: 0, breaking: 0, risky: 0, safe: 0, recommendedSemver: 'patch' }, entries: [], stats: { astUsed: false, filesParsed: 0, baseUsed: !!base, partialResult: false }, warnings: ['No files in scope'] };
+        }
+        // Step 2+3: Parse exports, diff
+        const entries = [];
+        let filesParsed = 0;
+        let totalExportsChecked = 0;
+        for (const filePath of scopeFiles) {
+            try {
+                const currentContent = fs.readFileSync(filePath, 'utf-8');
+                const currentRoot = parseSource(currentContent, filePath.endsWith('.tsx'));
+                const currentExports = currentRoot
+                    ? (astUsed = true, extractExportDeclarations(currentRoot, currentContent))
+                    : extractExportDeclarations(null, currentContent);
+                totalExportsChecked += currentExports.length;
+                // Get base exports
+                let baseExports = extractExportDeclarations(null, '');
+                if (base) {
+                    const baseContent = getBaseFileContent(filePath, base, engine.workspaceRoot);
+                    if (baseContent) {
+                        const baseRoot = parseSource(baseContent, filePath.endsWith('.tsx'));
+                        baseExports = baseRoot
+                            ? extractExportDeclarations(baseRoot, baseContent)
+                            : extractExportDeclarations(null, baseContent);
+                    }
+                }
+                const diffs = diffExportDeclarations(baseExports, currentExports);
+                for (const d of diffs) {
+                    if (params.symbol && d.name !== params.symbol)
+                        continue;
+                    entries.push({
+                        exportName: d.name,
+                        filePath,
+                        line: d.currentDecl?.line ?? d.baseDecl?.line,
+                        declarationKind: d.baseDecl?.declarationKind ?? d.currentDecl?.declarationKind,
+                        kind: d.kind,
+                        risk: d.risk,
+                        reason: d.reason,
+                        currentSignature: d.currentDecl?.signatureText,
+                        baseSignature: d.baseDecl?.signatureText,
+                        structuralDiff: d.structuralDiff,
+                        consumers: { samePackage: 0, crossPackage: 0, sampleFiles: [] },
+                        evidence: [],
+                    });
+                }
+                filesParsed++;
+            }
+            catch { }
+        }
+        // Step 4: Find consumers using declaration line data (no raw text rescanning)
+        let consumerChecks = 0;
+        for (const entry of entries.filter((e) => e.risk !== 'safe')) {
+            if (consumerChecks >= 15) {
+                warnings.push('Consumer lookup capped at 15 entries');
+                break;
+            }
+            try {
+                const { uri } = await engine.prepareFile(entry.filePath);
+                const exportLine0 = Math.max(0, (entry.line ?? 1) - 1);
+                const refs = await engine.request('textDocument/references', {
+                    textDocument: { uri },
+                    position: { line: exportLine0, character: 0 },
+                    context: { includeDeclaration: false },
+                }, timeout).catch((err) => { warnings.push(`Consumer lookup failed for ${entry.exportName}: ${err instanceof Error ? err.message : String(err)}`); return null; });
+                if (refs) {
+                    const currentPkg = getPackageName(entry.filePath);
+                    const samePackage = refs.filter((r) => getPackageName(uriToPath(r.uri)) === currentPkg).length;
+                    const crossPackage = refs.length - samePackage;
+                    const sampleFiles = [...new Set(refs.map((r) => relativePath(uriToPath(r.uri), engine.workspaceRoot)))].slice(0, 5);
+                    entry.consumers = { samePackage, crossPackage, sampleFiles };
+                    entry.evidence.push(`${crossPackage} cross-package, ${samePackage} same-package consumers`);
+                    // Populate diagnosticsInConsumers (sample up to 3 consumer files)
+                    let diagCount = 0;
+                    for (const fp of sampleFiles.slice(0, 3)) {
+                        try {
+                            const abs = fp.startsWith('/') ? fp : `${engine.workspaceRoot}/${fp}`;
+                            const { uri: consumerUri } = await engine.prepareFile(abs);
+                            const { waitForDiagnostics: waitDiag } = await import('../../engine/waitForDiagnostics.js');
+                            await waitDiag(engine.docManager, consumerUri, 500);
+                            diagCount += engine.docManager.getCachedDiagnostics(consumerUri).filter((d) => d.severity === 1).length;
+                        }
+                        catch (err) {
+                            warnings.push(`Consumer diagnostics failed for ${fp}: ${err instanceof Error ? err.message : String(err)}`);
+                        }
+                    }
+                    entry.diagnosticsInConsumers = diagCount;
+                    // Downgrade risk if no cross-package consumers
+                    if (crossPackage === 0 && entry.risk === 'risky') {
+                        entry.risk = 'safe';
+                        entry.reason += ' (no cross-package consumers)';
+                    }
+                }
+                consumerChecks++;
+            }
+            catch (err) {
+                warnings.push(`Consumer analysis failed for ${entry.exportName}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Step 5: Classify and summarize
+        const breaking = entries.filter((e) => e.risk === 'breaking').length;
+        const risky = entries.filter((e) => e.risk === 'risky').length;
+        const safe = entries.filter((e) => e.risk === 'safe').length;
+        // Semver: breaking → major, additive-only → minor, else patch
+        const hasAdditive = entries.some((e) => e.kind === 'added' && e.risk === 'safe');
+        const semver = breaking > 0 ? 'major' : hasAdditive ? 'minor' : 'patch';
+        const result = {
+            summary: {
+                exportsChecked: totalExportsChecked,
+                changedExports: entries.length,
+                breaking,
+                risky,
+                safe,
+                recommendedSemver: semver,
+            },
+            entries: entries.sort((a, b) => {
+                const riskOrder = { breaking: 0, risky: 1, safe: 2 };
+                return riskOrder[a.risk] - riskOrder[b.risk];
+            }),
+            stats: {
+                astUsed,
+                filesParsed,
+                baseUsed: !!base,
+                partialResult: consumerChecks >= 15,
+            },
+            warnings,
+        };
+        return result;
+    },
+});
+//# sourceMappingURL=apiGuard.js.map

package/dist/tools/composites/apiGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiGuard.js","sourceRoot":"","sources":["../../../src/tools/composites/apiGuard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAE5E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAErE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAuC5F,mDAAmD;AAEnD,SAAS,cAAc,CAAC,GAAW,EAAE,GAAW;IAC9C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,KAAa,EAAE,EAAE;QACxC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG;YAAE,OAAO;QAC7C,IAAI,CAAC;YACH,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtC,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;oBAAE,SAAS;gBACnC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;gBACjC,IAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;oBAAE,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;qBACtD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;oBACvF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACnB,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;IACZ,CAAC,CAAC;IACF,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACb,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,UAAU,CAAC;IACjC,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,6LAA6L;IAC1M,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;QACvF,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,qEAAqE,CAAC;QACpI,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;QACpF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;KACjF,CAAC;IACF,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM;QAC1B,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACvD,MAAM,IAAI,QAAQ,CAAC,YAAY,CAAC,eAAe,EAAE,4DAA4D,CAAC,CAAC;QACjH,CAAC;QAED,MAAM,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC;QAC3C,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,2BAA2B;QAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE/F,6BAA6B;QAC7B,IAAI,UAAoB,CAAC;QACzB,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,UAAU,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC;aAAM,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,EAAE,CAAC;YAC9C,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QAC3D,CAAC;aAAM,CAAC;YACN,UAAU,GAAG,cAAc,CAAC,MAAM,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;QACzD,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,iBAAiB,EAAE,OAAgB,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,CAAC,mBAAmB,CAAC,EAA2B,CAAC;QAC9R,CAAC;QAED,gCAAgC;QAChC,MAAM,OAAO,GAAoB,EAAE,CAAC;QACpC,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,IAAI,mBAAmB,GAAG,CAAC,CAAC;QAE5B,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YAClC,IAAI,CAAC;gBACH,MAAM,cAAc,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBAC1D,MAAM,WAAW,GAAG,WAAW,CAAC,cAAc,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3E,MAAM,cAAc,GAAG,WAAW;oBAChC,CAAC,CAAC,CAAC,OAAO,GAAG,IAAI,EAAE,yBAAyB,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;oBAC1E,CAAC,CAAC,yBAAyB,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;gBAEpD,mBAAmB,IAAI,cAAc,CAAC,MAAM,CAAC;gBAE7C,mBAAmB;gBACnB,IAAI,WAAW,GAAG,yBAAyB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBACtD,IAAI,IAAI,EAAE,CAAC;oBACT,MAAM,WAAW,GAAG,kBAAkB,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;oBAC7E,IAAI,WAAW,EAAE,CAAC;wBAChB,MAAM,QAAQ,GAAG,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;wBACrE,WAAW,GAAG,QAAQ;4BACpB,CAAC,CAAC,yBAAyB,CAAC,QAAQ,EAAE,WAAW,CAAC;4BAClD,CAAC,CAAC,yBAAyB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;oBACnD,CAAC;gBACH,CAAC;gBAED,MAAM,KAAK,GAAG,sBAAsB,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;gBAClE,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;oBACtB,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM;wBAAE,SAAS;oBAExD,OAAO,CAAC,IAAI,CAAC;wBACX,UAAU,EAAE,CAAC,CAAC,IAAI;wBAClB,QAAQ;wBACR,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,CAAC,QAAQ,EAAE,IAAI;wBAC7C,eAAe,EAAE,CAAC,CAAC,QAAQ,EAAE,eAAe,IAAI,CAAC,CAAC,WAAW,EAAE,eAAe;wBAC9E,IAAI,EAAE,CAAC,CAAC,IAAI;wBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;wBACZ,MAAM,EAAE,CAAC,CAAC,MAAM;wBAChB,gBAAgB,EAAE,CAAC,CAAC,WAAW,EAAE,aAAa;wBAC9C,aAAa,EAAE,CAAC,CAAC,QAAQ,EAAE,aAAa;wBACxC,cAAc,EAAE,CAAC,CAAC,cAAc;wBAChC,SAAS,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE;wBAC/D,QAAQ,EAAE,EAAE;qBACb,CAAC,CAAC;gBACL,CAAC;gBACD,WAAW,EAAE,CAAC;YAChB,CAAC;YAAC,MAAM,CAAC,CAAA,CAAC;QACZ,CAAC;QAED,8EAA8E;QAC9E,IAAI,cAAc,GAAG,CAAC,CAAC;QACvB,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,EAAE,CAAC;YAC7D,IAAI,cAAc,IAAI,EAAE,EAAE,CAAC;gBAAC,QAAQ,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;gBAAC,MAAM;YAAC,CAAC;YAC3F,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBACzD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBAEvD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAC/B,yBAAyB,EAAE;oBACzB,YAAY,EAAE,EAAE,GAAG,EAAE;oBACrB,QAAQ,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,EAAE;oBAC7C,OAAO,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE;iBACvC,EAAE,OAAO,CACX,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,8BAA8B,KAAK,CAAC,UAAU,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;gBAElK,IAAI,IAAI,EAAE,CAAC;oBACT,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;oBAClD,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,MAAM,CAAC;oBAC/F,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC;oBAC/C,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;oBACpH,KAAK,CAAC,SAAS,GAAG,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC;oBAC7D,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,mBAAmB,WAAW,yBAAyB,CAAC,CAAC;oBAE5F,kEAAkE;oBAClE,IAAI,SAAS,GAAG,CAAC,CAAC;oBAClB,KAAK,MAAM,EAAE,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;wBACzC,IAAI,CAAC;4BACH,MAAM,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,aAAa,IAAI,EAAE,EAAE,CAAC;4BACtE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;4BAC3D,MAAM,EAAE,kBAAkB,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,oCAAoC,CAAC,CAAC;4BAC5F,MAAM,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;4BACpD,SAAS,IAAI,MAAM,CAAC,UAAU,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;wBAC/G,CAAC;wBAAC,OAAO,GAAG,EAAE,CAAC;4BACb,QAAQ,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;wBAC9G,CAAC;oBACH,CAAC;oBACD,KAAK,CAAC,sBAAsB,GAAG,SAAS,CAAC;oBAEzC,+CAA+C;oBAC/C,IAAI,YAAY,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;wBACjD,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC;wBACpB,KAAK,CAAC,MAAM,IAAI,+BAA+B,CAAC;oBAClD,CAAC;gBACH,CAAC;gBACD,cAAc,EAAE,CAAC;YACnB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,QAAQ,CAAC,IAAI,CAAC,gCAAgC,KAAK,CAAC,UAAU,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACzH,CAAC;QACH,CAAC;QAED,iCAAiC;QACjC,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,MAAM,CAAC;QACrE,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;QAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,MAAM,CAAC;QAC7D,8DAA8D;QAC9D,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;QACjF,MAAM,MAAM,GAAgC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;QAErG,MAAM,MAAM,GAAmB;YAC7B,OAAO,EAAE;gBACP,cAAc,EAAE,mBAAmB;gBACnC,cAAc,EAAE,OAAO,CAAC,MAAM;gBAC9B,QAAQ;gBACR,KAAK;gBACL,IAAI;gBACJ,iBAAiB,EAAE,MAAM;aAC1B;YACD,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;gBAC7B,MAAM,SAAS,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;gBACrD,OAAO,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC/C,CAAC,CAAC;YACF,KAAK,EAAE;gBACL,OAAO;gBACP,WAAW;gBACX,QAAQ,EAAE,CAAC,CAAC,IAAI;gBAChB,aAAa,EAAE,cAAc,IAAI,EAAE;aACpC;YACD,QAAQ;SACT,CAAC;QAEF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/composites/explainError.js

@@ -14,8 +14,9 @@ export const explainError = defineTool({
     async handler(params, engine) {
         const { uri } = await engine.prepareFile(params.file_path);
         const timeout = DEFAULT_TIMEOUTS.composite;
-        // Wait for diagnostics
-        await new Promise((r) => setTimeout(r, 500));
+        // Wait for diagnostics (poll instead of fixed sleep)
+        const { waitForDiagnostics } = await import('../../engine/waitForDiagnostics.js');
+        await waitForDiagnostics(engine.docManager, uri, 800);
         const diags = engine.docManager.getCachedDiagnostics(uri);
         // Find diagnostic at or near the specified line
         const targetLine = params.line - 1; // 0-indexed

package/dist/tools/composites/explainError.js.map

@@ -1 +1 @@
-{"version":3,"file":"explainError.js","sourceRoot":"","sources":["../../../src/tools/composites/explainError.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"explainError.js","sourceRoot":"","sources":["../../../src/tools/composites/explainError.ts"],"names":[],"mappings":"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"}

package/dist/tools/composites/findCode.d.ts

@@ -0,0 +1 @@
+export declare const findCode: import("../registry.js").ToolDef;

package/dist/tools/composites/findCode.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { defineTool } from '../registry.js';
+import { resolveSearchScope } from '../../resolve/searchScope.js';
+import { parseQuery } from '../../search/query/parseQuery.js';
+import { planQuery } from '../../search/query/planQuery.js';
+import { getWorkspaceIndex } from '../../search/index/workspaceIndex.js';
+import { retrieveBehaviorCandidates } from '../../search/retrievers/behaviorRetriever.js';
+import { retrieveIdentifierCandidates } from '../../search/retrievers/identifierRetriever.js';
+import { retrieveStructuralCandidates } from '../../search/retrievers/structuralRetriever.js';
+import { mergeCandidates } from '../../search/ranking/mergeCandidates.js';
+import { rankCandidates } from '../../search/ranking/rankCandidates.js';
+import { assessConfidence } from '../../search/ranking/assessConfidence.js';
+export const findCode = defineTool({
+    name: 'find_code',
+    description: 'High-level code search: behavior discovery, identifier/API usage search, and structural queries. The agent does not need to choose the backend — the tool routes automatically based on the query.',
+    schema: z.object({
+        query: z.string().describe('Natural-language or code-oriented query'),
+        paths: z.array(z.string()).optional().describe('Directories/files to narrow search'),
+        max_results: z.number().default(10),
+        mode: z.enum(['auto', 'behavior', 'identifier', 'structural', 'mixed']).default('auto'),
+        family: z.enum(['auth', 'validation', 'fetching', 'errors', 'state', 'flags', 'retry', 'caching']).optional().describe('Optional family override'),
+        include_tests: z.boolean().default(false),
+    }),
+    async handler(params, engine) {
+        const startTime = Date.now();
+        const warnings = [];
+        const scope = resolveSearchScope(engine.workspaceRoot, params.paths, params.include_tests);
+        const ir = parseQuery(params.query, {
+            forcedMode: params.mode === 'auto' ? undefined : params.mode,
+            forcedFamily: params.family,
+        });
+        const plan = planQuery(ir);
+        const index = getWorkspaceIndex(scope);
+        const behavior = plan.retrievers.includes('behavior')
+            ? retrieveBehaviorCandidates(ir, scope, index)
+            : [];
+        const identifier = plan.retrievers.includes('identifier')
+            ? retrieveIdentifierCandidates(ir, scope, index)
+            : [];
+        const structural = plan.retrievers.includes('structural')
+            ? retrieveStructuralCandidates(ir, scope, index)
+            : [];
+        const merged = mergeCandidates({ behavior, identifier, structural });
+        const ranked = await rankCandidates(merged, { ir, plan, engine, scope });
+        const confidence = assessConfidence(ranked, ir, plan);
+        const topResults = ranked.slice(0, params.max_results);
+        const lspEnriched = ranked.filter((c) => c.sources.includes('lsp')).length;
+        const result = {
+            query: params.query,
+            ir,
+            plan,
+            confidence,
+            candidates: topResults,
+            stats: {
+                filesIndexed: index.files.size,
+                declarationHits: behavior.length,
+                usageHits: identifier.length,
+                structuralHits: structural.length,
+                lspEnriched,
+                elapsedMs: Date.now() - startTime,
+                partialResult: false,
+            },
+            warnings,
+        };
+        return result;
+    },
+});
+//# sourceMappingURL=findCode.js.map

package/dist/tools/composites/findCode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findCode.js","sourceRoot":"","sources":["../../../src/tools/composites/findCode.ts"],"names":[],"mappings":"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"}

package/dist/tools/composites/findPattern.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Thin wrapper over runPatternSearch().
+ * No duplicated file collection or parse loops.
+ */
+export declare const findPattern: import("../registry.js").ToolDef;

package/dist/tools/composites/findPattern.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { defineTool } from '../registry.js';
+import { resolveSearchScope } from '../../resolve/searchScope.js';
+import { runPatternSearch } from '../../analysis/pattern/runPatternSearch.js';
+/**
+ * Thin wrapper over runPatternSearch().
+ * No duplicated file collection or parse loops.
+ */
+export const findPattern = defineTool({
+    name: 'find_pattern',
+    description: 'Search for AST structural patterns across the codebase using ast-grep. Use $VAR for single node, $$$ for multiple nodes. Example: "useEffect($$$)" finds all useEffect calls.',
+    schema: z.object({
+        pattern: z.string().describe('ast-grep pattern. Use $VAR for single node, $$$ for any sequence.'),
+        language: z.enum(['typescript', 'tsx', 'javascript']).default('typescript'),
+        paths: z.array(z.string()).optional().describe('Limit search to specific directories (absolute paths)'),
+        max_results: z.number().default(50),
+        context_lines: z.number().default(1),
+        include_tests: z.boolean().default(true).describe('Include test/spec files in results'),
+    }),
+    async handler(params, engine) {
+        const scope = resolveSearchScope(engine.workspaceRoot, params.paths, params.include_tests);
+        const { filesScanned, matches, warnings } = runPatternSearch({
+            pattern: params.pattern,
+            language: params.language,
+            scope,
+            maxResults: params.max_results,
+            contextLines: params.context_lines,
+            workspaceRoot: engine.workspaceRoot,
+        });
+        const result = {
+            pattern: params.pattern,
+            language: params.language,
+            filesScanned,
+            matchCount: matches.length,
+            matches,
+            warnings,
+        };
+        return result;
+    },
+});
+//# sourceMappingURL=findPattern.js.map

package/dist/tools/composites/findPattern.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findPattern.js","sourceRoot":"","sources":["../../../src/tools/composites/findPattern.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAG9E;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;IACpC,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,+KAA+K;IACjL,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mEAAmE,CAAC;QACjG,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;QAC3E,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uDAAuD,CAAC;QACvG,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;QACpC,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,oCAAoC,CAAC;KACxF,CAAC;IACF,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM;QAC1B,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;QAE3F,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC;YAC3D,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,KAAK;YACL,UAAU,EAAE,MAAM,CAAC,WAAW;YAC9B,YAAY,EAAE,MAAM,CAAC,aAAa;YAClC,aAAa,EAAE,MAAM,CAAC,aAAa;SACpC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAsB;YAChC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,YAAY;YACZ,UAAU,EAAE,OAAO,CAAC,MAAM;YAC1B,OAAO;YACP,QAAQ;SACT,CAAC;QAEF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/composites/rootCauseTrace.d.ts

@@ -0,0 +1 @@
+export declare const rootCauseTrace: import("../registry.js").ToolDef;

package/dist/tools/composites/rootCauseTrace.js

@@ -0,0 +1,213 @@
+import { z } from 'zod';
+import * as fs from 'fs';
+import { defineTool } from '../registry.js';
+import { relativePath, uriToPath, pathToUri, fromPosition } from '../../engine/positions.js';
+import { formatHover } from '../../format/markdown.js';
+import { parseFile, parseSource } from '../../ast/parseFile.js';
+import { classifyErrorSite } from '../../ast/findNodeAtPosition.js';
+import { extractExportDeclarations } from '../../ast/extractExportDeclarations.js';
+import { diffExportDeclarations } from '../../ast/diffDeclarationShapes.js';
+import { getMergeBase } from '../../git/getMergeBase.js';
+import { getBaseFileContent } from '../../git/getBaseFileContent.js';
+import { fileChangedInBranch } from '../../git/getChangedHunks.js';
+import { resolveTarget, pickDiagnostic } from '../../resolve/targetResolver.js';
+import { DEFAULT_TIMEOUTS } from '../../engine/types.js';
+export const rootCauseTrace = defineTool({
+    name: 'root_cause_trace',
+    description: 'Trace the root cause of a TypeScript error. Accepts symbol name, file+line, or file+diagnostic_code. Identifies the originating declaration change with evidence chain.',
+    schema: z.object({
+        symbol: z.string().optional().describe('Symbol at or near the error site'),
+        file_path: z.string().optional().describe('File containing the error'),
+        line: z.number().optional().describe('1-indexed line number'),
+        diagnostic_code: z.string().optional().describe('Diagnostic code, e.g. TS2345'),
+        base: z.string().optional().describe('Git base ref'),
+    }),
+    async handler(params, engine) {
+        const timeout = DEFAULT_TIMEOUTS.composite;
+        const warnings = [];
+        let astUsed = false;
+        // Step 1: Resolve target via shared resolver (symbol-first)
+        let target;
+        try {
+            target = await resolveTarget(params, engine);
+        }
+        catch (err) {
+            return { errorSite: {}, candidates: [], stats: { candidatesConsidered: 0, callerFilesChecked: 0, astUsed: false, baseUsed: false, partialResult: false }, warnings: [`Target resolution failed: ${err instanceof Error ? err.message : String(err)}`] };
+        }
+        const { filePath, uri, position: targetPosition, symbol: symbolName } = target;
+        // Step 2: Anchor the diagnostic (poll for readiness instead of fixed sleep)
+        const { waitForDiagnostics } = await import('../../engine/waitForDiagnostics.js');
+        await waitForDiagnostics(engine.docManager, uri, 800);
+        const allDiags = engine.docManager.getCachedDiagnostics(uri);
+        const targetDiag = pickDiagnostic(allDiags, targetPosition, params.diagnostic_code);
+        if (!targetDiag) {
+            return { errorSite: { symbol: symbolName }, candidates: [], stats: { candidatesConsidered: 0, callerFilesChecked: 0, astUsed: false, baseUsed: false, partialResult: false }, warnings: [`No error diagnostic in ${relativePath(filePath, engine.workspaceRoot)}`] };
+        }
+        const base = engine.gitAvailable ? getMergeBase(engine.workspaceRoot, params.base) : undefined;
+        const errorPosition = targetDiag.range.start;
+        const diagPos = fromPosition(errorPosition);
+        // Step 3: Error site — LSP + AST (with proper error handling)
+        const [hoverResult, defResult] = await Promise.all([
+            engine.request('textDocument/hover', { textDocument: { uri }, position: errorPosition }, timeout)
+                .catch((err) => { warnings.push(`Hover failed: ${err instanceof Error ? err.message : String(err)}`); return null; }),
+            engine.request('textDocument/definition', { textDocument: { uri }, position: errorPosition }, timeout)
+                .catch((err) => { warnings.push(`Definition lookup failed: ${err instanceof Error ? err.message : String(err)}`); return null; }),
+        ]);
+        let localPattern = null;
+        try {
+            const root = parseFile(filePath);
+            if (root) {
+                astUsed = true;
+                localPattern = classifyErrorSite(root, errorPosition.line);
+            }
+        }
+        catch (err) {
+            warnings.push(`AST classification failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const hoverSummary = hoverResult ? formatHover(hoverResult).substring(0, 200) : undefined;
+        const defLocation = defResult ? uriToPath(Array.isArray(defResult) ? defResult[0].uri : defResult.uri) : undefined;
+        const errorSite = {
+            symbol: symbolName,
+            definitionFile: defLocation ? relativePath(defLocation, engine.workspaceRoot) : undefined,
+            enclosingNodeKind: localPattern ?? undefined,
+            localPattern: localPattern ?? undefined,
+            hoverSummary,
+        };
+        // Step 4: Collect candidates
+        const candidates = [];
+        // Candidate A: definition site
+        if (defLocation && defLocation !== filePath) {
+            candidates.push(await buildCandidate(defLocation, 'definition-site', 5, base, engine, warnings));
+        }
+        // Candidate B: type definition
+        try {
+            const typeDef = await engine.request('textDocument/typeDefinition', { textDocument: { uri }, position: errorPosition }, timeout);
+            if (typeDef) {
+                const typeDefPath = uriToPath(Array.isArray(typeDef) ? typeDef[0].uri : typeDef.uri);
+                if (typeDefPath !== filePath && typeDefPath !== defLocation) {
+                    candidates.push(await buildCandidate(typeDefPath, 'type-definition', 4, base, engine, warnings));
+                }
+            }
+        }
+        catch (err) {
+            warnings.push(`Type definition lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Candidate C: upstream callers (cap at 5)
+        let callerFilesChecked = 0;
+        try {
+            const items = await engine.request('textDocument/prepareCallHierarchy', { textDocument: { uri }, position: errorPosition }, timeout);
+            if (items?.length) {
+                const incomingCalls = await engine.request('callHierarchy/incomingCalls', { item: items[0] }, timeout);
+                for (const call of (incomingCalls ?? []).slice(0, 5)) {
+                    const callerPath = uriToPath(call.from.uri);
+                    if (callerPath === filePath)
+                        continue;
+                    try {
+                        const changed = base ? fileChangedInBranch(callerPath, base, engine.workspaceRoot) : false;
+                        await engine.prepareFile(callerPath);
+                        await waitForDiagnostics(engine.docManager, pathToUri(callerPath), 500);
+                        const callerDiags = engine.docManager.getCachedDiagnostics(pathToUri(callerPath)).filter((d) => d.severity === 1).length;
+                        let score = 2;
+                        const evidence = [`upstream-caller: ${relativePath(callerPath, engine.workspaceRoot)}`];
+                        if (changed) {
+                            score += 6;
+                            evidence.push('changed-in-branch');
+                        }
+                        if (callerDiags > 0) {
+                            score += 3;
+                            evidence.push(`caller-has-errors: ${callerDiags}`);
+                        }
+                        candidates.push({
+                            symbol: call.from.name, filePath: callerPath,
+                            reason: changed ? `Upstream caller changed${callerDiags ? ` (${callerDiags} errors)` : ''}` : `Upstream caller${callerDiags ? ` with ${callerDiags} errors` : ''}`,
+                            confidence: changed && callerDiags > 0 ? 'high' : 'low',
+                            score, evidence, changedInBranch: changed, diagnosticsNearby: callerDiags,
+                        });
+                    }
+                    catch (err) {
+                        warnings.push(`Caller analysis failed for ${call.from.name}: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    callerFilesChecked++;
+                }
+            }
+        }
+        catch (err) {
+            warnings.push(`Call hierarchy failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Step 5: Rank + impact
+        const sorted = candidates.sort((a, b) => b.score - a.score);
+        const topCandidate = sorted[0];
+        if (topCandidate) {
+            try {
+                if (topCandidate.symbol) {
+                    const resolved = await engine.resolveSymbol(topCandidate.symbol, topCandidate.filePath);
+                    const refs = await engine.request('textDocument/references', { textDocument: { uri: resolved.uri }, position: resolved.position, context: { includeDeclaration: false } }, timeout);
+                    if (refs)
+                        topCandidate.impactSummary = { affectedFiles: new Set(refs.map((r) => uriToPath(r.uri))).size };
+                }
+            }
+            catch (err) {
+                warnings.push(`Impact analysis failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (localPattern === 'unhandled_enum_member')
+                topCandidate.suggestedFix = 'Add a case for the new enum member';
+            else if (localPattern === 'bad_call_argument')
+                topCandidate.suggestedFix = 'Check function signature — a parameter type may have changed';
+            else if (localPattern === 'missing_property_access')
+                topCandidate.suggestedFix = 'A property may have been removed or renamed';
+            else if (localPattern === 'incompatible_assignment')
+                topCandidate.suggestedFix = 'Source type may have changed — check the definition';
+        }
+        return {
+            diagnostic: { code: targetDiag.code ? `TS${targetDiag.code}` : undefined, message: targetDiag.message, filePath, line: diagPos.line },
+            errorSite,
+            candidates: sorted,
+            topCandidate,
+            nextVerificationStep: topCandidate ? `Run impact_trace on ${relativePath(topCandidate.filePath, engine.workspaceRoot)}` : undefined,
+            stats: { candidatesConsidered: candidates.length, callerFilesChecked, astUsed, baseUsed: !!base, partialResult: callerFilesChecked >= 5 },
+            warnings,
+        };
+    },
+});
+async function buildCandidate(candidatePath, source, baseScore, base, engine, warnings) {
+    const changed = base ? fileChangedInBranch(candidatePath, base, engine.workspaceRoot) : false;
+    let score = baseScore;
+    const evidence = [`${source}: ${relativePath(candidatePath, engine.workspaceRoot)}`];
+    let structuralChange;
+    if (changed) {
+        score += 8;
+        evidence.push('changed-in-branch');
+        if (base) {
+            try {
+                const sc = classifyDeclarationChange(candidatePath, base, engine.workspaceRoot);
+                if (sc) {
+                    score += 5;
+                    evidence.push(`structural-change: ${sc}`);
+                    structuralChange = sc;
+                }
+            }
+            catch (err) {
+                warnings.push(`Structural classification failed for ${relativePath(candidatePath, engine.workspaceRoot)}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    return {
+        filePath: candidatePath,
+        reason: changed ? `${source} changed in this branch` : `${source} — trace upstream`,
+        confidence: changed ? 'high' : source === 'definition-site' ? 'medium' : 'low',
+        score, evidence, changedInBranch: changed, structuralChange,
+    };
+}
+function classifyDeclarationChange(filePath, base, workspaceRoot) {
+    const baseContent = getBaseFileContent(filePath, base, workspaceRoot);
+    if (!baseContent)
+        return null;
+    const currentContent = fs.readFileSync(filePath, 'utf-8');
+    const baseRoot = parseSource(baseContent, filePath.endsWith('.tsx'));
+    const currentRoot = parseSource(currentContent, filePath.endsWith('.tsx'));
+    const baseExports = extractExportDeclarations(baseRoot, baseContent);
+    const currentExports = extractExportDeclarations(currentRoot, currentContent);
+    const diffs = diffExportDeclarations(baseExports, currentExports);
+    return diffs.length > 0 ? diffs.map((d) => `${d.kind}: ${d.name}`).join(', ') : null;
+}
+//# sourceMappingURL=rootCauseTrace.js.map