@effected/lsp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+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/LspFrame.js

@@ -0,0 +1,277 @@
+import { Effect, Result, Schema, Stream } from "effect";
+
+//#region src/LspFrame.ts
+/** The longest header block, terminator excluded, the decoder buffers before failing `HeaderTooLarge`. */
+const MAX_HEADER_BYTES = 8192;
+/** How many bytes of an offending header an error echoes. */
+const EXCERPT_BYTES = 80;
+const CR = 13;
+const LF = 10;
+const EMPTY = /* @__PURE__ */ new Uint8Array(0);
+const END = /* @__PURE__ */ new Uint8Array(0);
+const encoder = new TextEncoder();
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+const lenient = new TextDecoder("utf-8");
+const JsonValue = Schema.fromJsonString(Schema.Unknown);
+const decodeJson = Schema.decodeUnknownResult(JsonValue);
+const encodeJson = Schema.encodeUnknownSync(JsonValue);
+const FIELD_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const DIGITS = /^[0-9]+$/;
+/**
+* Why a byte stream is not a sequence of LSP base-protocol frames.
+*
+* @remarks
+* - `MissingContentLength`: the header block has no `Content-Length` field.
+* - `InvalidContentLength`: a `Content-Length` that is not one decimal,
+*   non-negative safe integer, or a second `Content-Length` field.
+* - `InvalidHeader`: a header line that is not `Name: value`, or a header
+*   byte outside ASCII. A server that writes a log line to stdout before its
+*   first frame lands here, because the stray text joins the header block.
+* - `HeaderTooLarge`: more than 8 KiB without the `\r\n\r\n` terminator. The
+*   decoder refuses to buffer an unterminated header without bound.
+* - `InvalidBody`: the body is not valid UTF-8 or not valid JSON.
+* - `Truncated`: the input ended inside a frame.
+*
+* @public
+*/
+const LspFrameErrorCode = Schema.Literals([
+	"MissingContentLength",
+	"InvalidContentLength",
+	"InvalidHeader",
+	"HeaderTooLarge",
+	"InvalidBody",
+	"Truncated"
+]);
+/**
+* A byte stream that is not a sequence of LSP base-protocol frames.
+*
+* @remarks
+* `offset` is the stream position of the offending frame's first byte, so a
+* caller can point at it; `excerpt` echoes up to 80 bytes of the frame's
+* start, JSON-quoted so control characters stay visible; `cause` carries the
+* UTF-8 or JSON failure of an `InvalidBody` as the original value, never a
+* stringified copy. `message` is derived from those fields when read.
+*
+* @public
+*/
+var LspFrameError = class extends Schema.TaggedError()("LspFrameError", {
+	/** Which rule the frame broke; see {@link (LspFrameErrorCode:variable)}. */
+	code: LspFrameErrorCode,
+	/** The stream position of the offending frame's first byte. */
+	offset: Schema.Number,
+	/** Up to 80 bytes of the frame's start, JSON-quoted. */
+	excerpt: Schema.optionalKey(Schema.String),
+	/** The UTF-8 or JSON failure behind an `InvalidBody`. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		const at = `the LSP frame at byte ${this.offset}`;
+		const detail = this.code === "MissingContentLength" ? `${at} has no Content-Length header` : this.code === "InvalidContentLength" ? `${at} has a Content-Length that is not one non-negative decimal integer` : this.code === "InvalidHeader" ? `${at} has a header line that is not an ASCII "Name: value" field` : this.code === "HeaderTooLarge" ? `${at} has no \\r\\n\\r\\n header terminator within ${MAX_HEADER_BYTES} bytes` : this.code === "InvalidBody" ? `${at} has a body that is not UTF-8 JSON` : `the input ended inside ${at}`;
+		return this.excerpt === void 0 ? detail : `${detail}: ${this.excerpt}`;
+	}
+};
+const excerptOf = (bytes, start) => JSON.stringify(lenient.decode(bytes.subarray(start, Math.min(bytes.length, start + EXCERPT_BYTES))));
+const frameError = (code, offset, bytes, start) => LspFrameError.make({
+	code,
+	offset,
+	excerpt: excerptOf(bytes, start)
+});
+/** The index of the `\r\n\r\n` that ends the header starting at `from`, or -1, scanning at most the header cap. */
+const headerEnd = (bytes, from) => {
+	const limit = Math.min(bytes.length - 3, from + MAX_HEADER_BYTES + 1);
+	for (let i = from; i < limit; i++) if (bytes[i] === CR && bytes[i + 1] === LF && bytes[i + 2] === CR && bytes[i + 3] === LF) return i;
+	return -1;
+};
+const isOptionalWhitespace = (code) => code === 32 || code === 9;
+/**
+* `value` without leading and trailing spaces and tabs (a header value's optional whitespace). An index scan, not a
+* regex: a trailing-whitespace pattern backtracks quadratically over a long run of whitespace followed by anything
+* else, and header bytes are untrusted input.
+*/
+const trimOptionalWhitespace = (value) => {
+	let start = 0;
+	let end = value.length;
+	while (start < end && isOptionalWhitespace(value.charCodeAt(start))) start++;
+	while (end > start && isOptionalWhitespace(value.charCodeAt(end - 1))) end--;
+	return value.slice(start, end);
+};
+/** The `Content-Length` of the header block `bytes[from, to)`, or the code it breaks. */
+const contentLength = (bytes, from, to) => {
+	let text = "";
+	for (let i = from; i < to; i++) {
+		const byte = bytes[i] ?? 0;
+		if (byte > 127) return "InvalidHeader";
+		text += String.fromCharCode(byte);
+	}
+	if (text === "") return "MissingContentLength";
+	let length;
+	for (const line of text.split("\r\n")) {
+		const colon = line.indexOf(":");
+		if (colon <= 0 || line.includes("\r") || line.includes("\n")) return "InvalidHeader";
+		const name = line.slice(0, colon);
+		if (!FIELD_NAME.test(name)) return "InvalidHeader";
+		if (name.toLowerCase() !== "content-length") continue;
+		const value = trimOptionalWhitespace(line.slice(colon + 1));
+		if (length !== void 0 || !DIGITS.test(value)) return "InvalidContentLength";
+		const parsed = Number(value);
+		if (!Number.isSafeInteger(parsed)) return "InvalidContentLength";
+		length = parsed;
+	}
+	return length ?? "MissingContentLength";
+};
+const concatBytes = (left, right) => {
+	if (left.length === 0) return right;
+	if (right.length === 0) return left;
+	const joined = new Uint8Array(left.length + right.length);
+	joined.set(left, 0);
+	joined.set(right, left.length);
+	return joined;
+};
+const decodeResult = (bytes, offset = 0) => {
+	const messages = [];
+	let position = 0;
+	while (position < bytes.length) {
+		const start = position;
+		const end = headerEnd(bytes, start);
+		if (end === -1 ? bytes.length - start - 3 > MAX_HEADER_BYTES : end - start > MAX_HEADER_BYTES) return Result.fail(frameError("HeaderTooLarge", offset + start, bytes, start));
+		if (end === -1) break;
+		const length = contentLength(bytes, start, end);
+		if (typeof length === "string") return Result.fail(frameError(length, offset + start, bytes, start));
+		const bodyStart = end + 4;
+		if (bodyStart + length > bytes.length) break;
+		const body = bytes.subarray(bodyStart, bodyStart + length);
+		let text;
+		try {
+			text = utf8.decode(body);
+		} catch (cause) {
+			return Result.fail(LspFrameError.make({
+				code: "InvalidBody",
+				offset: offset + start,
+				excerpt: excerptOf(bytes, start),
+				cause
+			}));
+		}
+		const value = decodeJson(text);
+		if (Result.isFailure(value)) return Result.fail(LspFrameError.make({
+			code: "InvalidBody",
+			offset: offset + start,
+			excerpt: excerptOf(bytes, start),
+			cause: value.failure
+		}));
+		messages.push(value.success);
+		position = bodyStart + length;
+	}
+	return Result.succeed({
+		messages,
+		rest: bytes.slice(position)
+	});
+};
+const decodeAllResult = (input) => {
+	const bytes = typeof input === "string" ? encoder.encode(input) : input;
+	return Result.flatMap(decodeResult(bytes), ({ messages, rest }) => rest.length === 0 ? Result.succeed(messages) : Result.fail(frameError("Truncated", bytes.length - rest.length, rest, 0)));
+};
+/**
+* The LSP base protocol's framing: a `Content-Length` header block, a blank
+* line, and a UTF-8 JSON body of exactly that many bytes.
+*
+* @remarks
+* `Content-Length` counts **bytes**, never characters. A hand-rolled frame
+* that writes `body.length` is correct for ASCII and wrong by one for every
+* extra byte of a multi-byte character, so the server reads into the next
+* frame and the session fails far from the cause; {@link LspFrame.encode}
+* counts the UTF-8 encoding.
+*
+* The decoder is incremental and pure: {@link LspFrame.decodeResult} takes a
+* buffer and returns every complete frame plus the bytes of an incomplete
+* trailing one, so a chunk boundary may fall anywhere — inside a header,
+* inside a body, inside a multi-byte character — and one chunk may carry
+* several frames. {@link LspFrame.decodeStream} threads that state across a
+* `Stream` of chunks.
+*
+* Header fields end `\r\n` and the block ends `\r\n\r\n`; field names are
+* case-insensitive; unknown fields such as `Content-Type` are accepted and
+* ignored. A header longer than 8 KiB without its terminator fails rather
+* than buffering without bound.
+*
+* @example
+* ```ts
+* import { LspFrame } from "@effected/lsp";
+* import { Result } from "effect";
+*
+* const bytes = LspFrame.encode({ jsonrpc: "2.0", method: "exit" });
+* const decoded = LspFrame.decodeAllResult(bytes);
+* console.log(Result.isSuccess(decoded) ? decoded.success : decoded.failure.message);
+* // => [ { jsonrpc: '2.0', method: 'exit' } ]
+* ```
+*
+* @public
+*/
+var LspFrame = class {
+	constructor() {}
+	/**
+	* Frame one message: `Content-Length: N\r\n\r\n` followed by its JSON text,
+	* where `N` is the UTF-8 byte length of that text.
+	*
+	* @remarks
+	* A value JSON cannot encode (a `bigint`, a cycle) is a caller bug and
+	* throws; nothing a server sends reaches this function.
+	*/
+	static encode(message) {
+		const body = encoder.encode(encodeJson(message));
+		const header = encoder.encode(`Content-Length: ${body.length}\r\n\r\n`);
+		return concatBytes(header, body);
+	}
+	/**
+	* Decode every complete frame at the front of `bytes`, returning their
+	* bodies and the bytes of an incomplete trailing frame.
+	*
+	* @remarks
+	* The sync primitive; {@link LspFrame.decode} is its spanned `Effect`
+	* form. `offset` is the stream position of `bytes[0]` (default 0), so an
+	* error names a stream position rather than a buffer index. To decode a
+	* stream by hand, keep `rest`, prepend it to the next chunk, and advance
+	* `offset` by the bytes consumed.
+	*/
+	static decodeResult(bytes, offset) {
+		return decodeResult(bytes, offset);
+	}
+	/** The `Effect` form of {@link LspFrame.decodeResult}, behind the `LspFrame.decode` span. */
+	static decode = Effect.fn("LspFrame.decode")((bytes, offset) => Effect.fromResult(decodeResult(bytes, offset)));
+	/**
+	* Decode a complete buffer — a collected stdout — into its messages.
+	*
+	* @remarks
+	* A string is UTF-8 encoded first, so its byte counts are honoured.
+	* Leftover bytes after the last complete frame fail `Truncated`. The sync
+	* primitive; {@link LspFrame.decodeAll} is the spanned `Effect` form.
+	*/
+	static decodeAllResult(input) {
+		return decodeAllResult(input);
+	}
+	/** The `Effect` form of {@link LspFrame.decodeAllResult}, behind the `LspFrame.decodeAll` span. */
+	static decodeAll = Effect.fn("LspFrame.decodeAll")((input) => Effect.fromResult(decodeAllResult(input)));
+	/**
+	* Decode a stream of byte chunks into a stream of message bodies.
+	*
+	* @remarks
+	* Chunk boundaries may fall anywhere. A malformed frame fails the stream
+	* with an {@link LspFrameError}; a stream that ends inside a frame fails
+	* `Truncated`, so a server that dies mid-write is never read as a clean end.
+	*/
+	static decodeStream(self) {
+		return Stream.concat(self, Stream.succeed(END)).pipe(Stream.mapAccumEffect(() => ({
+			rest: EMPTY,
+			offset: 0
+		}), (state, chunk) => {
+			if (chunk === END) return state.rest.length === 0 ? Effect.succeed([state, []]) : Effect.fail(frameError("Truncated", state.offset, state.rest, 0));
+			const buffer = concatBytes(state.rest, chunk);
+			return Effect.map(Effect.fromResult(decodeResult(buffer, state.offset)), ({ messages, rest }) => [{
+				rest,
+				offset: state.offset + buffer.length - rest.length
+			}, messages]);
+		}));
+	}
+};
+
+//#endregion
+export { LspFrame, LspFrameError, LspFrameErrorCode };

package/LspProbe.js

@@ -0,0 +1,126 @@
+import { LspTestFailure } from "./LspTestFailure.js";
+import { truncate } from "./internal/messages.js";
+import { spawnParts } from "./LspProcess.js";
+import { Duration, Effect, Ref } from "effect";
+
+//#region src/LspProbe.ts
+/**
+* The smallest proof that an installed Language Server bin boots: the whole
+* LSP lifecycle over stdio, and exit code 0.
+*
+* @remarks
+* The exchange is `initialize` (id 1), its response, the `initialized`
+* notification, `shutdown` (id 2), its response, and the `exit`
+* notification; then the probe waits for the server to exit. The caller
+* asserts `response.error === undefined`, `exitCode === 0` and, for a clean
+* boot, `stderr === ""` — this is the LSP half of a packed-install proof, the
+* twin of `@effected/mcp/testing`'s `McpProbe`. Every frame is encoded with
+* `LspFrame.encode` from the main entry, so `Content-Length` counts bytes.
+*
+* - `initialized` is sent because the specification requires it before any
+*   other request, `shutdown` included; it is skipped only when `initialize`
+*   answered with an error, and the sequence still ends `shutdown`, `exit`.
+* - Stdin stays open after `exit`. The server must terminate itself on
+*   `exit`, as an editor never closes the pipe first; a server that waits
+*   for stdin to close fails with `TimedOut` instead of passing.
+* - A request the server sends (`client/registerCapability`, say) is
+*   recorded in `messages` and never answered.
+* - Never hangs: stdout that ends before a response fails `StreamEnded` with
+*   the exit code and stderr; bytes that are not a frame fail `InvalidFrame`;
+*   and the whole exchange runs under `timeout` (30 seconds by default),
+*   which fails `TimedOut` naming the step it was waiting on. The child is
+*   killed when the probe's scope closes.
+* - The timeout reads `Clock`, so under `it.effect`'s virtual clock it
+*   never fires on its own: run the probe under `it.live`.
+*
+* @example
+* ```ts
+* import { LspProbe } from "@effected/lsp/testing";
+* import { Effect } from "effect";
+* import { ChildProcess } from "effect/process";
+*
+* const program = Effect.gen(function* () {
+* 	const probe = yield* LspProbe.initialize(ChildProcess.make(process.execPath, ["./bin/lsp.js", "--stdio"]));
+* 	// A clean boot: no JSON-RPC error, exit code 0, empty stderr.
+* 	return probe.response.error === undefined && probe.exitCode === 0 && probe.stderr === "";
+* });
+* // Requires a `ChildProcessSpawner` from the platform layer.
+* ```
+*
+* @public
+*/
+var LspProbe = class {
+	constructor() {}
+	/**
+	* Spawn `command`, run `initialize` → `initialized` → `shutdown` → `exit`,
+	* and collect every server message, stderr and the exit code.
+	*/
+	static initialize = Effect.fn("LspProbe.initialize")(function* (command, options = {}) {
+		return yield* Effect.scoped(probe(command, options));
+	});
+};
+const probe = (command, options) => Effect.gen(function* () {
+	const stage = yield* Ref.make("the id-1 initialize response");
+	const server = yield* spawnParts(command, {
+		pending: Ref.get(stage),
+		settle: true
+	});
+	const messages = [];
+	const responseTo = (id) => Effect.map(server.readUntilResponse(id), ({ response, seen }) => {
+		messages.push(...seen);
+		return response;
+	});
+	return yield* Effect.gen(function* () {
+		yield* server.send({
+			jsonrpc: "2.0",
+			id: 1,
+			method: "initialize",
+			params: {
+				processId: options.processId ?? null,
+				rootUri: options.rootUri ?? null,
+				capabilities: options.capabilities ?? {},
+				...options.initializationOptions === void 0 ? {} : { initializationOptions: options.initializationOptions }
+			}
+		});
+		const response = yield* responseTo(1);
+		if (response.error === void 0) yield* server.send({
+			jsonrpc: "2.0",
+			method: "initialized",
+			params: {}
+		});
+		yield* Ref.set(stage, "the id-2 shutdown response");
+		yield* server.send({
+			jsonrpc: "2.0",
+			id: 2,
+			method: "shutdown"
+		});
+		const shutdown = yield* responseTo(2);
+		yield* Ref.set(stage, "the server's exit after the exit notification");
+		yield* server.send({
+			jsonrpc: "2.0",
+			method: "exit"
+		});
+		const exitCode = yield* server.exitCode;
+		yield* Ref.set(stage, "the end of stdout after the server exited");
+		while (true) if (!(yield* Effect.catchIf(Effect.map(server.nextMessage, (message) => messages.push(message) > 0), (failure) => failure.reason === "StreamEnded", () => Effect.succeed(false)))) break;
+		return {
+			response,
+			shutdown,
+			messages,
+			stderr: yield* server.stderrFinal,
+			exitCode
+		};
+	}).pipe(Effect.timeoutOrElse({
+		duration: options.timeout ?? Duration.seconds(30),
+		orElse: () => Effect.gen(function* () {
+			const text = yield* server.stderrSoFar;
+			return yield* new LspTestFailure({
+				reason: "TimedOut",
+				message: `timed out waiting for ${yield* Ref.get(stage)}; stderr so far: ${text === "" ? "(empty)" : truncate(text)}`
+			});
+		})
+	}));
+});
+
+//#endregion
+export { LspProbe };