@ian-pascoe/pi-lsp 0.1.0 → 0.2.0

package/README.md

@@ -45,6 +45,7 @@ Pi LSP reads only the `lsp` key from Pi's global `settings.json` and trusted pro
             "languageId": "typescriptreact"
           }
         ],
+        "requireRootMarker": true,
         "rootMarkers": ["tsconfig.json", "package.json", ".git"],
         "initializationOptions": {},
         "settings": {},
@@ -58,14 +59,18 @@ Pi LSP reads only the `lsp` key from Pi's global `settings.json` and trusted pro
 Every field is optional except an enabled server's non-empty `command` and `languages`. Each
 language needs a non-empty `languageId` and at least one extension or exact filename. Extensions
 include their leading period. `rootMarkers` are basename glob patterns; the nearest matching
-ancestor becomes the server root and Pi's working directory is the fallback.
+ancestor becomes the server root and Pi's working directory is the fallback. Set
+`requireRootMarker` to `true` to exclude the server for files without any matching ancestor; it
+defaults to `false`. A required empty `rootMarkers` list is invalid. Explicit requests naming an
+otherwise compatible excluded server report that its required root marker was not found.
 
 Global and project timeouts merge by field. A project server replaces the complete global server
 with the same ID; set a project server to `null` to remove it. `initializationOptions` is sent only
 during initialization. `settings` is used for `workspace/didChangeConfiguration` and
 `workspace/configuration`. Environment strings override `process.env`; `null` removes a variable.
-A malformed layer or unknown field disables LSP startup and remains visible through `status`.
-Untrusted project settings are ignored.
+Invalid server definitions and timeout fields are quarantined individually and remain visible
+through `status`; unrelated valid settings continue to work. An invalid project server replacement
+still shadows the global definition. Untrusted project settings are ignored.
 
 Pi's `/reload` reloads configuration. Servers start on first use, live for one Pi session, and stay
 unavailable after a process or protocol failure until `restart` or `/reload`.
@@ -97,8 +102,9 @@ UTF-32 encoding. `selection_ranges` accepts a `positions` array. `find_reference
 `workspace_symbols` requires `query` and a root-anchor `file_path`. `workspace_diagnostics`,
 `capabilities`, and `restart` require `server_id` and a root-anchor `file_path`. Other reads query
 every matching capable server unless narrowed by `server_id`; successful responses remain visible
-when another server fails. A mutation may omit `server_id` only when exactly one matching capable
-server exists.
+when another server fails. Automatic reads omit matching incapable servers and fail once if none
+are capable; explicitly selecting an incapable server reports that the operation is unsupported. A
+mutation may omit `server_id` only when exactly one matching capable server exists.
 
 Formatting requires `tab_size` and `insert_spaces`. It optionally accepts
 `trim_trailing_whitespace`, `insert_final_newline`, and `trim_final_newlines`. Range formatting also
@@ -164,6 +170,9 @@ Changed, created, and renamed destination files are diagnosed; deleted files are
 recognized result gets an explicit outcome, including `no diagnostics`, `no configured server`,
 timeout, unavailable server, or an `apply_patch` adapter-version warning. Diagnostics preserve
 duplicates from independent servers and never change the original tool's success or error state.
+Only servers that advertise document diagnostics participate; formatting-only servers remain
+available for explicit LSP formatting operations without appearing in Post-edit Diagnostics.
+Files excluded by every matching server's Activation Gate are skipped silently.
 
 Findings, matched-server failures, timeouts, and adapter warnings also appear in one expandable
 Post-edit Diagnostics Entry after the current tool batch. Clean results and files without a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-lsp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Configured language-server tools and post-edit diagnostics for Pi",
   "keywords": [
@@ -22,6 +22,7 @@
   },
   "files": [
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -30,10 +31,6 @@
     "access": "public",
     "provenance": true
   },
-  "scripts": {
-    "test": "vitest run --config ../../vitest.config.ts --root .",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
-  },
   "dependencies": {
     "cross-spawn": "^7.0.6",
     "vscode-languageserver-protocol": "^3.17.5"
@@ -52,6 +49,13 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
+  },
+  "scripts": {
+    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   }
-}
+}

package/skills/pi-lsp/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: pi-lsp
+description: Configure or diagnose Pi LSP when a Server Definition fails, a file does not route, diagnostics are missing, or lsp settings need changing.
+license: MIT
+---
+
+# Pi LSP
+
+1. Read [`../../README.md`](../../README.md)'s Settings and `lsp` tool sections, then identify the effective settings scope.
+2. Call `lsp` with `{"operation":"status"}`.
+3. Test a representative file with `capabilities`, then `diagnostics`, supplying `server_id` when needed.
+4. Classify the result as settings, routing, process, capability, or Post-edit Diagnostics behavior.
+5. If settings changed, reload Pi; if settings are unchanged and the Server Instance is unavailable, use `restart`.
+6. Repeat status, capabilities, and diagnostics. Finish when the representative file reaches the intended Server Instance and operation, or an exact unsupported capability is evidenced.
+
+`configured` has not routed a file yet. `unavailable` is sticky and retains stderr. Keep diagnosis read-only; stop before applying a Workspace Edit Preview.

package/src/lsp-position-encoding.ts

@@ -24,7 +24,8 @@ export function normalizeLspPositionEncoding(encoding: string | undefined): LspP
   return "utf-16";
 }
 
-function documentLines(documentText: string): readonly string[] {
+/** Split document text into lines on CRLF, LF, or CR separators. */
+export function documentLines(documentText: string): readonly string[] {
   return documentText.split(/\r\n|[\n\r]/u);
 }
 

package/src/lsp-post-edit-diagnostics-rendering.ts

@@ -68,7 +68,8 @@ function severityColor(severity: DiagnosticSeverity): ThemeColor {
   }
 }
 
-function pluralizedCount(count: number, singular: string, plural = `${singular}s`): string {
+/** Render one count with a pluralized noun, e.g. `3 files` or `1 file`. */
+export function pluralizedCount(count: number, singular: string, plural = `${singular}s`): string {
   return `${count} ${count === 1 ? singular : plural}`;
 }
 

package/src/lsp-post-edit-diagnostics.ts

@@ -98,28 +98,9 @@ export const PostEditDiagnosticOutcomeSchema = Type.Union([
 export type PostEditDiagnosticOutcome = Static<typeof PostEditDiagnosticOutcomeSchema>;
 
 /** Runs fresh Post-edit Diagnostics for changed paths after a Supported Mutation Tool result. */
-export interface PostEditDiagnosticsRunner {
-  /** Return every fresh diagnostic and explicit non-diagnostic outcome for the supplied paths. */
-  runPostEditDiagnostics(
-    paths: readonly PostEditDiagnosticPath[],
-  ): Promise<readonly PostEditDiagnosticOutcome[]>;
-}
-
-/** Minimal Tool Result shape accepted by the structural post-edit adapters. */
-export interface PostEditToolResult {
-  /** Tool name supplied by Pi's central tool-result event. */
-  readonly toolName: string;
-  /** Original tool arguments supplied to the central event. */
-  readonly input: ToolResultEvent["input"];
-  /** Tool-result details owned by the mutation implementation. */
-  readonly details: ToolResultEvent["details"];
-  /** Existing Pi content, retained verbatim before the appended LSP section. */
-  readonly content: ToolResultEvent["content"];
-  /** Existing tool failure state, which diagnostics must not change. */
-  readonly isError: boolean;
-  /** Existing usage accounting, which diagnostics must not change. */
-  readonly usage?: ToolResultEvent["usage"];
-}
+export type PostEditDiagnosticsRunner = (
+  paths: readonly PostEditDiagnosticPath[],
+) => Promise<readonly PostEditDiagnosticOutcome[]>;
 
 /** Tool-result fields returned by Post-edit Diagnostics middleware without changing mutation state. */
 export interface PostEditDiagnosticsResultPatch {
@@ -174,7 +155,7 @@ function pathsAfterMutation(result: ReturnType<typeof mutationResult>): PostEdit
 
 /** Extract exact changed destination paths from one Supported Mutation Tool result. */
 export function extractPostEditDiagnosticPaths(
-  event: Pick<PostEditToolResult, "toolName" | "input" | "details" | "isError">,
+  event: Pick<ToolResultEvent, "toolName" | "input" | "details" | "isError">,
 ): ExtractedMutation | undefined {
   if (event.toolName === "edit" || event.toolName === "write") {
     if (event.isError || !Value.Check(NativeMutationInputSchema, event.input)) return undefined;
@@ -261,7 +242,7 @@ export function formatPostEditDiagnostics(outcomes: readonly PostEditDiagnosticO
 
 /** Append fresh Post-edit Diagnostics while preserving every mutation-result field Pi already owns. */
 export async function appendPostEditDiagnostics(
-  event: PostEditToolResult,
+  event: ToolResultEvent,
   diagnostics: PostEditDiagnosticsRunner,
 ): Promise<PostEditDiagnosticsResultPatch | undefined> {
   const extracted = extractPostEditDiagnosticPaths(event);
@@ -271,8 +252,9 @@ export async function appendPostEditDiagnostics(
       kind: "warning",
       message,
     })),
-    ...(await diagnostics.runPostEditDiagnostics(extracted.paths)),
+    ...(await diagnostics(extracted.paths)),
   ];
+  if (outcomes.length === 0) return undefined;
   const patch: PostEditDiagnosticsResultPatch = {
     content: [...event.content, { type: "text", text: formatPostEditDiagnostics(outcomes) }],
     details: event.details,
@@ -281,11 +263,3 @@ export async function appendPostEditDiagnostics(
   };
   return event.usage === undefined ? patch : { ...patch, usage: event.usage };
 }
-
-/** Adapt Pi's central ToolResultEvent shape to Post-edit Diagnostics middleware. */
-export async function appendPiPostEditDiagnostics(
-  event: ToolResultEvent,
-  diagnostics: PostEditDiagnosticsRunner,
-): Promise<PostEditDiagnosticsResultPatch | undefined> {
-  return appendPostEditDiagnostics(event, diagnostics);
-}

package/src/lsp-server-client.ts

@@ -48,10 +48,12 @@ import {
   type WorkspaceEdit,
 } from "vscode-languageserver-protocol/node";
 import {
+  documentLines,
   measureLspPositionCharacters,
   normalizeLspPositionEncoding,
   type LspPositionEncoding,
 } from "./lsp-position-encoding.js";
+import type { LspTimeouts } from "./pi-lsp-settings.js";
 
 const MAX_OPEN_DOCUMENTS = 100;
 const MAX_STDERR_BYTES = 1024 * 1024;
@@ -79,16 +81,7 @@ const PrepareRenameProviderSchema = Type.Object(
 );
 
 /** Time budgets, in milliseconds, for one language-server process. */
-export interface LspServerClientTimeouts {
-  /** Initialize request budget. */
-  readonly initializeMs: number;
-  /** Ordinary request budget. */
-  readonly requestMs: number;
-  /** Fresh diagnostics budget. */
-  readonly diagnosticsMs: number;
-  /** Graceful shutdown budget before process termination. */
-  readonly shutdownMs: number;
-}
+export type LspServerClientTimeouts = LspTimeouts;
 
 /** Launch and protocol configuration for one language-server process. */
 export interface LspServerClientOptions {
@@ -118,8 +111,6 @@ export interface LspServerClientOptions {
 
 /** A valid UTF-8 document synchronized with one server instance. */
 export interface LspSynchronizedDocument {
-  /** Absolute file path. */
-  readonly filePath: string;
   /** File URI sent to the server. */
   readonly uri: string;
   /** Monotonic document version local to this server instance. */
@@ -148,8 +139,6 @@ export type LspWorkspaceDiagnosticResult =
 
 /** Classified process, protocol, timeout, cancellation, and UTF-8 client failure. */
 export class LspServerClientError extends Error {
-  readonly _tag = "LspServerClientError" as const;
-
   /** Construct a stable Pi LSP client failure that always names the stderr capture. */
   constructor(
     readonly kind:
@@ -218,7 +207,7 @@ function serverWantsSave(capabilities: ServerCapabilities): boolean {
 }
 
 function protocolLineEndPosition(text: string, encoding: LspPositionEncoding): Position {
-  const lines = text.split(/\r\n|\r|\n/);
+  const lines = documentLines(text);
   const lineText = lines.at(-1) ?? "";
   return {
     line: lines.length - 1,
@@ -268,13 +257,12 @@ export class LspServerClient {
   private positionEncodingValue: LspPositionEncoding = "utf-16";
   private textDocumentSyncKind: TextDocumentSyncKind = TextDocumentSyncKind.None;
   private readonly openDocuments = new Map<string, OpenDocumentState>();
+  private readonly documentSynchronizations = new Map<string, Promise<LspSynchronizedDocument>>();
   private readonly pushDiagnostics = new Map<string, PushDiagnosticsState>();
   private readonly pullDiagnostics = new Map<string, PullDiagnosticsState>();
   private readonly dynamicRegistrations = new Map<string, Registration>();
   private readonly diagnosticWaiters = new Map<string, Set<() => void>>();
-  private readonly protocolMessages: string[] = [];
   private diagnosticsRevision = 0;
-  private diagnosticsRefreshRevision = 0;
   private stderrTail: Buffer<ArrayBufferLike> = Buffer.alloc(0);
   private stderrWrite = Promise.resolve();
   private closing = false;
@@ -381,11 +369,6 @@ export class LspServerClient {
     return this.options.stderrPath;
   }
 
-  /** Most recent bounded protocol log/show messages, oldest first. */
-  get recentProtocolMessages(): readonly string[] {
-    return this.protocolMessages;
-  }
-
   /** Whether a static or dynamically registered LSP method is available. */
   hasCapability(method: string): boolean {
     if (
@@ -525,8 +508,33 @@ export class LspServerClient {
     filePath: string,
     languageId: string,
   ): Promise<LspSynchronizedDocument> {
-    this.throwIfUnavailable();
     const absolutePath = resolve(filePath);
+    const uri = pathToFileURL(absolutePath).href;
+    const activeSynchronization = this.documentSynchronizations.get(uri);
+    const waitForActiveSynchronization =
+      activeSynchronization?.then(
+        () => undefined,
+        () => undefined,
+      ) ?? Promise.resolve();
+    const synchronization = waitForActiveSynchronization.then(() =>
+      this.synchronizeDocumentOnce(absolutePath, uri, languageId),
+    );
+    this.documentSynchronizations.set(uri, synchronization);
+    try {
+      return await synchronization;
+    } finally {
+      if (this.documentSynchronizations.get(uri) === synchronization) {
+        this.documentSynchronizations.delete(uri);
+      }
+    }
+  }
+
+  private async synchronizeDocumentOnce(
+    absolutePath: string,
+    uri: string,
+    languageId: string,
+  ): Promise<LspSynchronizedDocument> {
+    this.throwIfUnavailable();
     let text: string;
     try {
       const bytes = await readFile(absolutePath);
@@ -544,10 +552,13 @@ export class LspServerClient {
       throw cause;
     }
 
-    const uri = pathToFileURL(absolutePath).href;
     const existing = this.openDocuments.get(uri);
+    if (existing?.text === text && existing.languageId === languageId) {
+      this.openDocuments.delete(uri);
+      this.openDocuments.set(uri, existing);
+      return existing;
+    }
     const next: OpenDocumentState = {
-      filePath: absolutePath,
       uri,
       version: (existing?.version ?? 0) + 1,
       text,
@@ -622,7 +633,12 @@ export class LspServerClient {
     }
 
     try {
-      return await this.firstDiagnosticResult(candidates, signal);
+      return await this.raceBudget(
+        Promise.any(candidates),
+        this.options.timeouts.diagnosticsMs,
+        "diagnostics",
+        signal,
+      );
     } catch (cause) {
       if (cause instanceof LspServerClientError) {
         if (cause.kind === "cancelled") throw cause;
@@ -805,22 +821,13 @@ export class LspServerClient {
       }
     });
     this.connection.onRequest(WorkDoneProgressCreateRequest.type, () => undefined);
-    this.connection.onRequest(DiagnosticRefreshRequest.type, () => {
-      this.diagnosticsRefreshRevision++;
-    });
+    this.connection.onRequest(DiagnosticRefreshRequest.type, () => undefined);
     this.connection.onRequest(ApplyWorkspaceEditRequest.type, async (parameters) =>
       this.rejectServerWorkspaceEdit(parameters),
     );
-    this.connection.onRequest(ShowMessageRequest.type, (parameters) => {
-      this.rememberProtocolMessage(parameters.message);
-      return null;
-    });
-    this.connection.onNotification(LogMessageNotification.type, (parameters) => {
-      this.rememberProtocolMessage(parameters.message);
-    });
-    this.connection.onNotification(ShowMessageNotification.type, (parameters) => {
-      this.rememberProtocolMessage(parameters.message);
-    });
+    this.connection.onRequest(ShowMessageRequest.type, () => null);
+    this.connection.onNotification(LogMessageNotification.type, () => undefined);
+    this.connection.onNotification(ShowMessageNotification.type, () => undefined);
   }
 
   private async initialize(): Promise<void> {
@@ -923,30 +930,19 @@ export class LspServerClient {
     if (signal?.aborted === true) throw abortError(this.options);
 
     const cancellation = new CancellationTokenSource();
-    let timeout: NodeJS.Timeout | undefined;
-    let abortListener: (() => void) | undefined;
-    const request = this.connection.sendRequest<TResult>(method, parameters, cancellation.token);
-    const timeoutPromise = new Promise<never>((_resolve, reject) => {
-      timeout = setTimeout(() => {
-        cancellation.cancel();
-        reject(timeoutError(this.options, operation));
-      }, budgetMs);
-      timeout.unref();
-    });
-    const abortPromise = new Promise<never>((_resolve, reject) => {
-      if (signal === undefined) return;
-      abortListener = () => {
-        cancellation.cancel();
-        reject(abortError(this.options));
-      };
-      signal.addEventListener("abort", abortListener, { once: true });
-    });
-    const terminalPromise = this.terminalErrorPromise.then((error) => {
-      throw error;
-    });
-
     try {
-      return await Promise.race([request, timeoutPromise, abortPromise, terminalPromise]);
+      return await Promise.race([
+        this.raceBudget(
+          this.connection.sendRequest<TResult>(method, parameters, cancellation.token),
+          budgetMs,
+          operation,
+          signal,
+          () => cancellation.cancel(),
+        ),
+        this.terminalErrorPromise.then((error) => {
+          throw error;
+        }),
+      ]);
     } catch (cause) {
       if (cause instanceof LspServerClientError) throw cause;
       throw new LspServerClientError(
@@ -957,10 +953,6 @@ export class LspServerClient {
         { cause },
       );
     } finally {
-      if (timeout !== undefined) clearTimeout(timeout);
-      if (signal !== undefined && abortListener !== undefined) {
-        signal.removeEventListener("abort", abortListener);
-      }
       cancellation.dispose();
     }
   }
@@ -1047,34 +1039,29 @@ export class LspServerClient {
     return { status: "fresh", source: "document_pull", diagnostics: report.items };
   }
 
-  private async firstDiagnosticResult(
-    candidates: readonly Promise<LspDocumentDiagnosticResult>[],
-    signal?: AbortSignal,
-  ): Promise<LspDocumentDiagnosticResult> {
-    return this.raceBudget(
-      Promise.any(candidates),
-      this.options.timeouts.diagnosticsMs,
-      "diagnostics",
-      signal,
-    );
-  }
-
   private async raceBudget<TResult>(
     value: Promise<TResult>,
     budgetMs: number,
     operation: string,
     signal?: AbortSignal,
+    onCancel?: () => void,
   ): Promise<TResult> {
     if (signal?.aborted === true) throw abortError(this.options);
     let timeout: NodeJS.Timeout | undefined;
     let abortListener: (() => void) | undefined;
     const timeoutPromise = new Promise<never>((_resolve, reject) => {
-      timeout = setTimeout(() => reject(timeoutError(this.options, operation)), budgetMs);
+      timeout = setTimeout(() => {
+        onCancel?.();
+        reject(timeoutError(this.options, operation));
+      }, budgetMs);
       timeout.unref();
     });
     const abortPromise = new Promise<never>((_resolve, reject) => {
       if (signal === undefined) return;
-      abortListener = () => reject(abortError(this.options));
+      abortListener = () => {
+        onCancel?.();
+        reject(abortError(this.options));
+      };
       signal.addEventListener("abort", abortListener, { once: true });
     });
     try {
@@ -1167,11 +1154,6 @@ export class LspServerClient {
     }
   }
 
-  private rememberProtocolMessage(message: string): void {
-    this.protocolMessages.push(message);
-    if (this.protocolMessages.length > 100) this.protocolMessages.shift();
-  }
-
   private async evictOldDocuments(): Promise<void> {
     while (this.openDocuments.size > MAX_OPEN_DOCUMENTS) {
       const oldestUri = this.openDocuments.keys().next().value;