@danypops/lector 0.1.7 → 0.1.9

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

@@ -1,5 +1,5 @@
 import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
-import { encodeJsonRpcMessage, type JsonRpcMessage, JsonRpcStreamDecoder } from "./json-rpc-stream.ts";
+import { encodeJsonRpcMessage, type JsonRpcMessage, JsonRpcMessageLimitExceeded, JsonRpcStreamDecoder } from "./json-rpc-stream.ts";
 
 export interface LanguageServerProcessOptions {
 	command: string;
@@ -9,6 +9,10 @@ export interface LanguageServerProcessOptions {
 	env?: Readonly<Record<string, string | undefined>>;
 	/** Per-request timeout. Default 10s. */
 	requestTimeoutMs?: number;
+	/** Maximum simultaneous requests. Default 64. */
+	maxPendingRequests?: number;
+	/** Maximum decoded server message size. Default 8 MiB. */
+	maxMessageBytes?: number;
 }
 
 /** Raised when a request is sent (or was pending) after the server process already exited. */
@@ -20,6 +24,13 @@ export class LanguageServerProcessExited extends Error {
 }
 
 /** Raised when a request does not receive a response within its timeout. */
+export class LanguageServerCapacityExceeded extends Error {
+	constructor(readonly maxPendingRequests: number) {
+		super(`language server request capacity reached (${maxPendingRequests} pending)`);
+		this.name = "LanguageServerCapacityExceeded";
+	}
+}
+
 export class LanguageServerRequestTimedOut extends Error {
 	constructor(
 		readonly method: string,
@@ -51,23 +62,34 @@ type NotificationHandler = (params: unknown) => void;
  */
 export class LanguageServerProcess {
 	private readonly child: ChildProcessWithoutNullStreams;
-	private readonly decoder = new JsonRpcStreamDecoder();
+	private readonly decoder: JsonRpcStreamDecoder;
 	private readonly pending = new Map<number, PendingRequest>();
 	private readonly notificationHandlers = new Map<string, Set<NotificationHandler>>();
 	private readonly requestTimeoutMs: number;
+	private readonly maxPendingRequests: number;
+	private readonly maxMessageBytes: number;
 	private nextId = 1;
 	private processExited = false;
 	private exitError: Error;
 
-	private constructor(child: ChildProcessWithoutNullStreams, label: string, requestTimeoutMs: number) {
+	private constructor(child: ChildProcessWithoutNullStreams, label: string, requestTimeoutMs: number, maxPendingRequests: number, maxMessageBytes: number) {
 		this.child = child;
 		this.requestTimeoutMs = requestTimeoutMs;
+		this.maxPendingRequests = maxPendingRequests;
+		this.maxMessageBytes = maxMessageBytes;
+		this.decoder = new JsonRpcStreamDecoder({ maxMessageBytes });
 		this.exitError = new LanguageServerProcessExited(label);
+		this.child.stderr.resume();
 
 		this.child.stdout.on("data", (chunk: Buffer) => {
-			for (const message of this.decoder.push(chunk)) this.dispatch(message);
+			try {
+				for (const message of this.decoder.push(chunk)) this.dispatch(message);
+			} catch (error) {
+				this.fail(error instanceof Error ? error : new Error(String(error)));
+			}
 		});
 
+		this.child.once("error", (error) => this.fail(error));
 		this.child.once("exit", () => {
 			this.processExited = true;
 			for (const [id, request] of this.pending) {
@@ -84,14 +106,18 @@ export class LanguageServerProcess {
 	}
 
 	static spawnProcess(options: LanguageServerProcessOptions): LanguageServerProcess {
+		const maxPendingRequests = options.maxPendingRequests ?? 64;
+		const maxMessageBytes = options.maxMessageBytes ?? 8 * 1024 * 1024;
+		if (!Number.isSafeInteger(maxPendingRequests) || maxPendingRequests < 1) throw new TypeError("maxPendingRequests must be a positive safe integer");
+		if (!Number.isSafeInteger(maxMessageBytes) || maxMessageBytes < 1) throw new TypeError("maxMessageBytes must be a positive safe integer");
 		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);
+		});
+		return new LanguageServerProcess(child, options.command, options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, maxPendingRequests, maxMessageBytes);
 	}
 
 	private dispatch(message: JsonRpcMessage): void {
@@ -120,20 +146,25 @@ export class LanguageServerProcess {
 
 	async request<T>(method: string, params: unknown): Promise<T> {
 		if (this.processExited) throw this.exitError;
+		if (this.pending.size >= this.maxPendingRequests) throw new LanguageServerCapacityExceeded(this.maxPendingRequests);
 		const id = this.nextId++;
+		const message = encodeJsonRpcMessage({ jsonrpc: "2.0", id, method, params });
+		if (message.byteLength > this.maxMessageBytes) throw new JsonRpcMessageLimitExceeded("message-bytes", this.maxMessageBytes, message.byteLength);
 		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 }));
+			this.child.stdin.write(message);
 		});
 	}
 
 	notify(method: string, params: unknown): void {
 		if (this.processExited) return;
-		this.child.stdin.write(encodeJsonRpcMessage({ jsonrpc: "2.0", method, params }));
+		const message = encodeJsonRpcMessage({ jsonrpc: "2.0", method, params });
+		if (message.byteLength > this.maxMessageBytes) throw new JsonRpcMessageLimitExceeded("message-bytes", this.maxMessageBytes, message.byteLength);
+		this.child.stdin.write(message);
 	}
 
 	/**
@@ -142,6 +173,18 @@ export class LanguageServerProcess {
 	 * graceful path hung, errored, or the process simply ignored it -- kills
 	 * the entire process group so no descendant is left running.
 	 */
+	private fail(error: Error): void {
+		if (this.processExited) return;
+		this.processExited = true;
+		this.exitError = error;
+		for (const [id, request] of this.pending) {
+			clearTimeout(request.timer);
+			request.reject(error);
+			this.pending.delete(id);
+		}
+		this.killProcessGroup();
+	}
+
 	async stop(stopTimeoutMs = DEFAULT_STOP_TIMEOUT_MS): Promise<void> {
 		if (this.processExited) return;
 
@@ -172,8 +215,9 @@ export class LanguageServerProcess {
 
 	private killProcessGroup(): void {
 		try {
-			if (process.platform !== "win32" && this.child.pid) {
-				process.kill(-this.child.pid, "SIGKILL"); // negative pid == the whole process group
+			const pid = this.child.pid;
+			if (process.platform !== "win32" && pid !== undefined) {
+				process.kill(-pid, "SIGKILL"); // negative pid == the whole process group
 			} else {
 				this.child.kill("SIGKILL");
 			}

package/src/adapters/lsp/lsp-symbol-index.ts

@@ -1,18 +1,59 @@
 import { readFileSync, realpathSync } from "node:fs";
-import { join } from "node:path";
+import { extname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import type { CallHierarchyEntry, IncomingCall, OutgoingCall } from "../../domain/call-hierarchy.ts";
 import type { CodeRange } from "../../domain/code-range.ts";
 import type { Diagnostic, DiagnosticSeverity } from "../../domain/diagnostic.ts";
 import type { DocumentSymbolEntry } from "../../domain/document-symbol.ts";
 import type { Hover } from "../../domain/hover.ts";
+import type { IntelligenceProvenance, SymbolSearchBounds } from "../../domain/intelligence-provenance.ts";
 import { DEFAULT_SETTLE_MS, type LanguageServerDescriptor } from "../../domain/language-server-descriptor.ts";
-import type { WorkspaceLocation, WorkspaceSymbol } from "../../domain/workspace-symbol.ts";
+import type { SymbolSearchResult, WorkspaceLocation, WorkspaceSymbol } from "../../domain/workspace-symbol.ts";
 import type { CodeIntelligencePort } from "../../ports/code-intelligence-port.ts";
 import type { SymbolIndexPort } from "../../ports/symbol-index-port.ts";
+import { TypeScriptCompilerSymbolIndex } from "../typescript-compiler-symbol-index.ts";
 import { resolveSeedFile } from "./discover-seed-file.ts";
 import { LanguageServerProcess } from "./language-server-process.ts";
 
+const DEFAULT_MAX_SYMBOL_RESULTS = 1_000;
+const DEFAULT_MAX_OPEN_FILES = 256;
+const DEFAULT_MAX_FILE_BYTES = 4 * 1024 * 1024;
+const MAX_SETTLE_MS = 30_000;
+
+export interface LspSymbolIndexOptions {
+	readonly maxOpenFiles?: number;
+	readonly maxFileBytes?: number;
+	readonly maxRefreshBytes?: number;
+	readonly maxFallbackSeedFiles?: number;
+}
+
+export class LanguageFileOutsideWorkspace extends Error {
+	constructor(
+		readonly path: string,
+		readonly root: string,
+	) {
+		super(`language file "${path}" resolves outside workspace root "${root}"`);
+		this.name = "LanguageFileOutsideWorkspace";
+	}
+}
+
+export class LanguageFileLimitExceeded extends Error {
+	constructor(
+		readonly limit: "open-files" | "file-bytes" | "refresh-bytes",
+		readonly max: number,
+		readonly observed: number,
+	) {
+		super(`language intelligence ${limit} limit exceeded: ${observed} > ${max}`);
+		this.name = "LanguageFileLimitExceeded";
+	}
+}
+
+function positiveLimit(value: number | undefined, fallback: number, field: string): number {
+	const result = value ?? fallback;
+	if (!Number.isSafeInteger(result) || result < 1) throw new TypeError(`${field} must be a positive safe integer`);
+	return result;
+}
+
 const LSP_SYMBOL_KIND_NAMES: Readonly<Record<number, string>> = {
 	1: "file",
 	2: "module",
@@ -237,19 +278,42 @@ function normalizeDocumentSymbol(path: string, item: LspDocumentSymbol | LspSymb
  * actually loaded -- open a file first to guarantee its usages are included.
  */
 export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
+	readonly provenance: IntelligenceProvenance;
 	private readonly cwd: string;
+	private readonly canonicalCwd: string;
 	private readonly descriptor: LanguageServerDescriptor;
 	private readonly explicitSeedFile: string | undefined;
-	private readonly openedFiles = new Set<string>();
+	private fallbackSeedFile: string | undefined;
+	private readonly maxOpenFiles: number;
+	private readonly maxFileBytes: number;
+	private readonly maxRefreshBytes: number;
+	private readonly maxFallbackSeedFiles: number;
+	private readonly openedFiles = new Map<string, { version: number; content: string }>();
 	private readonly latestDiagnostics = new Map<string, Diagnostic[]>();
 	private readonly diagnosticsWaiters = new Map<string, Array<() => void>>();
 	private process: LanguageServerProcess | undefined;
 	private initializing: Promise<LanguageServerProcess> | undefined;
 
-	constructor(cwd: string, descriptor: LanguageServerDescriptor, seedFile?: string) {
-		this.cwd = cwd;
+	constructor(cwd: string, descriptor: LanguageServerDescriptor, seedFile?: string, options: LspSymbolIndexOptions = {}) {
+		this.cwd = resolve(cwd);
+		this.canonicalCwd = realpathSync(this.cwd);
 		this.descriptor = descriptor;
 		this.explicitSeedFile = seedFile;
+		this.maxOpenFiles = positiveLimit(options.maxOpenFiles, DEFAULT_MAX_OPEN_FILES, "maxOpenFiles");
+		this.maxFileBytes = positiveLimit(options.maxFileBytes, DEFAULT_MAX_FILE_BYTES, "maxFileBytes");
+		this.maxRefreshBytes = positiveLimit(options.maxRefreshBytes, 50 * 1024 * 1024, "maxRefreshBytes");
+		this.maxFallbackSeedFiles = positiveLimit(options.maxFallbackSeedFiles, 8, "maxFallbackSeedFiles");
+		const settleMs = descriptor.settleMs ?? DEFAULT_SETTLE_MS;
+		if (!Number.isSafeInteger(settleMs) || settleMs < 0 || settleMs > MAX_SETTLE_MS)
+			throw new TypeError(`settleMs must be an integer from 0 through ${MAX_SETTLE_MS}`);
+		this.provenance = {
+			fidelity: "semantic",
+			backend: descriptor.backendId,
+			languageId: descriptor.languageId,
+			authority: "language-server",
+			freshness: "live-process",
+			limitations: [],
+		};
 	}
 
 	/** Undefined before the server process has been spawned (first real query). */
@@ -257,14 +321,27 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 		return this.process?.pid;
 	}
 
-	private async ensureInitialized(): Promise<LanguageServerProcess> {
+	private resolveTargetPath(path: string): string {
+		const absolute = resolve(this.cwd, path);
+		const canonical = realpathSync(absolute);
+		const relativeToRoot = relative(this.canonicalCwd, canonical);
+		if (relativeToRoot === ".." || relativeToRoot.startsWith(`..${sep}`) || isAbsolute(relativeToRoot)) {
+			throw new LanguageFileOutsideWorkspace(path, this.cwd);
+		}
+		return absolute;
+	}
+
+	private async ensureInitialized(initialPath?: string): Promise<LanguageServerProcess> {
+		const initialTargetPath = initialPath ? this.resolveTargetPath(initialPath) : undefined;
 		if (this.process) return this.process;
 		if (!this.initializing) {
+			let spawned: LanguageServerProcess | undefined;
 			this.initializing = (async () => {
 				const proc = LanguageServerProcess.spawnProcess({
 					...resolveLanguageServerCommand(this.descriptor),
 					cwd: this.cwd,
 				});
+				spawned = proc;
 				proc.onNotification("textDocument/publishDiagnostics", (params) => {
 					const { uri, diagnostics } = params as LspPublishDiagnosticsParams;
 					const path = fileURLToPath(uri);
@@ -296,24 +373,16 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 				});
 				proc.notify("initialized", {});
 
-				const seedFile = this.explicitSeedFile ?? resolveSeedFile(this.cwd, this.descriptor);
-				const seedPath = join(this.cwd, seedFile);
-				proc.notify("textDocument/didOpen", {
-					textDocument: {
-						uri: pathToFileURL(seedPath).href,
-						languageId: this.descriptor.languageId,
-						version: 1,
-						text: readFileSync(seedPath, "utf-8"),
-					},
-				});
-				this.openedFiles.add(seedPath);
-				// No server signals "project loaded"; must match ensureFileOpen's wait below,
-				// since the seed file is often the first file a caller queries.
-				await new Promise((resolve) => setTimeout(resolve, this.descriptor.settleMs ?? DEFAULT_SETTLE_MS));
+				const configuredSeedFile = this.fallbackSeedFile ?? this.explicitSeedFile;
+				const seedPath = configuredSeedFile
+					? resolve(this.cwd, configuredSeedFile)
+					: (initialTargetPath ?? resolve(this.cwd, resolveSeedFile(this.cwd, this.descriptor)));
+				await this.ensureFileOpen(proc, seedPath);
 
 				this.process = proc;
 				return proc;
-			})().catch((error: unknown) => {
+			})().catch(async (error: unknown) => {
+				await spawned?.stop();
 				// A failed initialize must not permanently poison this workspace's index --
 				// the next call retries fresh rather than replaying the same rejection forever.
 				this.initializing = undefined;
@@ -323,13 +392,38 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 		return this.initializing;
 	}
 
-	/** Opens `path` with the server if not already open, then waits for it to settle. A no-op past the first call for a given path. */
+	private readBoundedFile(path: string): string {
+		const content = readFileSync(path);
+		if (content.byteLength > this.maxFileBytes) throw new LanguageFileLimitExceeded("file-bytes", this.maxFileBytes, content.byteLength);
+		return content.toString("utf-8");
+	}
+
+	/** Opens a file or sends a monotonic full-document change when its disk content changed since the prior query. */
 	private async ensureFileOpen(proc: LanguageServerProcess, path: string): Promise<void> {
-		if (this.openedFiles.has(path)) return;
-		proc.notify("textDocument/didOpen", {
-			textDocument: { uri: pathToFileURL(path).href, languageId: this.descriptor.languageId, version: 1, text: readFileSync(path, "utf-8") },
-		});
-		this.openedFiles.add(path);
+		path = this.resolveTargetPath(path);
+		const content = this.readBoundedFile(path);
+		const opened = this.openedFiles.get(path);
+		if (opened?.content === content) return;
+		if (!opened) {
+			if (this.openedFiles.size >= this.maxOpenFiles) throw new LanguageFileLimitExceeded("open-files", this.maxOpenFiles, this.openedFiles.size + 1);
+			proc.notify("textDocument/didOpen", {
+				textDocument: {
+					uri: pathToFileURL(path).href,
+					languageId: this.descriptor.documentLanguageIds?.[extname(path)] ?? this.descriptor.languageId,
+					version: 1,
+					text: content,
+				},
+			});
+			this.openedFiles.set(path, { version: 1, content });
+		} else {
+			const version = opened.version + 1;
+			this.latestDiagnostics.delete(path);
+			proc.notify("textDocument/didChange", {
+				textDocument: { uri: pathToFileURL(path).href, version },
+				contentChanges: [{ text: content }],
+			});
+			this.openedFiles.set(path, { version, content });
+		}
 		await new Promise((resolve) => setTimeout(resolve, this.descriptor.settleMs ?? DEFAULT_SETTLE_MS));
 	}
 
@@ -346,10 +440,39 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 		});
 	}
 
-	async findSymbols(query: string): Promise<WorkspaceSymbol[]> {
-		const proc = await this.ensureInitialized();
-		const results = (await proc.request<LspSymbolInformation[] | null>("workspace/symbol", { query })) ?? [];
-		return results.map((symbol) => ({
+	private async restartForSeed(seedFile: string): Promise<LanguageServerProcess> {
+		await this.process?.stop();
+		this.process = undefined;
+		this.initializing = undefined;
+		this.openedFiles.clear();
+		this.latestDiagnostics.clear();
+		this.diagnosticsWaiters.clear();
+		this.fallbackSeedFile = seedFile;
+		return this.ensureInitialized();
+	}
+
+	async findSymbols(query: string, bounds: SymbolSearchBounds = { maxResults: DEFAULT_MAX_SYMBOL_RESULTS }): Promise<SymbolSearchResult> {
+		if (!Number.isSafeInteger(bounds.maxResults) || bounds.maxResults < 1) throw new TypeError("maxResults must be a positive safe integer");
+		let proc = await this.ensureInitialized();
+		let refreshedBytes = 0;
+		for (const path of this.openedFiles.keys()) {
+			await this.ensureFileOpen(proc, path);
+			refreshedBytes += Buffer.byteLength(this.openedFiles.get(path)?.content ?? "", "utf-8");
+			if (refreshedBytes > this.maxRefreshBytes) throw new LanguageFileLimitExceeded("refresh-bytes", this.maxRefreshBytes, refreshedBytes);
+		}
+		let results = (await proc.request<LspSymbolInformation[] | null>("workspace/symbol", { query })) ?? [];
+		if (results.length === 0 && this.descriptor.languageId === "typescript") {
+			const candidates = await new TypeScriptCompilerSymbolIndex(this.cwd, { maxResults: this.maxFallbackSeedFiles }).findSymbols(query, {
+				maxResults: this.maxFallbackSeedFiles,
+			});
+			const candidate = candidates.symbols[0];
+			if (candidate) {
+				proc = await this.restartForSeed(candidate.location.path);
+				results = (await proc.request<LspSymbolInformation[] | null>("workspace/symbol", { query })) ?? [];
+			}
+		}
+		const truncated = results.length > bounds.maxResults;
+		const symbols: WorkspaceSymbol[] = results.slice(0, bounds.maxResults).map((symbol) => ({
 			name: symbol.name,
 			kind: LSP_SYMBOL_KIND_NAMES[symbol.kind] ?? "unknown",
 			location: {
@@ -359,10 +482,11 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 			},
 			containerName: symbol.containerName,
 		}));
+		return { symbols, truncated, provenance: this.provenance };
 	}
 
 	async goToDefinition(at: WorkspaceLocation): Promise<WorkspaceLocation[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		await this.ensureFileOpen(proc, at.path);
 		const result = await proc.request<LspLocation | LspLocation[] | LspLocationLink[] | null>("textDocument/definition", {
 			textDocument: { uri: pathToFileURL(at.path).href },
@@ -372,7 +496,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async goToImplementation(at: WorkspaceLocation): Promise<WorkspaceLocation[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		await this.ensureFileOpen(proc, at.path);
 		const result = await proc.request<LspLocation | LspLocation[] | LspLocationLink[] | null>("textDocument/implementation", {
 			textDocument: { uri: pathToFileURL(at.path).href },
@@ -382,7 +506,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async findReferences(at: WorkspaceLocation, includeDeclaration: boolean): Promise<WorkspaceLocation[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		await this.ensureFileOpen(proc, at.path);
 		const results =
 			(await proc.request<LspLocation[] | null>("textDocument/references", {
@@ -394,7 +518,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async hover(at: WorkspaceLocation): Promise<Hover | undefined> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		await this.ensureFileOpen(proc, at.path);
 		const result = await proc.request<LspHover | null>("textDocument/hover", {
 			textDocument: { uri: pathToFileURL(at.path).href },
@@ -405,7 +529,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async documentSymbols(path: string): Promise<DocumentSymbolEntry[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(path);
 		await this.ensureFileOpen(proc, path);
 		const results =
 			(await proc.request<(LspDocumentSymbol | LspSymbolInformation)[] | null>("textDocument/documentSymbol", {
@@ -415,7 +539,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async diagnostics(path: string): Promise<Diagnostic[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(path);
 		await this.ensureFileOpen(proc, path);
 		if (!this.latestDiagnostics.has(path)) await this.waitForDiagnosticsNotification(path, 5000);
 		return this.latestDiagnostics.get(path) ?? [];
@@ -432,13 +556,13 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async prepareCallHierarchy(at: WorkspaceLocation): Promise<CallHierarchyEntry[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		const items = await this.prepareCallHierarchyRaw(proc, at);
 		return items.map((item) => normalizeCallHierarchyItem(item));
 	}
 
 	async incomingCalls(at: WorkspaceLocation): Promise<IncomingCall[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		const root = (await this.prepareCallHierarchyRaw(proc, at))[0];
 		if (!root) return [];
 		const results = (await proc.request<LspCallHierarchyIncomingCall[] | null>("callHierarchy/incomingCalls", { item: root })) ?? [];
@@ -449,7 +573,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async outgoingCalls(at: WorkspaceLocation): Promise<OutgoingCall[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		const root = (await this.prepareCallHierarchyRaw(proc, at))[0];
 		if (!root) return [];
 		const results = (await proc.request<LspCallHierarchyOutgoingCall[] | null>("callHierarchy/outgoingCalls", { item: root })) ?? [];
@@ -462,7 +586,9 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async close(): Promise<void> {
-		await this.process?.stop();
+		const initializing = this.initializing;
+		const process = this.process ?? (initializing ? await initializing.catch(() => undefined) : undefined);
+		await process?.stop();
 		this.process = undefined;
 		this.initializing = undefined;
 		this.openedFiles.clear();

package/src/adapters/normalize-npm-repository.ts

@@ -0,0 +1,77 @@
+import { posix } from "node:path";
+import type { NpmRepositoryMetadata } from "../domain/npm-package-metadata.ts";
+import type { RepoReference } from "../domain/repo-reference.ts";
+
+export interface NormalizedNpmRepository {
+	readonly url: string;
+	readonly host: string;
+	readonly owner: string;
+	readonly repo: string;
+	readonly directory: string | null;
+}
+
+function containsControlCharacter(value: string): boolean {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code <= 31 || code === 127) return true;
+	}
+	return false;
+}
+
+function normalizedDirectory(raw: string | null): string | null {
+	if (raw === null) return null;
+	if (raw.length === 0 || raw.length > 2048 || raw.includes("\\") || containsControlCharacter(raw) || posix.isAbsolute(raw)) return null;
+	const normalized = posix.normalize(raw.replace(/^\.\//, "")).replace(/\/$/, "");
+	if (normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.length === 0) return null;
+	return normalized;
+}
+
+function shorthand(raw: string): string {
+	for (const [prefix, host] of [
+		["github:", "github.com"],
+		["gitlab:", "gitlab.com"],
+		["bitbucket:", "bitbucket.org"],
+	] as const) {
+		if (raw.startsWith(prefix)) return `https://${host}/${raw.slice(prefix.length)}`;
+	}
+	if (/^[^/:\s]+\/[^/\s]+(?:\.git)?$/.test(raw)) return `https://github.com/${raw}`;
+	return raw;
+}
+
+function repositoryUrl(raw: string): URL | null {
+	let candidate = shorthand(raw.trim()).replace(/^git\+/, "");
+	const scp = candidate.match(/^git@([^:]+):(.+)$/);
+	if (scp) candidate = `ssh://git@${scp[1]}/${scp[2]}`;
+	if (candidate.startsWith("git://")) candidate = `https://${candidate.slice("git://".length)}`;
+	let parsed: URL;
+	try {
+		parsed = new URL(candidate);
+	} catch {
+		return null;
+	}
+	if (!["https:", "http:", "ssh:"].includes(parsed.protocol) || parsed.search || parsed.hash || parsed.password) return null;
+	if (parsed.username && parsed.username !== "git") return null;
+	return parsed;
+}
+
+export function normalizeNpmRepository(metadata: NpmRepositoryMetadata): NormalizedNpmRepository | null {
+	if (metadata.type !== null && metadata.type.toLowerCase() !== "git") return null;
+	const parsed = repositoryUrl(metadata.url);
+	if (parsed === null) return null;
+	const segments = parsed.pathname
+		.replace(/^\//, "")
+		.replace(/\.git$/, "")
+		.split("/")
+		.filter(Boolean);
+	if (segments.length !== 2) return null;
+	const [owner, repo] = segments;
+	if (!owner || !repo || owner === "." || owner === ".." || repo === "." || repo === "..") return null;
+	const directory = normalizedDirectory(metadata.directory);
+	if (metadata.directory !== null && directory === null) return null;
+	const host = parsed.hostname.toLowerCase();
+	return { url: `https://${host}/${owner}/${repo}.git`, host, owner, repo, directory };
+}
+
+export function npmRepositoryReference(repository: NormalizedNpmRepository, ref: string): RepoReference {
+	return { host: repository.host, owner: repository.owner, repo: repository.repo, ref };
+}