fix(core): add LSP diagnostics caching and document refresh fallback

Add publishDiagnostics notification handler in LspServerManager that
caches diagnostics and supports pending diagnostic promises. When
textDocument/diagnostic pull fails in NativeLspService, fall back to
force-refreshing the document (didClose + didOpen) and reading from
the cached diagnostics.

Also fix review findings:
- Clear cache/pending maps on server restart in resetHandle()
- Clean up pending diagnostics entries on timeout
- Re-track URI in openedDocuments on refresh failure
- Filter workspaceDiagnostics fallback by workspace root URI

Fixes #3029

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

Author: 2 people

packages/core/src/lsp/LspServerManager.ts

@@ -28,6 +28,7 @@ import type {
   LspServerStatus,
   LspSocketOptions,
 } from './types.js';
+import { isPublishDiagnosticsParams } from './types.js';
 import { createDebugLogger } from '../utils/debugLogger.js';
 
 const debugLogger = createDebugLogger('LSP');
@@ -58,6 +59,8 @@ export class LspServerManager {
       this.serverHandles.set(config.name, {
         config,
         status: 'NOT_STARTED',
+        cachedDiagnostics: new Map(),
+        pendingDiagnostics: new Map(),
       });
     }
   }
@@ -264,6 +267,21 @@ export class LspServerManager {
       handle.connection = connection.connection;
       handle.process = connection.process;
 
+      handle.connection.onNotification((msg) => {
+        if (
+          msg &&
+          msg.method === 'textDocument/publishDiagnostics' &&
+          isPublishDiagnosticsParams(msg.params)
+        ) {
+          handle.cachedDiagnostics.set(msg.params.uri, msg.params.diagnostics);
+          const pending = handle.pendingDiagnostics.get(msg.params.uri);
+          if (pending) {
+            handle.pendingDiagnostics.delete(msg.params.uri);
+            pending.resolve();
+          }
+        }
+      });
+
       // Initialize LSP server
       await this.initializeLspServer(connection, handle.config);
 
@@ -370,6 +388,8 @@ export class LspServerManager {
     handle.error = undefined;
     handle.warmedUp = false;
     handle.stopRequested = false;
+    handle.cachedDiagnostics?.clear();
+    handle.pendingDiagnostics?.clear();
   }
 
   private buildProcessEnv(
@@ -527,6 +547,8 @@ export class LspServerManager {
           references: { dynamicRegistration: true },
           documentSymbol: { dynamicRegistration: true },
           codeAction: { dynamicRegistration: true },
+          // Signal acceptance of publishDiagnostics notifications from server
+          publishDiagnostics: {},
         },
         workspace: {
           workspaceFolders: true,

packages/core/src/lsp/NativeLspService.ts

@@ -1064,6 +1064,87 @@ export class NativeLspService {
           `LSP textDocument/diagnostic failed for ${name}:`,
           error,
         );
+
+        // Force-refresh the document: send didClose + didOpen to trigger fresh analysis
+        handle.cachedDiagnostics.delete(uri);
+        const openedForServer = this.openedDocuments.get(name);
+        if (openedForServer?.has(uri)) {
+          openedForServer.delete(uri);
+          try {
+            const filePath = fileURLToPath(uri);
+            const text = fs.readFileSync(filePath, 'utf-8');
+            const languageId =
+              this.resolveLanguageId(filePath, handle) ?? 'plaintext';
+            handle.connection.send({
+              jsonrpc: '2.0',
+              method: 'textDocument/didClose',
+              params: { textDocument: { uri } },
+            });
+            handle.connection.send({
+              jsonrpc: '2.0',
+              method: 'textDocument/didOpen',
+              params: {
+                textDocument: {
+                  uri,
+                  languageId,
+                  version: Date.now(),
+                  text,
+                },
+              },
+            });
+            await this.delay(DEFAULT_LSP_DOCUMENT_OPEN_DELAY_MS * 5);
+            openedForServer.add(uri);
+          } catch (err) {
+            debugLogger.warn(`Failed to refresh document:`, err);
+            openedForServer.add(uri);
+          }
+        }
+        // Check push diagnostics cache (freshly updated after didOpen)
+        const cache = handle.cachedDiagnostics;
+        if (cache) {
+          const cached = cache.get(uri);
+          if (cached && cached.length > 0) {
+            for (const item of cached) {
+              const normalized2 = this.normalizer.normalizeDiagnostic(
+                item,
+                name,
+              );
+              if (normalized2) {
+                allDiagnostics.push(normalized2);
+              }
+            }
+            continue;
+          }
+        }
+        // Await push diagnostics via pub/sub (Promise.race with 5s timeout)
+        if (handle.pendingDiagnostics) {
+          await Promise.race([
+            new Promise<void>((resolve) => {
+              handle.pendingDiagnostics!.set(uri, { resolve });
+            }),
+            new Promise<void>((resolve) => {
+              setTimeout(() => {
+                handle.pendingDiagnostics!.delete(uri);
+                resolve();
+              }, 5000);
+            }),
+          ]);
+        }
+        // Read diagnostics after notification arrives or timeout
+        if (cache) {
+          const cached = cache.get(uri);
+          if (cached) {
+            for (const item of cached) {
+              const normalized = this.normalizer.normalizeDiagnostic(
+                item,
+                name,
+              );
+              if (normalized) {
+                allDiagnostics.push(normalized);
+              }
+            }
+          }
+        }
       }
     }
 
@@ -1112,6 +1193,32 @@ export class NativeLspService {
         }
       } catch (error) {
         debugLogger.warn(`LSP workspace/diagnostic failed for ${name}:`, error);
+
+        if (handle.cachedDiagnostics) {
+          const workspaceRootUris = this.workspaceContext
+            .getDirectories()
+            .map((dir) => pathToFileURL(dir).toString());
+          for (const [uri, diagnostics] of handle.cachedDiagnostics) {
+            if (!workspaceRootUris.some((rootUri) => uri.startsWith(rootUri))) {
+              continue;
+            }
+            if (results.length >= limit) break;
+            if (diagnostics && diagnostics.length > 0) {
+              const normalizedDiagnostics = [];
+              for (const diag of diagnostics) {
+                const n = this.normalizer.normalizeDiagnostic(diag, name);
+                if (n) normalizedDiagnostics.push(n);
+              }
+              if (normalizedDiagnostics.length > 0) {
+                results.push({
+                  uri,
+                  diagnostics: normalizedDiagnostics,
+                  serverName: name,
+                });
+              }
+            }
+          }
+        }
       }
 
       if (results.length >= limit) {

packages/core/src/lsp/types.ts

@@ -494,6 +494,10 @@ export interface LspServerHandle {
   restartAttempts?: number;
   /** Lock to prevent concurrent startup attempts */
   startingPromise?: Promise<void>;
+  /** Cache of diagnostics keyed by document URI */
+  cachedDiagnostics: Map<string, Array<Record<string, unknown>>>;
+  /** Pending diagnostic notification resolvers keyed by document URI */
+  pendingDiagnostics: Map<string, { resolve: () => void }>;
 }
 
 /**
@@ -521,3 +525,19 @@ export interface LspConnectionResult {
   /** Send initialize request */
   initialize: (params: unknown) => Promise<unknown>;
 }
+
+/**
+ * Type guard for publishDiagnostics notification params.
+ */
+export function isPublishDiagnosticsParams(
+  value: unknown,
+): value is { uri: string; diagnostics: Array<Record<string, unknown>> } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'uri' in value &&
+    typeof value['uri'] === 'string' &&
+    'diagnostics' in value &&
+    Array.isArray(value['diagnostics'])
+  );
+}