@mrclrchtr/supi-lsp 6.1.0 → 6.2.0

package/README.md

@@ -82,6 +82,24 @@ Configuration overrides merge with the built-in server definitions. Use `.pi/sup
 
 Gopls pull diagnostics stay opt-in while golang/go#70199 is open; without the option the built-in Go configuration stays in push mode. Kotlin's `--stdio` argument is already part of the built-in configuration and needs no override.
 
+### Automatic workspace path policy
+
+Automatic LSP work uses one path policy that does not change for each workspace runtime. It covers project discovery, route startup, warm-up, sentinel and source-file lists, created-file tracking, runtime guidance, and diagnostic summaries not tied to one request.
+
+The policy excludes these directories by default: `.git`, `.cache`, `.pi`, `.pnpm`, `node_modules`, `dist`, `build`, `out`, `coverage`, `.next`, `.nuxt`, `.turbo`, and `__pycache__`. It also applies `lsp.exclude` patterns and root or nested `.gitignore` rules. Patterns use gitignore syntax, including rules relative to each directory and `!` rules. Built-in exclusions cannot be enabled again. Symbolic-link directories are not visited. Other dot-directories, such as `.github` and `.storybook`, remain allowed.
+
+Set `lsp.exclude` in project or global SuPi configuration:
+
+```json
+{
+  "lsp": {
+    "exclude": ["generated/**", "!generated/keep.ts"]
+  }
+}
+```
+
+An exact semantic request can still route an excluded file when a compatible server is available. This does not add the file to automatic work. Configured diagnostic suppression still applies to diagnostic output.
+
 ### Custom server configuration
 
 A custom server needs a command and at least one file type:
@@ -104,7 +122,7 @@ A custom server needs a command and at least one file type:
 
 File types do not include a leading dot. If `rootMarkers` is omitted, the server uses the session root.
 
-The `lsp.enabled` and `lsp.active` settings are deprecated and ignored. Disable one language with `lsp.servers.<language>.enabled: false`. Use `/supi-ci-status` from `@mrclrchtr/supi-code-intelligence` to see detected, running, and missing servers.
+Disable one language with `lsp.servers.<language>.enabled: false`. Use `/supi-ci-status` from `@mrclrchtr/supi-code-intelligence` to see detected, running, and missing servers.
 
 ## What it provides
 
@@ -191,7 +209,7 @@ Detected servers start concurrently. In a polyglot workspace, disable unneeded l
 }
 ```
 
-The old `lsp.enabled` and `lsp.active` settings are deprecated and ignored. If every server definition is disabled, the controller publishes an explicit `disabled` runtime state instead of an empty `ready` runtime. When a ready owner has no active client yet, it stays published for lazy routing while semantic capability remains pending.
+If every server definition is disabled, the controller publishes an explicit `disabled` runtime state instead of an empty `ready` runtime. When a ready owner has no active client yet, it stays published for lazy routing while semantic capability remains pending.
 
 ## Architecture
 
@@ -212,7 +230,7 @@ See [`docs/adr/0016-workspace-lsp-runtime-interface.md`](../../docs/adr/0016-wor
 
 ## Package exports
 
-- `@mrclrchtr/supi-lsp/api` — runtime/controller/config types and registry operations
+- `@mrclrchtr/supi-lsp/api` — runtime/controller/config types, registry operations, and automatic path-policy helpers
 - `@mrclrchtr/supi-lsp/provider/lsp-semantic-provider` — semantic provider adapter
 
 ## Source

package/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Shared workspace context and capability contracts for code intelligence",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/debug-identity.ts

@@ -0,0 +1,11 @@
+/** Maximum UTF-16 code-unit length of one debug identity string. */
+export const MAX_DEBUG_IDENTITY_STRING = 512;
+
+/** Marker appended to a truncated debug identity string. */
+export const DEBUG_IDENTITY_TRUNCATION_MARKER = "…";
+
+/** Bound one debug identity string, including its truncation marker. */
+export function truncateDebugIdentity(value: string): string {
+  if (value.length <= MAX_DEBUG_IDENTITY_STRING) return value;
+  return `${value.slice(0, MAX_DEBUG_IDENTITY_STRING - 1)}${DEBUG_IDENTITY_TRUNCATION_MARKER}`;
+}

package/node_modules/@mrclrchtr/supi-core/src/debug.ts

@@ -3,6 +3,11 @@
 // Kept separate from debug-registry.ts so debug-timing.ts can import the
 // registry without creating an import cycle through the barrel re-export.
 
+export {
+  DEBUG_IDENTITY_TRUNCATION_MARKER,
+  MAX_DEBUG_IDENTITY_STRING,
+  truncateDebugIdentity,
+} from "./debug-identity.ts";
 // biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
 export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "Language Server Protocol runtime for SuPi code intelligence",
   "license": "MIT",
   "repository": {
@@ -37,8 +37,8 @@
     "vscode-jsonrpc": "^9.0.0",
     "vscode-languageserver-protocol": "^3.18.0",
     "vscode-languageserver-types": "^3.18.0",
-    "@mrclrchtr/supi-code-runtime": "6.1.0",
-    "@mrclrchtr/supi-core": "6.1.0"
+    "@mrclrchtr/supi-code-runtime": "6.2.0",
+    "@mrclrchtr/supi-core": "6.2.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",
@@ -53,7 +53,6 @@
   "exports": {
     "./api": "./src/api.ts",
     "./package.json": "./package.json",
-    "./provider/lsp-semantic-provider": "./src/provider/lsp-semantic-provider.ts",
-    "./debug-telemetry": "./src/debug-telemetry.ts"
+    "./provider/lsp-semantic-provider": "./src/provider/lsp-semantic-provider.ts"
   }
 }

package/src/api.ts

@@ -1,13 +1,8 @@
 // Public API surface for the LSP session-scoped service.
 
 export { type LoadConfigOptions, loadConfig } from "./config/config.ts";
-export type { DeprecatedLspKeys, LspSettings } from "./config/lsp-settings.ts";
-export {
-  getDeprecatedLspKeys,
-  getLspDisabledMessage,
-  hasDeprecatedLspKeys,
-  loadLspSettings,
-} from "./config/lsp-settings.ts";
+export type { LspSettings } from "./config/lsp-settings.ts";
+export { loadLspSettings } from "./config/lsp-settings.ts";
 export {
   clearTsconfigCache,
   type FileScopeDecision,
@@ -43,6 +38,8 @@ export { isLikelyStaleDiagnostic } from "./diagnostics/stale-diagnostics.ts";
 export {
   scanWorkspaceSentinels,
   syncWorkspaceSentinelSnapshot,
+  type WorkspaceSentinelScanOptions,
+  type WorkspaceSentinelSyncResult,
 } from "./diagnostics/workspace-sentinels.ts";
 export { raceReadinessValue, raceRequestControl } from "./session/readiness.ts";
 export type {
@@ -59,6 +56,7 @@ export type {
   DiagnosticEvidenceSummary,
   OutstandingDiagnosticSummaryEntry,
   ProcessCrashDiagnosticDemand,
+  ProcessCrashRecoverySummary,
   RecoverDiagnosticsResult,
   RoutedMutationResponse,
   SemanticReadinessResult,
@@ -71,8 +69,15 @@ export type {
 } from "./session/runtime-registry.ts";
 export {
   clearWorkspaceLspRuntime,
+  emptyProcessCrashRecoverySummary,
   getWorkspaceLspRuntime,
   setWorkspaceLspRuntimeState,
   waitForWorkspaceLspRuntime,
 } from "./session/runtime-registry.ts";
 export { scanMissingServers } from "./session/scanner.ts";
+export {
+  AUTOMATIC_LSP_EXCLUDED_DIRECTORIES,
+  type AutomaticLspPathPolicy,
+  createAutomaticLspPathPolicy,
+  createDefaultAutomaticLspPathPolicy,
+} from "./workspace-path-policy.ts";

package/src/client/client-diagnostic-cache.ts

@@ -1,5 +1,5 @@
+import { uriToFile } from "@mrclrchtr/supi-core/path";
 import type { PublishDiagnosticsParams } from "../config/types.ts";
-import { uriToFile } from "../utils.ts";
 import {
   type DiagnosticCacheEntry,
   isTentativePushEntry,

package/src/client/client-diagnostic-capabilities.ts

@@ -66,11 +66,6 @@ export class ClientDynamicRegistrations {
     return (this.idsByMethod.get(method)?.size ?? 0) > 0;
   }
 
-  /** Snapshot of the active registration ids for a method. */
-  ids(method: string): readonly string[] {
-    return [...(this.idsByMethod.get(method) ?? [])];
-  }
-
   /** Drop all registrations — capability loss on shutdown, crash, or disposal. */
   clear(): void {
     this.idsByMethod.clear();

package/src/client/client-diagnostic-publication.ts

@@ -9,9 +9,12 @@
 // and timing data. They never carry diagnostic payloads or source text.
 
 import * as path from "node:path";
-import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
-import { boundCwd, truncateIdentity } from "../debug-telemetry.ts";
-import { uriToFile } from "../utils.ts";
+import {
+  recordDebugEvent,
+  truncateDebugIdentity as truncateIdentity,
+} from "@mrclrchtr/supi-core/debug";
+import { uriToFile } from "@mrclrchtr/supi-core/path";
+import { boundCwd } from "../debug-telemetry.ts";
 
 /** Maximum tracked synchronizations before the oldest entry is evicted. */
 export const MAX_TRACKED_SYNCHRONIZATIONS = 64;

package/src/client/client-diagnostic-refresh.ts

@@ -5,12 +5,13 @@ import {
   isCodeRequestInterruption,
   throwIfCodeRequestInterrupted,
 } from "@mrclrchtr/supi-code-runtime/api";
+import { fileToUri, uriToFile } from "@mrclrchtr/supi-core/path";
 import type { TextDocumentIdentifier } from "../config/types.ts";
 import {
   type DiagnosticEvidenceSummary,
   summarizeDiagnosticEvidence,
 } from "../diagnostics/evidence.ts";
-import { detectLanguageId, fileToUri, uriToFile } from "../utils.ts";
+import { detectLanguageId } from "../utils.ts";
 import {
   type DiagnosticCacheEntry,
   type DiagnosticSynchronization,

package/src/client/client-diagnostic-timing.ts

@@ -1,6 +1,9 @@
 import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
-import { startDebugTimer } from "@mrclrchtr/supi-core/debug";
-import { boundCwd, truncateIdentity } from "../debug-telemetry.ts";
+import {
+  startDebugTimer,
+  truncateDebugIdentity as truncateIdentity,
+} from "@mrclrchtr/supi-core/debug";
+import { boundCwd } from "../debug-telemetry.ts";
 
 type DiagnosticCollection = "cache" | "fallback" | "none" | "pull" | "push";
 type DiagnosticFreshness = "not-observed" | "observed";

package/src/client/client-diagnostics.ts

@@ -7,9 +7,10 @@ import {
   throwIfCodeRequestInterrupted,
   unavailableCodeQuery,
 } from "@mrclrchtr/supi-code-runtime/api";
+import { fileToUri, uriToFile } from "@mrclrchtr/supi-core/path";
 import type { Diagnostic, TextDocumentItem } from "../config/types.ts";
 import type { DiagnosticEvidenceSummary } from "../diagnostics/evidence.ts";
-import { detectLanguageId, fileToUri, uriToFile } from "../utils.ts";
+import { detectLanguageId } from "../utils.ts";
 import { applyPushDiagnostics, buildClientDiagnosticSnapshot } from "./client-diagnostic-cache.ts";
 import { collectSynchronizedFileDiagnostics } from "./client-diagnostic-collection.ts";
 import {

package/src/client/client.ts

@@ -12,7 +12,11 @@ import {
   throwIfCodeRequestInterrupted,
   unavailableCodeQuery,
 } from "@mrclrchtr/supi-code-runtime/api";
-import { recordDebugEvent } from "@mrclrchtr/supi-core/debug";
+import {
+  recordDebugEvent,
+  truncateDebugIdentity as truncateIdentity,
+} from "@mrclrchtr/supi-core/debug";
+import { fileToUri } from "@mrclrchtr/supi-core/path";
 import { type ProgressToken, TextDocumentSyncKind } from "vscode-languageserver-protocol";
 import { CLIENT_CAPABILITIES } from "../config/capabilities.ts";
 import type {
@@ -35,10 +39,9 @@ import type {
   WorkspaceEdit,
   WorkspaceSymbol,
 } from "../config/types.ts";
-import { boundCwd, truncateIdentity } from "../debug-telemetry.ts";
+import { boundCwd } from "../debug-telemetry.ts";
 import type { DiagnosticEvidenceSummary } from "../diagnostics/evidence.ts";
 import { raceRequestControl } from "../session/readiness.ts";
-import { fileToUri } from "../utils.ts";
 import {
   ClientDynamicRegistrations,
   DOCUMENT_DIAGNOSTIC_METHOD,
@@ -141,6 +144,15 @@ function killProcessTree(pid: number): void {
   }
 }
 
+/** Terminate a failed startup without leaving server descendants running. */
+function killFailedStartupProcess(child: ChildProcess): void {
+  if (child.pid) {
+    killProcessTree(child.pid);
+    return;
+  }
+  child.kill();
+}
+
 // ── Types ─────────────────────────────────────────────────────────────
 export type ClientStatus = "initializing" | "running" | "error" | "shutdown";
 
@@ -285,7 +297,7 @@ export class LspClient {
     if (!this.process.stdin || !this.process.stdout) {
       const failure = new Error(`${cmd}: missing stdin/stdout`);
       this.handleProcessFailure(failure);
-      this.process.kill();
+      killFailedStartupProcess(this.process);
       throw failure;
     }
 
@@ -350,7 +362,7 @@ export class LspClient {
     } catch (err) {
       const failure = new Error(`${this.name}: initialize failed: ${err}`, { cause: err });
       this.handleProcessFailure(failure);
-      this.process.kill();
+      killFailedStartupProcess(this.process);
       throw failure;
     }
   }

package/src/client/transport.ts

@@ -7,7 +7,10 @@ import {
   type CodeRequestControl,
   CodeRequestDeadlineError,
 } from "@mrclrchtr/supi-code-runtime/api";
-import { startDebugTimer } from "@mrclrchtr/supi-core/debug";
+import {
+  startDebugTimer,
+  truncateDebugIdentity as truncateIdentity,
+} from "@mrclrchtr/supi-core/debug";
 import {
   CancellationTokenSource,
   createMessageConnection,
@@ -18,7 +21,7 @@ import {
   StreamMessageReader,
   StreamMessageWriter,
 } from "vscode-jsonrpc/node";
-import { boundCwd, LSP_REQUEST_TIMEOUT_ERROR_CODE, truncateIdentity } from "../debug-telemetry.ts";
+import { boundCwd, LSP_REQUEST_TIMEOUT_ERROR_CODE } from "../debug-telemetry.ts";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 
@@ -112,34 +115,40 @@ export class JsonRpcClient {
     const methodClass = classifyRequestMethod(method);
     const boundedMethod = truncateIdentity(method);
     const timer = startDebugTimer();
+    // A request cancelled before dispatch must not produce protocol traffic.
+    if (signal?.aborted) {
+      return rejectUndispatchedRequest(
+        signal.reason ?? new Error(`Request ${method} was cancelled`),
+        {
+          timer,
+          operationId: options?.operationId,
+          observation: { method: boundedMethod, methodClass, outcome: "cancelled" },
+          identity: { server: this.server, cwd: this.cwd },
+        },
+      );
+    }
     // An expired absolute deadline must not even send the request: the caller
     // no longer awaits a result, so no protocol traffic may start.
     if (deadlineMs !== undefined && deadlineMs <= 0) {
-      recordRequestTiming(
+      return rejectUndispatchedRequest(new CodeRequestDeadlineError(), {
         timer,
-        options?.operationId,
-        {
+        operationId: options?.operationId,
+        observation: {
           method: boundedMethod,
           methodClass,
           outcome: "timed-out",
           errorCode: LSP_REQUEST_TIMEOUT_ERROR_CODE,
         },
-        { server: this.server, cwd: this.cwd },
-      );
-      return Promise.reject(new CodeRequestDeadlineError());
+        identity: { server: this.server, cwd: this.cwd },
+      });
     }
     if (this.closed || !this.connection) {
-      recordRequestTiming(
+      return rejectUndispatchedRequest(new Error("JSON-RPC client is closed"), {
         timer,
-        options?.operationId,
-        {
-          method: boundedMethod,
-          methodClass,
-          outcome: "cancelled",
-        },
-        { server: this.server, cwd: this.cwd },
-      );
-      return Promise.reject(new Error("JSON-RPC client is closed"));
+        operationId: options?.operationId,
+        observation: { method: boundedMethod, methodClass, outcome: "cancelled" },
+        identity: { server: this.server, cwd: this.cwd },
+      });
     }
     const tokenSource = new CancellationTokenSource();
     let timeout: ReturnType<typeof setTimeout> | undefined;
@@ -344,6 +353,19 @@ function jsonRpcErrorCode(error: unknown): number | undefined {
   return typeof code === "number" && Number.isInteger(code) ? code : undefined;
 }
 
+function rejectUndispatchedRequest(
+  error: unknown,
+  timing: {
+    timer: ReturnType<typeof startDebugTimer>;
+    operationId: string | undefined;
+    observation: RequestTimingObservation;
+    identity: { server?: string; cwd?: string };
+  },
+): Promise<never> {
+  recordRequestTiming(timing.timer, timing.operationId, timing.observation, timing.identity);
+  return Promise.reject(error);
+}
+
 function recordRequestTiming(
   timer: ReturnType<typeof startDebugTimer>,
   operationId: string | undefined,

package/src/config/config.ts

@@ -4,6 +4,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadSupiConfigForScope } from "@mrclrchtr/supi-core/config";
+import { truncateDebugIdentity } from "@mrclrchtr/supi-core/debug";
 import type { LspConfig, ServerConfig } from "./types.ts";
 
 const CONFIG_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -24,17 +25,16 @@ export const LANGUAGE_ALIASES: Record<string, string> = {
   cpp: "c",
 };
 
-/** Resolve a language name through aliases. */
-export function resolveLanguageAlias(name: string): string {
-  return LANGUAGE_ALIASES[name] ?? name;
-}
-
-function resolveAliasesInOverrides(servers: Record<string, Partial<ServerConfig>>): void {
+function resolveAliasesInOverrides(servers: Record<string, unknown>): void {
   for (const [alias, target] of Object.entries(LANGUAGE_ALIASES)) {
-    if (servers[alias]) {
-      servers[target] = { ...(servers[target] ?? {}), ...servers[alias] };
-      delete servers[alias];
-    }
+    if (!Object.hasOwn(servers, alias)) continue;
+    const aliasOverride = servers[alias];
+    const targetOverride = servers[target];
+    servers[target] =
+      isRecord(aliasOverride) && isRecord(targetOverride)
+        ? { ...targetOverride, ...aliasOverride }
+        : aliasOverride;
+    delete servers[alias];
   }
 }
 
@@ -49,13 +49,13 @@ export function loadConfig(cwd: string, options?: LoadConfigOptions): LspConfig
   const globalLsp = loadSupiConfigForScope(
     "lsp",
     cwd,
-    { enabled: true, active: [], servers: {} as Record<string, ServerConfig> },
+    { servers: {} as Record<string, ServerConfig> },
     { scope: "global", homeDir: options?.homeDir },
   );
   const projectLsp = loadSupiConfigForScope(
     "lsp",
     cwd,
-    { enabled: true, active: [], servers: {} as Record<string, ServerConfig> },
+    { servers: {} as Record<string, ServerConfig> },
     { scope: "project" },
   );
 
@@ -91,6 +91,13 @@ function mergeServerConfigs(
   projectOverrides: unknown,
 ): Record<string, ServerConfig> {
   const merged: Record<string, ServerConfig> = { ...defaults };
+  const warnings = new Map<string, { fields: Set<string>; skipped: boolean }>();
+  const reportWarning: ServerConfigWarningReporter = (name, fields, skipped) => {
+    const warning = warnings.get(name) ?? { fields: new Set<string>(), skipped: false };
+    for (const field of fields) warning.fields.add(field);
+    warning.skipped ||= skipped;
+    warnings.set(name, warning);
+  };
 
   const globalServers = isServerRecord(globalOverrides) ? globalOverrides : {};
   const projectServers = isServerRecord(projectOverrides) ? projectOverrides : {};
@@ -100,14 +107,29 @@ function mergeServerConfigs(
 
   // Apply global per-key overrides against defaults
   for (const [lang, override] of Object.entries(globalServers)) {
-    const result = mergeSingleServer(defaults[lang], override);
+    const builtIn = defaults[lang] !== undefined;
+    const result = mergeSingleServer({
+      name: lang,
+      base: defaults[lang],
+      value: override,
+      builtIn,
+      reportWarning,
+    });
     if (result) merged[lang] = result;
   }
 
   // Apply project per-key overrides against the result so far
   for (const [lang, override] of Object.entries(projectServers)) {
-    const result = mergeSingleServer(merged[lang] ?? defaults[lang], override);
+    const builtIn = defaults[lang] !== undefined;
+    const result = mergeSingleServer({
+      name: lang,
+      base: merged[lang] ?? defaults[lang],
+      value: override,
+      builtIn,
+      reportWarning,
+    });
     if (result) merged[lang] = result;
+    else if (!builtIn) delete merged[lang];
   }
 
   // Remove servers whose final merged config has enabled === false
@@ -117,29 +139,141 @@ function mergeServerConfigs(
     }
   }
 
+  for (const [name, warning] of warnings) {
+    warnInvalidServerConfig(name, [...warning.fields], warning.skipped);
+  }
   return merged;
 }
 
-function mergeSingleServer(
-  base: ServerConfig | undefined,
-  override: Partial<ServerConfig>,
-): ServerConfig | null {
-  if (!base) {
-    // A custom server needs a command and at least one file extension.
-    if (
-      typeof override.command === "string" &&
-      override.command.length > 0 &&
-      Array.isArray(override.fileTypes) &&
-      override.fileTypes.length > 0 &&
-      (override.rootMarkers === undefined || Array.isArray(override.rootMarkers))
-    ) {
-      return { ...override, rootMarkers: override.rootMarkers ?? [] } as ServerConfig;
-    }
+type ServerConfigWarningReporter = (
+  name: string,
+  fields: readonly string[],
+  skipped: boolean,
+) => void;
+
+function mergeSingleServer(options: {
+  name: string;
+  base: ServerConfig | undefined;
+  value: unknown;
+  builtIn: boolean;
+  reportWarning: ServerConfigWarningReporter;
+}): ServerConfig | null {
+  const { name, base, value, builtIn, reportWarning } = options;
+  const { override, invalidFields } = validateServerOverride(value);
+  const missingFields = base
+    ? []
+    : [
+        ...(typeof override.command === "string" ? [] : ["command"]),
+        ...(override.fileTypes && override.fileTypes.length > 0 ? [] : ["fileTypes"]),
+      ];
+  const issues = [...new Set([...invalidFields, ...missingFields])];
+  if ((!builtIn && invalidFields.length > 0) || (!base && issues.length > 0)) {
+    reportWarning(name, issues, true);
     return null;
   }
+  if (!base) {
+    return {
+      ...override,
+      command: override.command as string,
+      fileTypes: override.fileTypes as string[],
+      rootMarkers: override.rootMarkers ?? [],
+    };
+  }
+
+  if (invalidFields.length > 0) reportWarning(name, invalidFields, false);
   return { ...base, ...override };
 }
 
-function isServerRecord(value: unknown): value is Record<string, Partial<ServerConfig>> {
+type ServerOverrideSetter = (override: Partial<ServerConfig>, candidate: unknown) => boolean;
+
+const SERVER_OVERRIDE_SETTERS: Record<string, ServerOverrideSetter> = {
+  command(override, candidate) {
+    if (typeof candidate !== "string" || candidate.trim().length === 0) return false;
+    override.command = candidate;
+    return true;
+  },
+  args(override, candidate) {
+    if (!isStringArray(candidate)) return false;
+    override.args = candidate;
+    return true;
+  },
+  fileTypes(override, candidate) {
+    if (!isNonEmptyStringArray(candidate)) return false;
+    override.fileTypes = candidate;
+    return true;
+  },
+  rootMarkers(override, candidate) {
+    if (!isStringArray(candidate)) return false;
+    override.rootMarkers = candidate;
+    return true;
+  },
+  enabled(override, candidate) {
+    if (typeof candidate !== "boolean") return false;
+    override.enabled = candidate;
+    return true;
+  },
+  env(override, candidate) {
+    if (!isStringRecord(candidate)) return false;
+    override.env = candidate;
+    return true;
+  },
+  initializationOptions(override, candidate) {
+    override.initializationOptions = candidate;
+    return true;
+  },
+  readinessTimeoutMs(override, candidate) {
+    if (typeof candidate !== "number" || !Number.isFinite(candidate) || candidate <= 0) {
+      return false;
+    }
+    override.readinessTimeoutMs = candidate;
+    return true;
+  },
+};
+
+function validateServerOverride(value: unknown): {
+  override: Partial<ServerConfig>;
+  invalidFields: string[];
+} {
+  if (!isRecord(value)) return { override: {}, invalidFields: ["definition"] };
+  const override: Partial<ServerConfig> = {};
+  const invalidFields: string[] = [];
+
+  for (const [field, candidate] of Object.entries(value)) {
+    const setter = SERVER_OVERRIDE_SETTERS[field];
+    if (!setter?.(override, candidate)) invalidFields.push(field);
+  }
+
+  return { override, invalidFields };
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+function isNonEmptyStringArray(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((entry) => typeof entry === "string" && entry.length > 0)
+  );
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+
+function warnInvalidServerConfig(name: string, fields: readonly string[], skipped: boolean): void {
+  const boundedName = truncateDebugIdentity(name);
+  const boundedFields = truncateDebugIdentity(fields.join(", "));
+  const action = skipped ? "Skipped invalid" : "Ignored invalid fields in";
+  // biome-ignore lint/suspicious/noConsole: malformed user configuration must be visible.
+  console.warn(`[supi-lsp] ${action} LSP server configuration "${boundedName}": ${boundedFields}`);
+}
+
+function isServerRecord(value: unknown): value is Record<string, unknown> {
+  return isRecord(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }