@alex-dbs/coderuler 1.4.0 → 1.6.0

package/dist/adapter/lsp/backend.js

@@ -0,0 +1,826 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse } from '@ast-grep/napi';
+import { ApplyWorkspaceEditRequest, CallHierarchyIncomingCallsRequest, CallHierarchyOutgoingCallsRequest, CallHierarchyPrepareRequest, DeclarationRequest, DefinitionRequest, DidOpenTextDocumentNotification, DocumentSymbolRequest, ExitNotification, HoverRequest, ImplementationRequest, InitializeRequest, InitializedNotification, MessageType, ReferencesRequest, ShowMessageNotification, ShowMessageRequest, ShutdownRequest, SymbolKind, TypeDefinitionRequest, WorkDoneProgress, WorkDoneProgressCreateRequest, WorkspaceSymbolRequest, } from 'vscode-languageserver-protocol';
+import { createProtocolConnection } from 'vscode-languageserver-protocol/node';
+import { resolveAstGrepLanguage } from '../scope/astgrep-languages.js';
+import { textLineSpan } from '../scope/lines.js';
+const DEFAULT_OPTIONS = {
+    command: 'gopls',
+    args: ['serve'],
+    languageId: 'go',
+};
+const MAX_STDERR_BYTES = 8 * 1024;
+const SHUTDOWN_GRACE_MS = 2_000;
+const AST_DECLARATION_KINDS = {
+    function_declaration: true,
+    method_declaration: true,
+    var_declaration: true,
+    const_declaration: true,
+    type_declaration: true,
+};
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function createTextIndex(text) {
+    const lineStarts = [0];
+    const lineEnds = [];
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        if (code === 10 || code === 13) {
+            lineEnds.push(index);
+            if (code === 13 && text.charCodeAt(index + 1) === 10)
+                index += 1;
+            lineStarts.push(index + 1);
+        }
+    }
+    lineEnds.push(text.length);
+    const offset = (position) => {
+        if (!Number.isSafeInteger(position.line) || position.line < 0 || position.line >= lineStarts.length) {
+            throw new Error(`LSP position line ${position.line + 1} is outside the document`);
+        }
+        if (!Number.isSafeInteger(position.character) || position.character < 0) {
+            throw new Error('LSP position character must be a nonnegative safe integer');
+        }
+        const start = lineStarts[position.line];
+        const end = lineEnds[position.line];
+        if (position.character > end - start) {
+            throw new Error(`LSP position column ${position.character + 1} is outside line ${position.line + 1}`);
+        }
+        return start + position.character;
+    };
+    return {
+        lineStarts,
+        lineEnds,
+        lineCount: lineStarts.length,
+        position(line, column) {
+            if (!Number.isSafeInteger(line) || line < 1) {
+                throw new Error('LSP line must be a positive safe integer');
+            }
+            if (!Number.isSafeInteger(column) || column < 1) {
+                throw new Error('LSP column must be a positive safe integer');
+            }
+            const zeroLine = line - 1;
+            if (zeroLine >= lineStarts.length)
+                throw new Error(`LSP line ${line} is outside the document`);
+            const character = column - 1;
+            if (character > lineEnds[zeroLine] - lineStarts[zeroLine]) {
+                throw new Error(`LSP column ${column} is outside line ${line}`);
+            }
+            return { line: zeroLine, character };
+        },
+        offset,
+    };
+}
+function isWithinRoot(root, filepath) {
+    const relativePath = relative(root, filepath);
+    if (relativePath === '')
+        return true;
+    const firstSegment = relativePath.split(sep)[0];
+    return firstSegment !== '..' && !isAbsolute(relativePath);
+}
+function comparePosition(left, right) {
+    return left.line - right.line || left.character - right.character;
+}
+function compareRanges(left, right) {
+    return comparePosition(left.start, right.start) || comparePosition(left.end, right.end);
+}
+function rangeContains(outer, inner) {
+    return comparePosition(outer.start, inner.start) <= 0 && comparePosition(outer.end, inner.end) >= 0;
+}
+function rangeStrictlyContains(outer, inner) {
+    return rangeContains(outer, inner) && compareRanges(outer, inner) !== 0;
+}
+function sameRange(left, right) {
+    return compareRanges(left, right) === 0;
+}
+function normalizeLocations(result) {
+    if (result === null || result === undefined)
+        return [];
+    const values = Array.isArray(result) ? result : [result];
+    const normalized = [];
+    for (const value of values) {
+        if (typeof value !== 'object' || value === null)
+            continue;
+        if ('targetUri' in value && 'targetSelectionRange' in value) {
+            const link = value;
+            normalized.push({ uri: link.targetUri, range: link.targetSelectionRange });
+        }
+        else if ('uri' in value && 'range' in value) {
+            normalized.push(value);
+        }
+    }
+    return normalized;
+}
+function isDocumentSymbol(value) {
+    return 'selectionRange' in value;
+}
+function flattenSymbols(symbols) {
+    const declarations = [];
+    const visit = (symbol) => {
+        declarations.push({
+            name: symbol.name,
+            kind: symbol.kind,
+            range: symbol.range,
+            selectionRange: symbol.selectionRange,
+            hasFullRange: true,
+        });
+        for (const child of symbol.children ?? [])
+            visit(child);
+    };
+    for (const symbol of symbols) {
+        if (isDocumentSymbol(symbol))
+            visit(symbol);
+        else
+            declarations.push({
+                name: symbol.name,
+                kind: symbol.kind,
+                range: symbol.location.range,
+                selectionRange: symbol.location.range,
+                hasFullRange: false,
+            });
+    }
+    return declarations;
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function createError(message, cause) {
+    return cause === undefined ? new Error(message) : new Error(message, { cause });
+}
+export async function createLspBackend(project, signal, options) {
+    const settings = options ?? DEFAULT_OPTIONS;
+    const timeoutMs = settings.requestTimeoutMs ?? 60_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+        throw new Error('LSP requestTimeoutMs must be a positive safe integer');
+    }
+    if (signal.aborted)
+        throw createError('LSP startup was aborted', signal.reason);
+    const root = resolve(project.root);
+    const rootUri = pathToFileURL(root).href;
+    const workspaceFolder = { uri: rootUri, name: basename(root) };
+    const usesProcessGroup = settings.languageId === 'ruby' && process.platform !== 'win32';
+    const child = spawn(settings.command, [...(settings.args ?? [])], {
+        cwd: root,
+        env: settings.env,
+        shell: process.platform === 'win32' && settings.languageId === 'typescript',
+        detached: usesProcessGroup,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stderr = Buffer.alloc(0);
+    let terminalError;
+    let initialized = false;
+    let closing = false;
+    let processClosed = false;
+    let releasePromise;
+    let closePromise;
+    let connection;
+    let capabilities;
+    let rubyPositionNeedsSurrogateAdjustment = false;
+    const controller = new AbortController();
+    const documentPromises = new Map();
+    const symbolPromises = new Map();
+    const astPromises = new Map();
+    const { promise: processClosedPromise, resolve: resolveProcessClosed } = Promise.withResolvers();
+    const progressToken = settings.initializationProgressToken;
+    const readiness = progressToken === undefined ? undefined : Promise.withResolvers();
+    let readinessPending = readiness !== undefined;
+    const stderrText = () => stderr.toString('utf8').trim();
+    const withStderr = (error) => {
+        const message = describe(error);
+        const detail = stderrText();
+        return createError(detail === '' ? message : `${message}\nLSP stderr (latest ${MAX_STDERR_BYTES} bytes):\n${detail}`, error);
+    };
+    const closedError = () => terminalError ?? new Error('LSP session is closed');
+    const signalChild = (signalName) => {
+        if (usesProcessGroup) {
+            const pid = child.pid;
+            if (pid === undefined)
+                return;
+            try {
+                process.kill(-pid, signalName);
+            }
+            catch (error) {
+                if (error?.code !== 'ESRCH')
+                    throw error;
+            }
+            return;
+        }
+        child.kill(signalName);
+    };
+    const cleanup = (graceful) => {
+        if (releasePromise !== undefined)
+            return releasePromise;
+        releasePromise = (async () => {
+            if (graceful && initialized && !processClosed && connection !== undefined) {
+                const shutdown = (async () => {
+                    try {
+                        await connection.sendRequest(ShutdownRequest.type);
+                        await connection.sendNotification(ExitNotification.type);
+                    }
+                    catch {
+                        // A bounded process release below handles failed shutdown handshakes.
+                    }
+                })();
+                void shutdown.catch(() => undefined);
+            }
+            else if (!processClosed) {
+                signalChild('SIGTERM');
+            }
+            if (!processClosed) {
+                const { promise: expired, resolve: resolveExpired } = Promise.withResolvers();
+                const releaseTimer = setTimeout(() => resolveExpired('timeout'), SHUTDOWN_GRACE_MS);
+                const closed = processClosedPromise.then(() => 'closed');
+                const result = await Promise.race([closed, expired]);
+                clearTimeout(releaseTimer);
+                if (result === 'timeout' && !processClosed)
+                    signalChild('SIGKILL');
+                if (!processClosed)
+                    await processClosedPromise;
+            }
+            connection?.dispose();
+            signal.removeEventListener('abort', onRunAbort);
+            child.removeAllListeners('error');
+            child.removeAllListeners('close');
+            child.stderr?.removeAllListeners('data');
+        })();
+        return releasePromise;
+    };
+    const fail = (error) => {
+        if (terminalError !== undefined || closing)
+            return;
+        terminalError = withStderr(error);
+        controller.abort(terminalError);
+        void cleanup(false).catch(() => undefined);
+    };
+    const onRunAbort = () => {
+        if (!closing)
+            fail(createError('LSP session was aborted', signal.reason));
+    };
+    signal.addEventListener('abort', onRunAbort, { once: true });
+    if (signal.aborted)
+        onRunAbort();
+    child.stderr?.on('data', (chunk) => {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        stderr = Buffer.concat([stderr, bytes]).subarray(-MAX_STDERR_BYTES);
+    });
+    child.once('error', (error) => {
+        fail(createError(`LSP process '${settings.command}' failed: ${describe(error)}`, error));
+    });
+    child.once('close', (code, processSignal) => {
+        processClosed = true;
+        resolveProcessClosed();
+        if (!closing && terminalError === undefined) {
+            fail(createError(`LSP process exited unexpectedly (code ${String(code)}, signal ${String(processSignal)})`));
+        }
+    });
+    const bounded = (method, operation) => {
+        if (terminalError !== undefined || closing || controller.signal.aborted) {
+            return Promise.reject(closedError());
+        }
+        let abortListener;
+        const { promise: aborted, reject: rejectAbort } = Promise.withResolvers();
+        abortListener = () => rejectAbort(closedError());
+        controller.signal.addEventListener('abort', abortListener, { once: true });
+        let operationPromise;
+        try {
+            operationPromise = operation();
+        }
+        catch (error) {
+            operationPromise = Promise.reject(error);
+        }
+        const { promise: timeout, reject: rejectTimeout } = Promise.withResolvers();
+        const timer = setTimeout(() => {
+            const error = createError(`LSP request ${method} timed out after ${timeoutMs}ms`);
+            rejectTimeout(error);
+            fail(error);
+        }, timeoutMs);
+        return Promise.race([operationPromise, aborted, timeout]).finally(() => {
+            clearTimeout(timer);
+            if (abortListener !== undefined)
+                controller.signal.removeEventListener('abort', abortListener);
+        });
+    };
+    const ensureAvailable = () => {
+        if (terminalError !== undefined || closing || controller.signal.aborted)
+            throw closedError();
+        if (connection === undefined)
+            throw new Error('LSP connection is not initialized');
+    };
+    const assertCapability = (method, capability) => {
+        ensureAvailable();
+        if (capabilities?.[capability] === undefined || capabilities[capability] === false) {
+            throw new Error(`LSP server does not support ${method}`);
+        }
+    };
+    const request = (type, method, params, capability) => {
+        ensureAvailable();
+        if (capability !== undefined)
+            assertCapability(method, capability);
+        return bounded(method, () => connection.sendRequest(type, params));
+    };
+    const notify = (method, operation) => {
+        ensureAvailable();
+        return bounded(method, operation);
+    };
+    try {
+        connection = createProtocolConnection(child.stdout, child.stdin);
+        connection.onError((details) => {
+            const [error, message, code] = details;
+            fail(createError(`LSP transport failed${message !== undefined && 'method' in message ? ` for ${message.method}` : ''}${code === undefined ? '' : ` (${code})`}: ${describe(error)}`, error));
+        });
+        connection.onClose(() => {
+            if (!closing && terminalError === undefined)
+                fail(new Error('LSP transport closed unexpectedly'));
+        });
+        connection.onRequest(ApplyWorkspaceEditRequest.type, () => ({
+            applied: false,
+            failureReason: 'Read-only LSP session',
+        }));
+        connection.onRequest(ShowMessageRequest.type, () => null);
+        if (readiness !== undefined && progressToken !== undefined) {
+            connection.onProgress(WorkDoneProgress.type, progressToken, progress => {
+                if (progress.kind !== 'end')
+                    return;
+                readinessPending = false;
+                readiness.resolve();
+            });
+            connection.onRequest(WorkDoneProgressCreateRequest.type, () => undefined);
+            connection.onNotification(ShowMessageNotification.type, ({ type, message }) => {
+                if (readinessPending &&
+                    type === MessageType.Error &&
+                    message.startsWith('Error while indexing ('))
+                    fail(new Error(message));
+            });
+        }
+        connection.listen();
+        const initializeResult = await bounded('initialize', () => connection.sendRequest(InitializeRequest.type, {
+            processId: process.pid,
+            rootUri,
+            capabilities: {
+                general: { positionEncodings: ['utf-16'] },
+                textDocument: { documentSymbol: { hierarchicalDocumentSymbolSupport: true } },
+                ...(readiness === undefined ? {} : { window: { workDoneProgress: true } }),
+            },
+            workspaceFolders: [workspaceFolder],
+        }));
+        capabilities = initializeResult.capabilities;
+        // Ruby LSP 0.26.11 counts a preceding surrogate pair as one cursor unit.
+        rubyPositionNeedsSurrogateAdjustment =
+            settings.languageId === 'ruby' &&
+                initializeResult.serverInfo?.name === 'Ruby LSP' &&
+                initializeResult.serverInfo.version === '0.26.11';
+        await notify('initialized', () => connection.sendNotification(InitializedNotification.type, {}));
+        initialized = true;
+        if (readiness !== undefined)
+            await bounded('$/progress', () => readiness.promise);
+    }
+    catch (error) {
+        fail(error);
+        await cleanup(false).catch(() => undefined);
+        throw terminalError ?? withStderr(error);
+    }
+    const canonicalPathFromUri = (uri) => {
+        let filepath;
+        try {
+            const parsed = new URL(uri);
+            if (parsed.protocol !== 'file:')
+                throw new Error(`Unsupported LSP source URI scheme '${parsed.protocol}'`);
+            filepath = fileURLToPath(parsed);
+        }
+        catch (error) {
+            throw createError(`Invalid LSP file URI '${uri}': ${describe(error)}`, error);
+        }
+        return resolve(filepath);
+    };
+    const isAllowedUri = (uri, includeDependencies) => {
+        let parsed;
+        try {
+            parsed = new URL(uri);
+        }
+        catch (error) {
+            throw createError(`Invalid LSP URI '${uri}': ${describe(error)}`, error);
+        }
+        if (parsed.protocol !== 'file:')
+            return includeDependencies;
+        return includeDependencies || isWithinRoot(root, canonicalPathFromUri(uri));
+    };
+    const documentForPath = (filepath, includeDependencies) => {
+        const absolute = resolve(root, filepath);
+        const relativePath = isWithinRoot(root, absolute) ? relative(root, absolute) : undefined;
+        if (relativePath === undefined && !includeDependencies) {
+            return Promise.reject(new Error(`LSP source is outside the project: ${filepath}`));
+        }
+        const uri = pathToFileURL(absolute).href;
+        const cached = documentPromises.get(uri);
+        if (cached !== undefined)
+            return cached;
+        const pending = (async () => {
+            let text;
+            if (relativePath !== undefined)
+                text = await project.readText(relativePath);
+            else {
+                const data = await readFile(absolute);
+                try {
+                    text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(data);
+                }
+                catch (error) {
+                    throw createError(`LSP source '${absolute}' is not valid UTF-8`, error);
+                }
+            }
+            const document = {
+                uri,
+                text,
+                index: createTextIndex(text),
+            };
+            await notify('textDocument/didOpen', () => connection.sendNotification(DidOpenTextDocumentNotification.type, {
+                textDocument: {
+                    uri,
+                    languageId: settings.languageId === 'typescript' && extname(absolute) === '.tsx'
+                        ? 'typescriptreact'
+                        : settings.languageId,
+                    version: 1,
+                    text,
+                },
+            }));
+            return document;
+        })();
+        documentPromises.set(uri, pending);
+        return pending;
+    };
+    const documentForUri = (uri, includeDependencies) => {
+        if (!isAllowedUri(uri, includeDependencies)) {
+            return Promise.reject(new Error(`LSP source is outside the project: ${uri}`));
+        }
+        if (!uri.startsWith('file:')) {
+            return Promise.reject(new Error(`LSP source URI is not a file URI: ${uri}`));
+        }
+        return documentForPath(canonicalPathFromUri(uri), includeDependencies);
+    };
+    const positionForTarget = (document, line, column) => {
+        const position = document.index.position(line, column);
+        if (!rubyPositionNeedsSurrogateAdjustment)
+            return position;
+        const start = document.index.lineStarts[position.line];
+        const end = start + position.character;
+        let surrogatePairs = 0;
+        for (let index = start; index + 1 < end; index += 1) {
+            const code = document.text.charCodeAt(index);
+            const next = document.text.charCodeAt(index + 1);
+            if (code >= 0xd800 && code <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) {
+                surrogatePairs += 1;
+                index += 1;
+            }
+        }
+        if (surrogatePairs === 0)
+            return position;
+        const character = position.character + surrogatePairs;
+        const lineLength = document.index.lineEnds[position.line] - start;
+        return character > lineLength ? position : { ...position, character };
+    };
+    const filterLocations = (result, includeDependencies) => normalizeLocations(result).filter(location => isAllowedUri(location.uri, includeDependencies));
+    const symbolQuery = async (document, includeDependencies) => {
+        assertCapability('textDocument/documentSymbol', 'documentSymbolProvider');
+        let pending = symbolPromises.get(document.uri);
+        if (pending === undefined) {
+            pending = request(DocumentSymbolRequest.type, 'textDocument/documentSymbol', {
+                textDocument: { uri: document.uri },
+            }, 'documentSymbolProvider').then(result => result ?? []);
+            symbolPromises.set(document.uri, pending);
+        }
+        const symbols = await pending;
+        if (symbols.every(isDocumentSymbol))
+            return symbols;
+        return symbols.filter(symbol => isAllowedUri(symbol.location.uri, includeDependencies));
+    };
+    const astFor = (document) => {
+        let pending = astPromises.get(document.uri);
+        if (pending === undefined) {
+            pending = Promise.resolve().then(() => parse(resolveAstGrepLanguage('go'), document.text));
+            astPromises.set(document.uri, pending);
+        }
+        return pending;
+    };
+    const astNodeRange = (node) => {
+        const native = node.range();
+        return {
+            start: { line: native.start.line, character: native.start.column },
+            end: { line: native.end.line, character: native.end.column },
+        };
+    };
+    const rangeOffsets = (document, range) => {
+        const start = document.index.offset(range.start);
+        const end = document.index.offset(range.end);
+        if (end < start)
+            throw new Error('LSP source range ends before it starts');
+        return { start, end };
+    };
+    const declarationFromRange = (document, range) => {
+        const { start, end } = rangeOffsets(document, range);
+        const source = document.text.slice(start, end);
+        if (source.length === 0)
+            throw new Error('LSP declaration range is empty');
+        return { source, lines: textLineSpan(range.start.line + 1, source) };
+    };
+    const bestSymbolRange = (document, declarations, selectionRange) => {
+        const completeDeclarations = declarations.filter(symbol => symbol.hasFullRange);
+        const exact = completeDeclarations.filter(symbol => sameRange(symbol.selectionRange, selectionRange));
+        const matching = exact.length > 0
+            ? exact
+            : completeDeclarations.filter(symbol => rangeContains(symbol.selectionRange, selectionRange));
+        return matching
+            .map(symbol => {
+            const offsets = rangeOffsets(document, symbol.range);
+            return { range: symbol.range, length: offsets.end - offsets.start };
+        })
+            .sort((left, right) => left.length - right.length || compareRanges(left.range, right.range))[0]?.range;
+    };
+    const astDeclarationRange = async (document, selectionRange) => {
+        const rootNode = (await astFor(document)).root();
+        const selectionStart = selectionRange.start;
+        const selectionEnd = selectionRange.end;
+        let best;
+        const pendingNodes = [rootNode];
+        while (pendingNodes.length > 0) {
+            const node = pendingNodes.pop();
+            for (const child of node.children())
+                pendingNodes.push(child);
+            if (AST_DECLARATION_KINDS[String(node.kind())] !== true)
+                continue;
+            const range = astNodeRange(node);
+            if (!rangeContains(range, { start: selectionStart, end: selectionEnd }))
+                continue;
+            const offsets = rangeOffsets(document, range);
+            const length = offsets.end - offsets.start;
+            if (best === undefined || length < best.length)
+                best = { node, range, length };
+        }
+        if (best === undefined)
+            return undefined;
+        const range = astNodeRange(best.node);
+        const native = best.node.range();
+        return { range, source: best.node.text(), startLine: native.start.line + 1 };
+    };
+    const declarationSource = async (item, includeDependencies) => {
+        const document = await documentForUri(item.uri, includeDependencies);
+        if (settings.languageId === 'go' && item.kind === SymbolKind.Variable) {
+            const astDeclaration = await astDeclarationRange(document, item.selectionRange);
+            if (astDeclaration !== undefined) {
+                return {
+                    source: astDeclaration.source,
+                    lines: textLineSpan(astDeclaration.startLine, astDeclaration.source),
+                    range: astDeclaration.range,
+                };
+            }
+        }
+        const documentSymbolProvider = capabilities?.documentSymbolProvider;
+        if (documentSymbolProvider !== undefined && documentSymbolProvider !== false) {
+            const symbols = await symbolQuery(document, includeDependencies);
+            const declarations = flattenSymbols(symbols);
+            const symbolRange = bestSymbolRange(document, declarations, item.selectionRange);
+            if (symbolRange !== undefined) {
+                return { ...declarationFromRange(document, symbolRange), range: symbolRange };
+            }
+        }
+        if (rangeStrictlyContains(item.range, item.selectionRange)) {
+            return { ...declarationFromRange(document, item.range), range: item.range };
+        }
+        if (settings.languageId === 'go') {
+            const astDeclaration = await astDeclarationRange(document, item.selectionRange);
+            if (astDeclaration !== undefined) {
+                return {
+                    source: astDeclaration.source,
+                    lines: textLineSpan(astDeclaration.startLine, astDeclaration.source),
+                    range: astDeclaration.range,
+                };
+            }
+        }
+        throw new Error(`Could not find the full declaration for LSP call hierarchy item '${item.name}' at ${item.uri}`);
+    };
+    const itemIdentity = (item) => {
+        const filepath = canonicalPathFromUri(item.uri);
+        const selection = item.selectionRange;
+        return `${filepath}\0${selection.start.line}:${selection.start.character}-${selection.end.line}:${selection.end.character}`;
+    };
+    const itemPath = (item) => {
+        const filepath = canonicalPathFromUri(item.uri);
+        const relativePath = relative(root, filepath);
+        return isWithinRoot(root, filepath) ? relativePath : filepath;
+    };
+    const symbolsForTarget = async (document, targetLine, includeDependencies) => {
+        const symbols = flattenSymbols(await symbolQuery(document, includeDependencies));
+        const line = targetLine - 1;
+        const sortCandidates = (candidates) => [...candidates].sort((left, right) => {
+            const leftRange = rangeOffsets(document, left.range);
+            const rightRange = rangeOffsets(document, right.range);
+            const leftSize = leftRange.end - leftRange.start;
+            const rightSize = rightRange.end - rightRange.start;
+            return leftSize - rightSize ||
+                comparePosition(left.selectionRange.start, right.selectionRange.start) ||
+                left.kind - right.kind ||
+                compareText(left.name, right.name);
+        });
+        const candidates = symbols.filter(symbol => (settings.languageId !== 'go' || symbol.hasFullRange) &&
+            (symbol.kind === SymbolKind.Function || symbol.kind === SymbolKind.Method) &&
+            symbol.name.trim() !== '' &&
+            symbol.range.start.line <= line &&
+            symbol.range.end.line >= line);
+        if (candidates.length > 0 || settings.languageId !== 'go') {
+            return sortCandidates(candidates);
+        }
+        const pendingNodes = [(await astFor(document)).root()];
+        const astCandidates = [];
+        while (pendingNodes.length > 0) {
+            const node = pendingNodes.pop();
+            for (const child of node.children())
+                pendingNodes.push(child);
+            const nodeKind = String(node.kind());
+            if (nodeKind !== 'function_declaration' &&
+                nodeKind !== 'method_declaration' &&
+                nodeKind !== 'method_elem')
+                continue;
+            const range = astNodeRange(node);
+            if (range.start.line > line || range.end.line < line)
+                continue;
+            const nameNode = node.field('name');
+            if (nameNode === null)
+                continue;
+            const name = nameNode.text();
+            if (name.trim() === '')
+                continue;
+            astCandidates.push({
+                name,
+                kind: nodeKind === 'function_declaration' ? SymbolKind.Function : SymbolKind.Method,
+                range,
+                selectionRange: astNodeRange(nameNode),
+                hasFullRange: true,
+            });
+        }
+        return sortCandidates(astCandidates);
+    };
+    const prepareRoots = async (target, includeDependencies) => {
+        assertCapability('textDocument/prepareCallHierarchy', 'callHierarchyProvider');
+        const document = await documentForPath(target.filepath, includeDependencies);
+        let position;
+        if (target.column !== undefined)
+            position = positionForTarget(document, target.line, target.column);
+        else {
+            if (!Number.isSafeInteger(target.line) || target.line < 1 || target.line > document.index.lineCount) {
+                throw new Error(`LSP line ${target.line} is outside the document`);
+            }
+            const candidates = await symbolsForTarget(document, target.line, includeDependencies);
+            if (candidates.length === 0)
+                return [];
+            position = candidates[0].selectionRange.start;
+        }
+        const prepared = await request(CallHierarchyPrepareRequest.type, 'textDocument/prepareCallHierarchy', {
+            textDocument: { uri: document.uri },
+            position,
+        }, 'callHierarchyProvider');
+        return prepared ?? [];
+    };
+    const traverse = async (target, options, direction) => {
+        if (!Number.isSafeInteger(options.depth) || options.depth < 0) {
+            throw new Error('LSP call depth must be a nonnegative safe integer');
+        }
+        if (options.depth === 0)
+            return [];
+        const includeDependencies = options.includeDependencies === true;
+        const roots = await prepareRoots(target, includeDependencies);
+        if (roots.length === 0)
+            return [];
+        const permittedRoots = roots.filter(item => isAllowedUri(item.uri, includeDependencies));
+        const rootIdentities = new Set(permittedRoots.map(itemIdentity));
+        const accepted = new Map();
+        const expanded = new Set();
+        const queue = [];
+        for (const item of permittedRoots) {
+            const identity = itemIdentity(item);
+            if (!expanded.has(identity)) {
+                expanded.add(identity);
+                queue.push({ item, depth: 0 });
+            }
+        }
+        for (let cursor = 0; cursor < queue.length; cursor += 1) {
+            const current = queue[cursor];
+            if (current.depth >= options.depth)
+                continue;
+            const response = direction === 'callers'
+                ? (await request(CallHierarchyIncomingCallsRequest.type, 'callHierarchy/incomingCalls', { item: current.item }, 'callHierarchyProvider')) ?? []
+                : (await request(CallHierarchyOutgoingCallsRequest.type, 'callHierarchy/outgoingCalls', { item: current.item }, 'callHierarchyProvider')) ?? [];
+            for (const edge of response) {
+                const item = direction === 'callers'
+                    ? edge.from
+                    : edge.to;
+                if (!isAllowedUri(item.uri, includeDependencies))
+                    continue;
+                const identity = itemIdentity(item);
+                const depth = current.depth + 1;
+                if (!rootIdentities.has(identity)) {
+                    const previous = accepted.get(identity);
+                    if (previous === undefined || depth < previous.depth)
+                        accepted.set(identity, { item, depth });
+                }
+                if (!expanded.has(identity)) {
+                    expanded.add(identity);
+                    queue.push({ item, depth });
+                }
+            }
+        }
+        const results = [];
+        for (const node of accepted.values()) {
+            const declaration = await declarationSource(node.item, includeDependencies);
+            results.push({
+                call: {
+                    name: node.item.name,
+                    filepath: itemPath(node.item),
+                    source: declaration.source,
+                    lines: declaration.lines,
+                    depth: node.depth,
+                },
+                declarationPosition: declaration.range.start,
+            });
+        }
+        results.sort((left, right) => left.call.depth - right.call.depth ||
+            compareText(left.call.filepath, right.call.filepath) ||
+            comparePosition(left.declarationPosition, right.declarationPosition) ||
+            compareText(left.call.name, right.call.name));
+        return results.map(result => result.call);
+    };
+    const navigate = async (method, capability, type, target, options) => {
+        const includeDependencies = options?.includeDependencies === true;
+        const document = await documentForPath(target.filepath, includeDependencies);
+        const position = positionForTarget(document, target.line, target.column ?? 1);
+        const result = await request(type, method, {
+            textDocument: { uri: document.uri },
+            position,
+        }, capability);
+        return filterLocations(result, includeDependencies);
+    };
+    const tools = {
+        definitions: (target, options) => navigate('textDocument/definition', 'definitionProvider', DefinitionRequest.type, target, options),
+        declarations: (target, options) => navigate('textDocument/declaration', 'declarationProvider', DeclarationRequest.type, target, options),
+        typeDefinitions: (target, options) => navigate('textDocument/typeDefinition', 'typeDefinitionProvider', TypeDefinitionRequest.type, target, options),
+        implementations: (target, options) => navigate('textDocument/implementation', 'implementationProvider', ImplementationRequest.type, target, options),
+        references: async (target, options) => {
+            const includeDependencies = options?.includeDependencies === true;
+            const document = await documentForPath(target.filepath, includeDependencies);
+            const position = positionForTarget(document, target.line, target.column ?? 1);
+            const result = await request(ReferencesRequest.type, 'textDocument/references', {
+                textDocument: { uri: document.uri },
+                position,
+                context: { includeDeclaration: options?.includeDeclaration ?? false },
+            }, 'referencesProvider');
+            return filterLocations(result, includeDependencies);
+        },
+        hover: async (target, options) => {
+            const includeDependencies = options?.includeDependencies === true;
+            const document = await documentForPath(target.filepath, includeDependencies);
+            const position = positionForTarget(document, target.line, target.column ?? 1);
+            const result = await request(HoverRequest.type, 'textDocument/hover', {
+                textDocument: { uri: document.uri },
+                position,
+            }, 'hoverProvider');
+            return result ?? null;
+        },
+        documentSymbols: async (filepath, options) => {
+            const document = await documentForPath(filepath, options?.includeDependencies === true);
+            return symbolQuery(document, options?.includeDependencies === true);
+        },
+        workspaceSymbols: async (query, options) => {
+            if (query.length === 0)
+                return [];
+            const result = await request(WorkspaceSymbolRequest.type, 'workspace/symbol', { query }, 'workspaceSymbolProvider');
+            const includeDependencies = options?.includeDependencies === true;
+            return (result ?? []).filter(symbol => isAllowedUri(symbol.location.uri, includeDependencies));
+        },
+        callers: (target, options) => traverse(target, options, 'callers'),
+        callees: (target, options) => traverse(target, options, 'callees'),
+    };
+    const close = () => {
+        if (closePromise !== undefined)
+            return closePromise;
+        closing = true;
+        controller.abort(new Error('LSP session is closed'));
+        closePromise = cleanup(initialized && terminalError === undefined);
+        return closePromise;
+    };
+    return { ...tools, close };
+}
+export function createRubyLspBackend(project, signal) {
+    return createLspBackend(project, signal, {
+        command: 'ruby-lsp',
+        args: [],
+        languageId: 'ruby',
+        initializationProgressToken: 'indexing-progress',
+    });
+}
+export function createTypescriptLspBackend(project, signal) {
+    return createLspBackend(project, signal, {
+        command: 'tsc',
+        args: ['--lsp', '--stdio'],
+        languageId: 'typescript',
+    });
+}