@qvac/harness 1.0.0-rc.0 → 1.0.0-rc.2

package/dist-lib/plugins/lsp/pool.d.ts

@@ -0,0 +1,24 @@
+import { type AbortSignalLike } from '../../lib/helpers/race-abort.ts';
+import { LanguageServer, type LspServerConfig, type SpawnServer } from './server.ts';
+export interface PoolOptions {
+    readonly idleMs: number;
+    readonly startWaitMs: number;
+    readonly spawn?: SpawnServer | undefined;
+}
+export interface UseAt {
+    readonly config: LspServerConfig;
+    readonly root: string;
+    readonly signal?: AbortSignalLike | undefined;
+}
+export declare class ServerPool {
+    private readonly _options;
+    private readonly _entries;
+    private _closed;
+    constructor(options: PoolOptions);
+    use<T>(at: UseAt, work: (server: LanguageServer) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+    private _start;
+    private _started;
+    private _forget;
+    private _drop;
+}

package/dist-lib/plugins/lsp/pool.js

@@ -0,0 +1,73 @@
+import { raceAbort } from '../../lib/helpers/race-abort.js';
+import { LanguageServer } from './server.js';
+export class ServerPool {
+    _options;
+    _entries = new Map();
+    _closed = false;
+    constructor(options) {
+        this._options = options;
+    }
+    async use(at, work) {
+        if (this._closed)
+            throw new Error('the lsp plugin is closed');
+        const { config, root, signal } = at;
+        const key = `${config.language}\0${root}`;
+        const entry = this._entries.get(key) ?? this._start(key, config, root);
+        entry.busy++;
+        if (entry.timer) {
+            clearTimeout(entry.timer);
+        }
+        entry.timer = null;
+        try {
+            return await work(await this._started(entry, config, signal));
+        }
+        finally {
+            if (--entry.busy === 0 && this._entries.get(key) === entry) {
+                entry.timer = setTimeout(() => this._drop(key, entry), this._options.idleMs);
+            }
+        }
+    }
+    async close() {
+        this._closed = true;
+        const entries = [...this._entries.keys()];
+        await Promise.all(entries.map((key) => this._drop(key, this._entries.get(key))));
+    }
+    _start(key, config, root) {
+        const server = new LanguageServer(config, root, this._options.spawn);
+        const ready = server.initialize();
+        const entry = { server, ready, busy: 0, timer: null };
+        this._entries.set(key, entry);
+        ready.catch(() => server.stop());
+        server.exited.then(() => this._forget(key, entry));
+        return entry;
+    }
+    async _started(entry, config, signal) {
+        let timer;
+        const waited = new Promise((_resolve, reject) => {
+            const ms = this._options.startWaitMs;
+            const still = `the ${config.language} language server is still starting after ${ms} ms; try again shortly`;
+            timer = setTimeout(() => reject(new Error(still)), ms);
+        });
+        try {
+            await raceAbort(Promise.race([entry.ready, waited]), signal);
+            return entry.server;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    _forget(key, entry) {
+        if (this._entries.get(key) !== entry)
+            return;
+        if (entry.timer) {
+            clearTimeout(entry.timer);
+        }
+        this._entries.delete(key);
+    }
+    async _drop(key, entry) {
+        if (!entry)
+            return;
+        this._forget(key, entry);
+        await entry.server.stop();
+    }
+}

package/dist-lib/plugins/lsp/rpc.d.ts

@@ -0,0 +1,37 @@
+import type { AbortSignal } from 'bare-abort-controller';
+export interface RpcMessage {
+    id?: number | string | null;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export interface RequestOptions {
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export type NotificationHandler = (method: string, params: unknown) => void;
+export declare function encodeMessage(message: RpcMessage): Buffer;
+export declare class FrameDecoder {
+    private _buffer;
+    push(chunk: Uint8Array): RpcMessage[];
+}
+export declare class RpcConnection {
+    private readonly _write;
+    private readonly _onNotification;
+    private readonly _decoder;
+    private readonly _pending;
+    private _nextId;
+    private _closed;
+    constructor(write: (bytes: Uint8Array) => void, onNotification: NotificationHandler);
+    request(method: string, params: unknown, options?: RequestOptions): Promise<unknown>;
+    notify(method: string, params?: unknown): void;
+    receive(chunk: Uint8Array): void;
+    close(reason: Error): void;
+    private _take;
+    private _dispatch;
+    private _send;
+}

package/dist-lib/plugins/lsp/rpc.js

@@ -0,0 +1,145 @@
+import b4a from 'b4a';
+import { isRecord } from '../../lib/guards.js';
+const HEADER_END = b4a.from('\r\n\r\n');
+const CONTENT_LENGTH = /^content-length:\s*(\d+)\s*$/im;
+export function encodeMessage(message) {
+    const body = JSON.stringify({ jsonrpc: '2.0', ...message });
+    return b4a.from(`Content-Length: ${b4a.byteLength(body)}\r\n\r\n${body}`);
+}
+export class FrameDecoder {
+    _buffer = b4a.alloc(0);
+    push(chunk) {
+        this._buffer = this._buffer.byteLength ? b4a.concat([this._buffer, chunk]) : chunk;
+        const messages = [];
+        while (true) {
+            const end = b4a.indexOf(this._buffer, HEADER_END);
+            if (end === -1) {
+                break;
+            }
+            const length = CONTENT_LENGTH.exec(b4a.toString(this._buffer, 'ascii', 0, end));
+            if (!length) {
+                throw new Error('language server sent a frame with no Content-Length');
+            }
+            const start = end + HEADER_END.byteLength;
+            const stop = start + Number(length[1]);
+            if (this._buffer.byteLength < stop) {
+                break;
+            }
+            const message = JSON.parse(b4a.toString(this._buffer, 'utf8', start, stop));
+            if (isRecord(message)) {
+                messages.push(toMessage(message));
+            }
+            this._buffer = this._buffer.subarray(stop);
+        }
+        return messages;
+    }
+}
+function toMessage(value) {
+    const { id, method, params, result, error } = value;
+    return {
+        id: typeof id === 'number' || typeof id === 'string' ? id : undefined,
+        method: typeof method === 'string' ? method : undefined,
+        params,
+        result,
+        error: isRecord(error)
+            ? { code: Number(error.code), message: String(error.message) }
+            : undefined
+    };
+}
+function configurationAnswer(params) {
+    const items = isRecord(params) && Array.isArray(params.items) ? params.items : [];
+    return items.map(() => null);
+}
+export class RpcConnection {
+    _write;
+    _onNotification;
+    _decoder = new FrameDecoder();
+    _pending = new Map();
+    _nextId = 1;
+    _closed = null;
+    constructor(write, onNotification) {
+        this._write = write;
+        this._onNotification = onNotification;
+    }
+    request(method, params, options = {}) {
+        const { signal, timeoutMs } = options;
+        if (this._closed) {
+            return Promise.reject(this._closed);
+        }
+        if (signal?.aborted) {
+            return Promise.reject(abortError(signal));
+        }
+        const id = this._nextId++;
+        const answer = new Promise((resolve, reject) => this._pending.set(id, { resolve, reject }));
+        const cancel = (error) => {
+            const pending = this._take(id);
+            if (!pending) {
+                return;
+            }
+            this._send({ method: '$/cancelRequest', params: { id } });
+            pending.reject(error);
+        };
+        const onAbort = () => cancel(abortError(signal));
+        const late = () => cancel(new Error(`${method} timed out after ${timeoutMs} ms`));
+        const timer = timeoutMs ? setTimeout(late, timeoutMs) : undefined;
+        signal?.addEventListener('abort', onAbort);
+        this._send({ id, method, params });
+        return answer.finally(() => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+        });
+    }
+    notify(method, params) {
+        if (!this._closed) {
+            this._send({ method, params });
+        }
+    }
+    receive(chunk) {
+        for (const message of this._decoder.push(chunk)) {
+            this._dispatch(message);
+        }
+    }
+    close(reason) {
+        if (this._closed)
+            return;
+        this._closed = reason;
+        const pending = [...this._pending.values()];
+        this._pending.clear();
+        for (const call of pending) {
+            call.reject(reason);
+        }
+    }
+    _take(id) {
+        const pending = this._pending.get(id);
+        this._pending.delete(id);
+        return pending;
+    }
+    _dispatch(message) {
+        const { id, method } = message;
+        if (method !== undefined && id !== undefined) {
+            const result = method === 'workspace/configuration' ? configurationAnswer(message.params) : null;
+            this._send({ id, result });
+            return;
+        }
+        if (method !== undefined) {
+            this._onNotification(method, message.params);
+            return;
+        }
+        const pending = typeof id === 'number' ? this._take(id) : undefined;
+        if (!pending) {
+            return;
+        }
+        if (message.error) {
+            pending.reject(new Error(message.error.message));
+            return;
+        }
+        pending.resolve(message.result ?? null);
+    }
+    _send(message) {
+        this._write(encodeMessage(message));
+    }
+}
+function abortError(signal) {
+    const reason = signal?.reason;
+    return reason instanceof Error ? reason : new Error('aborted');
+}

package/dist-lib/plugins/lsp/server.d.ts

@@ -0,0 +1,55 @@
+import { type AbortSignalLike } from '../../lib/helpers/race-abort.ts';
+import { type RequestOptions } from './rpc.ts';
+export interface LspServerConfig {
+    readonly language: string;
+    readonly extensions: readonly string[];
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly initializationOptions?: unknown;
+}
+interface Readable {
+    on(event: 'data', listener: (chunk: Uint8Array) => void): unknown;
+}
+interface Writable {
+    write(chunk: Uint8Array): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+}
+export interface ServerProcess {
+    readonly stdin: Writable | null;
+    readonly stdout: Readable | null;
+    readonly stderr: Readable | null;
+    on(event: 'exit', listener: (code: number | null) => void): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    kill(signal?: 'SIGKILL'): unknown;
+}
+export interface SpawnOptions {
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+}
+export type SpawnServer = (command: string, args: readonly string[], options: SpawnOptions) => ServerProcess;
+export declare const spawnServer: SpawnServer;
+export declare class LanguageServer {
+    readonly config: LspServerConfig;
+    readonly root: string;
+    readonly exited: Promise<void>;
+    capabilities: Record<string, unknown>;
+    private readonly _child;
+    private readonly _rpc;
+    private readonly _open;
+    private readonly _waiters;
+    private readonly _markExited;
+    private _failure;
+    constructor(config: LspServerConfig, root: string, spawnFn?: SpawnServer);
+    initialize(): Promise<void>;
+    request(method: string, params: unknown, options?: RequestOptions): Promise<unknown>;
+    notify(method: string, params?: unknown): void;
+    withDocument<T>(uri: string, text: string, use: () => Promise<T>): Promise<T>;
+    nextDiagnostics(uri: string, waitMs: number, signal?: AbortSignalLike): Promise<unknown>;
+    stop(): Promise<void>;
+    private _spawn;
+    private _receive;
+    private _fail;
+    private _exitWithin;
+    private _onNotification;
+}
+export {};

package/dist-lib/plugins/lsp/server.js

@@ -0,0 +1,192 @@
+import { spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import process from 'process';
+import { pathToFileURL } from 'url';
+import { errorMessage, isRecord } from '../../lib/guards.js';
+import { AbortedError } from '../../lib/helpers/race-abort.js';
+import { spawnEnv } from '../../lib/helpers/spawn-path.js';
+import { RpcConnection } from './rpc.js';
+const STOP_GRACE_MS = 1_000;
+export const spawnServer = (command, args, { cwd, env }) => spawn('/bin/sh', ['-c', 'exec "$0" "$@"', command, ...args], {
+    cwd,
+    env,
+    stdio: ['pipe', 'pipe', 'pipe']
+});
+const CLIENT_CAPABILITIES = {
+    textDocument: {
+        definition: { linkSupport: true },
+        references: {},
+        hover: { contentFormat: ['plaintext', 'markdown'] },
+        documentSymbol: { hierarchicalDocumentSymbolSupport: true },
+        diagnostic: {},
+        publishDiagnostics: {}
+    },
+    workspace: { symbol: {}, workspaceFolders: true }
+};
+export class LanguageServer {
+    config;
+    root;
+    exited;
+    capabilities = {};
+    _child;
+    _rpc;
+    _open = new Map();
+    _waiters = new Map();
+    _markExited;
+    _failure = null;
+    constructor(config, root, spawnFn = spawnServer) {
+        this.config = config;
+        this.root = root;
+        let markExited = noop;
+        this.exited = new Promise((resolve) => (markExited = resolve));
+        this._markExited = markExited;
+        this._rpc = new RpcConnection((bytes) => this._child.stdin?.write(bytes), (method, params) => this._onNotification(method, params));
+        this._child = this._spawn(spawnFn);
+    }
+    async initialize() {
+        const uri = pathToFileURL(this.root).href;
+        const result = await this.request('initialize', {
+            processId: process.pid,
+            rootUri: uri,
+            workspaceFolders: [{ uri, name: path.basename(this.root) }],
+            capabilities: CLIENT_CAPABILITIES,
+            initializationOptions: this.config.initializationOptions
+        });
+        if (isRecord(result) && isRecord(result.capabilities)) {
+            this.capabilities = result.capabilities;
+        }
+        this.notify('initialized', {});
+    }
+    request(method, params, options) {
+        return this._rpc.request(method, params, options);
+    }
+    notify(method, params) {
+        this._rpc.notify(method, params);
+    }
+    async withDocument(uri, text, use) {
+        const count = this._open.get(uri) ?? 0;
+        this._open.set(uri, count + 1);
+        if (count === 0) {
+            const textDocument = { uri, languageId: this.config.language, version: 1, text };
+            this.notify('textDocument/didOpen', { textDocument });
+        }
+        try {
+            return await use();
+        }
+        finally {
+            const left = (this._open.get(uri) ?? 1) - 1;
+            if (left > 0) {
+                this._open.set(uri, left);
+            }
+            else {
+                this._open.delete(uri);
+                this.notify('textDocument/didClose', { textDocument: { uri } });
+            }
+        }
+    }
+    nextDiagnostics(uri, waitMs, signal) {
+        if (this._failure) {
+            return Promise.reject(this._failure);
+        }
+        if (signal?.aborted) {
+            return Promise.reject(new AbortedError());
+        }
+        return new Promise((resolve, reject) => {
+            const waiters = this._waiters.get(uri) ?? new Set();
+            this._waiters.set(uri, waiters);
+            const done = (diagnostics, error) => {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                waiters.delete(done);
+                if (waiters.size === 0) {
+                    this._waiters.delete(uri);
+                }
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve(diagnostics);
+                }
+            };
+            const onAbort = () => done(null, new AbortedError());
+            const timer = setTimeout(() => done(null), waitMs);
+            signal?.addEventListener('abort', onAbort, { once: true });
+            waiters.add(done);
+        });
+    }
+    async stop() {
+        if (this._failure)
+            return;
+        await this.request('shutdown', undefined, { timeoutMs: STOP_GRACE_MS }).catch(noop);
+        this.notify('exit');
+        if (!(await this._exitWithin(STOP_GRACE_MS))) {
+            this._child.kill('SIGKILL');
+        }
+        await this.exited;
+    }
+    _spawn(spawnFn) {
+        const { command, args = [] } = this.config;
+        const child = spawnFn(command, args, {
+            cwd: this.root,
+            env: spawnEnv(process.env, process.platform)
+        });
+        child.on('error', (error) => this._fail(`could not start: ${errorMessage(error)}`));
+        child.on('exit', (code) => this._fail(exitReason(command, code)));
+        child.stdin?.on('error', noop);
+        child.stderr?.on('data', noop);
+        child.stdout?.on('data', (chunk) => this._receive(chunk));
+        return child;
+    }
+    _receive(chunk) {
+        try {
+            this._rpc.receive(chunk);
+        }
+        catch (error) {
+            this._rpc.close(new Error(`the ${this.config.language} language server: ${errorMessage(error)}`));
+            this._child.kill('SIGKILL');
+        }
+    }
+    _fail(reason) {
+        if (this._failure)
+            return;
+        this._failure = new Error(`the ${this.config.language} language server ${reason}`);
+        this._rpc.close(this._failure);
+        for (const waiter of [...this._waiters.values()].flatMap((set) => [...set])) {
+            waiter(null, this._failure);
+        }
+        this._markExited();
+    }
+    async _exitWithin(ms) {
+        let timer;
+        const late = new Promise((resolve) => (timer = setTimeout(() => resolve(false), ms)));
+        const exited = await Promise.race([this.exited.then(() => true), late]);
+        clearTimeout(timer);
+        return exited;
+    }
+    _onNotification(method, params) {
+        if (method !== 'textDocument/publishDiagnostics' || !isRecord(params)) {
+            return;
+        }
+        const uri = typeof params.uri === 'string' ? params.uri : '';
+        for (const waiter of [...(this._waiters.get(uri) ?? [])]) {
+            waiter(params.diagnostics);
+        }
+    }
+}
+function exitReason(command, code) {
+    if (code !== 126 && code !== 127) {
+        return `exited (code ${code})`;
+    }
+    let what = 'is not executable';
+    try {
+        if (fs.statSync(command).isDirectory()) {
+            what = 'is a directory';
+        }
+    }
+    catch {
+        what = 'was not found';
+    }
+    return `could not start: ${command} ${what}`;
+}
+function noop() { }

package/dist-lib/plugins/lsp/tool.d.ts

@@ -0,0 +1,12 @@
+import type { ToolDefinition } from '../../lib/contract/index.ts';
+import { type Realpath } from '../../lib/tools/fs/scope.ts';
+import type { ServerPool } from './pool.ts';
+import type { LspServerConfig } from './server.ts';
+export interface LspToolOptions {
+    readonly pool: ServerPool;
+    readonly servers: readonly LspServerConfig[];
+    readonly requestTimeoutMs: number;
+    readonly deniedRoots?: readonly string[] | undefined;
+    readonly realpath?: Realpath | undefined;
+}
+export declare function createLspTool(options: LspToolOptions): ToolDefinition;