@dreki-gg/pi-lsp 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @dreki-gg/pi-lsp
 
+## 0.4.0
+
+### Minor Changes
+
+- a5e800f: refactor(lsp): adopt Effect and stop enabling TypeScript by default
+
+  - **Effect-based architecture** — config loading, scaffolding, and the unified `lsp` tool now run as Effect programs against injectable services (`FileSystem`, `CommandResolver`, `ServerManager`). Failures are modeled as `Data.TaggedError` types (`ConfigReadError`, `ConfigWriteError`, `LspValidationError`, `NoCapableServerError`, `NoServerAvailableError`, `LspOperationError`), mirroring the firestore package's conventions. Promise-returning wrappers keep the public API stable.
+  - **TypeScript is no longer a default server** — the scaffolded starter config now ships TypeScript, Python, Rust, and Go as `disabled` examples. No language server is spawned until the user explicitly opts in, so the extension never auto-starts `typescript-language-server` on a fresh setup.
+  - New service-injection tests cover config resolution (global/npx/unavailable command paths) and scaffolding without touching disk or the shell.
+
+## 0.3.0
+
+### Minor Changes
+
+- [#43](https://github.com/dreki-gg/pi-extensions/pull/43) [`c8dc964`](https://github.com/dreki-gg/pi-extensions/commit/c8dc96448bd8cf1a594daf42a1ab0d56f932d629) Thanks [@jalbarrang](https://github.com/jalbarrang)! - feat(lsp): improve reliability and LLM guidance based on real-world usage feedback
+
+  - **documentSymbol now includes column positions** — output shows `line:col` instead of just `line`, eliminating the need for a follow-up `rg --column` to get positions for other LSP operations.
+  - **Retry with backoff during server indexing** — `hover`, `definition`, `references`, `implementation`, `documentSymbol`, and `workspaceSymbol` automatically retry (up to 2 times, 2s delay) when the server was recently initialized and returns empty results.
+  - **Send `didSave` notification** — the client now sends `textDocument/didSave` after opening or updating documents, fixing diagnostics for servers like `rust-analyzer` that require save events.
+  - **Improved diagnostics wait logic** — stale cached diagnostics are cleared on document re-sync, and the arbitrary 500ms delay is removed in favor of resolving immediately when fresh diagnostics arrive.
+  - **Rewritten `promptGuidelines`** — 9 targeted guidelines that teach LLMs (especially smaller models) how to use LSP tools effectively: prefer `hover` for quick inspection, position cursor in the middle of symbols, use compiler tools for diagnostics in compiled languages, and more.
+  - **Enhanced tool description** — includes tips section and notes that `incomingCalls`/`outgoingCalls` auto-prepare the call hierarchy.
+  - **Removed unused code** — `pathToUri` export, `capabilities` getter, and `closeDocument` method removed.
+
+### Patch Changes
+
+- [`87baca4`](https://github.com/dreki-gg/pi-extensions/commit/87baca402f6afa0bba627a3c179bacf0bbbeacba) Thanks [@jalbarrang](https://github.com/jalbarrang)! - fix(lsp): Windows URI normalization and diagnostic waiter race conditions
+
+  - Add `normalizeUri()` to decode percent-encoded URIs (`%3A` → `:`) and uppercase Windows drive letters, fixing key mismatches between `pathToUri` and server responses.
+  - `pathToUri()` now always uppercases the drive letter for consistency.
+  - `uriToPath()` now applies `decodeURIComponent` so encoded URIs from the server produce valid file paths.
+  - Replace per-URI waiter arrays with a single `PendingDiagnostic` promise per URI, eliminating manual timer/splice management.
+  - Track `invalidatedUris` to distinguish first-open (empty diagnostics = clean file → resolve immediately) from re-open (empty diagnostics = server clearing stale state → wait for real results).
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -38,6 +38,12 @@ Servers are configured via two config files (project overrides global):
 | `~/.pi/agent/extensions/lsp/config.json` | Global defaults |
 | `.pi/lsp.json` | Project-local overrides |
 
+On first run a starter `config.json` is scaffolded with example servers
+(TypeScript, Python, Rust, Go) — **all `disabled` by default**. No language
+server is enabled out of the box; flip `"disabled": false` (or remove the flag)
+on the ones you want. This keeps the extension from spawning a server you never
+asked for.
+
 ### Example: TypeScript + oxlint
 
 `.pi/lsp.json`:

package/extensions/lsp/client.ts

@@ -25,20 +25,41 @@ import type {
   ResolvedServerConfig,
   SymbolInformation,
 } from './types';
+import { withRetry } from './retry';
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
-export function pathToUri(filePath: string): string {
+/**
+ * Normalize a file URI for consistent map-key comparison.
+ *
+ * Some LSP servers (e.g. typescript-language-server on Windows) return URIs with
+ * percent-encoded colons (`%3A`) and lowercase drive letters.  We decode and
+ * uppercase so that `file:///d%3A/…` and `file:///D:/…` resolve to the same key.
+ */
+function normalizeUri(uri: string): string {
+  let normalized = decodeURIComponent(uri);
+  // Uppercase Windows drive letter: file:///d:/… → file:///D:/…
+  normalized = normalized.replace(
+    /^file:\/\/\/([a-z]):/,
+    (_, letter: string) => `file:///${letter.toUpperCase()}:`,
+  );
+  return normalized;
+}
+
+function pathToUri(filePath: string): string {
   const abs = resolve(filePath);
   const normalized = abs.replace(/\\/g, '/');
-  // Windows paths need file:///C:/... (three slashes)
-  if (/^[A-Za-z]:/.test(normalized)) return `file:///${normalized}`;
+  // Windows paths need file:///C:/... (three slashes), always uppercase drive letter
+  if (/^[A-Za-z]:/.test(normalized)) {
+    return `file:///${normalized[0].toUpperCase()}${normalized.slice(1)}`;
+  }
   return `file://${normalized}`;
 }
 
 export function uriToPath(uri: string): string {
   if (!uri.startsWith('file://')) return uri;
-  const path = uri.slice(7);
+  const decoded = decodeURIComponent(uri);
+  const path = decoded.slice(7);
   // Remove leading slash before Windows drive letter: /C:/... → C:/...
   if (/^\/[A-Za-z]:/.test(path)) return path.slice(1);
   return path;
@@ -86,9 +107,18 @@ interface OpenDocument {
   languageId: string;
 }
 
-interface DiagnosticWaiter {
+/**
+ * A single pending diagnostic request per URI.
+ *
+ * Instead of maintaining an array of waiters with individual timers, we keep one
+ * pending promise per URI.  Non-empty `publishDiagnostics` notifications resolve
+ * it immediately; empty ones are stored but do NOT resolve the pending — this
+ * avoids the "empty-then-real" race where the server clears stale diagnostics
+ * before sending real results.  A timeout passed via `Promise.race` in
+ * `waitForDiagnostics` acts as a safety net for genuinely clean files.
+ */
+interface PendingDiagnostic {
   resolve: () => void;
-  timer: ReturnType<typeof setTimeout>;
 }
 
 // ── Client ──────────────────────────────────────────────────────────────────
@@ -99,9 +129,12 @@ export class LspClient {
   private initializePromise: Promise<void> | null = null;
   private openDocs = new Map<string, OpenDocument>();
   private diagnosticStore = new Map<string, Diagnostic[]>();
-  private diagnosticWaiters = new Map<string, DiagnosticWaiter[]>();
+  private pendingDiagnostics = new Map<string, PendingDiagnostic>();
+  /** URIs where we just sent didChange and haven't yet received non-empty diagnostics. */
+  private invalidatedUris = new Set<string>();
   private serverCapabilities: Record<string, unknown> = {};
   private stderrLog: string[] = [];
+  private initTimestamp = 0;
 
   readonly config: ResolvedServerConfig;
   private rootPath: string;
@@ -123,15 +156,26 @@ export class LspClient {
     conn.setNotificationHandler((method, params) => {
       if (method === 'textDocument/publishDiagnostics') {
         const { uri, diagnostics } = params as PublishDiagnosticsParams;
-        this.diagnosticStore.set(uri, diagnostics);
+        const normalized = normalizeUri(uri);
+        this.diagnosticStore.set(normalized, diagnostics);
+
+        // Decide whether to resolve the pending promise:
+        // • Non-empty diagnostics always resolve (real errors found).
+        // • Empty diagnostics resolve ONLY when the URI was NOT recently
+        //   invalidated by a didChange — this avoids the "empty-then-real"
+        //   race where servers clear stale diagnostics before sending real ones.
+        const shouldResolve = diagnostics.length > 0 || !this.invalidatedUris.has(normalized);
+
+        if (diagnostics.length > 0) {
+          this.invalidatedUris.delete(normalized);
+        }
 
-        const waiters = this.diagnosticWaiters.get(uri);
-        if (waiters?.length) {
-          for (const w of waiters) {
-            clearTimeout(w.timer);
-            w.resolve();
+        if (shouldResolve) {
+          const pending = this.pendingDiagnostics.get(normalized);
+          if (pending) {
+            pending.resolve();
+            this.pendingDiagnostics.delete(normalized);
           }
-          this.diagnosticWaiters.delete(uri);
         }
       }
     });
@@ -209,6 +253,24 @@ export class LspClient {
     this.serverCapabilities = result?.capabilities ?? {};
     this.connection.sendNotification('initialized', {});
     this.initialized = true;
+    this.initTimestamp = Date.now();
+  }
+
+  /** Whether the server was initialized recently (within windowMs). */
+  private isRecentlyInitialized(windowMs = 30_000): boolean {
+    return this.initTimestamp > 0 && Date.now() - this.initTimestamp < windowMs;
+  }
+
+  /**
+   * Wrap an LSP operation with retry logic when the server was recently initialized.
+   * During indexing, servers may return empty results that resolve after a short wait.
+   */
+  private async retryIfIndexing<T>(
+    operation: () => Promise<T>,
+    isEmpty: (result: T) => boolean,
+  ): Promise<T> {
+    if (!this.isRecentlyInitialized()) return operation();
+    return withRetry(operation, isEmpty, { maxRetries: 2, delayMs: 2000 });
   }
 
   async shutdown(): Promise<void> {
@@ -228,17 +290,14 @@ export class LspClient {
     this.initializePromise = null;
     this.openDocs.clear();
     this.diagnosticStore.clear();
-    this.clearAllWaiters();
+    this.invalidatedUris.clear();
+    this.clearAllPending();
   }
 
   get isInitialized(): boolean {
     return this.initialized;
   }
 
-  get capabilities(): Record<string, unknown> {
-    return this.serverCapabilities;
-  }
-
   /** Check if the server advertised a specific capability. */
   hasCapability(name: string): boolean {
     return this.serverCapabilities[name] !== undefined && this.serverCapabilities[name] !== false;
@@ -258,6 +317,8 @@ export class LspClient {
 
     if (existing) {
       existing.version++;
+      this.diagnosticStore.delete(uri); // Clear stale diagnostics before re-sync
+      this.invalidatedUris.add(uri); // Mark as invalidated until real diagnostics arrive
       this.connection.sendNotification('textDocument/didChange', {
         textDocument: { uri, version: existing.version },
         contentChanges: [{ text }],
@@ -270,19 +331,14 @@ export class LspClient {
       this.openDocs.set(uri, { uri, version, languageId });
     }
 
-    return uri;
-  }
-
-  async closeDocument(filePath: string): Promise<void> {
-    const uri = pathToUri(resolve(this.rootPath, filePath));
-    const doc = this.openDocs.get(uri);
-    if (!doc) return;
-
-    this.connection.sendNotification('textDocument/didClose', {
+    // Notify the server that the file was saved — some servers (e.g. rust-analyzer)
+    // only generate diagnostics after a didSave notification.
+    this.connection.sendNotification('textDocument/didSave', {
       textDocument: { uri },
+      text,
     });
-    this.openDocs.delete(uri);
-    this.diagnosticStore.delete(uri);
+
+    return uri;
   }
 
   // ── Diagnostics ───────────────────────────────────────────────────────
@@ -293,103 +349,143 @@ export class LspClient {
     return this.diagnosticStore.get(uri) ?? [];
   }
 
-  private waitForDiagnostics(uri: string, timeoutMs: number): Promise<void> {
-    return new Promise<void>((resolveWait) => {
-      const existing = this.diagnosticStore.get(uri);
-      if (existing !== undefined) {
-        setTimeout(resolveWait, 500);
-        return;
-      }
+  /**
+   * Wait until non-empty diagnostics arrive for `uri`, or until `timeoutMs` elapses.
+   *
+   * If non-empty diagnostics are already in the store (e.g. from a previous
+   * notification), resolves immediately.  Otherwise sets up a single pending
+   * promise that the notification handler will resolve when real diagnostics
+   * arrive.  `Promise.race` against a timeout ensures we don't wait forever
+   * for genuinely clean files.
+   */
+  private async waitForDiagnostics(uri: string, timeoutMs: number): Promise<void> {
+    // Fast path: diagnostics already present and meaningful.
+    // • Non-empty → file has errors, return immediately.
+    // • Empty + not invalidated → genuinely clean file (e.g. first open), return.
+    const existing = this.diagnosticStore.get(uri);
+    if (existing !== undefined) {
+      if (existing.length > 0 || !this.invalidatedUris.has(uri)) return;
+    }
 
-      const timer = setTimeout(() => {
-        const waiters = this.diagnosticWaiters.get(uri);
-        if (waiters) {
-          const idx = waiters.findIndex((w) => w.resolve === resolveWait);
-          if (idx !== -1) waiters.splice(idx, 1);
-          if (waiters.length === 0) this.diagnosticWaiters.delete(uri);
-        }
-        resolveWait();
-      }, timeoutMs);
+    // Resolve any previous pending for this URI so it doesn't leak.
+    const prev = this.pendingDiagnostics.get(uri);
+    if (prev) prev.resolve();
 
-      const waiters = this.diagnosticWaiters.get(uri) ?? [];
-      waiters.push({ resolve: resolveWait, timer });
-      this.diagnosticWaiters.set(uri, waiters);
+    const { promise, resolve } = Promise.withResolvers<void>();
+    this.pendingDiagnostics.set(uri, { resolve });
+
+    // Safety-net timeout: resolves the race for files with zero errors.
+    let timer: ReturnType<typeof setTimeout>;
+    const timeout = new Promise<void>((r) => {
+      timer = setTimeout(r, timeoutMs);
     });
+
+    await Promise.race([promise, timeout]);
+
+    clearTimeout(timer!);
+    this.pendingDiagnostics.delete(uri);
   }
 
-  private clearAllWaiters(): void {
-    for (const [, waiters] of this.diagnosticWaiters) {
-      for (const w of waiters) {
-        clearTimeout(w.timer);
-        w.resolve();
-      }
+  private clearAllPending(): void {
+    for (const pending of this.pendingDiagnostics.values()) {
+      pending.resolve();
     }
-    this.diagnosticWaiters.clear();
+    this.pendingDiagnostics.clear();
   }
 
   // ── Hover ─────────────────────────────────────────────────────────────
 
   async hover(filePath: string, position: Position): Promise<Hover | null> {
     const uri = await this.openDocument(filePath);
-    const result = await this.connection.sendRequest('textDocument/hover', {
-      textDocument: { uri },
-      position,
-    });
-    return (result as Hover) ?? null;
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('textDocument/hover', {
+          textDocument: { uri },
+          position,
+        });
+        return (result as Hover) ?? null;
+      },
+      (result) => result === null,
+    );
   }
 
   // ── Definition ────────────────────────────────────────────────────────
 
   async definition(filePath: string, position: Position): Promise<Location[]> {
     const uri = await this.openDocument(filePath);
-    const result = await this.connection.sendRequest('textDocument/definition', {
-      textDocument: { uri },
-      position,
-    });
-    return normalizeLocations(result);
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('textDocument/definition', {
+          textDocument: { uri },
+          position,
+        });
+        return normalizeLocations(result);
+      },
+      (result) => result.length === 0,
+    );
   }
 
   // ── References ────────────────────────────────────────────────────────
 
   async references(filePath: string, position: Position): Promise<Location[]> {
     const uri = await this.openDocument(filePath);
-    const result = await this.connection.sendRequest('textDocument/references', {
-      textDocument: { uri },
-      position,
-      context: { includeDeclaration: true },
-    });
-    return normalizeLocations(result);
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('textDocument/references', {
+          textDocument: { uri },
+          position,
+          context: { includeDeclaration: true },
+        });
+        return normalizeLocations(result);
+      },
+      (result) => result.length === 0,
+    );
   }
 
   // ── Implementation ────────────────────────────────────────────────────
 
   async implementation(filePath: string, position: Position): Promise<Location[]> {
     const uri = await this.openDocument(filePath);
-    const result = await this.connection.sendRequest('textDocument/implementation', {
-      textDocument: { uri },
-      position,
-    });
-    return normalizeLocations(result);
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('textDocument/implementation', {
+          textDocument: { uri },
+          position,
+        });
+        return normalizeLocations(result);
+      },
+      (result) => result.length === 0,
+    );
   }
 
   // ── Document Symbols ──────────────────────────────────────────────────
 
   async documentSymbol(filePath: string): Promise<DocumentSymbol[] | SymbolInformation[]> {
     const uri = await this.openDocument(filePath);
-    const result = await this.connection.sendRequest('textDocument/documentSymbol', {
-      textDocument: { uri },
-    });
-    if (!Array.isArray(result)) return [];
-    return result as DocumentSymbol[] | SymbolInformation[];
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('textDocument/documentSymbol', {
+          textDocument: { uri },
+        });
+        if (!Array.isArray(result)) return [];
+        return result as DocumentSymbol[] | SymbolInformation[];
+      },
+      (result) => result.length === 0,
+    );
   }
 
   // ── Workspace Symbols ─────────────────────────────────────────────────
 
   async workspaceSymbol(query: string): Promise<SymbolInformation[]> {
     await this.ensureInitialized();
-    const result = await this.connection.sendRequest('workspace/symbol', { query });
-    if (!Array.isArray(result)) return [];
-    return result as SymbolInformation[];
+    return this.retryIfIndexing(
+      async () => {
+        const result = await this.connection.sendRequest('workspace/symbol', { query });
+        if (!Array.isArray(result)) return [];
+        return result as SymbolInformation[];
+      },
+      (result) => result.length === 0,
+    );
   }
 
   // ── Call Hierarchy ────────────────────────────────────────────────────