ast-mcp-server 0.6.0 → 0.7.1

package/dist/services/symbols.js

@@ -1,9 +1,19 @@
 import path from "node:path";
-import { Node, } from "ts-morph";
-import { buildFileOutline } from "./outline.js";
-export function sourceFileSymbols(sourceFile, projectRoot) {
+import { Node, ts } from "ts-morph";
+import { buildFileOutline, declarationSignature } from "./outline.js";
+import { isCooperativeInterruption, NO_REQUEST_CONTEXT, } from "./request-context.js";
+import { MAX_SYMBOL_INDEX_QUERY_CANDIDATES } from "./symbol-index-limits.js";
+import { compareSymbolIndexText } from "./symbol-index-order.js";
+class IndexedProjectionMismatchError extends Error {
+    code = "corrupt_storage";
+    constructor(message) {
+        super(message);
+        this.name = "IndexedProjectionMismatchError";
+    }
+}
+export function sourceFileSymbols(sourceFile, projectRoot, requestContext = NO_REQUEST_CONTEXT) {
     const file = path.relative(projectRoot, sourceFile.getFilePath());
-    const signatures = new Map(buildFileOutline(sourceFile).symbols.map((symbol) => [
+    const signatures = new Map(buildFileOutline(sourceFile, requestContext).symbols.map((symbol) => [
         `${symbol.symbolPath}@${symbol.startLine}`,
         symbol.signature,
     ]));
@@ -17,6 +27,36 @@ export function sourceFileSymbols(sourceFile, projectRoot) {
         signature: signatures.get(`${symbol.symbolPath}@${symbol.line}`) ?? symbol.node.getText(),
     }));
 }
+export function sourceFileIndexSymbols(sourceFile, projectRoot) {
+    const outlineSignatures = new Map(buildFileOutline(sourceFile).symbols.map((symbol) => [
+        `${symbol.symbolPath}@${symbol.startLine}`,
+        symbol.signature,
+    ]));
+    const locatedSymbols = new Map(collectSymbols(sourceFile).map((symbol) => [`${symbol.symbolPath}@${symbol.line}`, symbol]));
+    return sourceFileSymbols(sourceFile, projectRoot).map((symbol) => {
+        const located = locatedSymbols.get(symbol.selector);
+        if (!located) {
+            throw new Error(`Unable to locate indexed symbol ${symbol.selector}.`);
+        }
+        const start = sourceFile.getLineAndColumnAtPos(located.node.getStart());
+        const end = sourceFile.getLineAndColumnAtPos(Math.max(located.node.getStart(), located.node.getEnd() - 1));
+        const range = {
+            start_line: start.line,
+            start_column: start.column,
+            end_line: end.line,
+            end_column: end.column,
+        };
+        return {
+            name: symbol.name,
+            symbol_path: symbol.symbol_path,
+            selector: symbol.selector,
+            kind: symbol.kind,
+            signature: outlineSignatures.get(symbol.selector) ?? `${symbol.kind} ${symbol.name};`,
+            line: symbol.line,
+            range,
+        };
+    });
+}
 export function symbolMatchRank(query, symbol) {
     const normalizedQuery = query.toLowerCase();
     const normalizedPath = symbol.symbolPath.toLowerCase();
@@ -33,46 +73,236 @@ export function symbolMatchRank(query, symbol) {
     }
     return 4;
 }
-export function searchProjectSymbols(project, projectRoot, options) {
+export function searchProjectSymbols(project, projectRoot, options, requestContext = NO_REQUEST_CONTEXT) {
+    return searchProjectSymbolsPage(project, projectRoot, options, 0, MAX_SYMBOL_INDEX_QUERY_CANDIDATES, requestContext).items;
+}
+function candidateOrder(left, right) {
+    return (left.rank - right.rank ||
+        compareSymbolIndexText(left.file, right.file) ||
+        left.symbol.line - right.symbol.line ||
+        left.symbolPosition - right.symbolPosition);
+}
+function assertSearchPage(offset, limit) {
+    if (!Number.isSafeInteger(offset) || offset < 0) {
+        throw new Error("Symbol search offset must be a non-negative safe integer.");
+    }
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_SYMBOL_INDEX_QUERY_CANDIDATES) {
+        throw new Error(`Symbol search limit must be an integer from 1 to ${MAX_SYMBOL_INDEX_QUERY_CANDIDATES}.`);
+    }
+}
+export function searchProjectSymbolsPage(project, projectRoot, options, offset, limit, requestContext = NO_REQUEST_CONTEXT) {
+    assertSearchPage(offset, limit);
     const normalizedQuery = options.query.toLowerCase();
     const normalizedFileFilter = options.fileFilter?.toLowerCase();
     const kindSet = options.kinds ? new Set(options.kinds) : undefined;
-    const matches = [];
-    for (const sourceFile of project.getSourceFiles()) {
-        const file = path.relative(projectRoot, sourceFile.getFilePath());
+    const sourceFiles = project
+        .getSourceFiles()
+        .map((sourceFile) => ({
+        sourceFile,
+        file: path.relative(projectRoot, sourceFile.getFilePath()).replaceAll("\\", "/"),
+    }))
+        .sort((left, right) => compareSymbolIndexText(left.file, right.file));
+    const rankCounts = [0, 0, 0, 0, 0];
+    for (const { sourceFile, file } of sourceFiles) {
+        requestContext.checkpoint();
         if (normalizedFileFilter && !file.toLowerCase().includes(normalizedFileFilter))
             continue;
-        const matchingSymbols = sourceFileSymbols(sourceFile, projectRoot).filter((symbol) => {
-            return ((!kindSet || kindSet.has(symbol.kind)) &&
+        forEachLocatedSymbol(sourceFile, (symbol) => {
+            requestContext.checkpoint();
+            const selector = `${symbol.symbolPath}@${symbol.line}`;
+            if ((!kindSet || kindSet.has(symbol.kind)) &&
                 (symbol.name.toLowerCase().includes(normalizedQuery) ||
-                    symbol.symbol_path.toLowerCase().includes(normalizedQuery) ||
-                    symbol.selector.toLowerCase().includes(normalizedQuery)));
+                    symbol.symbolPath.toLowerCase().includes(normalizedQuery) ||
+                    selector.toLowerCase().includes(normalizedQuery))) {
+                rankCounts[symbolMatchRank(options.query, symbol)] += 1;
+            }
         });
-        if (matchingSymbols.length === 0)
-            continue;
-        for (const symbol of matchingSymbols) {
-            matches.push(symbol);
+    }
+    const total = rankCounts.reduce((sum, count) => sum + count, 0);
+    const rankSkips = [0, 0, 0, 0, 0];
+    const rankTakes = [0, 0, 0, 0, 0];
+    let rankOffset = 0;
+    for (let rank = 0; rank < rankCounts.length; rank += 1) {
+        const rankEnd = rankOffset + rankCounts[rank];
+        const pageStart = Math.max(offset, rankOffset);
+        const pageEnd = Math.min(offset + limit, rankEnd);
+        if (pageStart < pageEnd) {
+            rankSkips[rank] = pageStart - rankOffset;
+            rankTakes[rank] = pageEnd - pageStart;
         }
+        rankOffset = rankEnd;
     }
-    matches.sort((left, right) => {
-        const rank = symbolMatchRank(options.query, {
-            symbolPath: left.symbol_path,
-            name: left.name,
-            line: left.line,
-        }) -
-            symbolMatchRank(options.query, {
-                symbolPath: right.symbol_path,
-                name: right.name,
-                line: right.line,
+    const seenByRank = [0, 0, 0, 0, 0];
+    const selectedByRank = [[], [], [], [], []];
+    for (const { sourceFile, file } of sourceFiles) {
+        requestContext.checkpoint();
+        if (normalizedFileFilter && !file.toLowerCase().includes(normalizedFileFilter))
+            continue;
+        let symbolPosition = 0;
+        forEachLocatedSymbol(sourceFile, (symbol) => {
+            requestContext.checkpoint();
+            const selector = `${symbol.symbolPath}@${symbol.line}`;
+            const currentSymbolPosition = symbolPosition;
+            symbolPosition += 1;
+            if ((kindSet && !kindSet.has(symbol.kind)) ||
+                (!symbol.name.toLowerCase().includes(normalizedQuery) &&
+                    !symbol.symbolPath.toLowerCase().includes(normalizedQuery) &&
+                    !selector.toLowerCase().includes(normalizedQuery))) {
+                return;
+            }
+            const rank = symbolMatchRank(options.query, symbol);
+            const position = seenByRank[rank];
+            seenByRank[rank] += 1;
+            if (position < rankSkips[rank] || selectedByRank[rank].length >= rankTakes[rank]) {
+                return;
+            }
+            selectedByRank[rank].push({
+                file,
+                selector,
+                symbol,
+                rank,
+                symbolPosition: currentSymbolPosition,
             });
-        if (rank !== 0)
-            return rank;
-        return (left.file.localeCompare(right.file) ||
-            left.line - right.line ||
-            left.symbol_path.localeCompare(right.symbol_path) ||
-            left.kind.localeCompare(right.kind));
+        });
+    }
+    requestContext.checkpoint();
+    const pageCandidates = selectedByRank.flat().sort(candidateOrder);
+    const items = pageCandidates.map((match) => {
+        requestContext.checkpoint();
+        return {
+            file: match.file,
+            symbol_path: match.symbol.symbolPath,
+            selector: match.selector,
+            name: match.symbol.name,
+            kind: match.symbol.kind,
+            line: match.symbol.line,
+            signature: declarationSignature(match.symbol.node, requestContext),
+        };
     });
-    return matches;
+    const nextOffset = offset + items.length;
+    const hasMore = nextOffset < total;
+    return {
+        items,
+        offset,
+        limit,
+        total,
+        has_more: hasMore,
+        next_offset: hasMore ? nextOffset : null,
+    };
+}
+export async function searchProjectSymbolsWithIndex(project, projectRoot, projectIdentity, symbolIndex, symbolIndexReady, options, onIndexFailure, requestContext = NO_REQUEST_CONTEXT) {
+    const page = await searchProjectSymbolsPageWithIndex(project, projectRoot, projectIdentity, symbolIndex, symbolIndexReady, options, 0, MAX_SYMBOL_INDEX_QUERY_CANDIDATES, onIndexFailure, requestContext);
+    return page?.items;
+}
+function sameSymbolRecord(left, right) {
+    return (left.file === right.file &&
+        left.symbol_path === right.symbol_path &&
+        left.selector === right.selector &&
+        left.name === right.name &&
+        left.kind === right.kind &&
+        left.line === right.line &&
+        left.signature === right.signature);
+}
+export async function searchProjectSymbolsPageWithIndex(project, projectRoot, projectIdentity, symbolIndex, symbolIndexReady, options, offset, limit, onIndexFailure, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    if (!symbolIndexReady)
+        return undefined;
+    const canonical = searchProjectSymbolsPage(project, projectRoot, options, offset, limit, requestContext);
+    try {
+        requestContext.checkpoint();
+        const indexQuery = {
+            project: projectIdentity,
+            query: options.query,
+            filters: {
+                ...(options.kinds ? { kinds: options.kinds } : {}),
+                ...(options.fileFilter ? { file_path: options.fileFilter } : {}),
+            },
+        };
+        const indexedTotal = await symbolIndex.countSymbols(indexQuery);
+        requestContext.checkpoint();
+        let complete = indexedTotal === canonical.total;
+        if (complete) {
+            const matches = await symbolIndex.querySymbols({ ...indexQuery, offset, limit });
+            requestContext.checkpoint();
+            const indexedPage = matches.map((match) => {
+                requestContext.checkpoint();
+                return validateIndexedSymbol(project, projectRoot, match, requestContext);
+            });
+            complete =
+                indexedPage.length === canonical.items.length &&
+                    indexedPage.every((record, index) => sameSymbolRecord(record, canonical.items[index]));
+        }
+        if (!complete) {
+            requestContext.checkpoint();
+            try {
+                await onIndexFailure?.("corrupt_storage");
+            }
+            catch (error) {
+                if (isCooperativeInterruption(error))
+                    throw error;
+                // Failure reporting cannot suppress the compiler-authoritative result.
+            }
+            requestContext.checkpoint();
+            return canonical;
+        }
+        return canonical;
+    }
+    catch (error) {
+        requestContext.checkpoint();
+        if (isCooperativeInterruption(error))
+            throw error;
+        if (error.code !== "scan_limit_exceeded") {
+            try {
+                await onIndexFailure?.(typeof error?.code === "string"
+                    ? error.code
+                    : "sqlite_read_failed");
+            }
+            catch (reportError) {
+                if (isCooperativeInterruption(reportError))
+                    throw reportError;
+                // Failure reporting cannot suppress the compiler-authoritative result.
+            }
+        }
+        requestContext.checkpoint();
+        return canonical;
+    }
+}
+function validateIndexedSymbol(project, projectRoot, match, requestContext) {
+    const sourceFile = project.getSourceFile(path.resolve(projectRoot, match.file_path));
+    if (!sourceFile) {
+        throw new IndexedProjectionMismatchError(`Indexed source file "${match.file_path}" was not found in the compiler project.`);
+    }
+    const expectedFile = path.relative(projectRoot, sourceFile.getFilePath()).replaceAll("\\", "/");
+    if (expectedFile !== match.file_path.replaceAll("\\", "/")) {
+        throw new IndexedProjectionMismatchError(`Indexed source file "${match.file_path}" resolved ambiguously.`);
+    }
+    const located = findLocatedSymbol(sourceFile, match.selector);
+    if (!located) {
+        throw new IndexedProjectionMismatchError(`Indexed symbol "${match.selector}" does not exist in the compiler project.`);
+    }
+    const node = located.node;
+    if (node.getStartLineNumber() !== match.line || node.getKindName() !== match.kind) {
+        throw new IndexedProjectionMismatchError(`Indexed symbol "${match.selector}" does not match the compiler declaration.`);
+    }
+    const canonicalName = namedNode(node);
+    const canonicalSymbolPath = located.symbolPath;
+    const canonicalSignature = declarationSignature(node, requestContext);
+    if (!canonicalName ||
+        canonicalSymbolPath !== match.symbol_path ||
+        canonicalName !== match.name ||
+        canonicalSignature !== match.signature ||
+        node.getStartLineNumber() !== match.range.start_line) {
+        throw new IndexedProjectionMismatchError(`Indexed symbol "${match.selector}" does not match canonical compiler metadata.`);
+    }
+    return {
+        file: expectedFile,
+        symbol_path: canonicalSymbolPath,
+        selector: match.selector,
+        name: canonicalName,
+        kind: node.getKindName(),
+        line: node.getStartLineNumber(),
+        signature: canonicalSignature,
+    };
 }
 function namedNode(node) {
     if (Node.isConstructorDeclaration(node))
@@ -94,82 +324,176 @@ function namedNode(node) {
     }
     return undefined;
 }
-function addLocated(node, symbolPath, output) {
+function locatedSymbol(node, symbolPath) {
     const name = namedNode(node);
     if (!name)
-        return;
-    output.push({
+        return undefined;
+    return {
         node,
         symbolPath,
         name,
         kind: node.getKindName(),
         line: node.getStartLineNumber(),
-    });
+    };
 }
-function collectClassLike(node, prefix, output) {
+function visitClassLike(node, prefix, visit) {
     if (!Node.isClassDeclaration(node) && !Node.isInterfaceDeclaration(node))
-        return;
-    for (const member of node.getMembers()) {
+        return true;
+    let complete = true;
+    node.forEachChild((member) => {
         const name = namedNode(member);
-        if (name)
-            addLocated(member, `${prefix}.${name}`, output);
-    }
+        const located = name ? locatedSymbol(member, `${prefix}.${name}`) : undefined;
+        if (located && visit(located) === false) {
+            complete = false;
+            return true;
+        }
+        return undefined;
+    });
+    return complete;
 }
-function moduleStatements(module) {
+function visitModuleStatements(module, prefix, visit) {
     let body = module.getBody();
     while (body && Node.isModuleDeclaration(body))
         body = body.getBody();
-    return body && Node.isModuleBlock(body) ? body.getStatements() : [];
+    return !body || !Node.isModuleBlock(body) || visitChildStatements(body, prefix, visit);
 }
-function collectStatements(statements, prefix, output) {
-    for (const statement of statements) {
-        if (Node.isVariableStatement(statement)) {
-            for (const declaration of statement.getDeclarations()) {
+function visitStatement(statement, prefix, visit) {
+    if (Node.isVariableStatement(statement)) {
+        let complete = true;
+        statement.getDeclarationList().forEachChild((declaration) => {
+            if (Node.isVariableDeclaration(declaration)) {
                 const path = prefix ? `${prefix}.${declaration.getName()}` : declaration.getName();
-                addLocated(declaration, path, output);
+                const located = locatedSymbol(declaration, path);
+                if (located && visit(located) === false) {
+                    complete = false;
+                    return true;
+                }
             }
-            continue;
-        }
-        const name = namedNode(statement);
-        if (!name)
-            continue;
-        const symbolPath = prefix ? `${prefix}.${name}` : name;
-        addLocated(statement, symbolPath, output);
-        collectClassLike(statement, symbolPath, output);
-        if (Node.isModuleDeclaration(statement)) {
-            collectStatements(moduleStatements(statement), symbolPath, output);
-        }
+            return undefined;
+        });
+        return complete;
     }
+    const name = namedNode(statement);
+    if (!name)
+        return true;
+    const symbolPath = prefix ? `${prefix}.${name}` : name;
+    const located = locatedSymbol(statement, symbolPath);
+    if (located && visit(located) === false)
+        return false;
+    if (!visitClassLike(statement, symbolPath, visit))
+        return false;
+    if (Node.isModuleDeclaration(statement)) {
+        return visitModuleStatements(statement, symbolPath, visit);
+    }
+    return true;
+}
+function visitChildStatements(container, prefix, visit) {
+    let complete = true;
+    container.forEachChild((statement) => {
+        if (!visitStatement(statement, prefix, visit)) {
+            complete = false;
+            return true;
+        }
+        return undefined;
+    });
+    return complete;
+}
+export function forEachLocatedSymbol(sourceFile, visit) {
+    visitChildStatements(sourceFile, undefined, visit);
 }
 export function collectSymbols(sourceFile) {
     const symbols = [];
-    collectStatements(sourceFile.getStatements(), undefined, symbols);
+    forEachLocatedSymbol(sourceFile, (symbol) => {
+        symbols.push(symbol);
+    });
     return symbols;
 }
+export function containingSymbol(sourceFile, node) {
+    return collectSymbols(sourceFile)
+        .filter((symbol) => symbol.node.getStart() <= node.getStart() && symbol.node.getEnd() >= node.getEnd())
+        .sort((left, right) => {
+        const leftSize = left.node.getEnd() - left.node.getStart();
+        const rightSize = right.node.getEnd() - right.node.getStart();
+        return (leftSize - rightSize ||
+            left.line - right.line ||
+            left.symbolPath.localeCompare(right.symbolPath));
+    })[0];
+}
 function parseSelector(symbolPath) {
     const match = /^(.*)@(\d+)$/.exec(symbolPath);
     return match ? { path: match[1], line: Number(match[2]) } : { path: symbolPath };
 }
-export function findDeclaration(sourceFile, requestedPath) {
-    const selector = parseSelector(requestedPath);
-    let matches = collectSymbols(sourceFile).filter((symbol) => symbol.symbolPath === selector.path && (!selector.line || symbol.line === selector.line));
-    if (matches.length > 1) {
-        const implementations = matches.filter((symbol) => {
-            const node = symbol.node;
-            return ((Node.isFunctionDeclaration(node) || Node.isMethodDeclaration(node)) &&
-                node.getBody() !== undefined);
-        });
-        if (implementations.length === 1)
-            matches = implementations;
+export function findLocatedSymbol(sourceFile, requestedSelector, onVisit = () => undefined) {
+    const selector = parseSelector(requestedSelector);
+    if (selector.line === undefined) {
+        throw new Error("Located-symbol resolution requires an exact selector with a line number.");
     }
-    if (matches.length === 1)
-        return matches[0].node;
-    if (matches.length === 0) {
+    let match;
+    forEachLocatedSymbol(sourceFile, (symbol) => {
+        onVisit(symbol);
+        if (symbol.symbolPath !== selector.path || symbol.line !== selector.line)
+            return;
+        match = symbol;
+        return false;
+    });
+    return match;
+}
+export function findLocatedDeclaration(sourceFile, requestedPath, onVisit = () => undefined) {
+    const selector = parseSelector(requestedPath);
+    let match;
+    forEachLocatedSymbol(sourceFile, (symbol) => {
+        onVisit(symbol);
+        if (symbol.symbolPath !== selector.path)
+            return;
+        if (selector.line !== undefined && symbol.line !== selector.line)
+            return;
+        match = symbol;
+        return false;
+    });
+    if (!match) {
         throw new Error(`Symbol "${requestedPath}" was not found in ${sourceFile.getFilePath()}. Use ast_get_outline or ast_search_symbols to obtain an exact symbol path.`);
     }
-    throw new Error(`Symbol "${requestedPath}" is ambiguous. Select one by line: ${matches
-        .map((symbol) => `${symbol.symbolPath}@${symbol.line}`)
-        .join(", ")}.`);
+    if (selector.line !== undefined)
+        return match;
+    const compilerDeclarations = match.node.getSymbol()?.compilerSymbol.declarations;
+    if (!compilerDeclarations)
+        return match;
+    let declarationsInFile = 0;
+    let implementationNode;
+    let implementationCount = 0;
+    const selectors = [];
+    for (const declaration of compilerDeclarations) {
+        if (declaration.getSourceFile() !== sourceFile.compilerNode)
+            continue;
+        declarationsInFile += 1;
+        if (selectors.length < 20) {
+            const line = sourceFile.compilerNode.getLineAndCharacterOfPosition(declaration.getStart()).line + 1;
+            selectors.push(`${match.symbolPath}@${line}`);
+        }
+        if ((ts.isFunctionDeclaration(declaration) || ts.isMethodDeclaration(declaration)) &&
+            declaration.body) {
+            implementationNode = declaration;
+            implementationCount += 1;
+        }
+    }
+    if (declarationsInFile <= 1)
+        return match;
+    if (implementationCount === 1) {
+        let implementation;
+        forEachLocatedSymbol(sourceFile, (symbol) => {
+            onVisit(symbol);
+            if (symbol.node.compilerNode !== implementationNode)
+                return;
+            implementation = symbol;
+            return false;
+        });
+        if (implementation)
+            return implementation;
+    }
+    throw new Error(`Symbol "${requestedPath}" is ambiguous. Select one by line: ${selectors.join(", ")}${declarationsInFile > selectors.length ? ", ..." : ""}.`);
+}
+export function findDeclaration(sourceFile, requestedPath) {
+    return findLocatedDeclaration(sourceFile, requestedPath).node;
 }
 export function executableDeclaration(node) {
     if (Node.isFunctionDeclaration(node) ||