@narumitw/pi-lsp 0.18.0 → 0.19.0

package/README.md

@@ -36,7 +36,47 @@ pi -e ./extensions/pi-lsp
 
 ## ⚙️ Configuration
 
-If no config is provided, pi-lsp ships compatible defaults for Biome, ty, and Ruff.
+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.
+
+| Language or format | Default server | Startup command | Extensions |
+| --- | --- | --- | --- |
+| JavaScript, TypeScript, JSON, CSS, GraphQL, HTML, Vue, Astro, Svelte | `biome` | `biome lsp-proxy` | `.js`, `.jsx`, `.ts`, `.tsx`, `.json`, `.jsonc`, `.css`, `.graphql`, `.gql`, `.html`, `.vue`, `.astro`, `.svelte`, and module variants |
+| Python typing | `ty` | `ty server` | `.py`, `.pyi` |
+| Python linting and fixes | `ruff` | `ruff server` | `.py`, `.pyi` |
+| Rust | `rust-analyzer` | `rust-analyzer` | `.rs` |
+| Go | `gopls` | `gopls` | `.go` |
+| Ruby | `rubocop` | `rubocop --lsp` | `.rb`, `.rake`, `.gemspec`, `.ru` |
+| Elixir | `elixir-ls` | `language_server.sh` (`language_server.bat` on Windows) | `.ex`, `.exs` |
+| Zig | `zls` | `zls` | `.zig`, `.zon` |
+| C# | `csharp` | `roslyn-language-server --stdio --autoLoadProjects` | `.cs`, `.csx` |
+| F# | `fsharp` | `fsautocomplete` | `.fs`, `.fsi`, `.fsx`, `.fsscript` |
+| Swift and Objective-C++ | `sourcekit-lsp` | `sourcekit-lsp` | `.swift`, `.mm` |
+| C and C++ | `clangd` | `clangd --background-index --clang-tidy` | C/C++ source and header extensions |
+| Java | `jdtls` | `jdtls` | `.java` |
+| Kotlin | `kotlin-lsp` | `kotlin-lsp --stdio` | `.kt`, `.kts` |
+| YAML | `yaml-language-server` | `yaml-language-server --stdio` | `.yaml`, `.yml` |
+| Lua | `lua-language-server` | `lua-language-server` | `.lua` |
+| PHP | `intelephense` | `intelephense --stdio` | `.php` |
+| Prisma | `prisma` | `prisma-language-server --stdio` | `.prisma` |
+| Dart | `dart` | `dart language-server` | `.dart` |
+| OCaml | `ocaml-lsp` | `ocamllsp` | `.ml`, `.mli` |
+| Bash | `bash-language-server` | `bash-language-server start` | `.sh`, `.bash` |
+| Terraform | `terraform-ls` | `terraform-ls serve` | `.tf`, `.tfvars` |
+| LaTeX and BibTeX | `texlab` | `texlab` | `.tex`, `.bib` |
+| Gleam | `gleam` | `gleam lsp` | `.gleam` |
+| Clojure | `clojure-lsp` | `clojure-lsp listen` | `.clj`, `.cljs`, `.cljc`, `.edn` |
+| Nix | `nixd` | `nixd` | `.nix` |
+| Typst | `tinymist` | `tinymist` | `.typ`, `.typc` |
+| Haskell | `haskell-language-server` | `haskell-language-server-wrapper --lsp` | `.hs`, `.lhs` |
+
+For example, install the Rust and Go servers with their official toolchains:
+
+```bash
+rustup component add rust-analyzer rust-src
+go install golang.org/x/tools/gopls@latest
+```
+
+Ensure the Go install directory (`$GOBIN` or `$(go env GOPATH)/bin`) is also on `PATH`.
 
 Custom config can be supplied in one of these locations:
 
@@ -48,7 +88,7 @@ Custom config can be supplied in one of these locations:
 
 Compatibility: a user-scoped legacy `lsp.json` is migrated automatically. A project-scoped legacy `.pi/lsp.json` remains readable with a warning but is not renamed automatically, so the extension never modifies a repository working tree. New paths take precedence when both names exist.
 
-`pi-lsp.json` can be a plain object keyed by server name:
+Providing custom config replaces the default server map. The following `pi-lsp.json` example intentionally keeps five selected servers:
 
 ```json
 {
@@ -76,6 +116,14 @@ Compatibility: a user-scoped legacy `lsp.json` is migrated automatically. A proj
       ".tsx",
       ".vue"
     ]
+  },
+  "rust-analyzer": {
+    "command": ["rust-analyzer"],
+    "extensions": [".rs"]
+  },
+  "gopls": {
+    "command": ["gopls"],
+    "extensions": [".go"]
   }
 }
 ```
@@ -94,7 +142,8 @@ Use `servers` when you need global pi-lsp options such as timeout:
       },
       "initialization": {
         "settings": {}
-      }
+      },
+      "skipDirectories": ["generated"]
     }
   }
 }
@@ -106,6 +155,7 @@ Each server entry supports:
 - `extensions`: file extensions that should route to this server.
 - `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.
 
 Global options:
 

package/package.json

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

package/src/adapters.ts

@@ -31,6 +31,8 @@ const COMMON_SKIP_DIRECTORIES = new Set([
 	"dist",
 	"node_modules",
 	"out",
+	"target",
+	"vendor",
 	"venv",
 ]);
 
@@ -70,6 +72,150 @@ export const DEFAULT_SERVER_CONFIGS: InternalLspServer[] = [
 		command: ["ruff", "server"],
 		extensions: [".py", ".pyi"],
 	},
+	{
+		name: "rust-analyzer",
+		command: ["rust-analyzer"],
+		extensions: [".rs"],
+	},
+	{
+		name: "gopls",
+		command: ["gopls"],
+		extensions: [".go"],
+	},
+	{
+		name: "rubocop",
+		command: ["rubocop", "--lsp"],
+		extensions: [".rb", ".rake", ".gemspec", ".ru"],
+	},
+	{
+		name: "elixir-ls",
+		command: [process.platform === "win32" ? "language_server.bat" : "language_server.sh"],
+		extensions: [".ex", ".exs"],
+		skipDirectories: ["_build", "deps"],
+	},
+	{
+		name: "zls",
+		command: ["zls"],
+		extensions: [".zig", ".zon"],
+		skipDirectories: [".zig-cache", "zig-out"],
+	},
+	{
+		name: "csharp",
+		command: ["roslyn-language-server", "--stdio", "--autoLoadProjects"],
+		extensions: [".cs", ".csx"],
+		skipDirectories: ["bin", "obj"],
+	},
+	{
+		name: "fsharp",
+		command: ["fsautocomplete"],
+		extensions: [".fs", ".fsi", ".fsx", ".fsscript"],
+		skipDirectories: ["bin", "obj"],
+		initialization: { AutomaticWorkspaceInit: true },
+	},
+	{
+		name: "sourcekit-lsp",
+		command: ["sourcekit-lsp"],
+		extensions: [".swift", ".mm"],
+		skipDirectories: [".build", "DerivedData"],
+	},
+	{
+		name: "clangd",
+		command: ["clangd", "--background-index", "--clang-tidy"],
+		extensions: [".c", ".cpp", ".cc", ".cxx", ".c++", ".h", ".hpp", ".hh", ".hxx", ".h++"],
+		skipDirectories: ["build"],
+	},
+	{
+		name: "jdtls",
+		command: ["jdtls"],
+		extensions: [".java"],
+		skipDirectories: [".gradle", "build"],
+	},
+	{
+		name: "kotlin-lsp",
+		command: ["kotlin-lsp", "--stdio"],
+		extensions: [".kt", ".kts"],
+		skipDirectories: [".gradle", "build"],
+	},
+	{
+		name: "yaml-language-server",
+		command: ["yaml-language-server", "--stdio"],
+		extensions: [".yaml", ".yml"],
+	},
+	{
+		name: "lua-language-server",
+		command: ["lua-language-server"],
+		extensions: [".lua"],
+	},
+	{
+		name: "intelephense",
+		command: ["intelephense", "--stdio"],
+		extensions: [".php"],
+		initialization: { intelephense: { telemetry: { enabled: false } } },
+	},
+	{
+		name: "prisma",
+		command: ["prisma-language-server", "--stdio"],
+		extensions: [".prisma"],
+	},
+	{
+		name: "dart",
+		command: ["dart", "language-server"],
+		extensions: [".dart"],
+		skipDirectories: [".dart_tool", "build"],
+	},
+	{
+		name: "ocaml-lsp",
+		command: ["ocamllsp"],
+		extensions: [".ml", ".mli"],
+		skipDirectories: ["_build", "_opam"],
+	},
+	{
+		name: "bash-language-server",
+		command: ["bash-language-server", "start"],
+		extensions: [".sh", ".bash"],
+	},
+	{
+		name: "terraform-ls",
+		command: ["terraform-ls", "serve"],
+		extensions: [".tf", ".tfvars"],
+		skipDirectories: [".terraform"],
+		initialization: {
+			experimentalFeatures: { prefillRequiredFields: true },
+		},
+	},
+	{
+		name: "texlab",
+		command: ["texlab"],
+		extensions: [".tex", ".bib"],
+	},
+	{
+		name: "gleam",
+		command: ["gleam", "lsp"],
+		extensions: [".gleam"],
+		skipDirectories: ["build"],
+	},
+	{
+		name: "clojure-lsp",
+		command: ["clojure-lsp", "listen"],
+		extensions: [".clj", ".cljs", ".cljc", ".edn"],
+		skipDirectories: [".cpcache"],
+	},
+	{
+		name: "nixd",
+		command: ["nixd"],
+		extensions: [".nix"],
+	},
+	{
+		name: "tinymist",
+		command: ["tinymist"],
+		extensions: [".typ", ".typc"],
+	},
+	{
+		name: "haskell-language-server",
+		command: ["haskell-language-server-wrapper", "--lsp"],
+		extensions: [".hs", ".lhs"],
+		skipDirectories: [".stack-work", "dist-newstyle"],
+	},
 ];
 
 export function loadRuntime(cwd = process.cwd()) {
@@ -82,7 +228,11 @@ export function loadRuntime(cwd = process.cwd()) {
 
 export function loadConfig(cwd = process.cwd()): LspConfig {
 	const configured = loadConfiguredConfig(cwd);
-	return configured ?? { servers: DEFAULT_SERVER_CONFIGS };
+	return (
+		configured ?? {
+			servers: DEFAULT_SERVER_CONFIGS.map((server) => ({ ...server, isDefault: true })),
+		}
+	);
 }
 
 let pendingConfigNotice: string | undefined;
@@ -268,6 +418,7 @@ function normalizeServer(name: string, value: unknown, label: string): InternalL
 		extensions,
 		env: optionalStringRecordField(value, "env", label),
 		initialization: optionalRecordField(value, "initialization", label),
+		skipDirectories: optionalDirectoryNamesField(value, "skipDirectories", label),
 	};
 }
 
@@ -285,13 +436,14 @@ function configToAdapter(config: InternalLspServer): LspServerAdapter {
 	if (!command) throw new Error(`${config.name}.command must contain at least one string.`);
 	return {
 		name: config.name,
+		isDefault: config.isDefault ?? false,
 		defaultCommand: { command, args },
 		commandEnvVar: envName(config.name, "COMMAND"),
 		missingCommandHint: `Install ${config.name} or set ${envName(config.name, "COMMAND")}.`,
 		extensions: config.extensions,
 		env: config.env,
 		initialization: config.initialization,
-		skipDirectories: COMMON_SKIP_DIRECTORIES,
+		skipDirectories: new Set([...COMMON_SKIP_DIRECTORIES, ...(config.skipDirectories ?? [])]),
 		isSupportedFile: (filePath) => extensionSet.has(path.extname(filePath)),
 		languageIdFor: (filePath) => languageIdFor(config, filePath),
 	};
@@ -303,18 +455,73 @@ function languageIdFor(_config: InternalLspServer, filePath: string) {
 }
 
 const LANGUAGE_IDS: Record<string, string> = {
+	".bash": "shellscript",
+	".bib": "bibtex",
+	".c": "c",
+	".c++": "cpp",
+	".cc": "cpp",
 	".cjs": "javascript",
+	".clj": "clojure",
+	".cljc": "clojure",
+	".cljs": "clojure",
+	".cpp": "cpp",
+	".cs": "csharp",
+	".csx": "csharp",
 	".cts": "typescript",
+	".cxx": "cpp",
+	".dart": "dart",
+	".edn": "clojure",
+	".ex": "elixir",
+	".exs": "elixir",
+	".fs": "fsharp",
+	".fsi": "fsharp",
+	".fsscript": "fsharp",
+	".fsx": "fsharp",
+	".gemspec": "ruby",
+	".go": "go",
 	".gql": "graphql",
+	".h": "c",
+	".h++": "cpp",
+	".hh": "cpp",
+	".hpp": "cpp",
+	".hs": "haskell",
+	".hxx": "cpp",
+	".jl": "julia",
 	".js": "javascript",
 	".jsx": "javascriptreact",
 	".jsonc": "jsonc",
+	".ksh": "shellscript",
+	".kt": "kotlin",
+	".kts": "kotlin",
+	".lhs": "lhaskell",
+	".m": "objective-c",
 	".mjs": "javascript",
+	".ml": "ocaml",
+	".mli": "ocaml.interface",
+	".mm": "objective-cpp",
 	".mts": "typescript",
+	".nix": "nix",
+	".php": "php",
 	".py": "python",
 	".pyi": "python",
+	".rake": "ruby",
+	".rb": "ruby",
+	".rs": "rust",
+	".ru": "ruby",
+	".sh": "shellscript",
+	".swift": "swift",
+	".tex": "latex",
+	".tf": "terraform",
+	".tfvars": "terraform-vars",
 	".ts": "typescript",
 	".tsx": "typescriptreact",
+	".typ": "typst",
+	".typc": "typst-code",
+	".yaml": "yaml",
+	".yml": "yaml",
+	".zig": "zig",
+	".zon": "zig",
+	".zsh": "shellscript",
 };
 
 function commandFromEnvName(name: string): string {
@@ -361,6 +568,25 @@ function optionalRecordField(value: Record<string, unknown>, field: string, labe
 	return fieldValue;
 }
 
+function optionalDirectoryNamesField(value: Record<string, unknown>, field: string, label: string) {
+	const fieldValue = value[field];
+	if (fieldValue === undefined) return undefined;
+	if (!Array.isArray(fieldValue) || !fieldValue.every((item) => typeof item === "string")) {
+		throw new Error(`${label}.${field} must be an array of directory names.`);
+	}
+	const names = fieldValue.map((item) => item.trim());
+	if (
+		names.some(
+			(name) => !name || name === "." || name === ".." || name.includes("/") || name.includes("\\"),
+		)
+	) {
+		throw new Error(
+			`${label}.${field} must contain non-empty directory names without path separators.`,
+		);
+	}
+	return [...new Set(names)];
+}
+
 function expandHome(filePath: string) {
 	if (filePath === "~") return os.homedir();
 	if (filePath.startsWith("~/") || filePath.startsWith("~\\")) {

package/src/command.ts

@@ -13,28 +13,89 @@ export function commandFromEnv(envVar: string, fallback: ServerCommand): ServerC
 	return fallback;
 }
 
-export function commandExists(command: string, cwd = process.cwd()) {
+export function commandExists(
+	command: string,
+	cwd = process.cwd(),
+	pathValue = process.env.PATH ?? "",
+) {
+	return resolveCommandPath(command, cwd, process.platform, pathValue) !== undefined;
+}
+
+export function commandPathValue(
+	env: Record<string, string> | undefined,
+	platform: NodeJS.Platform = process.platform,
+) {
+	return (
+		environmentValue(env, "PATH", platform) ?? environmentValue(process.env, "PATH", platform) ?? ""
+	);
+}
+
+export function mergeEnvironment(
+	overrides: Record<string, string> | undefined,
+	platform: NodeJS.Platform = process.platform,
+) {
+	const environment: NodeJS.ProcessEnv = { ...process.env };
+	for (const [key, value] of Object.entries(overrides ?? {})) {
+		if (platform === "win32") {
+			for (const existingKey of Object.keys(environment)) {
+				if (existingKey.toLowerCase() === key.toLowerCase()) delete environment[existingKey];
+			}
+		}
+		environment[key] = value;
+	}
+	return environment;
+}
+
+function environmentValue(
+	environment: NodeJS.ProcessEnv | Record<string, string> | undefined,
+	name: string,
+	platform: NodeJS.Platform,
+) {
+	if (platform !== "win32") return environment?.[name];
+	let value: string | undefined;
+	for (const [key, candidate] of Object.entries(environment ?? {})) {
+		if (key.toLowerCase() === name.toLowerCase()) value = candidate;
+	}
+	return value;
+}
+
+export function resolveCommandPath(
+	command: string,
+	cwd = process.cwd(),
+	platform: NodeJS.Platform = process.platform,
+	pathValue = process.env.PATH ?? "",
+) {
+	const extensions = platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
 	if (command.includes("/") || command.includes("\\")) {
-		return isRunnableFile(path.isAbsolute(command) ? command : path.resolve(cwd, command));
+		const commandPath = path.isAbsolute(command) ? command : path.resolve(cwd, command);
+		return resolveRunnableFile(commandPath, extensions, platform);
 	}
 
-	const pathValue = process.env.PATH ?? "";
-	const extensions = process.platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
-	for (const directory of pathValue.split(process.platform === "win32" ? ";" : ":")) {
-		if (!directory) continue;
-		for (const extension of extensions) {
-			if (isRunnableFile(path.join(directory, `${command}${extension}`))) return true;
-		}
+	for (const directory of pathValue.split(platform === "win32" ? ";" : ":")) {
+		const resolved = resolveRunnableFile(
+			path.resolve(cwd, directory || ".", command),
+			extensions,
+			platform,
+		);
+		if (resolved) return resolved;
 	}
 
-	return false;
+	return undefined;
+}
+
+function resolveRunnableFile(filePath: string, extensions: string[], platform: NodeJS.Platform) {
+	for (const extension of extensions) {
+		const candidate = `${filePath}${extension}`;
+		if (isRunnableFile(candidate, platform)) return candidate;
+	}
+	return undefined;
 }
 
-function isRunnableFile(filePath: string) {
+function isRunnableFile(filePath: string, platform: NodeJS.Platform) {
 	if (!existsSync(filePath)) return false;
 	try {
 		if (!statSync(filePath).isFile()) return false;
-		if (process.platform !== "win32") accessSync(filePath, constants.X_OK);
+		if (platform !== "win32") accessSync(filePath, constants.X_OK);
 		return true;
 	} catch {
 		return false;

package/src/lsp-client.ts

@@ -1,7 +1,7 @@
 import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
 import path from "node:path";
 import process from "node:process";
-import { commandExists } from "./command.js";
+import { commandPathValue, mergeEnvironment, resolveCommandPath } from "./command.js";
 import { directoryUri } from "./files.js";
 import { positionAt } from "./text-edits.js";
 import type {
@@ -12,6 +12,18 @@ import type {
 	ServerCommand,
 } from "./types.js";
 
+export function resolveSpawnCommand(
+	command: ServerCommand,
+	platform: NodeJS.Platform = process.platform,
+	comSpec = process.env.ComSpec,
+): ServerCommand {
+	if (platform !== "win32" || !/\.(?:bat|cmd)$/i.test(command.command)) return command;
+	return {
+		command: comSpec?.trim() || "cmd.exe",
+		args: ["/d", "/s", "/c", command.command, ...command.args],
+	};
+}
+
 export class LspClient {
 	#child?: ChildProcessWithoutNullStreams;
 	#buffer = Buffer.alloc(0);
@@ -47,15 +59,22 @@ export class LspClient {
 	}
 
 	async start() {
-		if (!commandExists(this.#command.command, this.#cwd)) {
+		const commandPath = resolveCommandPath(
+			this.#command.command,
+			this.#cwd,
+			process.platform,
+			commandPathValue(this.#adapter.env),
+		);
+		if (!commandPath) {
 			throw new Error(
 				`${this.#adapter.name} LSP command not found: ${this.#command.command}. ${this.#adapter.missingCommandHint}`,
 			);
 		}
 
-		const child = spawn(this.#command.command, this.#command.args, {
+		const spawnCommand = resolveSpawnCommand({ ...this.#command, command: commandPath });
+		const child = spawn(spawnCommand.command, spawnCommand.args, {
 			cwd: this.#cwd,
-			env: { ...process.env, ...this.#adapter.env },
+			env: mergeEnvironment(this.#adapter.env),
 			stdio: "pipe",
 		});
 		this.#child = child;
@@ -233,7 +252,9 @@ export class LspClient {
 			const timeout = setTimeout(() => {
 				this.#pending.delete(id);
 				reject(
-					new Error(`${this.#adapter.name} 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 });
@@ -334,7 +355,8 @@ export class LspClient {
 				resolve,
 				reject,
 				timeout: setTimeout(() => {
-					const waiters = this.#diagnosticWaiters.get(uri)?.filter((entry) => entry !== waiter) ?? [];
+					const waiters =
+						this.#diagnosticWaiters.get(uri)?.filter((entry) => entry !== waiter) ?? [];
 					if (waiters.length) this.#diagnosticWaiters.set(uri, waiters);
 					else this.#diagnosticWaiters.delete(uri);
 					reject(
@@ -396,7 +418,10 @@ export class LspClient {
 }
 
 function isUnsupportedMethodError(error: unknown) {
-	return error instanceof Error && /method not found|unhandled method|not supported|unsupported/i.test(error.message);
+	return (
+		error instanceof Error &&
+		/method not found|unhandled method|not supported|unsupported/i.test(error.message)
+	);
 }
 
 function formatErrorMessage(error: unknown) {

package/src/pi-lsp.ts

@@ -1,7 +1,7 @@
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { consumeLspConfigNotice, loadRuntime } from "./adapters.js";
-import { commandExists, commandFromEnv } from "./command.js";
+import { commandExists, commandFromEnv, commandPathValue } from "./command.js";
 import { resolveRoot } from "./files.js";
 import { selectDiagnosticRoutes, selectFixRoute } from "./routes.js";
 import { DEFAULT_FILE_LIMIT, runDiagnostics, runFix, textResult } from "./runner.js";
@@ -60,7 +60,7 @@ const lspDiagnosticsTool = defineTool({
 	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 		const requestedRoot = resolveRoot(params.root);
 		const { adapters, timeoutMs } = loadRuntime(requestedRoot);
-		const { root, routes } = selectDiagnosticRoutes(
+		const { root, routes, skipped } = selectDiagnosticRoutes(
 			adapters,
 			{ ...params, root: requestedRoot },
 			DEFAULT_FILE_LIMIT,
@@ -78,11 +78,23 @@ const lspDiagnosticsTool = defineTool({
 			results.push({ route, result });
 		}
 
-		const text = results
-			.map(({ route, result }) => `${route.reason}\n\n${textFromResult(result)}`)
-			.join("\n\n---\n\n");
-		return textResult(text, {
+		const sections = results.map(
+			({ route, result }) => `${route.reason}\n\n${textFromResult(result)}`,
+		);
+		if (skipped.length) {
+			sections.push(
+				`Skipped unavailable default LSP server(s): ${skipped
+					.map((route) => route.adapter.name)
+					.join(", ")}.`,
+			);
+		}
+		return textResult(sections.join("\n\n---\n\n"), {
 			root,
+			skipped: skipped.map((route) => ({
+				server: route.adapter.name,
+				reason: route.reason,
+				files: route.files,
+			})),
 			routes: results.map(({ route, result }) => ({
 				server: route.adapter.name,
 				backend: route.adapter.name,
@@ -174,7 +186,11 @@ function buildStatusMessage(adapters: ReturnType<typeof loadRuntime>["adapters"]
 			const command = commandFromEnv(adapter.commandEnvVar, adapter.defaultCommand);
 			return [
 				`${adapter.name} LSP command: ${command.command} ${command.args.join(" ")}`.trim(),
-				`${adapter.name} status: ${commandExists(command.command, cwd) ? "ready" : "command missing"}`,
+				`${adapter.name} status: ${
+					commandExists(command.command, cwd, commandPathValue(adapter.env))
+						? "ready"
+						: "command missing"
+				}`,
 			];
 		})
 		.join("\n");
@@ -183,7 +199,7 @@ function buildStatusMessage(adapters: ReturnType<typeof loadRuntime>["adapters"]
 function statusLevel(adapters: ReturnType<typeof loadRuntime>["adapters"], cwd: string) {
 	return adapters.every((adapter) => {
 		const command = commandFromEnv(adapter.commandEnvVar, adapter.defaultCommand);
-		return commandExists(command.command, cwd);
+		return commandExists(command.command, cwd, commandPathValue(adapter.env));
 	})
 		? "info"
 		: "warning";

package/src/routes.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { commandExists, commandFromEnv, commandPathValue } from "./command.js";
 import { collectSupportedFiles, resolveRoot } from "./files.js";
 import type { LspServerAdapter } from "./types.js";
 
@@ -38,14 +39,33 @@ export function selectDiagnosticRoutes(
 ) {
 	const root = resolveRoot(params.root);
 	const candidates = filterAdapters(adapters, params.server);
-	const filesByExtensions = new Map<string, string[]>();
-	const routes = candidates
+	const skipped: DiagnosticRoute[] = [];
+	const runnableCandidates = params.server
+		? candidates
+		: candidates.filter((adapter) => {
+				if (!adapter.isDefault) return true;
+				const command = commandFromEnv(adapter.commandEnvVar, adapter.defaultCommand);
+				if (commandExists(command.command, root, commandPathValue(adapter.env))) return true;
+				skipped.push({ adapter, reason: `${adapter.name} command missing`, files: [] });
+				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) => {
-			const key = adapter.extensions.join("\0");
-			let files = filesByExtensions.get(key);
+			const key = diagnosticFilePolicyKey(adapter);
+			let files = filesByPolicy.get(key);
 			if (!files) {
 				files = collectSupportedFiles(adapter, root, params.paths, params.limit ?? defaultLimit);
-				filesByExtensions.set(key, files);
+				filesByPolicy.set(key, files);
 			}
 			return { adapter, reason: `${adapter.name} diagnostics`, files };
 		})
@@ -53,16 +73,26 @@ export function selectDiagnosticRoutes(
 
 	if (routes.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}`);
 	}
 
-	return { root, routes };
+	return { root, routes, skipped };
 }
 
 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));
+	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(
@@ -80,11 +110,18 @@ export function selectFixRoute(adapters: LspServerAdapter[], params: SingleFileR
 	};
 }
 
+function diagnosticFilePolicyKey(adapter: LspServerAdapter) {
+	return JSON.stringify([
+		adapter.extensions,
+		[...adapter.skipDirectories].sort((left, right) => left.localeCompare(right)),
+	]);
+}
+
 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,
-	);
+	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));
@@ -94,5 +131,7 @@ function filterAdapters(adapters: LspServerAdapter[], selected: string | string[
 
 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}`);
+	return new Error(
+		`No ${action} route supports ${filePath}${override}. ${SUPPORTED_SERVER_DESCRIPTION}`,
+	);
 }

package/src/types.ts

@@ -66,6 +66,7 @@ export interface ConfiguredLspServer {
 	extensions: string[];
 	env?: Record<string, string>;
 	initialization?: Record<string, unknown>;
+	skipDirectories?: string[];
 }
 
 export interface LspConfig {
@@ -75,10 +76,12 @@ export interface LspConfig {
 
 export interface InternalLspServer extends ConfiguredLspServer {
 	name: string;
+	isDefault?: boolean;
 }
 
 export interface LspServerAdapter {
 	name: string;
+	isDefault: boolean;
 	defaultCommand: ServerCommand;
 	commandEnvVar: string;
 	missingCommandHint: string;