@adecore/lsp 0.0.1 → 0.17.0-beta.2

package/src/test-transport.ts

@@ -0,0 +1,92 @@
+import { LspSession } from './session.ts';
+import type { LspTransport, RpcMessage, ServerCapabilities } from './protocol.ts';
+
+/* A transport that records what is sent and lets a test say what comes back, for tests that assert on the exact wire. */
+export class ScriptedTransport implements LspTransport {
+    sent: RpcMessage[] = [];
+    messages = new Set<(message: unknown) => void>();
+    closes = new Set<(error?: Error) => void>();
+    autoInitialize: ServerCapabilities | undefined;
+
+    send(message: RpcMessage): void {
+        this.sent.push(message);
+        if ('method' in message && message.method === 'initialize' && 'id' in message && this.autoInitialize) {
+            queueMicrotask(() => this.emit({ jsonrpc: '2.0', id: message.id, result: { capabilities: this.autoInitialize } }));
+        }
+        if ('method' in message && message.method === 'shutdown' && 'id' in message) {
+            queueMicrotask(() => this.emit({ jsonrpc: '2.0', id: message.id, result: null }));
+        }
+    }
+
+    onMessage(listener: (message: unknown) => void) {
+        this.messages.add(listener);
+        return {
+            dispose: () => {
+                this.messages.delete(listener);
+            }
+        };
+    }
+
+    onClose(listener: (error?: Error) => void) {
+        this.closes.add(listener);
+        return {
+            dispose: () => {
+                this.closes.delete(listener);
+            }
+        };
+    }
+
+    close() {
+        for (const listener of this.closes) {
+            listener();
+        }
+    }
+
+    emit(message: RpcMessage) {
+        for (const listener of this.messages) {
+            listener(message);
+        }
+    }
+
+    /* The last request of `method` the client sent. */
+    request(method: string) {
+        return [...this.sent].reverse().find((message) => 'method' in message && message.method === method && 'id' in message) as {
+            id: number;
+            params: unknown;
+        };
+    }
+
+    respond(method: string, result: unknown) {
+        this.emit({ jsonrpc: '2.0', id: this.request(method).id, result });
+    }
+
+    methods(): string[] {
+        return this.sent.flatMap((message) => ('method' in message ? [message.method] : []));
+    }
+}
+
+export async function flush(): Promise<void> {
+    for (let i = 0; i < 15; i++) {
+        await Promise.resolve();
+    }
+}
+
+export const origin = { line: 0, character: 0 };
+
+export async function sessionWith(capabilities: ServerCapabilities = {}) {
+    const transport = new ScriptedTransport();
+    transport.autoInitialize = { textDocumentSync: 2, ...capabilities };
+    const session = new LspSession(transport);
+    await session.initialize();
+    return { transport, session };
+}
+
+/* Bun runs the event loop inside `expect(promise).rejects` of a promise that has not settled, so a rejection that comes later is checked here. */
+export function rejecting(promise: Promise<unknown>, check: (error: unknown) => void): Promise<void> {
+    return promise.then(
+        () => {
+            throw new Error('Expected the promise to reject');
+        },
+        (error) => check(error)
+    );
+}

package/src/testing.ts

@@ -0,0 +1,105 @@
+import { JsonRpcConnection, type RequestHandler } from './connection.ts';
+import { applyContentChanges } from './edits.ts';
+import type { ContentChange, Diagnostic, InitializeResult, LspTransport, ServerCapabilities } from './protocol.ts';
+
+export { createMemoryTransportPair } from './transport.ts';
+
+export interface FakeLanguageServerOptions {
+    capabilities?: ServerCapabilities;
+    serverInfo?: InitializeResult['serverInfo'];
+    handlers?: Record<string, RequestHandler>;
+    /* Never answers the handshake, like a server that hangs while it starts. */
+    silent?: boolean;
+}
+
+export interface FakeDocument {
+    languageId: string;
+    text: string;
+    version: number;
+}
+
+export interface ReceivedMessage {
+    method: string;
+    params: unknown;
+    /* Present for a request, absent for a notification. */
+    id?: number | string;
+}
+
+/*
+ * A language server for tests, on the far end of a transport. It answers the handshake, keeps the
+ * text of every document it was told about the way a real server does, and answers whatever a test
+ * registers with `handle`; any other request is refused as unsupported.
+ */
+export class FakeLanguageServer {
+    readonly connection: JsonRpcConnection;
+    readonly received: ReceivedMessage[] = [];
+    readonly documents = new Map<string, FakeDocument>();
+    shutdownRequested = false;
+    exited = false;
+
+    constructor(transport: LspTransport, options: FakeLanguageServerOptions = {}) {
+        this.connection = new JsonRpcConnection(transport, 0);
+        transport.onMessage((message) => {
+            const { method, params, id } = message as ReceivedMessage;
+            if (typeof method === 'string') {
+                this.received.push({ method, params, id });
+            }
+        });
+        this.connection.onRequest('initialize', () =>
+            options.silent
+                ? new Promise<never>(() => undefined)
+                : { capabilities: options.capabilities ?? { textDocumentSync: 2 }, serverInfo: options.serverInfo }
+        );
+        this.connection.onRequest('shutdown', () => {
+            this.shutdownRequested = true;
+            return null;
+        });
+        this.connection.onNotification('exit', () => {
+            this.exited = true;
+        });
+        this.connection.onNotification('textDocument/didOpen', (params) => {
+            const { textDocument } = params as { textDocument: { uri: string; languageId: string; text: string; version: number } };
+            this.documents.set(textDocument.uri, { languageId: textDocument.languageId, text: textDocument.text, version: textDocument.version });
+        });
+        this.connection.onNotification('textDocument/didChange', (params) => {
+            const { textDocument, contentChanges } = params as { textDocument: { uri: string; version: number }; contentChanges: ContentChange[] };
+            const document = this.documents.get(textDocument.uri);
+            if (document) {
+                document.text = applyContentChanges(document.text, contentChanges);
+                document.version = textDocument.version;
+            }
+        });
+        this.connection.onNotification('textDocument/didClose', (params) => {
+            this.documents.delete((params as { textDocument: { uri: string } }).textDocument.uri);
+        });
+        for (const [method, handler] of Object.entries(options.handlers ?? {})) {
+            this.connection.onRequest(method, handler);
+        }
+    }
+
+    handle(method: string, handler: RequestHandler): void {
+        this.connection.onRequest(method, handler);
+    }
+
+    /* The params of every request or notification of `method`, in the order they came. */
+    paramsOf(method: string): unknown[] {
+        return this.received.filter((message) => message.method === method).map((message) => message.params);
+    }
+
+    publishDiagnostics(uri: string, diagnostics: Diagnostic[], version?: number): Promise<void> {
+        return this.connection.notify('textDocument/publishDiagnostics', { uri, version, diagnostics });
+    }
+
+    notify(method: string, params?: unknown): Promise<void> {
+        return this.connection.notify(method, params);
+    }
+
+    request<T = unknown>(method: string, params?: unknown): Promise<T> {
+        return this.connection.request<T>(method, params);
+    }
+
+    /* The process went away: the transport closes under the client. */
+    crash(): Promise<void> {
+        return this.connection.close();
+    }
+}

package/src/transport.ts

@@ -0,0 +1,290 @@
+import type { Disposable, LspTransport, RpcMessage } from './protocol.ts';
+
+const DEFAULT_MAX_MESSAGE_BYTES = 32 * 1024 * 1024;
+const MAX_HEADER_BYTES = 8192;
+
+function asError(error: unknown): Error {
+    return error instanceof Error ? error : new Error(String(error));
+}
+
+/*
+ * The listeners of a transport. A message that arrives before anyone listens is held and handed to
+ * the first listener, since a server may speak the moment its pipe opens.
+ */
+class TransportEvents {
+    closed = false;
+    private readonly messages = new Set<(message: unknown) => void>();
+    private readonly closes = new Set<(error?: Error) => void>();
+    private backlog: unknown[] = [];
+    private error?: Error;
+
+    onMessage = (listener: (message: unknown) => void): Disposable => {
+        this.messages.add(listener);
+        for (const message of this.backlog.splice(0)) {
+            listener(message);
+        }
+        return {
+            dispose: () => {
+                this.messages.delete(listener);
+            }
+        };
+    };
+
+    onClose = (listener: (error?: Error) => void): Disposable => {
+        this.closes.add(listener);
+        if (this.closed) {
+            listener(this.error);
+        }
+        return {
+            dispose: () => {
+                this.closes.delete(listener);
+            }
+        };
+    };
+
+    receive(message: unknown): void {
+        if (this.closed) {
+            return;
+        }
+        if (this.messages.size === 0) {
+            this.backlog.push(message);
+            return;
+        }
+        for (const listener of this.messages) {
+            listener(message);
+        }
+    }
+
+    finish(error?: Error): void {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.error = error;
+        this.backlog = [];
+        for (const listener of this.closes) {
+            listener(error);
+        }
+        this.closes.clear();
+        this.messages.clear();
+    }
+}
+
+function concat(chunks: readonly Uint8Array[], size: number): Uint8Array {
+    if (chunks.length === 1) {
+        return chunks[0];
+    }
+    const joined = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return joined;
+}
+
+function indexOfHeaderEnd(bytes: Uint8Array): number {
+    for (let i = 0; i + 3 < bytes.length; i++) {
+        if (bytes[i] === 13 && bytes[i + 1] === 10 && bytes[i + 2] === 13 && bytes[i + 3] === 10) {
+            return i;
+        }
+    }
+    return -1;
+}
+
+/* Reads `Content-Length` framed messages, the way a language server speaks over stdio. */
+export class ContentLengthDecoder {
+    private readonly maxMessageBytes: number;
+    private chunks: Uint8Array[] = [];
+    private size = 0;
+    private length: number | null = null;
+
+    constructor(maxMessageBytes = DEFAULT_MAX_MESSAGE_BYTES) {
+        this.maxMessageBytes = maxMessageBytes;
+    }
+
+    /* Every complete message in what has arrived so far. Throws on a frame it cannot read, after which the stream is no use. */
+    accept(chunk: Uint8Array): unknown[] {
+        this.chunks.push(chunk);
+        this.size += chunk.length;
+        const messages: unknown[] = [];
+        while (true) {
+            if (this.length === null) {
+                const buffer = concat(this.chunks, this.size);
+                this.chunks = [buffer];
+                const boundary = indexOfHeaderEnd(buffer);
+                if (boundary < 0) {
+                    if (buffer.length > MAX_HEADER_BYTES) {
+                        throw new Error('LSP header is too large');
+                    }
+                    break;
+                }
+                const header = new TextDecoder().decode(buffer.subarray(0, boundary));
+                const match = /^Content-Length:\s*(\d+)\s*$/im.exec(header);
+                if (!match || boundary > MAX_HEADER_BYTES) {
+                    throw new Error('Invalid LSP Content-Length header');
+                }
+                const length = Number(match[1]);
+                if (!length || length > this.maxMessageBytes) {
+                    throw new Error('LSP message is too large');
+                }
+                this.length = length;
+                this.chunks = [buffer.subarray(boundary + 4)];
+                this.size = buffer.length - boundary - 4;
+            }
+            if (this.size < this.length) {
+                break;
+            }
+            const buffer = concat(this.chunks, this.size);
+            messages.push(JSON.parse(new TextDecoder().decode(buffer.subarray(0, this.length))));
+            this.chunks = [buffer.subarray(this.length)];
+            this.size = buffer.length - this.length;
+            this.length = null;
+        }
+        return messages;
+    }
+}
+
+export function encodeMessage(message: RpcMessage): Uint8Array {
+    const body = new TextEncoder().encode(JSON.stringify(message));
+    const header = new TextEncoder().encode(`Content-Length: ${body.length}\r\n\r\n`);
+    const framed = new Uint8Array(header.length + body.length);
+    framed.set(header, 0);
+    framed.set(body, header.length);
+    return framed;
+}
+
+/* What a stdio transport needs of a process: its stdin and stdout as bytes, which the host adapts a child to. */
+export interface ByteStream {
+    write(chunk: Uint8Array): void | Promise<void>;
+    onData(listener: (chunk: Uint8Array) => void): Disposable;
+    /* Called once, when the stream ended; an error when it ended badly. */
+    onClose(listener: (error?: Error) => void): Disposable;
+    close(): void | Promise<void>;
+}
+
+export function createStreamTransport(stream: ByteStream, options: { maxMessageBytes?: number } = {}): LspTransport {
+    const events = new TransportEvents();
+    const decoder = new ContentLengthDecoder(options.maxMessageBytes);
+    stream.onData((chunk) => {
+        try {
+            for (const message of decoder.accept(chunk)) {
+                events.receive(message);
+            }
+        } catch (error) {
+            events.finish(asError(error));
+            void Promise.resolve(stream.close()).catch(() => undefined);
+        }
+    });
+    stream.onClose((error) => events.finish(error));
+    return {
+        onMessage: events.onMessage,
+        onClose: events.onClose,
+        async send(message) {
+            if (events.closed) {
+                throw new Error('LSP stream is closed');
+            }
+            await stream.write(encodeMessage(message));
+        },
+        async close() {
+            events.finish();
+            await stream.close();
+        }
+    };
+}
+
+/* Two ends of one connection in memory: what one sends the other receives, as JSON and one tick later. Closing either ends both. */
+export function createMemoryTransportPair(): [LspTransport, LspTransport] {
+    const left = new TransportEvents();
+    const right = new TransportEvents();
+    const end = (inbox: TransportEvents, outbox: TransportEvents): LspTransport => ({
+        onMessage: inbox.onMessage,
+        onClose: inbox.onClose,
+        send(message) {
+            if (inbox.closed || outbox.closed) {
+                throw new Error('LSP transport is closed');
+            }
+            const copy: unknown = JSON.parse(JSON.stringify(message));
+            queueMicrotask(() => outbox.receive(copy));
+        },
+        close() {
+            inbox.finish();
+            outbox.finish();
+        }
+    });
+    return [end(left, right), end(right, left)];
+}
+
+export interface WebSocketTransportOptions {
+    protocols?: string[];
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    createWebSocket?: (url: string, protocols?: string[]) => WebSocket;
+}
+
+const MAX_SOCKET_BUFFER_BYTES = 8 * 1024 * 1024;
+
+/* JSON text frames over a WebSocket, which a browser can open and a daemon can serve. */
+export async function connectWebSocket(url: string, options: WebSocketTransportOptions = {}): Promise<LspTransport> {
+    if (options.signal?.aborted) {
+        throw new Error('WebSocket connection cancelled');
+    }
+    const socket = options.createWebSocket ? options.createWebSocket(url, options.protocols) : new WebSocket(url, options.protocols);
+    const events = new TransportEvents();
+    socket.addEventListener('message', (event) => {
+        try {
+            if (typeof event.data !== 'string') {
+                throw new Error('LSP WebSocket expects JSON text frames');
+            }
+            events.receive(JSON.parse(event.data));
+        } catch (error) {
+            events.finish(asError(error));
+            socket.close(1003, 'Invalid JSON message');
+        }
+    });
+    socket.addEventListener('close', (event) => events.finish(event.code === 1000 ? undefined : new Error(`LSP WebSocket closed (${event.code})`)));
+    socket.addEventListener('error', () => events.finish(new Error('LSP WebSocket failed')));
+    await new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(() => fail(new Error('LSP WebSocket connection timed out')), options.timeoutMs ?? 10_000);
+        const cleanup = (): void => {
+            clearTimeout(timer);
+            socket.removeEventListener('open', open);
+            socket.removeEventListener('error', failed);
+            socket.removeEventListener('close', closed);
+            options.signal?.removeEventListener('abort', abort);
+        };
+        const fail = (reason: Error): void => {
+            cleanup();
+            socket.close();
+            reject(reason);
+        };
+        const open = (): void => {
+            cleanup();
+            resolve();
+        };
+        const failed = (): void => fail(new Error('LSP WebSocket connection failed'));
+        const closed = (): void => fail(new Error('LSP WebSocket closed before opening'));
+        const abort = (): void => fail(new Error('LSP WebSocket connection cancelled'));
+        socket.addEventListener('open', open, { once: true });
+        socket.addEventListener('error', failed, { once: true });
+        socket.addEventListener('close', closed, { once: true });
+        options.signal?.addEventListener('abort', abort, { once: true });
+    });
+    return {
+        onMessage: events.onMessage,
+        onClose: events.onClose,
+        send(message) {
+            if (events.closed || socket.readyState !== 1) {
+                throw new Error('LSP WebSocket is closed');
+            }
+            if (socket.bufferedAmount > MAX_SOCKET_BUFFER_BYTES) {
+                throw new Error('LSP WebSocket send buffer is full');
+            }
+            socket.send(JSON.stringify(message));
+        },
+        close() {
+            events.finish();
+            socket.close(1000);
+        }
+    };
+}

package/src/uris.ts

@@ -0,0 +1,29 @@
+function isWindowsDrive(segment: string): boolean {
+    return /^[A-Za-z]:$/.test(segment);
+}
+
+/* An absolute path, POSIX or with a Windows drive, as the `file:` URI a language server names it by. */
+export function pathToFileUri(path: string): string {
+    const normalized = path.replaceAll('\\', '/');
+    const rooted = normalized.startsWith('/') ? normalized : `/${normalized}`;
+    const segments = rooted.split('/').map((segment, index) => (index === 1 && isWindowsDrive(segment) ? segment : encodeURIComponent(segment)));
+    return `file://${segments.join('/')}`;
+}
+
+/* The path behind a `file:` URI, in the form of the machine it names, or null for any other kind of URI. */
+export function fileUriToPath(uri: string): string | null {
+    let url: URL;
+    try {
+        url = new URL(uri);
+    } catch {
+        return null;
+    }
+    if (url.protocol !== 'file:') {
+        return null;
+    }
+    const path = decodeURIComponent(url.pathname);
+    if (/^\/[A-Za-z]:/.test(path)) {
+        return path.slice(1).replaceAll('/', '\\');
+    }
+    return path;
+}

package/src/vue.ts

@@ -0,0 +1,93 @@
+import { offsetAt } from './edits.ts';
+import type { Disposable } from './protocol.ts';
+import type { LspSession } from './session.ts';
+
+/*
+ * Vue's server leaves TypeScript to a tsserver of its own project and asks for it with
+ * `tsserver/request` notifications, which this relays to the TypeScript server's
+ * `typescript.tsserverRequest` command. Attach it before the Vue session initializes, and open each
+ * `.vue` document in both sessions, TypeScript first.
+ */
+export function bridgeVueTypeScript(vue: LspSession, typescript: LspSession): Disposable {
+    let disposed = false;
+    const subscription = vue.onNotification('tsserver/request', async (params) => {
+        // vscode-jsonrpc encodes this single positional argument as an outer array.
+        const positional = Array.isArray(params) && params.length === 1 && Array.isArray(params[0]);
+        const tuple = positional ? params[0] : params;
+        if (!Array.isArray(tuple) || tuple.length !== 3) {
+            throw new Error('Invalid Vue tsserver/request notification');
+        }
+        const [id, command, args] = tuple as [number, string, unknown];
+        let body: unknown = null;
+        try {
+            const response = await typescript.executeCommand<{ body?: unknown }>('typescript.tsserverRequest', [
+                command,
+                args,
+                { isAsync: false, lowPriority: true }
+            ]);
+            body = response?.body ?? null;
+        } catch (error) {
+            vue.connection.reportError(error);
+        }
+        // Vue keeps the request pending until it gets an answer, a null one included.
+        if (!disposed && !vue.connection.isClosed) {
+            await vue.connection.notify('tsserver/response', positional ? [[id, body]] : [id, body]);
+        }
+    });
+    return {
+        dispose() {
+            disposed = true;
+            subscription.dispose();
+        }
+    };
+}
+
+export type VueServer = 'vue' | 'typescript';
+
+/* A `<script>` body, or the expression of an interpolation or a `v-` / `:` / `@` attribute: the places TypeScript knows more than Vue does. */
+export function isVueExpression(text: string, offset: number): boolean {
+    const script = /<script\b[^>]*>[\s\S]*?<\/script\s*>/gi;
+    for (let match = script.exec(text); match; match = script.exec(text)) {
+        if (offset > match.index + match[0].indexOf('>') && offset < match.index + match[0].lastIndexOf('</')) {
+            return true;
+        }
+    }
+    const expressions = /\{\{[\s\S]*?\}\}|(?:[:@][\w.:-]+|v-[\w.:-]+)\s*=\s*(?:"[^"]*"|'[^']*')/g;
+    for (let match = expressions.exec(text); match; match = expressions.exec(text)) {
+        if (offset >= match.index && offset <= match.index + match[0].length) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function paramsOffset(text: string, params: unknown): number | null {
+    if (!params || typeof params !== 'object') {
+        return null;
+    }
+    const position =
+        'position' in params
+            ? params.position
+            : 'range' in params && params.range && typeof params.range === 'object' && 'start' in params.range
+              ? params.range.start
+              : null;
+    if (!position || typeof position !== 'object') {
+        return null;
+    }
+    try {
+        return offsetAt(text, position as { line: number; character: number });
+    } catch {
+        return null;
+    }
+}
+
+/*
+ * Which of the two servers of a Vue document to ask first, the other being the fallback when the
+ * first does not support the method. Vue answers template markup, HTML and CSS; TypeScript answers
+ * a script and the expressions of a template, and the inlay hints of all of it.
+ */
+export function vueServerOrder(method: string, text: string, params: unknown): [VueServer, VueServer] {
+    const offset = paramsOffset(text, params);
+    const typescriptFirst = method === 'textDocument/inlayHint' || (offset !== null && isVueExpression(text, offset));
+    return typescriptFirst ? ['typescript', 'vue'] : ['vue', 'typescript'];
+}

package/src/watched-files.ts

@@ -0,0 +1,49 @@
+import { globMatch } from './glob.ts';
+import type { FileSystemWatcher } from './protocol.ts';
+import { fileUriToPath } from './uris.ts';
+
+/* A change of a file as the protocol numbers it: created, changed, deleted. */
+export type FileChangeType = 1 | 2 | 3;
+
+/* Folders whose files a server hears about only when a pattern of its own names the folder. */
+const SPARING_FOLDERS = ['node_modules', 'vendor', '.git'];
+
+function relativeTo(root: string, path: string): string | null {
+    const prefix = root.endsWith('/') ? root : `${root}/`;
+    return path.startsWith(prefix) ? path.slice(prefix.length) : null;
+}
+
+/* A pattern with the folder it is relative to, or null for a relative pattern whose base is no folder of this machine. `base` is undefined for a string pattern. */
+function patternOf(watcher: FileSystemWatcher): { base: string | undefined; pattern: string } | null {
+    const { globPattern } = watcher;
+    if (typeof globPattern === 'string') {
+        return { base: undefined, pattern: globPattern };
+    }
+    const base = fileUriToPath(typeof globPattern.baseUri === 'string' ? globPattern.baseUri : globPattern.baseUri.uri);
+    return base === null ? null : { base, pattern: globPattern.pattern };
+}
+
+/*
+ * Whether a server asked to hear about this change. A string pattern is relative to the project folder
+ * (or absolute), a relative pattern to its own base. A path inside `node_modules`, `vendor` or `.git` only
+ * matches a pattern that names that folder, since `**` over a dependency tree is what a server never means.
+ */
+export function watchesFile(watchers: readonly FileSystemWatcher[], root: string, path: string, type: FileChangeType): boolean {
+    const inProject = relativeTo(root, path);
+    const segments = (inProject ?? path).split('/');
+    return watchers.some((watcher) => {
+        if (((watcher.kind ?? 7) & (1 << (type - 1))) === 0) {
+            return false;
+        }
+        const parts = patternOf(watcher);
+        if (parts === null) {
+            return false;
+        }
+        const { base, pattern } = parts;
+        const subject = pattern.startsWith('/') ? path : base === undefined ? inProject : relativeTo(base, path);
+        if (subject === null || !globMatch(subject, pattern)) {
+            return false;
+        }
+        return SPARING_FOLDERS.every((folder) => !segments.includes(folder) || pattern.includes(folder));
+    });
+}