@narumitw/pi-lsp 0.20.0 → 0.22.0

package/README.md

@@ -36,7 +36,7 @@ pi -e ./extensions/pi-lsp
 
 ## ⚙️ Configuration
 
-If no config is provided, pi-lsp ships a broad catalog of direct-command defaults. Servers are started only when matching files are requested. pi-lsp does not download language servers, so install the commands you need and make them available on `PATH`. During no-config diagnostics, unavailable default commands are filtered before workspace discovery; explicitly selected or custom-configured missing commands still report an error.
+If no config is provided, pi-lsp ships a broad catalog of direct-command defaults. Servers are started only when matching files are requested. pi-lsp does not download language servers, so install the commands you need and make them available on `PATH`. During no-config diagnostics, unavailable default commands are filtered before workspace discovery. If none can run, diagnostics completes successfully and reports the skipped servers. Explicitly selected or custom-configured missing commands still report an error.
 
 | Language or format | Default server | Startup command | Extensions |
 | --- | --- | --- | --- |
@@ -156,6 +156,7 @@ Each server entry supports:
 - `env`: extra environment variables for the LSP server process.
 - `initialization`: LSP initialization options and workspace configuration values.
 - `skipDirectories`: additional directory names to exclude from recursive discovery. Explicitly requested paths remain available.
+- `diagnosticsSettleMs`: positive number of milliseconds without another push-diagnostics publication before using the latest result. Defaults to `800`; the built-in intelephense route uses `4000`. The global timeout remains the upper bound.
 
 Global options:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-lsp",
-	"version": "0.20.0",
+	"version": "0.22.0",
 	"description": "Pi extension that exposes configurable, language-agnostic LSP tools through a shared runner.",
 	"type": "module",
 	"license": "MIT",

package/src/adapters.ts

@@ -151,6 +151,8 @@ export const DEFAULT_SERVER_CONFIGS: InternalLspServer[] = [
 		command: ["intelephense", "--stdio"],
 		extensions: [".php"],
 		initialization: { intelephense: { telemetry: { enabled: false } } },
+		// Publishes empty on didOpen, then real diagnostics ~0.2-3s later.
+		diagnosticsSettleMs: 4000,
 	},
 	{
 		name: "prisma",
@@ -419,6 +421,7 @@ function normalizeServer(name: string, value: unknown, label: string): InternalL
 		env: optionalStringRecordField(value, "env", label),
 		initialization: optionalRecordField(value, "initialization", label),
 		skipDirectories: optionalDirectoryNamesField(value, "skipDirectories", label),
+		diagnosticsSettleMs: optionalPositiveNumberField(value, "diagnosticsSettleMs", label),
 	};
 }
 
@@ -444,6 +447,7 @@ function configToAdapter(config: InternalLspServer): LspServerAdapter {
 		env: config.env,
 		initialization: config.initialization,
 		skipDirectories: new Set([...COMMON_SKIP_DIRECTORIES, ...(config.skipDirectories ?? [])]),
+		diagnosticsSettleMs: config.diagnosticsSettleMs,
 		isSupportedFile: (filePath) => extensionSet.has(path.extname(filePath)),
 		languageIdFor: (filePath) => languageIdFor(config, filePath),
 	};
@@ -547,6 +551,15 @@ function stringArrayField(value: Record<string, unknown>, field: string, label:
 	return fieldValue;
 }
 
+function optionalPositiveNumberField(value: Record<string, unknown>, field: string, label: string) {
+	const fieldValue = value[field];
+	if (fieldValue === undefined) return undefined;
+	if (typeof fieldValue !== "number" || !Number.isFinite(fieldValue) || fieldValue <= 0) {
+		throw new Error(`${label}.${field} must be a positive number.`);
+	}
+	return fieldValue;
+}
+
 function optionalStringRecordField(value: Record<string, unknown>, field: string, label: string) {
 	const fieldValue = value[field];
 	if (fieldValue === undefined) return undefined;

package/src/lsp-client.ts

@@ -24,6 +24,9 @@ export function resolveSpawnCommand(
 	};
 }
 
+// Quiet period (ms) after each publish before treating push diagnostics as settled.
+const PUBLISHED_DIAGNOSTICS_SETTLE_MS = 800;
+
 export class LspClient {
 	#child?: ChildProcessWithoutNullStreams;
 	#buffer = Buffer.alloc(0);
@@ -39,13 +42,14 @@ export class LspClient {
 	#publishedDiagnostics = new Map<string, LspDiagnostic[]>();
 	#diagnosticWaiters = new Map<
 		string,
-		Array<{
-			resolve: (diagnostics: LspDiagnostic[]) => void;
+		Set<{
+			onPublish: () => void;
 			reject: (reason: unknown) => void;
-			timeout: NodeJS.Timeout;
+			dispose: () => void;
 		}>
 	>();
 	#stderr = "";
+	#serverCapabilities: Record<string, unknown> = {};
 	#adapter: LspServerAdapter;
 	#command: ServerCommand;
 	#cwd: string;
@@ -118,18 +122,20 @@ export class LspClient {
 	async initialize(root: string) {
 		const rootUri = directoryUri(root);
 		const workspaceFolders = [{ uri: rootUri, name: path.basename(root) || "workspace" }];
-		await this.request("initialize", {
+		const response = await this.request("initialize", {
 			processId: process.pid,
 			rootUri,
 			workspaceFolders,
 			initializationOptions: this.#adapter.initialization ?? {},
 			capabilities: {
 				textDocument: {
+					// This spawn-per-call client can't track dynamic registrations, so
+					// capabilities must be advertised statically.
 					codeAction: {
-						dynamicRegistration: true,
+						dynamicRegistration: false,
 						resolveSupport: { properties: ["edit"] },
 					},
-					diagnostic: { dynamicRegistration: true, relatedDocumentSupport: true },
+					diagnostic: { dynamicRegistration: false, relatedDocumentSupport: true },
 					publishDiagnostics: {},
 					synchronization: { didSave: true },
 				},
@@ -140,6 +146,9 @@ export class LspClient {
 				},
 			},
 		});
+		this.#serverCapabilities =
+			(response.result as { capabilities?: Record<string, unknown> } | undefined)?.capabilities ??
+			{};
 		this.notify("initialized", {});
 		if (this.#adapter.initialization) {
 			this.notify("workspace/didChangeConfiguration", { settings: this.#adapter.initialization });
@@ -161,18 +170,17 @@ export class LspClient {
 	}
 
 	async diagnostics(uri: string) {
-		try {
-			const response = await this.request("textDocument/diagnostic", {
-				textDocument: { uri },
-				identifier: null,
-				previousResultId: null,
-			});
-			const result = response.result as { items?: LspDiagnostic[] } | undefined;
-			return result?.items ?? [];
-		} catch (error) {
-			if (!isUnsupportedMethodError(error)) throw error;
+		// Only pull if the server advertised it; otherwise use push diagnostics.
+		if (!this.#serverCapabilities.diagnosticProvider) {
 			return this.#waitForPublishedDiagnostics(uri);
 		}
+		const response = await this.request("textDocument/diagnostic", {
+			textDocument: { uri },
+			identifier: null,
+			previousResultId: null,
+		});
+		const result = response.result as { items?: LspDiagnostic[] } | undefined;
+		return result?.items ?? [];
 	}
 
 	async codeActions(uri: string, text: string, diagnostics: LspDiagnostic[], kind: string) {
@@ -185,20 +193,23 @@ export class LspClient {
 	}
 
 	async resolveActions(actions: CodeAction[]) {
+		// Only resolve when the server advertised resolveProvider; otherwise use the
+		// action as-is. Any error from an advertised resolve is real and propagates.
+		const codeActionProvider = this.#serverCapabilities.codeActionProvider;
+		const canResolve =
+			typeof codeActionProvider === "object" &&
+			codeActionProvider !== null &&
+			(codeActionProvider as { resolveProvider?: boolean }).resolveProvider === true;
+
 		const resolvedActions: CodeAction[] = [];
 		for (const action of actions) {
-			if (action.edit) {
+			if (action.edit || !canResolve) {
 				resolvedActions.push(action);
 				continue;
 			}
 
-			try {
-				const response = await this.request("codeAction/resolve", action);
-				resolvedActions.push((response.result as CodeAction | undefined) ?? action);
-			} catch (error) {
-				if (!isUnsupportedMethodError(error)) throw error;
-				resolvedActions.push(action);
-			}
+			const response = await this.request("codeAction/resolve", action);
+			resolvedActions.push((response.result as CodeAction | undefined) ?? action);
 		}
 
 		return resolvedActions;
@@ -231,8 +242,7 @@ export class LspClient {
 		}
 		this.#pending.clear();
 		for (const waiters of this.#diagnosticWaiters.values()) {
-			for (const waiter of waiters) {
-				clearTimeout(waiter.timeout);
+			for (const waiter of [...waiters]) {
 				waiter.reject(new Error(typeof message === "string" ? message : message("diagnostics")));
 			}
 		}
@@ -331,11 +341,9 @@ export class LspClient {
 			if (params?.uri) {
 				const diagnostics = params.diagnostics ?? [];
 				this.#publishedDiagnostics.set(params.uri, diagnostics);
-				const waiters = this.#diagnosticWaiters.get(params.uri) ?? [];
-				this.#diagnosticWaiters.delete(params.uri);
-				for (const waiter of waiters) {
-					clearTimeout(waiter.timeout);
-					waiter.resolve(diagnostics);
+				const waiters = this.#diagnosticWaiters.get(params.uri);
+				if (waiters) {
+					for (const waiter of [...waiters]) waiter.onPublish();
 				}
 			}
 			return;
@@ -347,26 +355,53 @@ export class LspClient {
 	}
 
 	#waitForPublishedDiagnostics(uri: string) {
-		const diagnostics = this.#publishedDiagnostics.get(uri);
-		if (diagnostics) return Promise.resolve(diagnostics);
-
+		// See PUBLISHED_DIAGNOSTICS_SETTLE_MS. Bounded by #timeoutMs.
 		return new Promise<LspDiagnostic[]>((resolve, reject) => {
-			const waiter = {
-				resolve,
-				reject,
-				timeout: setTimeout(() => {
-					const waiters =
-						this.#diagnosticWaiters.get(uri)?.filter((entry) => entry !== waiter) ?? [];
-					if (waiters.length) this.#diagnosticWaiters.set(uri, waiters);
-					else this.#diagnosticWaiters.delete(uri);
-					reject(
+			let settleTimer: NodeJS.Timeout | undefined;
+			let overallTimer: NodeJS.Timeout | undefined;
+
+			const dispose = () => {
+				if (settleTimer) clearTimeout(settleTimer);
+				if (overallTimer) clearTimeout(overallTimer);
+				const set = this.#diagnosticWaiters.get(uri);
+				set?.delete(waiter);
+				if (set && set.size === 0) this.#diagnosticWaiters.delete(uri);
+			};
+			const settleWith = (diagnostics: LspDiagnostic[]) => {
+				dispose();
+				resolve(diagnostics);
+			};
+			const fail = (reason: unknown) => {
+				dispose();
+				reject(reason);
+			};
+			const onPublish = () => {
+				if (settleTimer) clearTimeout(settleTimer);
+				settleTimer = setTimeout(
+					() => settleWith(this.#publishedDiagnostics.get(uri) ?? []),
+					this.#adapter.diagnosticsSettleMs ?? PUBLISHED_DIAGNOSTICS_SETTLE_MS,
+				);
+			};
+
+			const waiter = { onPublish, reject: fail, dispose };
+			const set = this.#diagnosticWaiters.get(uri) ?? new Set<typeof waiter>();
+			set.add(waiter);
+			this.#diagnosticWaiters.set(uri, set);
+
+			overallTimer = setTimeout(() => {
+				const latest = this.#publishedDiagnostics.get(uri);
+				if (latest !== undefined) {
+					settleWith(latest);
+				} else {
+					fail(
 						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]);
+				}
+			}, this.#timeoutMs);
+
+			if (this.#publishedDiagnostics.has(uri)) onPublish();
 		});
 	}
 
@@ -417,13 +452,6 @@ export class LspClient {
 	}
 }
 
-function isUnsupportedMethodError(error: unknown) {
-	return (
-		error instanceof Error &&
-		/method not found|unhandled method|not supported|unsupported/i.test(error.message)
-	);
-}
-
 function formatErrorMessage(error: unknown) {
 	return error instanceof Error ? error.message : String(error);
 }

package/src/routes.ts

@@ -50,14 +50,6 @@ export function selectDiagnosticRoutes(
 				return false;
 			});
 
-	if (runnableCandidates.length === 0 && skipped.length > 0) {
-		const names = skipped.map((route) => route.adapter.name).join(", ");
-		throw new Error(
-			`No available default LSP commands: ${names}. ` +
-				"Install a matching server command or explicitly select a configured server.",
-		);
-	}
-
 	const filesByPolicy = new Map<string, string[]>();
 	const routes = runnableCandidates
 		.map((adapter) => {
@@ -71,16 +63,8 @@ export function selectDiagnosticRoutes(
 		})
 		.filter((route) => route.files.length > 0);
 
-	if (routes.length === 0) {
+	if (routes.length === 0 && skipped.length === 0) {
 		const scope = params.paths?.length ? ` in requested paths: ${params.paths.join(", ")}` : "";
-		if (skipped.length > 0) {
-			const names = skipped.map((route) => route.adapter.name).join(", ");
-			throw new Error(
-				`No supported files found for available LSP commands${scope}. ` +
-					`Skipped unavailable default LSP commands: ${names}. ` +
-					"Install a matching server command or explicitly select a configured server.",
-			);
-		}
 		throw new Error(`No supported files found${scope}. ${SUPPORTED_SERVER_DESCRIPTION}`);
 	}
 
@@ -125,7 +109,13 @@ function filterAdapters(adapters: LspServerAdapter[], selected: string | string[
 	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(", ")}.`);
+	if (missing.length) {
+		const configured = adapters.map((adapter) => adapter.name).join(", ") || "none";
+		throw new Error(
+			`Unknown LSP server(s): ${missing.join(", ")}. Configured LSP servers: ${configured}. ` +
+				"Omit the server parameter to select matching servers automatically.",
+		);
+	}
 	return matched;
 }
 

package/src/runner.ts

@@ -47,26 +47,32 @@ export async function runDiagnostics(
 		await client.start();
 		await client.initialize(root);
 
-		const entries: DiagnosticEntry[] = [];
-		for (const file of files) {
-			throwIfAborted(signal, adapter);
-			const uri = pathToFileURL(file).href;
-			const text = readFileSync(file, "utf8");
-			client.didOpen(uri, text, adapter.languageIdFor(file));
-			try {
-				const diagnostics = await client.diagnostics(uri);
-				entries.push({ path: path.relative(root, file) || file, uri, diagnostics });
-			} finally {
-				client.didClose(uri);
+		const openedFiles: Array<{ file: string; uri: string }> = [];
+		try {
+			for (const file of files) {
+				throwIfAborted(signal, adapter);
+				const uri = pathToFileURL(file).href;
+				const text = readFileSync(file, "utf8");
+				client.didOpen(uri, text, adapter.languageIdFor(file));
+				openedFiles.push({ file, uri });
 			}
-		}
 
-		return textResult(formatDiagnostics(adapter, entries), {
-			root,
-			command,
-			files: entries,
-			summary: summarize(entries),
-		});
+			const entries: DiagnosticEntry[] = await Promise.all(
+				openedFiles.map(async ({ file, uri }) => ({
+					path: path.relative(root, file) || file,
+					uri,
+					diagnostics: await client.diagnostics(uri),
+				})),
+			);
+			return textResult(formatDiagnostics(adapter, entries), {
+				root,
+				command,
+				files: entries,
+				summary: summarize(entries),
+			});
+		} finally {
+			for (const { uri } of openedFiles) client.didClose(uri);
+		}
 	} finally {
 		ctx.ui.setStatus(statusKey, undefined);
 		signal?.removeEventListener("abort", abort);

package/src/types.ts

@@ -67,6 +67,8 @@ export interface ConfiguredLspServer {
 	env?: Record<string, string>;
 	initialization?: Record<string, unknown>;
 	skipDirectories?: string[];
+	// Quiet period in ms after the latest push-diagnostics publication.
+	diagnosticsSettleMs?: number;
 }
 
 export interface LspConfig {
@@ -89,6 +91,7 @@ export interface LspServerAdapter {
 	env?: Record<string, string>;
 	initialization?: Record<string, unknown>;
 	skipDirectories: Set<string>;
+	diagnosticsSettleMs?: number;
 	isSupportedFile: (filePath: string) => boolean;
 	languageIdFor: (filePath: string) => string;
 }