@effected/lsp 0.0.0-stage → 0.1.0

package/testing.d.ts

@@ -0,0 +1,307 @@
+import { Duration, Effect, PlatformError, Schema, Scope } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+//#region src/LspMessage.d.ts
+/**
+ * A JSON-RPC 2.0 message as an LSP frame body carries it: a request (an `id`
+ * and a `method`), a notification (a `method`, no `id`) or a response (an
+ * `id` and either `result` or `error`).
+ *
+ * @remarks
+ * Structural on purpose. Every field but `jsonrpc` is optional, because one
+ * shape describes all three kinds and the reader distinguishes them by which
+ * fields are present: `method` and `id` is a request, `method` alone is a
+ * notification, `id` without `method` is a response. A decoded frame body is
+ * `unknown` until a caller has checked it is one of these.
+ *
+ * @public
+ */
+interface LspMessage {
+  /** Always `"2.0"`. */
+  readonly jsonrpc: "2.0";
+  /** Present on a request and a response; `null` on a response to a request whose id could not be read. */
+  readonly id?: number | string | null;
+  /** Present on a request and a notification. */
+  readonly method?: string;
+  /** A request's or notification's parameters. */
+  readonly params?: unknown;
+  /** A successful response's result; `null` is a valid result (`shutdown` answers it). */
+  readonly result?: unknown;
+  /** A failed response's error. */
+  readonly error?: {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+  };
+}
+//#endregion
+//#region src/LspTestFailure.d.ts
+declare const LspTestFailure_base: Schema.Class<LspTestFailure, Schema.TaggedStruct<"LspTestFailure", {
+  /** Which failure occurred; see the list above. */
+  readonly reason: Schema.Literals<readonly ["StreamEnded", "InvalidFrame", "NotJsonRpc", "TimedOut"]>;
+  /** A human-readable description of what went wrong. */
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Why {@link LspProbe.initialize} could not prove a Language Server boots.
+ *
+ * @remarks
+ * - `StreamEnded`: the server's stdout ended before the response the probe
+ *   was waiting for, usually because it exited; a stream that ended inside a
+ *   frame lands here too. The message carries the exit code and stderr.
+ * - `InvalidFrame`: stdout carried bytes that are not an LSP frame — most
+ *   often a log line written to stdout, which is the protocol wire. The
+ *   message carries the frame error, excerpt included.
+ * - `NotJsonRpc`: a well-framed body that is not a JSON-RPC 2.0 message.
+ * - `TimedOut`: the exchange outlived `LspProbeOptions.timeout`. The message
+ *   names the step the probe was waiting on and the stderr so far; a server
+ *   that ignores `exit` and waits for stdin to close fails here.
+ *
+ * A JSON-RPC error answering `initialize` or `shutdown` is not a failure: it
+ * is returned in the result for the caller to assert on.
+ *
+ * @public
+ */
+export declare class LspTestFailure extends LspTestFailure_base {}
+//#endregion
+//#region src/LspProbe.d.ts
+/**
+ * Options for {@link LspProbe.initialize}.
+ *
+ * @public
+ */
+interface LspProbeOptions {
+  /** `initialize`'s `rootUri`. Defaults to `null`: no workspace folder. */
+  readonly rootUri?: string | null;
+  /** `initialize`'s `processId`. Defaults to `null`, so the server never watches a client process for liveness. */
+  readonly processId?: number | null;
+  /** The client capabilities `initialize` announces. Defaults to `{}`. */
+  readonly capabilities?: {
+    readonly [key: string]: unknown;
+  };
+  /** `initialize`'s `initializationOptions`; omitted from the request unless given. */
+  readonly initializationOptions?: unknown;
+  /** A ceiling over the whole exchange, spawn excluded. Defaults to 30 seconds. */
+  readonly timeout?: Duration.Input;
+}
+/**
+ * What {@link LspProbe.initialize} observed.
+ *
+ * @public
+ */
+interface LspProbeResult {
+  /** The id-1 `initialize` response. A refused handshake is still a response: assert `response.error === undefined`. */
+  readonly response: LspMessage;
+  /** The id-2 `shutdown` response; a clean server answers `result: null`. */
+  readonly shutdown: LspMessage;
+  /** Every message the server sent, in order: responses, notifications, and requests the probe left unanswered. */
+  readonly messages: ReadonlyArray<LspMessage>;
+  /** Everything the server wrote to stderr; a clean boot leaves it empty. */
+  readonly stderr: string;
+  /** The server's exit code; 0 means `exit` arrived after `shutdown`, as the specification requires. */
+  readonly exitCode: number;
+}
+/**
+ * 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
+ */
+export declare class LspProbe {
+  private constructor();
+  /**
+   * Spawn `command`, run `initialize` → `initialized` → `shutdown` → `exit`,
+   * and collect every server message, stderr and the exit code.
+   */
+  static readonly initialize: (command: ChildProcess.Command, options?: LspProbeOptions) => Effect.Effect<LspProbeResult, LspTestFailure | PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
+}
+//#endregion
+//#region src/LspProcess.d.ts
+/**
+ * Options for {@link LspProcess.stderrUntil}.
+ *
+ * @public
+ */
+interface LspProcessStderrUntilOptions {
+  /**
+   * How long to wait for the predicate to hold before failing with
+   * `TimedOut`. Real time: under `it.effect`'s `TestClock` it never fires,
+   * so a test that waits on stderr runs under `it.live`. Keep it below the
+   * test runner's own timeout, or the runner kills the test first.
+   */
+  readonly timeout: Duration.Input;
+}
+/**
+ * A spawned Language Server bin a test writes `Content-Length` frames to
+ * while it runs — the LSP twin of `@effected/mcp/testing`'s `McpProcess`.
+ *
+ * @remarks
+ * Build the command in the test file with `execPath` and an explicit `env`:
+ * `ChildProcess.make(process.execPath, [bin, "--stdio"], { env })`. The child
+ * lives for the scope `spawn` runs in, and is killed when it closes.
+ *
+ * - `nextMessage` fails `StreamEnded` once stdout ends — a stream that ends
+ *   inside a frame included — so a child that exits early fails the test
+ *   instead of hanging it. Bytes that are not a frame fail `InvalidFrame`; a
+ *   frame whose body is not a JSON-RPC 2.0 message fails `NotJsonRpc`.
+ * - `send` writes one frame with `LspFrame.encode` from the main entry, so `Content-Length`
+ *   counts bytes; `sendRaw` writes a string or bytes exactly as given, for a
+ *   malformed frame or one frame split across writes.
+ * - `readUntilResponse` reads past notifications and server requests to the
+ *   response with the matching id, and returns what it saw.
+ * - `closeStdin` is `Queue.end`, so every frame already sent is delivered
+ *   before stdin closes. The specification makes a server exit on the `exit`
+ *   notification with stdin still open; close stdin only to test a client
+ *   disconnect.
+ * - Every stdout byte is kept, apart from the decoder: `stdoutSoFar` and
+ *   `stdoutFinal` return it raw, and `assertOnlyFrames` proves it held
+ *   nothing but well-formed frames, even after the decoder has failed.
+ *
+ * @example
+ * ```ts
+ * import { LspProcess } from "@effected/lsp/testing";
+ * import { Effect } from "effect";
+ * import { ChildProcess } from "effect/process";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const server = yield* LspProcess.spawn(ChildProcess.make(process.execPath, ["./bin/lsp.js", "--stdio"]));
+ * 	yield* server.send({ jsonrpc: "2.0", id: 1, method: "initialize", params: { processId: null, rootUri: null, capabilities: {} } });
+ * 	const { response } = yield* server.readUntilResponse(1);
+ * 	yield* server.send({ jsonrpc: "2.0", method: "initialized", params: {} });
+ * 	yield* server.send({ jsonrpc: "2.0", id: 2, method: "shutdown" });
+ * 	yield* server.readUntilResponse(2);
+ * 	yield* server.send({ jsonrpc: "2.0", method: "exit" });
+ * 	const exitCode = yield* server.exitCode;
+ * 	// Stdout carried nothing but frames: no stray log line before, between or after them.
+ * 	yield* server.assertOnlyFrames;
+ * 	return { response, exitCode };
+ * }).pipe(Effect.scoped);
+ * // Requires a `ChildProcessSpawner` from the platform layer.
+ * ```
+ *
+ * @public
+ */
+export declare class LspProcess {
+  /**
+   * Write one message to the child's stdin as a `Content-Length` frame.
+   *
+   * @remarks
+   * Never fails. A frame sent after `closeStdin` is dropped, and a write the
+   * child can no longer receive fails the stdin pump instead; the next
+   * `StreamEnded` message names that failure.
+   */
+  readonly send: (message: unknown) => Effect.Effect<void>;
+  /**
+   * Write `bytes` to the child's stdin exactly as given: a string as UTF-8,
+   * bytes unchanged, with no framing added.
+   *
+   * @remarks
+   * For frames `send` cannot produce: a header without `Content-Length`, a
+   * body that is not JSON, or one frame split across several writes,
+   * including mid-character by passing bytes. Never fails, on the same terms
+   * as `send`.
+   */
+  readonly sendRaw: (bytes: string | Uint8Array) => Effect.Effect<void>;
+  /**
+   * The next message on stdout.
+   *
+   * @remarks
+   * Fails `StreamEnded` once stdout ends, including inside a frame;
+   * `InvalidFrame` when stdout carried bytes that are not a frame (a log
+   * line on the wire); `NotJsonRpc` for a well-framed body that is not a
+   * JSON-RPC 2.0 message. A frame failure is final: every later read fails
+   * the same way.
+   */
+  readonly nextMessage: Effect.Effect<LspMessage, LspTestFailure>;
+  /** Read messages up to and including the response with this id; `seen` holds every message read, the response last. */
+  readonly readUntilResponse: (id: string | number) => Effect.Effect<{
+    readonly response: LspMessage;
+    readonly seen: ReadonlyArray<LspMessage>;
+  }, LspTestFailure>;
+  /** End stdin after every frame already sent. */
+  readonly closeStdin: Effect.Effect<void>;
+  /** Wait for the child to exit. */
+  readonly exitCode: Effect.Effect<number, PlatformError.PlatformError>;
+  /** Everything written to stderr so far. */
+  readonly stderrSoFar: Effect.Effect<string>;
+  /**
+   * Wait until everything written to stderr so far satisfies `predicate`,
+   * and return that text.
+   *
+   * @remarks
+   * Event-driven: the predicate is checked against the current text at once,
+   * then again on every chunk the child writes, never on a polling timer.
+   * Fails `StreamEnded` when stderr ends (the child exited) without the
+   * predicate holding, and `TimedOut` once `options.timeout` passes; both
+   * messages carry the stderr seen so far. Reach for it whenever a report
+   * lands on a later tick than the messages a test reads, such as a crash
+   * guard's report once the server is serving. `options.timeout` is real
+   * time: run the test under `it.live`.
+   */
+  readonly stderrUntil: (predicate: (stderr: string) => boolean, options: LspProcessStderrUntilOptions) => Effect.Effect<string, LspTestFailure>;
+  /** Everything written to stderr, once stderr has ended. Waits for the child to exit. */
+  readonly stderrFinal: Effect.Effect<string>;
+  /** Every byte written to stdout so far, undecoded. */
+  readonly stdoutSoFar: Effect.Effect<Uint8Array>;
+  /** Every byte written to stdout, once stdout has ended. Waits for the child to exit. */
+  readonly stdoutFinal: Effect.Effect<Uint8Array>;
+  /**
+   * Wait for stdout to end, then prove it carried nothing but well-formed
+   * `Content-Length` frames of JSON-RPC 2.0 messages, and return those
+   * messages.
+   *
+   * @remarks
+   * The stdout hygiene check: a stray byte before the first frame, between
+   * two frames or after the last fails `InvalidFrame`, whose message names
+   * the stream offset and quotes the offending bytes; so does a stream that
+   * ends inside a frame. A well-framed body that is not JSON-RPC fails
+   * `NotJsonRpc`. It reads the raw capture, not `nextMessage`'s queue, so
+   * the messages a test already read are still checked. It waits for the
+   * child to exit: send `exit` (or close stdin) first.
+   */
+  readonly assertOnlyFrames: Effect.Effect<ReadonlyArray<LspMessage>, LspTestFailure>;
+  private constructor();
+  /** Spawn `command` for the life of the current scope. */
+  static readonly spawn: (command: ChildProcess.Command) => Effect.Effect<LspProcess, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner | Scope.Scope>;
+}
+//#endregion
+export type { LspMessage, LspProbeOptions, LspProbeResult, LspProcessStderrUntilOptions };
+//# sourceMappingURL=testing.d.ts.map

package/testing.js

@@ -0,0 +1,5 @@
+import { LspTestFailure } from "./LspTestFailure.js";
+import { LspProcess } from "./LspProcess.js";
+import { LspProbe } from "./LspProbe.js";
+
+export { LspProbe, LspProcess, LspTestFailure };

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.59.1"
+    }
+  ]
+}