@adecore/lsp 0.0.1 → 0.17.0-beta.1

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Bas Milius
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @adecore/lsp
+
+Read the [LSP handbook](https://adecore.dev/lsp/handbook/) for the complete setup, concepts, host integration and testing guides.
+
+A DOM-free LSP 3.17 client, and the `LanguageService` interface the smart editor asks its language features through. It spawns nothing and imports no Node or Bun API outside its tests, so a host can use it in a server process or browser. The document model it feeds is `@adecore/editor-core`; the view is `@adecore/editor`.
+
+Positions are LSP positions: zero-based lines and UTF-16 characters, with a line ending at `\n`, `\r\n` or a lone `\r`. Turning them into editor offsets is the view's job.
+
+## API
+
+Everything comes from the package root; `@adecore/lsp/testing` holds the test doubles.
+
+- `LspSession`: one conversation with one server over an `LspTransport`. `initialize` negotiates capabilities (UTF-16 only, snippets off unless asked), `openDocument` returns an `LspDocument`, and `supports` / `providerOptions` answer from static capabilities and dynamic registrations alike. It answers the server's configuration, folder, registration, progress and message requests, and `onDiagnostics`, `onCapabilitiesChanged` (registrations and refresh requests), `onProgress`, `onNotification` and `onError` observe it. `shutdown` closes the documents, then sends `shutdown` and `exit`.
+- `LspDocument`: one open file in one session, and the owner of its version. `applyChanges` takes `didChange` entries and sends them as they are to a server that negotiated incremental sync, or the whole text to one that negotiated full sync. `updateText` sends the one range that differs from the held text. Every call raises the version by one. A request is cancelled when the text changes or a newer one for the same feature is made (`cancelPrevious`), and an answer for an older version rejects with `StaleResultError`, so does resolving a completion item, code action, lens or hint of an older version. One method per feature: completion, hover, signature help, the four navigations, references, highlights, symbols, rename, code actions, code lenses, formatting, folding, semantic tokens (full, delta, range), inlay hints and pull diagnostics.
+- `JsonRpcConnection`: correlation, `$/cancelRequest`, a request timeout (30 seconds, `0` turns it off) and the requests a server sends. `LspError` carries a JSON-RPC code; `ErrorCodes` names the ones used here.
+- Transports: `createStreamTransport` over a `ByteStream` (a child's stdin and stdout, which the host adapts), `ContentLengthDecoder` and `encodeMessage` for the framing, `createMemoryTransportPair` and `connectWebSocket`.
+- Edits: `applyTextEdits` and `planWorkspaceEdit` (simultaneous edits and a multi-file plan, which refuses file operations), `applyContentChanges` (sequential), `minimalChange`, `offsetAt`, `positionAt` and `endPosition`.
+- File renames: `willRenameFiles` and `didRenameFiles` of `LspSession` take the files that move (`RenamedFile`, which says whether each is a folder) and pass on only those that the filters of the server take, from its capabilities and its registrations (`fileOperationFilters`, `renamesTaken`: scheme, glob on the path the file leaves, `matches`, `ignoreCase`). The session declares `resourceOperations: ['rename']`, `workspace.fileOperations` and the `refactor.move` kind in `initialize`.
+- `bridgeVueTypeScript` relays Vue's `tsserver/request` to the TypeScript server, and `vueServerOrder` says which of the two servers of a `.vue` document to ask first.
+- `pathToFileUri` and `fileUriToPath`.
+- `LanguageService`: what the editor asks of the language side (open, change and close a document, every feature above, `executeCommand`, `supports`, `providerOptions`, `onProvidersChanged` and `onDiagnostics`). Results stay in LSP shapes. A request takes `signal` and `parallel`, which lets many requests of one feature run side by side instead of each taking over from the one before. A host adapts server sessions or its own transport to this interface. Server discovery, process startup, authorization and saving remain outside the library.
+- `@adecore/lsp/testing`: `FakeLanguageServer`, a server on the far end of a transport that answers the handshake, mirrors document text and answers whatever a test registers, and `createMemoryTransportPair`.
+
+## Known limits
+
+- Unversioned diagnostics cannot be proven fresh and are accepted while their document is open.
+- The package applies no workspace edit and touches no file. File creates, renames and deletes in a `WorkspaceEdit` are the host's, and the host only declares renames.
+- Only UTF-16 position encoding is negotiated; a server that insists on another one fails to initialize.
+- Servers that negotiated no document changes (`change: 0`) cannot follow an edit.
+
+## Packaging
+
+This unpublished package is private at version `0.0.0` and retains FSL-1.1-MIT. Source consumers enable `source` in the bundler and TypeScript `customConditions`. Default consumers use compiled JavaScript and declarations. Run `bun run build`, `bun run typecheck` and `bun run test` from the package after workspace installation. Tests use memory transports and fake servers; no installed language server is required.

package/dist/connection.d.ts

@@ -0,0 +1,50 @@
+import type { Disposable, LspTransport, RequestOptions } from './protocol.ts';
+export declare const ErrorCodes: {
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InternalError: -32603;
+    readonly ServerNotInitialized: -32002;
+    readonly RequestCancelled: -32800;
+    readonly ContentModified: -32801;
+};
+export declare class LspError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(message: string, code?: number, data?: unknown);
+}
+export declare class StaleResultError extends LspError {
+    readonly uri: string;
+    constructor(uri: string);
+}
+export type RequestHandler = (params: unknown, signal: AbortSignal) => unknown | Promise<unknown>;
+type NotificationHandler = (params: unknown) => void | Promise<void>;
+export declare class JsonRpcConnection {
+    readonly transport: LspTransport;
+    readonly timeoutMs: number;
+    private nextId;
+    private closed;
+    private sendQueue;
+    private readonly pending;
+    private readonly incoming;
+    private readonly handlers;
+    private readonly notifications;
+    private readonly errors;
+    private readonly closes;
+    private readonly subscriptions;
+    constructor(transport: LspTransport, timeoutMs?: number);
+    get isClosed(): boolean;
+    request<T = unknown>(method: string, params?: unknown, options?: RequestOptions): Promise<T>;
+    notify(method: string, params?: unknown): Promise<void>;
+    onRequest(method: string, handler: RequestHandler): Disposable;
+    onNotification(method: string, listener: NotificationHandler): Disposable;
+    onError(listener: (error: Error) => void): Disposable;
+    onClose(listener: (error?: Error) => void): Disposable;
+    reportError(error: unknown): void;
+    close(): Promise<void>;
+    private send;
+    private settle;
+    private receive;
+    private handleRequest;
+    private finish;
+}
+export {};

package/dist/connection.js

@@ -0,0 +1,290 @@
+/* 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
+};
+export class LspError extends Error {
+    code;
+    data;
+    constructor(message, code = ErrorCodes.InternalError, data) {
+        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 {
+    uri;
+    constructor(uri) {
+        super(`The document changed before its language result arrived: ${uri}`, ErrorCodes.ContentModified);
+        this.name = 'StaleResultError';
+        this.uri = uri;
+    }
+}
+function asError(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 {
+    transport;
+    timeoutMs;
+    nextId = 0;
+    closed = false;
+    sendQueue = Promise.resolve();
+    pending = new Map();
+    incoming = new Map();
+    handlers = new Map();
+    notifications = new Map();
+    errors = new Set();
+    closes = new Set();
+    subscriptions;
+    /* A `timeoutMs` of 0 turns the deadline off; a request then ends by its reply or its signal. */
+    constructor(transport, 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() {
+        return this.closed;
+    }
+    request(method, params, options = {}) {
+        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((resolve, reject) => {
+            let timer;
+            const cancel = (error) => {
+                if (!this.pending.has(id)) {
+                    return;
+                }
+                this.settle(id, undefined, error);
+                void this.notify('$/cancelRequest', { id }).catch((failure) => this.reportError(failure));
+            };
+            const abort = () => cancel(new LspError('Request cancelled', ErrorCodes.RequestCancelled));
+            this.pending.set(id, {
+                resolve: (value) => resolve(value),
+                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, params) {
+        return this.send({ jsonrpc: '2.0', method, params });
+    }
+    onRequest(method, handler) {
+        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, listener) {
+        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) {
+        this.errors.add(listener);
+        return {
+            dispose: () => {
+                this.errors.delete(listener);
+            }
+        };
+    }
+    onClose(listener) {
+        this.closes.add(listener);
+        if (this.closed) {
+            listener();
+        }
+        return {
+            dispose: () => {
+                this.closes.delete(listener);
+            }
+        };
+    }
+    reportError(error) {
+        const normalized = asError(error);
+        for (const listener of this.errors) {
+            try {
+                listener(normalized);
+            }
+            catch {
+                // An error observer must not break protocol dispatch.
+            }
+        }
+    }
+    async close() {
+        this.finish();
+        await this.transport.close();
+    }
+    send(message) {
+        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;
+    }
+    settle(id, result, error) {
+        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);
+        }
+    }
+    async receive(value) {
+        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;
+        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?.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);
+        }
+    }
+    async handleRequest(message) {
+        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);
+        }
+    }
+    finish(error) {
+        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/dist/document.d.ts

@@ -0,0 +1,60 @@
+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';
+export declare class LspDocument {
+    readonly session: LspSession;
+    readonly uri: string;
+    readonly languageId: string;
+    readonly ready: Promise<void>;
+    private revision;
+    private content;
+    private closed;
+    private synced;
+    private closePromise?;
+    private readonly inFlight;
+    private readonly latest;
+    private readonly resultVersions;
+    constructor(session: LspSession, item: DocumentItem);
+    get version(): number;
+    get text(): string;
+    get isClosed(): boolean;
+    updateText(text: string): Promise<void>;
+    applyChanges(changes: readonly ContentChange[]): Promise<void>;
+    save(): Promise<void>;
+    completion(position: Position, context?: CompletionContext, options?: DocumentRequestOptions): Promise<CompletionResult>;
+    resolveCompletion(item: CompletionItem, options?: DocumentRequestOptions): Promise<CompletionItem>;
+    hover(position: Position, options?: DocumentRequestOptions): Promise<Hover | null>;
+    signatureHelp(position: Position, context?: SignatureHelpContext, options?: DocumentRequestOptions): Promise<SignatureHelp | null>;
+    definition(position: Position, options?: DocumentRequestOptions): Promise<NavigationResult>;
+    declaration(position: Position, options?: DocumentRequestOptions): Promise<NavigationResult>;
+    typeDefinition(position: Position, options?: DocumentRequestOptions): Promise<NavigationResult>;
+    implementation(position: Position, options?: DocumentRequestOptions): Promise<NavigationResult>;
+    references(position: Position, includeDeclaration?: boolean, options?: DocumentRequestOptions): Promise<Location[] | null>;
+    documentHighlights(position: Position, options?: DocumentRequestOptions): Promise<DocumentHighlight[] | null>;
+    documentSymbols(options?: DocumentRequestOptions): Promise<DocumentSymbolResult>;
+    prepareRename(position: Position, options?: DocumentRequestOptions): Promise<PrepareRenameResult>;
+    rename(position: Position, newName: string, options?: DocumentRequestOptions): Promise<WorkspaceEdit | null>;
+    codeActions(range: Range, context?: CodeActionContext, options?: DocumentRequestOptions): Promise<(CodeAction | Command)[] | null>;
+    resolveCodeAction(action: CodeAction, options?: DocumentRequestOptions): Promise<CodeAction>;
+    codeLenses(options?: DocumentRequestOptions): Promise<CodeLens[] | null>;
+    resolveCodeLens(lens: CodeLens, options?: DocumentRequestOptions): Promise<CodeLens>;
+    formatting(formatting: FormattingOptions, options?: DocumentRequestOptions): Promise<TextEdit[] | null>;
+    rangeFormatting(range: Range, formatting: FormattingOptions, options?: DocumentRequestOptions): Promise<TextEdit[] | null>;
+    foldingRanges(options?: DocumentRequestOptions): Promise<FoldingRange[] | null>;
+    selectionRanges(positions: readonly Position[], options?: DocumentRequestOptions): Promise<SelectionRange[] | null>;
+    semanticTokens(options?: DocumentRequestOptions): Promise<SemanticTokens | null>;
+    semanticTokensDelta(previousResultId: string, options?: DocumentRequestOptions): Promise<SemanticTokens | SemanticTokensDelta | null>;
+    semanticTokensRange(range: Range, options?: DocumentRequestOptions): Promise<SemanticTokens | null>;
+    inlayHints(range: Range, options?: DocumentRequestOptions): Promise<InlayHint[] | null>;
+    resolveInlayHint(hint: InlayHint, options?: DocumentRequestOptions): Promise<InlayHint>;
+    diagnostics(previousResultId?: string, identifier?: string, options?: DocumentRequestOptions): Promise<DocumentDiagnosticReport>;
+    request<T = unknown>(method: string, params: object, options?: DocumentRequestOptions): Promise<T>;
+    close(): Promise<void>;
+    disconnect(): void;
+    private feature;
+    private resolve;
+    private perform;
+    private remember;
+    private assertOpen;
+    private assertCurrent;
+    private cancelRequests;
+}