@danypops/lector 0.1.0

package/src/adapters/lsp/discover-seed-file.ts

@@ -0,0 +1,130 @@
+import { type Dirent, existsSync, readdirSync } from "node:fs";
+import { extname, join, sep } from "node:path";
+import type { LanguageServerDescriptor } from "../../domain/language-server-descriptor.ts";
+import { refineTypescriptSeedFile } from "./typescript-project-files.ts";
+
+const SKIP_DIRECTORY_NAMES = new Set(["node_modules", "dist", "build", "out", "coverage"]);
+const MAX_SCAN_DEPTH = 4;
+const MAX_ENTRIES_SCANNED = 2_000;
+
+/** Raised when no matching source file could be found to warm a language server with. */
+export class NoSeedFileFound extends Error {
+	constructor(
+		readonly rootPath: string,
+		readonly extensions: readonly string[],
+	) {
+		super(`no source file matching [${extensions.join(", ")}] found under "${rootPath}" to warm the language server with`);
+		this.name = "NoSeedFileFound";
+	}
+}
+
+/**
+ * True when `relativeFilePath` has `marker` in its own directory or any ancestor directory up
+ * to and including rootPath -- i.e. whether a language server would actually associate this
+ * file with a real, config-backed project, as opposed to treating it as an orphan file with no
+ * project coverage (a standalone root-level *.config.ts next to a monorepo root that has no
+ * root tsconfig.json is exactly this case: real extension match, zero project coverage).
+ */
+function hasMarkerAncestor(rootPath: string, relativeFilePath: string, marker: string): boolean {
+	const parts = relativeFilePath.split(sep);
+	parts.pop();
+	for (let i = parts.length; i >= 0; i--) {
+		if (existsSync(join(rootPath, ...parts.slice(0, i), marker))) return true;
+	}
+	return false;
+}
+
+/**
+ * Pick a workspace-relative file to open first so a language server has a live project to
+ * search (see LspSymbolIndex's own doc comment on the "No Project." gotcha). A caller
+ * should never have to know or care which file this is -- it is a pure implementation
+ * detail of warming the language server, not part of the workspace's identity or the
+ * query's meaning.
+ *
+ * Tries `commonCandidates` first (e.g. a language's usual entry-point names); falls back to a
+ * bounded (depth- and entry-count-limited, per "Bound resources and outputs explicitly")
+ * directory scan matching `extensions`, deterministic (alphabetically sorted). Among files found
+ * during that scan, prefers one with `rootMarkers[0]` (e.g. tsconfig.json) among its ancestors --
+ * a real, previously-undetected bug (confirmed against this project's own monorepo root) let a
+ * standalone root-level eslint.config.ts win purely by alphabetical luck over any real project
+ * file, silently limiting workspace/symbol to a project that doesn't include the actual source
+ * tree at all. Only falls back to the first alphabetical match when nothing in the scanned
+ * subtree has real project coverage.
+ */
+export function discoverSeedFile(
+	rootPath: string,
+	extensions: readonly string[],
+	commonCandidates: readonly string[],
+	rootMarkers: readonly string[] = [],
+): string {
+	for (const candidate of commonCandidates) {
+		if (existsSync(join(rootPath, candidate))) return candidate;
+	}
+	const sourceExtensions = new Set(extensions);
+	const primaryMarker = rootMarkers[0];
+	let fallback: string | undefined;
+
+	let scanned = 0;
+	const visit = (relativeDir: string, depth: number): string | undefined => {
+		if (depth > MAX_SCAN_DEPTH) return undefined;
+		let entries: Dirent[];
+		try {
+			entries = readdirSync(join(rootPath, relativeDir), { withFileTypes: true, encoding: "utf-8" });
+		} catch {
+			return undefined;
+		}
+		const sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+
+		for (const entry of sorted) {
+			if (scanned >= MAX_ENTRIES_SCANNED) return fallback;
+			scanned++;
+			const relativePath = relativeDir ? join(relativeDir, entry.name) : entry.name;
+			if (entry.isDirectory()) {
+				if (SKIP_DIRECTORY_NAMES.has(entry.name) || entry.name.startsWith(".")) continue;
+				const found = visit(relativePath, depth + 1);
+				if (found) return found;
+			} else if (entry.isFile() && sourceExtensions.has(extname(entry.name))) {
+				if (!primaryMarker || hasMarkerAncestor(rootPath, relativePath, primaryMarker)) return relativePath;
+				fallback ??= relativePath;
+			}
+		}
+		return undefined;
+	};
+
+	const found = visit("", 0) ?? fallback;
+	if (!found) throw new NoSeedFileFound(rootPath, extensions);
+	return found;
+}
+
+/**
+ * discoverSeedFile plus a TypeScript-specific refinement pass -- the generic ancestor-marker
+ * heuristic isn't sufficient for TypeScript specifically: a real tsconfig.json ancestor doesn't
+ * mean that tsconfig's own include/exclude actually covers the candidate (confirmed empirically
+ * against this project's own monorepo, see typescript-project-files.ts). Kept as an explicit,
+ * named special case here rather than a generic hook on LanguageServerDescriptor -- only one
+ * language currently needs it, and forcing every descriptor to carry an unused hook field would
+ * be speculative generality this project's own conventions argue against.
+ */
+export function resolveSeedFile(rootPath: string, descriptor: LanguageServerDescriptor): string {
+	const candidate = discoverSeedFile(rootPath, descriptor.extensions, descriptor.commonSeedCandidates, descriptor.rootMarkers);
+	return descriptor.languageId === "typescript" ? refineTypescriptSeedFile(rootPath, candidate) : candidate;
+}
+
+/**
+ * For workspace.findSymbols called with no seedFile -- no anchor file to pick a language from.
+ * Tries each descriptor's own discoverSeedFile in declared order; first real match wins.
+ */
+export function discoverWorkspaceDescriptor(
+	rootPath: string,
+	descriptors: readonly LanguageServerDescriptor[],
+): { descriptor: LanguageServerDescriptor; seedFile: string } | undefined {
+	for (const descriptor of descriptors) {
+		try {
+			const seedFile = resolveSeedFile(rootPath, descriptor);
+			return { descriptor, seedFile };
+		} catch (error) {
+			if (!(error instanceof NoSeedFileFound)) throw error;
+		}
+	}
+	return undefined;
+}

package/src/adapters/lsp/json-rpc-stream.ts

@@ -0,0 +1,67 @@
+/**
+ * Content-Length-framed JSON-RPC message encoding/decoding, per the LSP
+ * specification's base protocol. Pure and subprocess-free by design: this
+ * module never touches child_process, so it is independently testable
+ * against arbitrary byte-chunk boundaries without spawning anything.
+ */
+
+export interface JsonRpcMessage {
+	readonly jsonrpc: "2.0";
+	readonly id?: number | string;
+	readonly method?: string;
+	readonly params?: unknown;
+	readonly result?: unknown;
+	readonly error?: { readonly code: number; readonly message: string; readonly data?: unknown };
+}
+
+export function encodeJsonRpcMessage(message: JsonRpcMessage): Buffer {
+	const body = Buffer.from(JSON.stringify(message), "utf-8");
+	const header = Buffer.from(`Content-Length: ${body.byteLength}\r\n\r\n`, "ascii");
+	return Buffer.concat([header, body]);
+}
+
+/**
+ * Incrementally parses Content-Length-framed messages from a byte stream
+ * that may deliver partial messages, multiple messages per chunk, or a
+ * header/body split across chunk boundaries -- exactly what a real child
+ * process's stdout does under backpressure or large payloads.
+ */
+export class JsonRpcStreamDecoder {
+	private buffer: Buffer = Buffer.alloc(0);
+
+	/** Feed one chunk; returns every complete message it produced (zero or more, in order). */
+	push(chunk: Buffer): JsonRpcMessage[] {
+		this.buffer = Buffer.concat([this.buffer, chunk]);
+		const messages: JsonRpcMessage[] = [];
+
+		for (;;) {
+			const headerEnd = this.buffer.indexOf("\r\n\r\n");
+			if (headerEnd === -1) break; // header itself split across chunks -- wait for more
+
+			const header = this.buffer.subarray(0, headerEnd).toString("ascii");
+			const match = /Content-Length:\s*(\d+)/i.exec(header);
+			const digits = match?.[1];
+			if (digits === undefined) {
+				// Malformed header we cannot recover a length from: drop through the
+				// terminator and keep going rather than getting stuck on it forever.
+				this.buffer = this.buffer.subarray(headerEnd + 4);
+				continue;
+			}
+
+			const length = Number.parseInt(digits, 10);
+			const bodyStart = headerEnd + 4;
+			const bodyEnd = bodyStart + length;
+			if (this.buffer.byteLength < bodyEnd) break; // body split across chunks -- wait for more
+
+			const body = this.buffer.subarray(bodyStart, bodyEnd).toString("utf-8");
+			this.buffer = this.buffer.subarray(bodyEnd);
+			try {
+				messages.push(JSON.parse(body) as JsonRpcMessage);
+			} catch {
+				// An unparseable body must not crash the whole stream -- skip it and continue.
+			}
+		}
+
+		return messages;
+	}
+}

package/src/adapters/lsp/language-server-process.ts

@@ -0,0 +1,184 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { encodeJsonRpcMessage, type JsonRpcMessage, JsonRpcStreamDecoder } from "./json-rpc-stream.ts";
+
+export interface LanguageServerProcessOptions {
+	command: string;
+	args?: readonly string[];
+	cwd: string;
+	/** Extra environment variables merged over process.env for the spawned process. */
+	env?: Readonly<Record<string, string | undefined>>;
+	/** Per-request timeout. Default 10s. */
+	requestTimeoutMs?: number;
+}
+
+/** Raised when a request is sent (or was pending) after the server process already exited. */
+export class LanguageServerProcessExited extends Error {
+	constructor(readonly command: string) {
+		super(`language server process "${command}" exited; the request cannot be fulfilled`);
+		this.name = "LanguageServerProcessExited";
+	}
+}
+
+/** Raised when a request does not receive a response within its timeout. */
+export class LanguageServerRequestTimedOut extends Error {
+	constructor(
+		readonly method: string,
+		readonly timeoutMs: number,
+	) {
+		super(`language server request "${method}" did not respond within ${timeoutMs}ms`);
+		this.name = "LanguageServerRequestTimedOut";
+	}
+}
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+const DEFAULT_STOP_TIMEOUT_MS = 3_000;
+
+interface PendingRequest {
+	resolve: (result: unknown) => void;
+	reject: (error: Error) => void;
+	timer: ReturnType<typeof setTimeout>;
+}
+
+type NotificationHandler = (params: unknown) => void;
+
+/**
+ * A spawned language server subprocess with safe lifecycle management:
+ * spawned detached so stop() can kill its whole process group, not just
+ * the immediate child; a request made after the process has already
+ * exited is rejected immediately rather than left pending forever; and
+ * stop() force-kills the process group if a graceful shutdown doesn't
+ * complete in time.
+ */
+export class LanguageServerProcess {
+	private readonly child: ChildProcessWithoutNullStreams;
+	private readonly decoder = new JsonRpcStreamDecoder();
+	private readonly pending = new Map<number, PendingRequest>();
+	private readonly notificationHandlers = new Map<string, Set<NotificationHandler>>();
+	private readonly requestTimeoutMs: number;
+	private nextId = 1;
+	private processExited = false;
+	private exitError: Error;
+
+	private constructor(child: ChildProcessWithoutNullStreams, label: string, requestTimeoutMs: number) {
+		this.child = child;
+		this.requestTimeoutMs = requestTimeoutMs;
+		this.exitError = new LanguageServerProcessExited(label);
+
+		this.child.stdout.on("data", (chunk: Buffer) => {
+			for (const message of this.decoder.push(chunk)) this.dispatch(message);
+		});
+
+		this.child.once("exit", () => {
+			this.processExited = true;
+			for (const [id, request] of this.pending) {
+				clearTimeout(request.timer);
+				request.reject(this.exitError);
+				this.pending.delete(id);
+			}
+		});
+	}
+
+	/** Undefined only if the OS never assigned one, i.e. spawn itself failed before this constructor ran. */
+	get pid(): number | undefined {
+		return this.child.pid;
+	}
+
+	static spawnProcess(options: LanguageServerProcessOptions): LanguageServerProcess {
+		const child = spawn(options.command, [...(options.args ?? [])], {
+			cwd: options.cwd,
+			env: { ...process.env, ...options.env },
+			stdio: ["pipe", "pipe", "pipe"],
+			// Own process group on POSIX so stop() can kill every descendant as a unit.
+			detached: process.platform !== "win32",
+		}) as ChildProcessWithoutNullStreams;
+		return new LanguageServerProcess(child, options.command, options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+	}
+
+	private dispatch(message: JsonRpcMessage): void {
+		if (typeof message.id === "number") {
+			const request = this.pending.get(message.id);
+			if (!request) return;
+			clearTimeout(request.timer);
+			this.pending.delete(message.id);
+			if (message.error) request.reject(new Error(message.error.message));
+			else request.resolve(message.result);
+			return;
+		}
+		// No numeric id: either a notification (no id at all) or a server-initiated request
+		// (its own id space, not this client's) -- only notifications are handled.
+		if (message.id !== undefined || !message.method) return;
+		for (const handler of this.notificationHandlers.get(message.method) ?? []) handler(message.params);
+	}
+
+	/** Subscribes to a server-pushed notification (e.g. textDocument/publishDiagnostics). Returns an unsubscribe function. */
+	onNotification(method: string, handler: NotificationHandler): () => void {
+		const handlers = this.notificationHandlers.get(method) ?? new Set();
+		handlers.add(handler);
+		this.notificationHandlers.set(method, handlers);
+		return () => handlers.delete(handler);
+	}
+
+	async request<T>(method: string, params: unknown): Promise<T> {
+		if (this.processExited) throw this.exitError;
+		const id = this.nextId++;
+		return new Promise<T>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(new LanguageServerRequestTimedOut(method, this.requestTimeoutMs));
+			}, this.requestTimeoutMs);
+			this.pending.set(id, { resolve: resolve as (result: unknown) => void, reject, timer });
+			this.child.stdin.write(encodeJsonRpcMessage({ jsonrpc: "2.0", id, method, params }));
+		});
+	}
+
+	notify(method: string, params: unknown): void {
+		if (this.processExited) return;
+		this.child.stdin.write(encodeJsonRpcMessage({ jsonrpc: "2.0", method, params }));
+	}
+
+	/**
+	 * Attempts a graceful `shutdown` request followed by an `exit` notification,
+	 * bounded by `stopTimeoutMs`. If the process has not exited by then -- the
+	 * graceful path hung, errored, or the process simply ignored it -- kills
+	 * the entire process group so no descendant is left running.
+	 */
+	async stop(stopTimeoutMs = DEFAULT_STOP_TIMEOUT_MS): Promise<void> {
+		if (this.processExited) return;
+
+		const exited = new Promise<void>((resolve) => {
+			if (this.processExited) resolve();
+			else this.child.once("exit", () => resolve());
+		});
+
+		await Promise.race([
+			(async () => {
+				try {
+					await this.request("shutdown", null);
+					this.notify("exit", null);
+				} catch {
+					// Falls through to the hard kill below regardless of why the graceful
+					// path failed (timeout, process already gone, protocol error, ...).
+				}
+			})(),
+			new Promise<void>((resolve) => setTimeout(resolve, stopTimeoutMs)),
+		]);
+
+		if (!this.processExited) this.killProcessGroup();
+
+		// Bounded wait for the exit event to actually land; stop() must itself never hang
+		// even if, somehow, neither the graceful path nor SIGKILL produced one promptly.
+		await Promise.race([exited, new Promise<void>((resolve) => setTimeout(resolve, stopTimeoutMs))]);
+	}
+
+	private killProcessGroup(): void {
+		try {
+			if (process.platform !== "win32" && this.child.pid) {
+				process.kill(-this.child.pid, "SIGKILL"); // negative pid == the whole process group
+			} else {
+				this.child.kill("SIGKILL");
+			}
+		} catch {
+			// ESRCH etc. -- already gone.
+		}
+	}
+}