@adecore/lsp 0.0.1 → 0.17.0-beta.2

package/src/connection.ts

@@ -0,0 +1,310 @@
+import type { Disposable, LspTransport, RequestId, RequestOptions, RpcMessage, RpcRequest } from './protocol.ts';
+
+/* The JSON-RPC and LSP codes this package answers with. */
+export const ErrorCodes = {
+    InvalidRequest: -32600,
+    MethodNotFound: -32601,
+    InternalError: -32603,
+    ServerNotInitialized: -32002,
+    RequestCancelled: -32800,
+    ContentModified: -32801
+} as const;
+
+export class LspError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+
+    constructor(message: string, code: number = ErrorCodes.InternalError, data?: unknown) {
+        super(message);
+        this.name = 'LspError';
+        this.code = code;
+        this.data = data;
+    }
+}
+
+/* The document changed or closed before the answer arrived, so the answer describes a text that is gone. */
+export class StaleResultError extends LspError {
+    readonly uri: string;
+
+    constructor(uri: string) {
+        super(`The document changed before its language result arrived: ${uri}`, ErrorCodes.ContentModified);
+        this.name = 'StaleResultError';
+        this.uri = uri;
+    }
+}
+
+export type RequestHandler = (params: unknown, signal: AbortSignal) => unknown | Promise<unknown>;
+type NotificationHandler = (params: unknown) => void | Promise<void>;
+
+interface PendingRequest {
+    resolve(value: unknown): void;
+    reject(error: unknown): void;
+    cleanup(): void;
+}
+
+function asError(error: unknown): Error {
+    return error instanceof Error ? error : new Error(String(error));
+}
+
+/* JSON-RPC 2.0 over an `LspTransport`: correlation, cancellation, and the requests a server sends back. */
+export class JsonRpcConnection {
+    readonly transport: LspTransport;
+    readonly timeoutMs: number;
+    private nextId = 0;
+    private closed = false;
+    private sendQueue: Promise<void> = Promise.resolve();
+    private readonly pending = new Map<RequestId, PendingRequest>();
+    private readonly incoming = new Map<RequestId, AbortController>();
+    private readonly handlers = new Map<string, RequestHandler>();
+    private readonly notifications = new Map<string, Set<NotificationHandler>>();
+    private readonly errors = new Set<(error: Error) => void>();
+    private readonly closes = new Set<(error?: Error) => void>();
+    private readonly subscriptions: Disposable[];
+
+    /* A `timeoutMs` of 0 turns the deadline off; a request then ends by its reply or its signal. */
+    constructor(transport: LspTransport, timeoutMs = 30_000) {
+        this.transport = transport;
+        this.timeoutMs = timeoutMs;
+        this.subscriptions = [
+            transport.onMessage((message) => {
+                void this.receive(message).catch((error) => this.reportError(error));
+            }),
+            transport.onClose((error) => this.finish(error))
+        ];
+    }
+
+    get isClosed(): boolean {
+        return this.closed;
+    }
+
+    request<T = unknown>(method: string, params?: unknown, options: RequestOptions = {}): Promise<T> {
+        if (this.closed) {
+            return Promise.reject(new LspError('LSP connection is closed'));
+        }
+        if (options.signal?.aborted) {
+            return Promise.reject(new LspError('Request cancelled', ErrorCodes.RequestCancelled));
+        }
+        const id = ++this.nextId;
+        return new Promise<T>((resolve, reject) => {
+            let timer: ReturnType<typeof setTimeout> | undefined;
+            const cancel = (error: LspError): void => {
+                if (!this.pending.has(id)) {
+                    return;
+                }
+                this.settle(id, undefined, error);
+                void this.notify('$/cancelRequest', { id }).catch((failure) => this.reportError(failure));
+            };
+            const abort = (): void => cancel(new LspError('Request cancelled', ErrorCodes.RequestCancelled));
+            this.pending.set(id, {
+                resolve: (value) => resolve(value as T),
+                reject,
+                cleanup: () => {
+                    clearTimeout(timer);
+                    options.signal?.removeEventListener('abort', abort);
+                }
+            });
+            options.signal?.addEventListener('abort', abort, { once: true });
+            const timeout = options.timeoutMs ?? this.timeoutMs;
+            if (timeout > 0) {
+                timer = setTimeout(() => cancel(new LspError(`LSP request timed out: ${method}`, ErrorCodes.RequestCancelled)), timeout);
+            }
+            void this.send({ jsonrpc: '2.0', id, method, params }).catch((error) => this.settle(id, undefined, error));
+        });
+    }
+
+    notify(method: string, params?: unknown): Promise<void> {
+        return this.send({ jsonrpc: '2.0', method, params });
+    }
+
+    onRequest(method: string, handler: RequestHandler): Disposable {
+        if (this.handlers.has(method)) {
+            throw new Error(`LSP request handler already registered: ${method}`);
+        }
+        this.handlers.set(method, handler);
+        return {
+            dispose: () => {
+                if (this.handlers.get(method) === handler) {
+                    this.handlers.delete(method);
+                }
+            }
+        };
+    }
+
+    onNotification(method: string, listener: NotificationHandler): Disposable {
+        let listeners = this.notifications.get(method);
+        if (!listeners) {
+            listeners = new Set();
+            this.notifications.set(method, listeners);
+        }
+        const registered = listeners;
+        registered.add(listener);
+        return {
+            dispose: () => {
+                registered.delete(listener);
+                if (registered.size === 0) {
+                    this.notifications.delete(method);
+                }
+            }
+        };
+    }
+
+    onError(listener: (error: Error) => void): Disposable {
+        this.errors.add(listener);
+        return {
+            dispose: () => {
+                this.errors.delete(listener);
+            }
+        };
+    }
+
+    onClose(listener: (error?: Error) => void): Disposable {
+        this.closes.add(listener);
+        if (this.closed) {
+            listener();
+        }
+        return {
+            dispose: () => {
+                this.closes.delete(listener);
+            }
+        };
+    }
+
+    reportError(error: unknown): void {
+        const normalized = asError(error);
+        for (const listener of this.errors) {
+            try {
+                listener(normalized);
+            } catch {
+                // An error observer must not break protocol dispatch.
+            }
+        }
+    }
+
+    async close(): Promise<void> {
+        this.finish();
+        await this.transport.close();
+    }
+
+    private send(message: RpcMessage): Promise<void> {
+        const sent = this.sendQueue.then(async () => {
+            if (this.closed) {
+                throw new LspError('LSP connection is closed');
+            }
+            await this.transport.send(message);
+        });
+        this.sendQueue = sent.catch((error) => this.finish(asError(error)));
+        return sent;
+    }
+
+    private settle(id: RequestId, result?: unknown, error?: unknown): void {
+        const request = this.pending.get(id);
+        if (!request) {
+            return;
+        }
+        this.pending.delete(id);
+        request.cleanup();
+        if (error !== undefined) {
+            request.reject(error);
+        } else {
+            request.resolve(result);
+        }
+    }
+
+    private async receive(value: unknown): Promise<void> {
+        if (this.closed) {
+            return;
+        }
+        if (!value || typeof value !== 'object' || !('jsonrpc' in value) || value.jsonrpc !== '2.0') {
+            throw new LspError('Invalid JSON-RPC message', ErrorCodes.InvalidRequest);
+        }
+        const message = value as RpcMessage;
+        if ('method' in message) {
+            if (typeof message.method !== 'string') {
+                throw new LspError('Invalid JSON-RPC method', ErrorCodes.InvalidRequest);
+            }
+            if ('id' in message) {
+                if (typeof message.id !== 'number' && typeof message.id !== 'string') {
+                    throw new LspError('Invalid request id', ErrorCodes.InvalidRequest);
+                }
+                await this.handleRequest(message);
+            } else if (message.method === '$/cancelRequest') {
+                const id = (message.params as { id?: RequestId } | undefined)?.id;
+                if (id !== undefined) {
+                    this.incoming.get(id)?.abort();
+                }
+            } else {
+                for (const listener of this.notifications.get(message.method) ?? []) {
+                    try {
+                        await listener(message.params);
+                    } catch (error) {
+                        this.reportError(error);
+                    }
+                }
+            }
+        } else if ('id' in message && message.id !== null) {
+            if (message.error) {
+                this.settle(message.id, undefined, new LspError(message.error.message, message.error.code, message.error.data));
+            } else if ('result' in message) {
+                this.settle(message.id, message.result);
+            } else {
+                this.settle(message.id, undefined, new LspError('Invalid JSON-RPC response', ErrorCodes.InvalidRequest));
+            }
+        } else {
+            throw new LspError('Invalid JSON-RPC response', ErrorCodes.InvalidRequest);
+        }
+    }
+
+    private async handleRequest(message: RpcRequest): Promise<void> {
+        const controller = new AbortController();
+        this.incoming.set(message.id, controller);
+        try {
+            const handler = this.handlers.get(message.method);
+            if (!handler) {
+                throw new LspError(`Unsupported server request: ${message.method}`, ErrorCodes.MethodNotFound);
+            }
+            const result = await handler(message.params, controller.signal);
+            if (controller.signal.aborted) {
+                throw new LspError('Request cancelled', ErrorCodes.RequestCancelled);
+            }
+            await this.send({ jsonrpc: '2.0', id: message.id, result: result ?? null });
+        } catch (error) {
+            const failure = error instanceof LspError ? error : new LspError(asError(error).message);
+            if (!this.closed) {
+                await this.send({ jsonrpc: '2.0', id: message.id, error: { code: failure.code, message: failure.message, data: failure.data } });
+            }
+        } finally {
+            this.incoming.delete(message.id);
+        }
+    }
+
+    private finish(error?: Error): void {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        for (const id of [...this.pending.keys()]) {
+            this.settle(id, undefined, error ?? new LspError('LSP connection closed'));
+        }
+        for (const controller of this.incoming.values()) {
+            controller.abort();
+        }
+        this.incoming.clear();
+        // A transport that is closed already calls back from inside the constructor, before the subscriptions exist.
+        for (const subscription of this.subscriptions ?? []) {
+            subscription.dispose();
+        }
+        for (const listener of this.closes) {
+            try {
+                listener(error);
+            } catch (failure) {
+                this.reportError(failure);
+            }
+        }
+        this.handlers.clear();
+        this.notifications.clear();
+        this.closes.clear();
+        if (error) {
+            this.reportError(error);
+        }
+    }
+}

package/src/document.ts

@@ -0,0 +1,357 @@
+import { ErrorCodes, LspError, StaleResultError } from './connection.ts';
+import { applyContentChanges, minimalChange } from './edits.ts';
+import type { LspSession } from './session.ts';
+import type {
+    CodeAction,
+    CodeActionContext,
+    CodeLens,
+    Command,
+    CompletionContext,
+    CompletionItem,
+    CompletionResult,
+    ContentChange,
+    DocumentDiagnosticReport,
+    DocumentHighlight,
+    DocumentItem,
+    DocumentRequestOptions,
+    DocumentSymbolResult,
+    FoldingRange,
+    FormattingOptions,
+    Hover,
+    InlayHint,
+    Location,
+    NavigationResult,
+    Position,
+    PrepareRenameResult,
+    Range,
+    SelectionRange,
+    SemanticTokens,
+    SemanticTokensDelta,
+    SignatureHelp,
+    SignatureHelpContext,
+    TextEdit,
+    WorkspaceEdit
+} from './protocol.ts';
+
+/*
+ * One open text document in one session. It owns the version: every change raises it by one, and a
+ * result that arrives for an older version is refused, so nothing computed for a text that is gone
+ * reaches the caller.
+ */
+export class LspDocument {
+    readonly session: LspSession;
+    readonly uri: string;
+    readonly languageId: string;
+    readonly ready: Promise<void>;
+    private revision: number;
+    private content: string;
+    private closed = false;
+    private synced: Promise<void>;
+    private closePromise?: Promise<void>;
+    private readonly inFlight = new Set<AbortController>();
+    private readonly latest = new Map<string, AbortController>();
+    private readonly resultVersions = new WeakMap<object, number>();
+
+    constructor(session: LspSession, item: DocumentItem) {
+        // A uri that does not parse is the caller's bug, and fails here instead of inside a server.
+        new URL(item.uri);
+        this.session = session;
+        this.uri = item.uri;
+        this.languageId = item.languageId;
+        this.content = item.text;
+        this.revision = item.version ?? 1;
+        if (!Number.isSafeInteger(this.revision) || this.revision < 0) {
+            throw new LspError('Invalid document version');
+        }
+        this.ready = session.syncOptions.openClose
+            ? session.notify('textDocument/didOpen', { textDocument: { ...item, version: this.revision } })
+            : Promise.resolve();
+        this.synced = this.ready;
+        void this.ready.catch((error) => session.connection.reportError(error));
+    }
+
+    get version(): number {
+        return this.revision;
+    }
+
+    get text(): string {
+        return this.content;
+    }
+
+    get isClosed(): boolean {
+        return this.closed;
+    }
+
+    /* Sends the difference to the text as the one range that changed, or the whole text to a server that wants no ranges. */
+    updateText(text: string): Promise<void> {
+        this.assertOpen();
+        if (text === this.content) {
+            return this.synced;
+        }
+        return this.applyChanges([minimalChange(this.content, text)]);
+    }
+
+    /*
+     * Applies `didChange` entries in order, which a server that negotiated incremental sync gets as
+     * they are. The version goes up by one even when the text ends up the same.
+     */
+    applyChanges(changes: readonly ContentChange[]): Promise<void> {
+        this.assertOpen();
+        const kind = this.session.syncOptions.change ?? 0;
+        if (!kind) {
+            return Promise.reject(new LspError('Server did not negotiate document changes', ErrorCodes.MethodNotFound));
+        }
+        let next: string;
+        try {
+            next = applyContentChanges(this.content, changes);
+        } catch (error) {
+            return Promise.reject(error);
+        }
+        this.content = next;
+        const version = ++this.revision;
+        this.cancelRequests();
+        const contentChanges = kind === 1 ? [{ text: next }] : changes.map((change) => ({ ...change }));
+        this.synced = this.synced.then(() =>
+            this.session.connection.notify('textDocument/didChange', { textDocument: { uri: this.uri, version }, contentChanges })
+        );
+        void this.synced.catch((error) => this.session.connection.reportError(error));
+        return this.synced;
+    }
+
+    /* Call it once the file is on disk; it sends `didSave` when the server asked for it. */
+    async save(): Promise<void> {
+        this.assertOpen();
+        const version = this.version;
+        const text = this.text;
+        await this.synced;
+        this.assertCurrent(version);
+        const save = this.session.syncOptions.save;
+        if (save) {
+            await this.session.notify('textDocument/didSave', {
+                textDocument: { uri: this.uri },
+                text: typeof save === 'object' && save.includeText ? text : undefined
+            });
+        }
+    }
+
+    completion(position: Position, context?: CompletionContext, options?: DocumentRequestOptions): Promise<CompletionResult> {
+        return this.feature('textDocument/completion', { position, context }, options);
+    }
+
+    resolveCompletion(item: CompletionItem, options?: DocumentRequestOptions): Promise<CompletionItem> {
+        return this.resolve('completionItem/resolve', item, options);
+    }
+
+    hover(position: Position, options?: DocumentRequestOptions): Promise<Hover | null> {
+        return this.feature('textDocument/hover', { position }, options);
+    }
+
+    signatureHelp(position: Position, context?: SignatureHelpContext, options?: DocumentRequestOptions): Promise<SignatureHelp | null> {
+        return this.feature('textDocument/signatureHelp', { position, context }, options);
+    }
+
+    definition(position: Position, options?: DocumentRequestOptions): Promise<NavigationResult> {
+        return this.feature('textDocument/definition', { position }, options);
+    }
+
+    declaration(position: Position, options?: DocumentRequestOptions): Promise<NavigationResult> {
+        return this.feature('textDocument/declaration', { position }, options);
+    }
+
+    typeDefinition(position: Position, options?: DocumentRequestOptions): Promise<NavigationResult> {
+        return this.feature('textDocument/typeDefinition', { position }, options);
+    }
+
+    implementation(position: Position, options?: DocumentRequestOptions): Promise<NavigationResult> {
+        return this.feature('textDocument/implementation', { position }, options);
+    }
+
+    references(position: Position, includeDeclaration = true, options?: DocumentRequestOptions): Promise<Location[] | null> {
+        return this.feature('textDocument/references', { position, context: { includeDeclaration } }, options);
+    }
+
+    documentHighlights(position: Position, options?: DocumentRequestOptions): Promise<DocumentHighlight[] | null> {
+        return this.feature('textDocument/documentHighlight', { position }, options);
+    }
+
+    documentSymbols(options?: DocumentRequestOptions): Promise<DocumentSymbolResult> {
+        return this.feature('textDocument/documentSymbol', {}, options);
+    }
+
+    prepareRename(position: Position, options?: DocumentRequestOptions): Promise<PrepareRenameResult> {
+        return this.feature('textDocument/prepareRename', { position }, options);
+    }
+
+    rename(position: Position, newName: string, options?: DocumentRequestOptions): Promise<WorkspaceEdit | null> {
+        return this.feature('textDocument/rename', { position, newName }, options);
+    }
+
+    codeActions(range: Range, context: CodeActionContext = { diagnostics: [] }, options?: DocumentRequestOptions): Promise<(CodeAction | Command)[] | null> {
+        return this.feature('textDocument/codeAction', { range, context }, options);
+    }
+
+    resolveCodeAction(action: CodeAction, options?: DocumentRequestOptions): Promise<CodeAction> {
+        return this.resolve('codeAction/resolve', action, options);
+    }
+
+    codeLenses(options?: DocumentRequestOptions): Promise<CodeLens[] | null> {
+        return this.feature('textDocument/codeLens', {}, options);
+    }
+
+    resolveCodeLens(lens: CodeLens, options?: DocumentRequestOptions): Promise<CodeLens> {
+        return this.resolve('codeLens/resolve', lens, options);
+    }
+
+    formatting(formatting: FormattingOptions, options?: DocumentRequestOptions): Promise<TextEdit[] | null> {
+        return this.feature('textDocument/formatting', { options: formatting }, options);
+    }
+
+    rangeFormatting(range: Range, formatting: FormattingOptions, options?: DocumentRequestOptions): Promise<TextEdit[] | null> {
+        return this.feature('textDocument/rangeFormatting', { range, options: formatting }, options);
+    }
+
+    foldingRanges(options?: DocumentRequestOptions): Promise<FoldingRange[] | null> {
+        return this.feature('textDocument/foldingRange', {}, options);
+    }
+
+    selectionRanges(positions: readonly Position[], options?: DocumentRequestOptions): Promise<SelectionRange[] | null> {
+        return this.feature('textDocument/selectionRange', { positions }, options);
+    }
+
+    semanticTokens(options?: DocumentRequestOptions): Promise<SemanticTokens | null> {
+        return this.feature('textDocument/semanticTokens/full', {}, options);
+    }
+
+    semanticTokensDelta(previousResultId: string, options?: DocumentRequestOptions): Promise<SemanticTokens | SemanticTokensDelta | null> {
+        return this.feature('textDocument/semanticTokens/full/delta', { previousResultId }, options);
+    }
+
+    semanticTokensRange(range: Range, options?: DocumentRequestOptions): Promise<SemanticTokens | null> {
+        return this.feature('textDocument/semanticTokens/range', { range }, options);
+    }
+
+    inlayHints(range: Range, options?: DocumentRequestOptions): Promise<InlayHint[] | null> {
+        return this.feature('textDocument/inlayHint', { range }, options);
+    }
+
+    resolveInlayHint(hint: InlayHint, options?: DocumentRequestOptions): Promise<InlayHint> {
+        return this.resolve('inlayHint/resolve', hint, options);
+    }
+
+    diagnostics(previousResultId?: string, identifier?: string, options?: DocumentRequestOptions): Promise<DocumentDiagnosticReport> {
+        return this.feature('textDocument/diagnostic', { previousResultId, identifier }, options);
+    }
+
+    /* Any feature by its LSP method, for a caller that gets the method from elsewhere. `params` leave out `textDocument`; a resolve method takes the item. */
+    request<T = unknown>(method: string, params: object, options?: DocumentRequestOptions): Promise<T> {
+        return method.endsWith('/resolve') ? (this.resolve(method, params, options) as Promise<T>) : this.feature<T>(method, params, options);
+    }
+
+    /* Sends `didClose` after every change queued before it. The uri stays taken until then, so a reopen cannot overtake it. */
+    close(): Promise<void> {
+        if (this.closePromise) {
+            return this.closePromise;
+        }
+        if (this.closed) {
+            return Promise.resolve();
+        }
+        this.closed = true;
+        this.cancelRequests();
+        this.closePromise = this.synced
+            .then(async () => {
+                if (!this.session.connection.isClosed && this.session.syncOptions.openClose) {
+                    await this.session.connection.notify('textDocument/didClose', { textDocument: { uri: this.uri } });
+                }
+            })
+            .finally(() => this.session.forgetDocument(this));
+        return this.closePromise;
+    }
+
+    /* The connection is gone, so there is nobody to tell. */
+    disconnect(): void {
+        this.closed = true;
+        this.cancelRequests();
+        this.session.forgetDocument(this);
+    }
+
+    private feature<T>(method: string, params: object, options?: DocumentRequestOptions): Promise<T> {
+        return this.perform(method, { ...params, textDocument: { uri: this.uri } }, options);
+    }
+
+    private resolve<T extends object>(method: string, item: T, options?: DocumentRequestOptions): Promise<T> {
+        const version = this.resultVersions.get(item);
+        if (version !== undefined && version !== this.version) {
+            return Promise.reject(new StaleResultError(this.uri));
+        }
+        return this.perform(method, item, options);
+    }
+
+    private async perform<T>(method: string, params: unknown, options: DocumentRequestOptions = {}): Promise<T> {
+        this.assertOpen();
+        if (!this.session.supports(method, this)) {
+            throw new LspError(`Server does not support ${method}`, ErrorCodes.MethodNotFound);
+        }
+        const version = this.version;
+        const controller = new AbortController();
+        if (options.cancelPrevious !== false) {
+            this.latest.get(method)?.abort();
+        }
+        this.latest.set(method, controller);
+        this.inFlight.add(controller);
+        const abort = (): void => controller.abort();
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted) {
+            abort();
+        }
+        try {
+            await this.synced;
+            this.assertCurrent(version);
+            const result = await this.session.request<T>(method, params, { signal: controller.signal, timeoutMs: options.timeoutMs });
+            this.assertCurrent(version);
+            this.remember(result, version);
+            return result;
+        } catch (error) {
+            this.assertCurrent(version);
+            throw error;
+        } finally {
+            options.signal?.removeEventListener('abort', abort);
+            this.inFlight.delete(controller);
+            if (this.latest.get(method) === controller) {
+                this.latest.delete(method);
+            }
+        }
+    }
+
+    /* A completion item, code action or hint resolves only against the version it was produced for. */
+    private remember(result: unknown, version: number): void {
+        if (!result || typeof result !== 'object') {
+            return;
+        }
+        this.resultVersions.set(result, version);
+        if (Array.isArray(result)) {
+            for (const item of result) {
+                this.remember(item, version);
+            }
+        } else if ('items' in result) {
+            this.remember(result.items, version);
+        }
+    }
+
+    private assertOpen(): void {
+        if (this.closed) {
+            throw new LspError(`Document is closed: ${this.uri}`);
+        }
+    }
+
+    private assertCurrent(version: number): void {
+        if (this.closed || this.version !== version) {
+            throw new StaleResultError(this.uri);
+        }
+    }
+
+    private cancelRequests(): void {
+        for (const controller of this.inFlight) {
+            controller.abort();
+        }
+    }
+}