@narumitw/pi-lsp 0.1.26 → 0.1.27

package/src/lsp-client.ts

@@ -9,7 +9,6 @@ import type {
 	JsonRpcMessage,
 	LspDiagnostic,
 	LspServerAdapter,
-	LspTextEdit,
 	ServerCommand,
 } from "./types.js";
 
@@ -50,12 +49,13 @@ export class LspClient {
 	async start() {
 		if (!commandExists(this.#command.command, this.#cwd)) {
 			throw new Error(
-				`${this.#adapter.label} LSP command not found: ${this.#command.command}. ${this.#adapter.missingCommandHint}`,
+				`${this.#adapter.name} LSP command not found: ${this.#command.command}. ${this.#adapter.missingCommandHint}`,
 			);
 		}
 
 		const child = spawn(this.#command.command, this.#command.args, {
 			cwd: this.#cwd,
+			env: { ...process.env, ...this.#adapter.env },
 			stdio: "pipe",
 		});
 		this.#child = child;
@@ -64,7 +64,7 @@ export class LspClient {
 				this.#onData(chunk);
 			} catch (error) {
 				this.#fail(
-					`${this.#adapter.label} LSP server sent invalid JSON-RPC data: ${formatErrorMessage(error)}.${this.#formatStderr()}`,
+					`${this.#adapter.name} LSP server sent invalid JSON-RPC data: ${formatErrorMessage(error)}.${this.#formatStderr()}`,
 				);
 			}
 		});
@@ -73,7 +73,7 @@ export class LspClient {
 		});
 		child.stdin.on("error", (error) => {
 			this.#fail(
-				`${this.#adapter.label} LSP stdin write failed: ${formatErrorMessage(error)}.${this.#formatStderr()}`,
+				`${this.#adapter.name} LSP stdin write failed: ${formatErrorMessage(error)}.${this.#formatStderr()}`,
 			);
 		});
 		child.once("exit", (code, signal) => {
@@ -81,14 +81,14 @@ export class LspClient {
 			const reason = signal ? `signal ${signal}` : `code ${code ?? "unknown"}`;
 			this.#rejectPending(
 				(id) =>
-					`${this.#adapter.label} LSP server exited before response ${id} (${reason}).${this.#formatStderr()}`,
+					`${this.#adapter.name} LSP server exited before response ${id} (${reason}).${this.#formatStderr()}`,
 			);
 		});
 
 		await new Promise<void>((resolve, reject) => {
 			child.once("spawn", resolve);
 			child.once("error", (error) => {
-				const message = `${this.#adapter.label} LSP process failed to start: ${error.message}.${this.#formatStderr()}`;
+				const message = `${this.#adapter.name} LSP process failed to start: ${error.message}.${this.#formatStderr()}`;
 				this.#rejectPending(message);
 				if (this.#child === child) this.#child = undefined;
 				reject(new Error(message));
@@ -99,49 +99,32 @@ export class LspClient {
 	async initialize(root: string) {
 		const rootUri = directoryUri(root);
 		const workspaceFolders = [{ uri: rootUri, name: path.basename(root) || "workspace" }];
-		const init = this.#adapter.initialize;
 		await this.request("initialize", {
 			processId: process.pid,
 			rootUri,
-			workspaceFolders: this.#adapter.serverRequestWorkspaceFolders ? workspaceFolders : null,
+			workspaceFolders,
+			initializationOptions: this.#adapter.initialization ?? {},
 			capabilities: {
 				textDocument: {
-					...(init.codeAction
-						? {
-								codeAction: {
-									dynamicRegistration: init.codeActionDynamicRegistration,
-									resolveSupport: { properties: ["edit"] },
-								},
-							}
-						: {}),
-					diagnostic: { dynamicRegistration: init.diagnosticDynamicRegistration },
-					...(init.formattingDynamicRegistration === undefined
-						? {}
-						: { formatting: { dynamicRegistration: init.formattingDynamicRegistration } }),
-					publishDiagnostics: {},
-					synchronization: {
-						didSave: true,
-						...(init.didSaveDynamicRegistration === undefined
-							? {}
-							: { dynamicRegistration: init.didSaveDynamicRegistration }),
+					codeAction: {
+						dynamicRegistration: true,
+						resolveSupport: { properties: ["edit"] },
 					},
+					diagnostic: { dynamicRegistration: true, relatedDocumentSupport: true },
+					publishDiagnostics: {},
+					synchronization: { didSave: true },
 				},
 				workspace: {
 					configuration: true,
-					...(init.didChangeConfigurationDynamicRegistration === undefined
-						? {}
-						: {
-								didChangeConfiguration: {
-									dynamicRegistration: init.didChangeConfigurationDynamicRegistration,
-								},
-							}),
 					workspaceEdit: { documentChanges: true },
-					workspaceFolders: this.#adapter.serverRequestWorkspaceFolders,
+					workspaceFolders: true,
 				},
 			},
 		});
 		this.notify("initialized", {});
-		if (this.#adapter.fallbackToPublishDiagnostics) await wait(300);
+		if (this.#adapter.initialization) {
+			this.notify("workspace/didChangeConfiguration", { settings: this.#adapter.initialization });
+		}
 	}
 
 	didOpen(uri: string, text: string, languageId: string) {
@@ -168,19 +151,11 @@ export class LspClient {
 			const result = response.result as { items?: LspDiagnostic[] } | undefined;
 			return result?.items ?? [];
 		} catch (error) {
-			if (!this.#adapter.fallbackToPublishDiagnostics || !isUnsupportedMethodError(error)) throw error;
+			if (!isUnsupportedMethodError(error)) throw error;
 			return this.#waitForPublishedDiagnostics(uri);
 		}
 	}
 
-	async format(uri: string) {
-		const response = await this.request("textDocument/formatting", {
-			textDocument: { uri },
-			options: this.#adapter.formattingOptions,
-		});
-		return (response.result as LspTextEdit[] | null | undefined) ?? [];
-	}
-
 	async codeActions(uri: string, text: string, diagnostics: LspDiagnostic[], kind: string) {
 		const response = await this.request("textDocument/codeAction", {
 			textDocument: { uri },
@@ -202,7 +177,7 @@ export class LspClient {
 				const response = await this.request("codeAction/resolve", action);
 				resolvedActions.push((response.result as CodeAction | undefined) ?? action);
 			} catch (error) {
-				if (!this.#adapter.resolveUnsupportedCodeActions || !isUnsupportedMethodError(error)) throw error;
+				if (!isUnsupportedMethodError(error)) throw error;
 				resolvedActions.push(action);
 			}
 		}
@@ -224,7 +199,7 @@ export class LspClient {
 	}
 
 	close() {
-		this.#rejectPending(`${this.#adapter.label} LSP request cancelled.`);
+		this.#rejectPending(`${this.#adapter.name} LSP request cancelled.`);
 
 		if (this.#child && !this.#child.killed) this.#child.kill("SIGTERM");
 		this.#child = undefined;
@@ -258,7 +233,7 @@ export class LspClient {
 			const timeout = setTimeout(() => {
 				this.#pending.delete(id);
 				reject(
-					new Error(`${this.#adapter.label} LSP request timed out: ${method}.${this.#formatStderr()}`),
+					new Error(`${this.#adapter.name} LSP request timed out: ${method}.${this.#formatStderr()}`),
 				);
 			}, this.#timeoutMs);
 			this.#pending.set(id, { resolve, reject, timeout });
@@ -280,14 +255,14 @@ export class LspClient {
 	}
 
 	#send(message: JsonRpcMessage) {
-		if (!this.#child) throw new Error(`${this.#adapter.label} LSP server is not running.`);
+		if (!this.#child) throw new Error(`${this.#adapter.name} LSP server is not running.`);
 
 		const body = JSON.stringify(message);
 		try {
 			this.#child.stdin.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
 		} catch (error) {
 			const errorMessage =
-				`${this.#adapter.label} LSP stdin write failed: ${formatErrorMessage(error)}.` +
+				`${this.#adapter.name} LSP stdin write failed: ${formatErrorMessage(error)}.` +
 				this.#formatStderr();
 			this.#fail(errorMessage);
 			throw new Error(errorMessage);
@@ -323,7 +298,7 @@ export class LspClient {
 			clearTimeout(pending.timeout);
 			this.#pending.delete(message.id as number);
 			if (message.error) {
-				pending.reject(new Error(`${this.#adapter.label} LSP error: ${message.error.message}`));
+				pending.reject(new Error(`${this.#adapter.name} LSP error: ${message.error.message}`));
 			} else {
 				pending.resolve(message);
 			}
@@ -362,7 +337,11 @@ export class LspClient {
 					const waiters = this.#diagnosticWaiters.get(uri)?.filter((entry) => entry !== waiter) ?? [];
 					if (waiters.length) this.#diagnosticWaiters.set(uri, waiters);
 					else this.#diagnosticWaiters.delete(uri);
-					resolve(this.#publishedDiagnostics.get(uri) ?? []);
+					reject(
+						new Error(
+							`${this.#adapter.name} LSP did not return diagnostics for ${uri} before timeout.`,
+						),
+					);
 				}, this.#timeoutMs),
 			};
 			this.#diagnosticWaiters.set(uri, [...(this.#diagnosticWaiters.get(uri) ?? []), waiter]);
@@ -371,11 +350,11 @@ export class LspClient {
 
 	#respondToServerRequest(message: JsonRpcMessage) {
 		if (message.method === "workspace/configuration") {
-			const params = message.params as { items?: unknown[] } | undefined;
+			const params = message.params as { items?: Array<{ section?: string }> } | undefined;
 			this.#send({
 				jsonrpc: "2.0",
 				id: message.id,
-				result: (params?.items ?? []).map(() => ({})),
+				result: (params?.items ?? []).map((item) => this.#configurationValue(item.section)),
 			});
 			return;
 		}
@@ -385,9 +364,7 @@ export class LspClient {
 			this.#send({
 				jsonrpc: "2.0",
 				id: message.id,
-				result: this.#adapter.serverRequestWorkspaceFolders
-					? [{ uri: rootUri, name: path.basename(this.#cwd) || "workspace" }]
-					: null,
+				result: [{ uri: rootUri, name: path.basename(this.#cwd) || "workspace" }],
 			});
 			return;
 		}
@@ -407,6 +384,11 @@ export class LspClient {
 		});
 	}
 
+	#configurationValue(section: string | undefined) {
+		if (!section) return this.#adapter.initialization ?? {};
+		return this.#adapter.initialization?.[section] ?? {};
+	}
+
 	#formatStderr() {
 		const stderr = this.#stderr.trim();
 		return stderr ? `\nServer stderr:\n${stderr}` : "";
@@ -420,7 +402,3 @@ function isUnsupportedMethodError(error: unknown) {
 function formatErrorMessage(error: unknown) {
 	return error instanceof Error ? error.message : String(error);
 }
-
-function wait(ms: number) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/src/pi-lsp.ts

@@ -1,185 +1,140 @@
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { adapters, biomeAdapter, ruffAdapter, tyAdapter } from "./adapters.js";
+import { loadRuntime } from "./adapters.js";
 import { commandExists, commandFromEnv } from "./command.js";
-import { runDiagnostics, runFix, runFormat } from "./runner.js";
+import { resolveRoot } from "./files.js";
+import { selectDiagnosticRoutes, selectFixRoute } from "./routes.js";
+import { DEFAULT_FILE_LIMIT, runDiagnostics, runFix, textResult } from "./runner.js";
 
 const STATUS_KEY = "lsp";
 
-const BiomePathsParameters = {
+const ServerParameter = Type.Optional(
+	Type.Union([Type.String(), Type.Array(Type.String())], {
+		description:
+			"Optional configured LSP server name, or names for diagnostics. Defaults to all servers matching the file extension.",
+	}),
+);
+
+const DiagnosticsParameters = Type.Object({
 	paths: Type.Optional(
 		Type.Array(Type.String(), {
-			description: "Biome-supported files or directories to check. Defaults to the project root.",
+			description:
+				"Files or directories to check. Defaults to the workspace root and routes by configured server extensions.",
 		}),
 	),
 	root: Type.Optional(
-		Type.String({ description: "Workspace root for the Biome language server. Defaults to cwd." }),
+		Type.String({ description: "Workspace root for language servers. Defaults to cwd." }),
 	),
-	limit: Type.Optional(
-		Type.Number({ description: "Maximum files to open when directories are provided." }),
-	),
-};
+	limit: Type.Optional(Type.Number({ description: "Maximum files to open per selected server." })),
+	server: ServerParameter,
+});
 
-const PythonPathsParameters = {
-	paths: Type.Optional(
-		Type.Array(Type.String(), {
-			description: "Python files or directories to check. Defaults to the project root.",
-		}),
-	),
+const SingleFileParameters = {
+	path: Type.String({
+		description: "File to process. The server is selected from configured file extensions.",
+	}),
 	root: Type.Optional(
-		Type.String({ description: "Workspace root for the language server. Defaults to cwd." }),
+		Type.String({ description: "Workspace root for language servers. Defaults to cwd." }),
 	),
-	limit: Type.Optional(
-		Type.Number({ description: "Maximum Python files to open when directories are provided." }),
+	write: Type.Optional(
+		Type.Boolean({ description: "Write changed text back to the file. Defaults to false." }),
+	),
+	server: Type.Optional(
+		Type.String({
+			description: "Optional configured LSP server name. Defaults to extension-based inference.",
+		}),
 	),
 };
 
-const biomeDiagnosticsTool = defineTool({
-	name: "biome_lsp_diagnostics",
-	label: "Biome LSP: Diagnostics",
-	description: "Run Biome's language server and return diagnostics for supported files.",
-	promptSnippet: "Get Biome diagnostics through the Biome language server",
-	promptGuidelines: [
-		"Use biome_lsp_diagnostics when JavaScript, TypeScript, JSON, CSS, GraphQL, or framework files need Biome lint/format diagnostics.",
-		"If Biome is missing, report the configuration error and suggest installing @biomejs/biome or setting PI_BIOME_LSP_COMMAND.",
-	],
-	parameters: Type.Object(BiomePathsParameters),
-	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-		return runDiagnostics(biomeAdapter, params, signal, ctx, STATUS_KEY);
-	},
-});
-
-const biomeFormatTool = defineTool({
-	name: "biome_lsp_format",
-	label: "Biome LSP: Format",
-	description: "Format a Biome-supported file through Biome's language server.",
-	promptSnippet: "Format a file through Biome LSP",
-	parameters: Type.Object({
-		path: Type.String({ description: "File to format." }),
-		root: Type.Optional(
-			Type.String({ description: "Workspace root for the Biome language server. Defaults to cwd." }),
-		),
-		write: Type.Optional(
-			Type.Boolean({ description: "Write formatted text back to the file. Defaults to false." }),
-		),
-	}),
-	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-		return runFormat(biomeAdapter, params, signal, ctx, STATUS_KEY);
-	},
-});
-
-const biomeFixTool = defineTool({
-	name: "biome_lsp_fix",
-	label: "Biome LSP: Fix",
-	description: "Apply Biome LSP source fixes or import organization to a file.",
-	promptSnippet: "Apply Biome LSP fixes to a file",
-	parameters: Type.Object({
-		path: Type.String({ description: "File to fix." }),
-		root: Type.Optional(
-			Type.String({ description: "Workspace root for the Biome language server. Defaults to cwd." }),
-		),
-		kind: Type.Optional(
-			Type.String({
-				description:
-					"Biome source action kind. Defaults to source.fixAll.biome. Common value: source.organizeImports.biome.",
-			}),
-		),
-		write: Type.Optional(
-			Type.Boolean({ description: "Write fixed text back to the file. Defaults to false." }),
-		),
-	}),
-	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-		return runFix(biomeAdapter, params, signal, ctx, STATUS_KEY);
-	},
-});
-
-const tyDiagnosticsTool = defineTool({
-	name: "ty_lsp_diagnostics",
-	label: "Python LSP: ty Diagnostics",
-	description: "Run ty's language server and return Python type diagnostics for files.",
-	promptSnippet: "Get Python type diagnostics from ty's language server",
+const lspDiagnosticsTool = defineTool({
+	name: "lsp_diagnostics",
+	label: "LSP: Diagnostics",
+	description: "Run diagnostics using configured, language-agnostic LSP server routes.",
+	promptSnippet: "Get diagnostics from configured LSP servers selected by file extension",
 	promptGuidelines: [
-		"Use ty_lsp_diagnostics when Python changes need type-checking through ty's language server.",
-		"If ty is missing, report the configuration error and suggest installing ty or setting PI_TY_LSP_COMMAND.",
+		"Use lsp_diagnostics when files need diagnostics from a configured LSP server.",
+		"Use the server parameter only when the user asks for a specific configured LSP server or multiple servers match the same extension.",
+		"If a configured server command is missing, report the configuration error and suggest installing the command or setting its PI_<SERVER>_LSP_COMMAND environment variable.",
 	],
-	parameters: Type.Object(PythonPathsParameters),
+	parameters: DiagnosticsParameters,
 	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-		return runDiagnostics(tyAdapter, params, signal, ctx, STATUS_KEY);
+		const requestedRoot = resolveRoot(params.root);
+		const { adapters, timeoutMs } = loadRuntime(requestedRoot);
+		const { root, routes } = selectDiagnosticRoutes(
+			adapters,
+			{ ...params, root: requestedRoot },
+			DEFAULT_FILE_LIMIT,
+		);
+		const results = [];
+		for (const route of routes) {
+			const result = await runDiagnostics(
+				route.adapter,
+				{ root, paths: params.paths, limit: params.limit, files: route.files },
+				timeoutMs,
+				signal,
+				ctx,
+				STATUS_KEY,
+			);
+			results.push({ route, result });
+		}
+
+		const text = results
+			.map(({ route, result }) => `${route.reason}\n\n${textFromResult(result)}`)
+			.join("\n\n---\n\n");
+		return textResult(text, {
+			root,
+			routes: results.map(({ route, result }) => ({
+				server: route.adapter.name,
+				backend: route.adapter.name,
+				reason: route.reason,
+				files: route.files,
+				details: result.details,
+			})),
+		});
 	},
 });
 
-const ruffDiagnosticsTool = defineTool({
-	name: "ruff_lsp_diagnostics",
-	label: "Python LSP: Ruff Diagnostics",
-	description: "Run Ruff's language server and return Python lint diagnostics for files.",
-	promptSnippet: "Get Python lint diagnostics from Ruff's language server",
+const lspFixTool = defineTool({
+	name: "lsp_fix",
+	label: "LSP: Fix",
+	description: "Apply source fixes or import organization using configured LSP server routes.",
+	promptSnippet: "Apply configured LSP source fixes to a file",
 	promptGuidelines: [
-		"Use ruff_lsp_diagnostics when Python changes need Ruff lint checks through the language server.",
-		"If ruff is missing, report the configuration error and suggest installing ruff or setting PI_RUFF_LSP_COMMAND.",
+		"Use lsp_fix for files handled by a configured LSP code-action server.",
+		"Use kind when the server needs a specific source action kind such as source.organizeImports.",
 	],
-	parameters: Type.Object(PythonPathsParameters),
-	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-		return runDiagnostics(ruffAdapter, params, signal, ctx, STATUS_KEY);
-	},
-});
-
-const ruffFormatTool = defineTool({
-	name: "ruff_lsp_format",
-	label: "Python LSP: Ruff Format",
-	description: "Format a Python file through Ruff's language server.",
-	promptSnippet: "Format a Python file through Ruff LSP",
 	parameters: Type.Object({
-		path: Type.String({ description: "Python file to format." }),
-		root: Type.Optional(
-			Type.String({ description: "Workspace root for the language server. Defaults to cwd." }),
-		),
-		write: Type.Optional(
-			Type.Boolean({ description: "Write formatted text back to the file. Defaults to false." }),
-		),
-	}),
-	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-		return runFormat(ruffAdapter, params, signal, ctx, STATUS_KEY);
-	},
-});
-
-const ruffFixTool = defineTool({
-	name: "ruff_lsp_fix",
-	label: "Python LSP: Ruff Fix",
-	description: "Apply Ruff LSP source fixes or import organization to a Python file.",
-	promptSnippet: "Apply Ruff LSP fixes to a Python file",
-	parameters: Type.Object({
-		path: Type.String({ description: "Python file to fix." }),
-		root: Type.Optional(
-			Type.String({ description: "Workspace root for the language server. Defaults to cwd." }),
-		),
+		...SingleFileParameters,
 		kind: Type.Optional(
 			Type.String({
-				description:
-					"Ruff source action kind. Defaults to source.fixAll.ruff. Common value: source.organizeImports.ruff.",
+				description: "Source action kind. Defaults to source.fixAll.",
 			}),
 		),
-		write: Type.Optional(
-			Type.Boolean({ description: "Write fixed text back to the file. Defaults to false." }),
-		),
 	}),
 	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-		return runFix(ruffAdapter, params, signal, ctx, STATUS_KEY);
+		const requestedRoot = resolveRoot(params.root);
+		const { adapters, timeoutMs } = loadRuntime(requestedRoot);
+		const { root, route } = selectFixRoute(adapters, { ...params, root: requestedRoot });
+		return runFix(
+			route.adapter,
+			{ root, path: params.path, kind: params.kind, write: params.write },
+			timeoutMs,
+			signal,
+			ctx,
+			STATUS_KEY,
+		);
 	},
 });
 
 export default function lsp(pi: ExtensionAPI) {
-	pi.registerTool(biomeDiagnosticsTool);
-	pi.registerTool(biomeFormatTool);
-	pi.registerTool(biomeFixTool);
-	pi.registerTool(tyDiagnosticsTool);
-	pi.registerTool(ruffDiagnosticsTool);
-	pi.registerTool(ruffFormatTool);
-	pi.registerTool(ruffFixTool);
+	pi.registerTool(lspDiagnosticsTool);
+	pi.registerTool(lspFixTool);
 
 	pi.registerCommand("lsp", {
 		description: "Show shared LSP extension configuration",
 		handler: async (_args, ctx) => {
-			ctx.ui.notify(buildStatusMessage(), statusLevel());
+			const { adapters } = loadRuntime(ctx.cwd);
+			ctx.ui.notify(buildStatusMessage(adapters, ctx.cwd), statusLevel(adapters, ctx.cwd));
 		},
 	});
 
@@ -192,22 +147,26 @@ export default function lsp(pi: ExtensionAPI) {
 	});
 }
 
-function buildStatusMessage() {
+function textFromResult(result: { content?: Array<{ type?: string; text?: string }> }) {
+	return result.content?.find((item) => item.type === "text")?.text ?? "";
+}
+
+function buildStatusMessage(adapters: ReturnType<typeof loadRuntime>["adapters"], cwd: string) {
 	return adapters
 		.flatMap((adapter) => {
 			const command = commandFromEnv(adapter.commandEnvVar, adapter.defaultCommand);
 			return [
-				`${adapter.label} LSP command: ${command.command} ${command.args.join(" ")}`.trim(),
-				`${adapter.label} status: ${commandExists(command.command) ? "ready" : "command missing"}`,
+				`${adapter.name} LSP command: ${command.command} ${command.args.join(" ")}`.trim(),
+				`${adapter.name} status: ${commandExists(command.command, cwd) ? "ready" : "command missing"}`,
 			];
 		})
 		.join("\n");
 }
 
-function statusLevel() {
+function statusLevel(adapters: ReturnType<typeof loadRuntime>["adapters"], cwd: string) {
 	return adapters.every((adapter) => {
 		const command = commandFromEnv(adapter.commandEnvVar, adapter.defaultCommand);
-		return commandExists(command.command);
+		return commandExists(command.command, cwd);
 	})
 		? "info"
 		: "warning";

package/src/routes.ts

@@ -0,0 +1,98 @@
+import path from "node:path";
+import { collectSupportedFiles, resolveRoot } from "./files.js";
+import type { LspServerAdapter } from "./types.js";
+
+export type LspAction = "diagnostics" | "fix";
+
+export interface DiagnosticRoute {
+	adapter: LspServerAdapter;
+	reason: string;
+	files: string[];
+}
+
+export interface SingleFileRoute {
+	adapter: LspServerAdapter;
+	reason: string;
+}
+
+export interface DiagnosticRouteParams {
+	root?: string;
+	paths?: string[];
+	limit?: number;
+	server?: string | string[];
+}
+
+export interface SingleFileRouteParams {
+	root?: string;
+	path: string;
+	server?: string;
+}
+
+export const SUPPORTED_SERVER_DESCRIPTION =
+	"Supported LSP servers are defined by pi-lsp config and selected by file extension.";
+
+export function selectDiagnosticRoutes(
+	adapters: LspServerAdapter[],
+	params: DiagnosticRouteParams,
+	defaultLimit: number,
+) {
+	const root = resolveRoot(params.root);
+	const candidates = filterAdapters(adapters, params.server);
+	const filesByExtensions = new Map<string, string[]>();
+	const routes = candidates
+		.map((adapter) => {
+			const key = adapter.extensions.join("\0");
+			let files = filesByExtensions.get(key);
+			if (!files) {
+				files = collectSupportedFiles(adapter, root, params.paths, params.limit ?? defaultLimit);
+				filesByExtensions.set(key, files);
+			}
+			return { adapter, reason: `${adapter.name} diagnostics`, files };
+		})
+		.filter((route) => route.files.length > 0);
+
+	if (routes.length === 0) {
+		const scope = params.paths?.length ? ` in requested paths: ${params.paths.join(", ")}` : "";
+		throw new Error(`No supported files found${scope}. ${SUPPORTED_SERVER_DESCRIPTION}`);
+	}
+
+	return { root, routes };
+}
+
+export function selectFixRoute(adapters: LspServerAdapter[], params: SingleFileRouteParams) {
+	const root = resolveRoot(params.root);
+	const file = path.resolve(root, params.path);
+	const candidates = filterAdapters(adapters, params.server).filter((adapter) => adapter.isSupportedFile(file));
+	if (candidates.length === 0) throw unsupportedFileError("fix", params.path, params.server);
+	if (!params.server && candidates.length > 1) {
+		throw new Error(
+			`Multiple LSP servers support ${params.path}: ${candidates.map((adapter) => adapter.name).join(", ")}. ` +
+				"Specify the server parameter for lsp_fix.",
+		);
+	}
+	const adapter = candidates[0];
+	return {
+		root,
+		route: {
+			adapter,
+			reason: `${adapter.name} fix`,
+		},
+	};
+}
+
+function filterAdapters(adapters: LspServerAdapter[], selected: string | string[] | undefined) {
+	if (!selected) return adapters;
+	const names = [...new Set((Array.isArray(selected) ? selected : [selected]).map((name) => name.trim()))].filter(
+		(name) => name.length > 0,
+	);
+	if (names.length === 0) throw new Error("LSP server parameter must not be blank.");
+	const matched = adapters.filter((adapter) => names.includes(adapter.name));
+	const missing = names.filter((name) => !adapters.some((adapter) => adapter.name === name));
+	if (missing.length) throw new Error(`Unknown LSP server(s): ${missing.join(", ")}.`);
+	return matched;
+}
+
+function unsupportedFileError(action: LspAction, filePath: string, server: string | undefined) {
+	const override = server ? ` for server '${server}'` : "";
+	return new Error(`No ${action} route supports ${filePath}${override}. ${SUPPORTED_SERVER_DESCRIPTION}`);
+}