@effected/lsp 0.4.0 → 0.6.0

package/LspFrame.js

@@ -1,6 +1,6 @@
 import { Effect, Result, Schema, Stream } from "effect";
 
-//#region src/LspFrame.ts
+// 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. */
@@ -273,5 +273,4 @@ var LspFrame = class {
 	}
 };
 
-//#endregion
 export { LspFrame, LspFrameError, LspFrameErrorCode };

package/LspProbe.js

@@ -3,7 +3,7 @@ import { truncate } from "./internal/messages.js";
 import { spawnParts } from "./LspProcess.js";
 import { Duration, Effect, Ref } from "effect";
 
-//#region src/LspProbe.ts
+// src/LspProbe.ts
 /**
 * The smallest proof that an installed Language Server bin boots: the whole
 * LSP lifecycle over stdio, and exit code 0.
@@ -122,5 +122,4 @@ const probe = (command, options) => Effect.gen(function* () {
 	}));
 });
 
-//#endregion
 export { LspProbe };

package/LspProcess.js

@@ -4,7 +4,7 @@ import { isLspMessage, notJsonRpc, truncate } from "./internal/messages.js";
 import { Cause, Deferred, Duration, Effect, Option, Queue, Ref, Result, Stream, SubscriptionRef } from "effect";
 import { ChildProcessSpawner } from "effect/process";
 
-//#region src/LspProcess.ts
+// src/LspProcess.ts
 const concat = (chunks) => {
 	const bytes = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.length, 0));
 	let at = 0;
@@ -278,5 +278,4 @@ const spawnParts = (command, options = {}) => Effect.gen(function* () {
 	};
 });
 
-//#endregion
 export { LspProcess, spawnParts };

package/LspStdio.js

@@ -1,7 +1,7 @@
 import { LaunchFailed } from "./internal/LaunchFailed.js";
 import { Cause, Effect, Exit, References, Runtime } from "effect";
 
-//#region src/LspStdio.ts
+// src/LspStdio.ts
 /**
 * Run an Effect Language Server over stdio without ever writing a log line or
 * a failure report onto stdout, which is the LSP wire, and exit with the code
@@ -113,5 +113,4 @@ var LspStdio = class LspStdio {
 	}
 };
 
-//#endregion
 export { LspStdio };

package/LspTestFailure.js

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 
-//#region src/LspTestFailure.ts
+// src/LspTestFailure.ts
 /**
 * Why {@link LspProbe.initialize} could not prove a Language Server boots.
 *
@@ -33,5 +33,4 @@ var LspTestFailure = class extends Schema.TaggedError()("LspTestFailure", {
 	message: Schema.String
 }) {};
 
-//#endregion
 export { LspTestFailure };

package/LspUri.js

@@ -0,0 +1,266 @@
+import { Option } from "effect";
+
+// src/LspUri.ts
+const FILE_SCHEME = /^file:/i;
+const DRIVE = /^[A-Za-z][:|]$/;
+const DRIVE_PATH = /^[A-Za-z]:(?:\/|$)/;
+const HOSTNAME = /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/;
+const EXTRA = /[!'()*]/g;
+/**
+* Remove `.` and `..` segments (RFC 3986 §5.2.4) from the segments after a
+* root, never climbing above it. A `.` or `..` in the last position leaves an
+* empty segment behind, so the result keeps its trailing slash.
+*/
+const removeDotSegments = (segments) => {
+	const out = [];
+	segments.forEach((segment, index) => {
+		const last = index === segments.length - 1;
+		if (segment === ".") {
+			if (last) out.push("");
+		} else if (segment === "..") {
+			out.pop();
+			if (last) out.push("");
+		} else out.push(segment);
+	});
+	return out;
+};
+/**
+* Percent-encode one path segment or host: every character except RFC 3986's
+* unreserved set (`A-Z a-z 0-9 - . _ ~`) becomes its UTF-8 bytes as `%XX`,
+* uppercase. A lone surrogate has no UTF-8 encoding, so it throws.
+*/
+const encode = (segment) => {
+	try {
+		return encodeURIComponent(segment).replace(EXTRA, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+	} catch {
+		throw new TypeError(`LspUri.fromPath: ${JSON.stringify(segment)} holds a lone surrogate, which no URI can encode`);
+	}
+};
+/** Percent-decode one segment, or `undefined` for a malformed escape or invalid UTF-8. */
+const decode = (segment) => {
+	try {
+		return decodeURIComponent(segment);
+	} catch {
+		return;
+	}
+};
+const DEVICE_NAME = /^(?:con|prn|aux|nul|com[0-9\xb9\xb2\xb3]|lpt[0-9\xb9\xb2\xb3]|conin\$|conout\$) *(?:\..*)?$/i;
+/**
+* Why win32 would not open a segment as the entry it spells, or `undefined`:
+* a `:` (an NTFS alternate data stream, `b:stream`), a trailing dot or space
+* (which win32 trims, so `a.` opens `a`), or a DOS device name.
+*/
+const segmentRefusal = (segment) => {
+	if (segment.includes(":")) return `has a segment ${JSON.stringify(segment)} holding a ':', which win32 reads as an alternate data stream`;
+	if (segment.endsWith(".") || segment.endsWith(" ")) return `has a segment ${JSON.stringify(segment)} ending in a dot or a space, which win32 trims away`;
+	if (DEVICE_NAME.test(segment)) return `has a segment ${JSON.stringify(segment)} that names a DOS device`;
+};
+/**
+* Why `fromPath` refuses a Win32 path, or `undefined` when it accepts it.
+* The one statement of the refused set: `fromPath` throws on a reason, and
+* `toPath` answers `Option.none()` for any path this refuses, so `toPath`
+* never answers a path `fromPath` would not write. Segments are checked
+* after `.` and `..` are removed, as both directions remove them.
+*/
+const win32Refusal = (path) => {
+	if (path.includes("\0")) return "holds a NUL character";
+	const slashed = path.replaceAll("\\", "/");
+	if (slashed.startsWith("//?/") || slashed.startsWith("//./") || slashed.startsWith("/??/")) return "is a Win32 device or namespace path, which no file: URI names";
+	let segments;
+	if (slashed.startsWith("//")) {
+		const [server = "", share = "", ...rest] = slashed.slice(2).split("/");
+		if (!HOSTNAME.test(server)) return "is not a UNC path whose server is a hostname";
+		if (share === "" || share === "." || share === "..") return "is not a UNC path with a server and a share";
+		segments = [share, ...removeDotSegments(rest)];
+	} else if (DRIVE_PATH.test(slashed)) {
+		const rest = slashed.slice(2);
+		segments = rest === "" ? [] : removeDotSegments(rest.slice(1).split("/"));
+	} else return "is not an absolute win32 path";
+	for (const segment of segments) {
+		const refusal = segmentRefusal(segment);
+		if (refusal !== void 0) return refusal;
+	}
+};
+const toPosixPath = (host, tail) => host === "" ? Option.some(`/${removeDotSegments(tail).join("/")}`) : Option.none();
+const toWin32Path = (host, tail) => {
+	const unc = (server, rest) => {
+		const [share, ...after] = rest;
+		if (server === "" || share === void 0 || share === "") return Option.none();
+		const root = `\\\\${server.toLowerCase()}\\${share}`;
+		return Option.some(after.length === 0 ? root : `${root}\\${removeDotSegments(after).join("\\")}`);
+	};
+	if (host !== "") return unc(host, tail);
+	const [first, ...rest] = tail;
+	if (first === void 0) return Option.none();
+	if (first === "" && rest.length > 0 && rest[0] !== "") return unc(rest[0], rest.slice(1));
+	if (DRIVE.test(first)) return Option.some(`${first.charAt(0).toLowerCase()}:\\${removeDotSegments(rest).join("\\")}`);
+	return Option.none();
+};
+const toWin32 = (host, tail) => Option.filter(toWin32Path(host, tail), (path) => win32Refusal(path) === void 0);
+/**
+* Conversion between `file:` URIs and absolute file-system paths, the two
+* spellings every Language Server juggles: LSP names documents by URI
+* (`textDocument.uri`, `rootUri`, `workspaceFolders`), the file system by
+* path. Pure, with no `node:url` and no `process` read, so it runs in a
+* worker or a browser. Not instantiable.
+*
+* @remarks
+* Follows RFC 8089 and RFC 3986, and agrees with Node's `fileURLToPath` /
+* `pathToFileURL` and VS Code's `vscode-uri` (`URI.file`, `fsPath`) wherever
+* they agree with each other. The rulings where they do not:
+*
+* - **A non-`file:` scheme (`untitled:`, `vscode-notebook-cell:`) or a
+*   malformed URI is `Option.none()`, never a throw**: a client may name
+*   any document, and only `file:` documents have paths. So is a `%2F`
+*   inside a segment (it would smuggle a separator into one name), a `%5C`
+*   under `"win32"` (the same), a `%00`, a malformed or non-UTF-8 escape, a
+*   relative `file:` URI, a host under `"posix"`, and a rooted path with no
+*   drive or share under `"win32"`. Node throws for each of these.
+* - **`toPath` never answers a Win32 device or namespace path**, nor any
+*   other path `fromPath` would refuse: `file://./pipe/x` and
+*   `file://%3F/C:/x` would read as `\\.\pipe\x` and `\\?\C:\x`, and
+*   are `Option.none()`, as is a host spelled inside the path
+*   (`file:////./x`). A host must be a plain hostname: dot-separated labels
+*   of ASCII letters, digits, `-` and `_`. The authority is matched as
+*   written, never percent-decoded, so a percent-encoded host is
+*   `Option.none()`, as is a `.` or `?` host, a separator, `%`, NUL,
+*   userinfo, a port, an IPv6 literal, and a UNC share of `.` or `..`.
+* - **`toPath` never answers a path win32 would open as something else**,
+*   and `fromPath` refuses one, through the same check: a segment naming a
+*   DOS device (`CON`, `PRN`, `AUX`, `NUL`, `COM0`-`COM9`, `LPT0`-`LPT9`,
+*   their superscript-digit variants, `CONIN$`, `CONOUT$`), in any case and
+*   with or without an extension (`file:///c:/con` and `file:///c:/a/nul.txt`
+*   are `Option.none()`); a segment holding a `:` after the drive (an NTFS
+*   alternate data stream, `file:///c:/a/b:stream`); and a segment ending in
+*   a dot or a space, which win32 trims, so `c:\a.` would open `c:\a`. Node
+*   reads all of these as paths.
+* - **`.` and `..` segments are removed (RFC 3986 §5.2.4) and never climb
+*   above the root**, in both directions, including their encoded forms
+*   (`%2E%2E`). Node's WHATWG parser collapses them the same way; `vscode-uri`
+*   keeps them. A URI is never a path traversal: `file:///a/../../etc` is
+*   `/etc`.
+* - **A Windows drive letter is lowercase in both directions.** `toPath`
+*   answers `c:\…` for `file:///C:/…`, `file:///c:/…` and VS Code's
+*   `file:///c%3A/…` alike, as `vscode-uri`'s `fsPath` does, so the paths of
+*   one file agree however a client spelled its URI; `fromPath` writes
+*   `file:///c:/…`, RFC 8089's form, with the colon literal. Compare
+*   documents by path, or by a URI this module wrote, never by the client's
+*   URI string.
+* - **Encoding.** `fromPath` percent-encodes every character outside RFC
+*   3986's unreserved set, `/` aside (non-ASCII as UTF-8 bytes, uppercase
+*   hex), as `vscode-uri` does; Node leaves more characters bare. Every
+*   decoder reads both.
+* - **`localhost` is the local machine** (RFC 8089 §2): `file://localhost/a`
+*   is `/a`. Any other host is a UNC path under `"win32"`
+*   (`file://server/share/a` is `\\server\share\a`, host lowercased) and
+*   `Option.none()` under `"posix"`. So `file://localhost/share/a` is
+*   `Option.none()` under `"win32"`, as Node refuses it; `fromPath` writes a
+*   UNC path whose server is literally `localhost` with the host inside the
+*   path, `file:////localhost/share/a`, which `toPath` reads back as
+*   `\\localhost\share\a`. (Node's `pathToFileURL` writes that path as
+*   `file:///share/a`, a different file, and its `fileURLToPath` reads
+*   neither spelling.) An IDN host is read and written only in
+*   its ASCII (punycode) form; neither direction converts it.
+* - A query or fragment is ignored, as Node ignores it.
+*
+* @example
+* ```ts
+* import { LspUri } from "@effected/lsp";
+*
+* console.log(LspUri.toPath("file:///home/me/My%20Project/a.ts"));
+* // => Option.some("/home/me/My Project/a.ts")
+* console.log(LspUri.toPath("untitled:Untitled-1"));
+* // => Option.none()
+* console.log(LspUri.fromPath("C:\\Users\\me\\a.ts", { platform: "win32" }));
+* // => "file:///c:/Users/me/a.ts"
+* ```
+*
+* @public
+*/
+var LspUri = class {
+	constructor() {}
+	/**
+	* The absolute path a `file:` URI names, or `Option.none()` when it names
+	* none: a different scheme, or a URI that is malformed or cannot be a path
+	* on `options.platform` (see the class remarks for every case).
+	*
+	* @param uri - A URI as a client sent it, e.g. a `textDocument.uri`.
+	* @param options - The path syntax to answer in; defaults to `"posix"`.
+	* @returns The path, `.` and `..` segments removed, or `Option.none()`.
+	*/
+	static toPath(uri, options) {
+		if (!FILE_SCHEME.test(uri)) return Option.none();
+		let rest = uri.slice(5);
+		const hash = rest.indexOf("#");
+		if (hash !== -1) rest = rest.slice(0, hash);
+		const query = rest.indexOf("?");
+		if (query !== -1) rest = rest.slice(0, query);
+		let authority = "";
+		let path = rest;
+		if (rest.startsWith("//")) {
+			const slash = rest.indexOf("/", 2);
+			authority = slash === -1 ? rest.slice(2) : rest.slice(2, slash);
+			path = slash === -1 ? "" : rest.slice(slash);
+		}
+		if (!path.startsWith("/")) return Option.none();
+		const win32 = options?.platform === "win32";
+		const tail = [];
+		for (const raw of path.slice(1).split("/")) {
+			const segment = decode(raw);
+			if (segment === void 0 || segment.includes("/") || segment.includes("\0")) return Option.none();
+			if (win32 && segment.includes("\\")) return Option.none();
+			tail.push(segment);
+		}
+		const local = authority.toLowerCase() === "localhost" ? "" : authority;
+		return win32 ? toWin32(local, tail) : toPosixPath(local, tail);
+	}
+	/**
+	* The `file:` URI of an absolute path.
+	*
+	* @remarks
+	* The path is taken literally apart from its `.` and `..` segments, which
+	* are removed so the URI round-trips: `toPath(fromPath(p))` is `p`
+	* normalized, and `p` itself for an already-normalized path (a Windows
+	* drive letter lowercased). Under `"win32"`, `\` and `/` both separate,
+	* and a UNC path `\\server\share\…` becomes `file://server/share/…`
+	* (`file:////localhost/share/…` for a server named `localhost`, since
+	* `file://localhost/` is the local machine).
+	*
+	* A path that is not absolute on `options.platform` (`a/b`, `C:a`, or a
+	* rooted `\a` with no drive), one holding a NUL, a lone surrogate, a Win32
+	* device or namespace path (`\\?\…`, `\\.\…`, `\??\…`), a UNC path
+	* whose server is not a plain hostname or whose share is missing, `.` or
+	* `..`, or, under `"win32"`, a segment naming a DOS device (`con`,
+	* `nul.txt`), holding a `:` after the drive (`b:stream`) or ending in a
+	* dot or a space throws a `TypeError`: these are
+	* programmer errors, since a server's own paths are absolute, and no URI
+	* could name them faithfully. Resolve a relative path first, with the
+	* platform's path module.
+	*
+	* @param path - An absolute path in `options.platform`'s syntax.
+	* @param options - The path syntax to read; defaults to `"posix"`.
+	* @returns The URI, e.g. `"file:///home/me/a%20b.ts"`.
+	*/
+	static fromPath(path, options) {
+		if (path.includes("\0")) throw new TypeError("LspUri.fromPath: a path cannot hold a NUL character");
+		if (options?.platform !== "win32") {
+			if (!path.startsWith("/")) throw new TypeError(`LspUri.fromPath: ${JSON.stringify(path)} is not an absolute posix path`);
+			return `file:///${removeDotSegments(path.slice(1).split("/")).map(encode).join("/")}`;
+		}
+		const refusal = win32Refusal(path);
+		if (refusal !== void 0) throw new TypeError(`LspUri.fromPath: ${JSON.stringify(path)} ${refusal}`);
+		const slashed = path.replaceAll("\\", "/");
+		if (slashed.startsWith("//")) {
+			const [server = "", share = "", ...rest] = slashed.slice(2).split("/");
+			const after = rest.length === 0 ? "" : `/${removeDotSegments(rest).map(encode).join("/")}`;
+			const host = server.toLowerCase();
+			return host === "localhost" ? `file:////${host}/${encode(share)}${after}` : `file://${host}/${encode(share)}${after}`;
+		}
+		const drive = slashed.charAt(0).toLowerCase();
+		const rest = slashed.slice(2);
+		const segments = rest === "" ? [] : rest.slice(1).split("/");
+		return `file:///${drive}:/${removeDotSegments(segments).map(encode).join("/")}`;
+	}
+};
+
+export { LspUri };

package/README.md

@@ -88,6 +88,22 @@ The kit does not own the message loop, so it cannot see `shutdown` or `exit` its
 
 `LogToStderr` reaches Effect's default logger and `Logger.consolePretty`. `Logger.consoleJson`, `consoleLogFmt` and `consoleStructured` write through `console.log` regardless — wrap a formatter in `Logger.withConsoleError` instead — and `Console.log` still writes to stdout.
 
+## LspUri
+
+LSP names documents by `file:` URI, the file system by path. `LspUri` converts both ways without `node:url`, so it also runs in a worker:
+
+```ts
+import { LspUri } from "@effected/lsp";
+
+const platform = process.platform === "win32" ? "win32" : "posix";
+
+LspUri.toPath("file:///home/me/My%20Project/a.ts", { platform }); // Option.some("/home/me/My Project/a.ts")
+LspUri.toPath("untitled:Untitled-1", { platform }); // Option.none()
+LspUri.fromPath("C:\\Users\\me\\a.ts", { platform: "win32" }); // "file:///c:/Users/me/a.ts"
+```
+
+`toPath` answers `Option.none()` instead of throwing for a URI that names no path: another scheme, a malformed escape, a `%2F` inside a name, a host on posix. `.` and `..` never climb above the root, a drive or a UNC share. The drive letter comes back lowercase however the client spelled it (`C:`, `c:` or VS Code's `c%3A`), so key documents by path, not by the client's URI string.
+
 ## LspProbe (`@effected/lsp/testing`)
 
 The packed-install proof for a Language Server bin, the twin of `@effected/mcp/testing`'s `McpProbe`. It spawns the command and runs the lifecycle an editor runs — `initialize`, `initialized`, `shutdown`, `exit` — then waits for the server to exit:

package/index.d.ts

@@ -1,5 +1,4 @@
-import { Effect, Result, Runtime, Schema, Stream } from "effect";
-//#region src/LspFrame.d.ts
+import { Effect, Option, Result, Runtime, Schema, Stream } from "effect";
 /**
  * Why a byte stream is not a sequence of LSP base-protocol frames.
  *
@@ -142,8 +141,6 @@ export declare class LspFrame {
    */
   static decodeStream<E, R>(self: Stream.Stream<Uint8Array, E, R>): Stream.Stream<unknown, E | LspFrameError, R>;
 }
-//#endregion
-//#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
@@ -176,8 +173,6 @@ interface LspMessage {
     readonly data?: unknown;
   };
 }
-//#endregion
-//#region src/LspStdio.d.ts
 /**
  * How a Language Server session ended, as the server's own message loop
  * observed it. {@link LspStdio.exitCode} maps it to the exit code the LSP
@@ -310,6 +305,148 @@ export declare class LspStdio {
    */
   static teardown(host: LspExitHost): Runtime.Teardown;
 }
-//#endregion
-export type { LspExitHost, LspFrameDecoded, LspMessage, LspSessionEnd };
+/**
+ * Which path syntax {@link LspUri} reads and writes: `"posix"` (`/home/a`)
+ * or `"win32"` (`C:\Users\a`, `\\server\share\a`).
+ *
+ * @remarks
+ * Always passed explicitly, never read from the running process, so the
+ * conversion is pure and a worker or a test can convert either platform's
+ * paths anywhere. A server picks it once at its edge, typically from
+ * `process.platform === "win32"`.
+ *
+ * @public
+ */
+type LspUriPlatform = "posix" | "win32";
+/**
+ * Options for {@link LspUri.toPath} and {@link LspUri.fromPath}.
+ *
+ * @public
+ */
+interface LspUriOptions {
+  /** The path syntax to read or write. Defaults to `"posix"`. */
+  readonly platform?: LspUriPlatform;
+}
+/**
+ * Conversion between `file:` URIs and absolute file-system paths, the two
+ * spellings every Language Server juggles: LSP names documents by URI
+ * (`textDocument.uri`, `rootUri`, `workspaceFolders`), the file system by
+ * path. Pure, with no `node:url` and no `process` read, so it runs in a
+ * worker or a browser. Not instantiable.
+ *
+ * @remarks
+ * Follows RFC 8089 and RFC 3986, and agrees with Node's `fileURLToPath` /
+ * `pathToFileURL` and VS Code's `vscode-uri` (`URI.file`, `fsPath`) wherever
+ * they agree with each other. The rulings where they do not:
+ *
+ * - **A non-`file:` scheme (`untitled:`, `vscode-notebook-cell:`) or a
+ *   malformed URI is `Option.none()`, never a throw**: a client may name
+ *   any document, and only `file:` documents have paths. So is a `%2F`
+ *   inside a segment (it would smuggle a separator into one name), a `%5C`
+ *   under `"win32"` (the same), a `%00`, a malformed or non-UTF-8 escape, a
+ *   relative `file:` URI, a host under `"posix"`, and a rooted path with no
+ *   drive or share under `"win32"`. Node throws for each of these.
+ * - **`toPath` never answers a Win32 device or namespace path**, nor any
+ *   other path `fromPath` would refuse: `file://./pipe/x` and
+ *   `file://%3F/C:/x` would read as `\\.\pipe\x` and `\\?\C:\x`, and
+ *   are `Option.none()`, as is a host spelled inside the path
+ *   (`file:////./x`). A host must be a plain hostname: dot-separated labels
+ *   of ASCII letters, digits, `-` and `_`. The authority is matched as
+ *   written, never percent-decoded, so a percent-encoded host is
+ *   `Option.none()`, as is a `.` or `?` host, a separator, `%`, NUL,
+ *   userinfo, a port, an IPv6 literal, and a UNC share of `.` or `..`.
+ * - **`toPath` never answers a path win32 would open as something else**,
+ *   and `fromPath` refuses one, through the same check: a segment naming a
+ *   DOS device (`CON`, `PRN`, `AUX`, `NUL`, `COM0`-`COM9`, `LPT0`-`LPT9`,
+ *   their superscript-digit variants, `CONIN$`, `CONOUT$`), in any case and
+ *   with or without an extension (`file:///c:/con` and `file:///c:/a/nul.txt`
+ *   are `Option.none()`); a segment holding a `:` after the drive (an NTFS
+ *   alternate data stream, `file:///c:/a/b:stream`); and a segment ending in
+ *   a dot or a space, which win32 trims, so `c:\a.` would open `c:\a`. Node
+ *   reads all of these as paths.
+ * - **`.` and `..` segments are removed (RFC 3986 §5.2.4) and never climb
+ *   above the root**, in both directions, including their encoded forms
+ *   (`%2E%2E`). Node's WHATWG parser collapses them the same way; `vscode-uri`
+ *   keeps them. A URI is never a path traversal: `file:///a/../../etc` is
+ *   `/etc`.
+ * - **A Windows drive letter is lowercase in both directions.** `toPath`
+ *   answers `c:\…` for `file:///C:/…`, `file:///c:/…` and VS Code's
+ *   `file:///c%3A/…` alike, as `vscode-uri`'s `fsPath` does, so the paths of
+ *   one file agree however a client spelled its URI; `fromPath` writes
+ *   `file:///c:/…`, RFC 8089's form, with the colon literal. Compare
+ *   documents by path, or by a URI this module wrote, never by the client's
+ *   URI string.
+ * - **Encoding.** `fromPath` percent-encodes every character outside RFC
+ *   3986's unreserved set, `/` aside (non-ASCII as UTF-8 bytes, uppercase
+ *   hex), as `vscode-uri` does; Node leaves more characters bare. Every
+ *   decoder reads both.
+ * - **`localhost` is the local machine** (RFC 8089 §2): `file://localhost/a`
+ *   is `/a`. Any other host is a UNC path under `"win32"`
+ *   (`file://server/share/a` is `\\server\share\a`, host lowercased) and
+ *   `Option.none()` under `"posix"`. So `file://localhost/share/a` is
+ *   `Option.none()` under `"win32"`, as Node refuses it; `fromPath` writes a
+ *   UNC path whose server is literally `localhost` with the host inside the
+ *   path, `file:////localhost/share/a`, which `toPath` reads back as
+ *   `\\localhost\share\a`. (Node's `pathToFileURL` writes that path as
+ *   `file:///share/a`, a different file, and its `fileURLToPath` reads
+ *   neither spelling.) An IDN host is read and written only in
+ *   its ASCII (punycode) form; neither direction converts it.
+ * - A query or fragment is ignored, as Node ignores it.
+ *
+ * @example
+ * ```ts
+ * import { LspUri } from "@effected/lsp";
+ *
+ * console.log(LspUri.toPath("file:///home/me/My%20Project/a.ts"));
+ * // => Option.some("/home/me/My Project/a.ts")
+ * console.log(LspUri.toPath("untitled:Untitled-1"));
+ * // => Option.none()
+ * console.log(LspUri.fromPath("C:\\Users\\me\\a.ts", { platform: "win32" }));
+ * // => "file:///c:/Users/me/a.ts"
+ * ```
+ *
+ * @public
+ */
+export declare class LspUri {
+  private constructor();
+  /**
+   * The absolute path a `file:` URI names, or `Option.none()` when it names
+   * none: a different scheme, or a URI that is malformed or cannot be a path
+   * on `options.platform` (see the class remarks for every case).
+   *
+   * @param uri - A URI as a client sent it, e.g. a `textDocument.uri`.
+   * @param options - The path syntax to answer in; defaults to `"posix"`.
+   * @returns The path, `.` and `..` segments removed, or `Option.none()`.
+   */
+  static toPath(uri: string, options?: LspUriOptions): Option.Option<string>;
+  /**
+   * The `file:` URI of an absolute path.
+   *
+   * @remarks
+   * The path is taken literally apart from its `.` and `..` segments, which
+   * are removed so the URI round-trips: `toPath(fromPath(p))` is `p`
+   * normalized, and `p` itself for an already-normalized path (a Windows
+   * drive letter lowercased). Under `"win32"`, `\` and `/` both separate,
+   * and a UNC path `\\server\share\…` becomes `file://server/share/…`
+   * (`file:////localhost/share/…` for a server named `localhost`, since
+   * `file://localhost/` is the local machine).
+   *
+   * A path that is not absolute on `options.platform` (`a/b`, `C:a`, or a
+   * rooted `\a` with no drive), one holding a NUL, a lone surrogate, a Win32
+   * device or namespace path (`\\?\…`, `\\.\…`, `\??\…`), a UNC path
+   * whose server is not a plain hostname or whose share is missing, `.` or
+   * `..`, or, under `"win32"`, a segment naming a DOS device (`con`,
+   * `nul.txt`), holding a `:` after the drive (`b:stream`) or ending in a
+   * dot or a space throws a `TypeError`: these are
+   * programmer errors, since a server's own paths are absolute, and no URI
+   * could name them faithfully. Resolve a relative path first, with the
+   * platform's path module.
+   *
+   * @param path - An absolute path in `options.platform`'s syntax.
+   * @param options - The path syntax to read; defaults to `"posix"`.
+   * @returns The URI, e.g. `"file:///home/me/a%20b.ts"`.
+   */
+  static fromPath(path: string, options?: LspUriOptions): string;
+}
+export type { LspExitHost, LspFrameDecoded, LspMessage, LspSessionEnd, LspUriOptions, LspUriPlatform };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,4 +1,5 @@
 import { LspFrame, LspFrameError, LspFrameErrorCode } from "./LspFrame.js";
 import { LspStdio } from "./LspStdio.js";
+import { LspUri } from "./LspUri.js";
 
-export { LspFrame, LspFrameError, LspFrameErrorCode, LspStdio };
+export { LspFrame, LspFrameError, LspFrameErrorCode, LspStdio, LspUri };

package/internal/LaunchFailed.js

@@ -1,6 +1,6 @@
 import { Runtime } from "effect";
 
-//#region src/internal/LaunchFailed.ts
+// src/internal/LaunchFailed.ts
 /**
 * The failure `LspStdio.launch` re-raises after reporting a failed server on
 * stderr itself. `errorReported: false` keeps `runMain` from reporting it a
@@ -31,5 +31,4 @@ var LaunchFailed = class extends Error {
 	}
 };
 
-//#endregion
 export { LaunchFailed };

package/internal/messages.js

@@ -1,6 +1,6 @@
 import { LspTestFailure } from "../LspTestFailure.js";
 
-//#region src/internal/messages.ts
+// src/internal/messages.ts
 /** How much text a failure message echoes. */
 const ECHO = 2e3;
 /**
@@ -26,5 +26,4 @@ const notJsonRpc = (message) => new LspTestFailure({
 	message: `the server sent a frame that is not a JSON-RPC 2.0 message: ${truncate(JSON.stringify(message) ?? String(message))}`
 });
 
-//#endregion
 export { isLspMessage, notJsonRpc, truncate };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/lsp",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"private": false,
 	"description": "Language Server Protocol base-protocol framing for Effect v4, plus a packed-install initialize probe for a Language Server bin",
 	"keywords": [

package/testing.d.ts

@@ -1,6 +1,5 @@
 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
@@ -33,8 +32,6 @@ interface LspMessage {
     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"]>;
@@ -62,8 +59,6 @@ declare const LspTestFailure_base: Schema.Class<LspTestFailure, Schema.TaggedStr
  * @public
  */
 export declare class LspTestFailure extends LspTestFailure_base {}
-//#endregion
-//#region src/LspProbe.d.ts
 /**
  * Options for {@link LspProbe.initialize}.
  *
@@ -153,8 +148,6 @@ export declare class LspProbe {
    */
   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}.
  *
@@ -302,6 +295,5 @@ export declare class LspProcess {
   /** 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/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.1"
+      "packageVersion": "7.59.4"
     }
   ]
 }