@mrclrchtr/supi-code-intelligence 4.9.0 → 5.0.0

package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostics.ts

@@ -1,54 +1,63 @@
-// LSP client document synchronization and diagnostic state.
-
-import { existsSync, readFileSync } from "node:fs";
-import type {
-  Diagnostic,
-  DocumentDiagnosticReport,
-  PublishDiagnosticsParams,
-  TextDocumentIdentifier,
-  TextDocumentItem,
-  VersionedTextDocumentIdentifier,
-} from "../config/types.ts";
+// biome-ignore-all lint/style/noExcessiveLinesPerFile: one client's document sync, diagnostics, refresh, and sync-file flow stay in one cohesive class.
+import * as path from "node:path";
+import {
+  type CodeQueryResult,
+  type CodeRequestControl,
+  completedCodeQuery,
+  throwIfCodeRequestInterrupted,
+  unavailableCodeQuery,
+} from "@mrclrchtr/supi-code-runtime/api";
+import type { Diagnostic, TextDocumentItem } from "../config/types.ts";
+import type { DiagnosticEvidenceSummary } from "../diagnostics/evidence.ts";
 import { detectLanguageId, fileToUri, uriToFile } from "../utils.ts";
+import { applyPushDiagnostics, buildClientDiagnosticSnapshot } from "./client-diagnostic-cache.ts";
+import { collectSynchronizedFileDiagnostics } from "./client-diagnostic-collection.ts";
+import {
+  type DiagnosticCacheEntry,
+  type DiagnosticSynchronization,
+  hasFreshPush,
+  isCurrentSynchronization,
+  isValidPublishDiagnosticsParams,
+  nextDocumentVersion,
+} from "./client-diagnostic-evidence.ts";
+import type { ClientDiagnosticsHost } from "./client-diagnostic-host.ts";
+import {
+  pullClientDiagnosticEvidenceFromHost,
+  refreshClientOpenDiagnostics,
+  sendDidCloseNotification,
+} from "./client-diagnostic-refresh.ts";
+import { DiagnosticObserver, type DiagnosticPushWaitOutcome } from "./client-diagnostic-timing.ts";
+import { DiagnosticWaitRegistry } from "./client-diagnostic-waiters.ts";
+import {
+  type ClientDiagnosticSnapshot,
+  type DiagnosticEntry,
+  fingerprintDocumentContent,
+  hasCurrentDiagnosticEvidence,
+  type OpenDocumentState,
+} from "./client-document-state.ts";
+import {
+  clearTrackedDocumentState,
+  reopenDocument,
+  synchronizeTrackedDocument,
+} from "./client-document-sync.ts";
+import { getDiagnosticFileState } from "./client-file-state.ts";
 
 const DIAGNOSTIC_WAIT_MS = 3_000;
-
-type OpenDocument = { version: number };
-
-type DiagnosticCacheEntry = {
-  diagnostics: Diagnostic[];
-  receivedAt: number;
-  version?: number;
-  resultId?: string;
-};
-
-/** One file's stored diagnostics as consumed by manager-level collection. */
-export interface DiagnosticEntry {
-  uri: string;
-  diagnostics: Diagnostic[];
-}
-
-interface ClientDiagnosticsHost {
-  isOperational(): boolean;
-  supportsPullDiagnostics(): boolean;
-  sendNotification(method: string, params: unknown): void;
-  pullDocumentDiagnostics(
-    uri: string,
-    previousResultId: string | undefined,
-    timeoutMs: number,
-  ): Promise<DocumentDiagnosticReport | null>;
-}
-
-/**
- * Owns one LSP client's open documents, diagnostic cache, waiters, and refresh policy.
- *
- * The host supplies transport and readiness operations. Callers use `LspClient` as
- * the external seam and do not access this state directly.
- */
+/** Bounded push wait after a reopen-resync fallback, in milliseconds. */
+const REOPEN_EVIDENCE_WAIT_MS = 1_000;
+/** Own one client's document and diagnostic evidence; revisions prevent stale reuse. */
 export class ClientDiagnostics {
-  readonly #openDocs = new Map<string, OpenDocument>();
+  readonly #openDocs = new Map<string, OpenDocumentState>();
   readonly #diagnosticStore = new Map<string, DiagnosticCacheEntry>();
-  readonly #diagnosticWaiters = new Map<string, Array<() => void>>();
+  readonly #waiters = new DiagnosticWaitRegistry();
+  readonly #versionHistory = new Map<string, number>();
+  readonly #failedUris = new Set<string>();
+  /** Client-side sync moment per URI: unversioned pushes before it stay rejected. */
+  readonly #unversionedPushSyncMoments = new Map<string, number>();
+  /** URIs closed by a lifecycle operation: versioned pushes stay fail-closed. */
+  readonly #closedVersionedBarrier = new Set<string>();
+  #evidenceRevision = 0;
+  #nextSynchronizationId = 0;
 
   constructor(private readonly host: ClientDiagnosticsHost) {}
 
@@ -56,36 +65,58 @@ export class ClientDiagnostics {
     return Array.from(this.#openDocs.keys()).map(uriToFile);
   }
 
-  /** Release all waiters and remove all document and diagnostic state. */
-  clear(): void {
+  clear(options: { preserveFailedDocuments?: boolean } = {}): void {
+    if (options.preserveFailedDocuments) {
+      for (const uri of [...this.#openDocs.keys(), ...this.#diagnosticStore.keys()]) {
+        this.#failedUris.add(uri);
+        this.#closedVersionedBarrier.add(uri);
+      }
+    } else {
+      this.#failedUris.clear();
+      this.#closedVersionedBarrier.clear();
+    }
     this.#openDocs.clear();
     this.#diagnosticStore.clear();
-    this.#releaseAllDiagnosticWaiters();
+    this.#versionHistory.clear();
+    this.#evidenceRevision++;
+    this.#unversionedPushSyncMoments.clear();
+    this.#waiters.releaseAll();
+    this.#waiters.cancelSettle();
   }
 
-  /** Open a document, or update it when it is already open. */
   didOpen(filePath: string, content: string): void {
     if (!this.host.isOperational()) return;
 
     const uri = fileToUri(filePath);
+    this.#failedUris.delete(uri);
     if (this.#openDocs.has(uri)) {
       this.didChange(filePath, content);
       return;
     }
 
     const languageId = detectLanguageId(filePath);
-    this.#openDocs.set(uri, { version: 1 });
+    this.#waiters.cancelSettle();
+    // A didOpen is a synchronization: pushes the server sends after it are
+    // responses to the open and can become fresh evidence (ADR 0020).
+    this.#unversionedPushSyncMoments.set(uri, Date.now());
+    this.#closedVersionedBarrier.delete(uri);
+    const version = nextDocumentVersion(this.#versionHistory, uri);
+    this.#openDocs.set(uri, {
+      version,
+      synchronizationId: ++this.#nextSynchronizationId,
+      evidenceRevision: this.#evidenceRevision,
+      contentFingerprint: fingerprintDocumentContent(content),
+    });
     this.host.sendNotification("textDocument/didOpen", {
       textDocument: {
         uri,
         languageId,
-        version: 1,
+        version,
         text: content,
       } satisfies TextDocumentItem,
     });
   }
 
-  /** Update a document, or open it when it is not tracked yet. */
   didChange(filePath: string, content: string): void {
     if (!this.host.isOperational()) return;
 
@@ -95,267 +126,340 @@ export class ClientDiagnostics {
       this.didOpen(filePath, content);
       return;
     }
-
-    doc.version++;
-    this.#sendDidChange(uri, doc.version, content);
+    const nextFingerprint = fingerprintDocumentContent(content);
+    if (doc.contentFingerprint === nextFingerprint) return;
+    synchronizeTrackedDocument({
+      uri,
+      content,
+      document: doc,
+      nextVersion: () => nextDocumentVersion(this.#versionHistory, uri),
+      nextSynchronizationId: () => ++this.#nextSynchronizationId,
+      evidenceRevision: this.#evidenceRevision,
+      waiters: this.#waiters,
+      sendNotification: (method, params) => this.host.sendNotification(method, params),
+      markUnversionedSyncMoment: () => this.#unversionedPushSyncMoments.set(uri, Date.now()),
+      clearFailedFile: () => this.#failedUris.delete(uri),
+      open: () => this.didOpen(filePath, content),
+    });
   }
 
-  /** Close a document and remove its cached diagnostic state. */
   didClose(filePath: string): void {
     const uri = fileToUri(filePath);
     const wasOpen = this.#openDocs.has(uri);
-    this.#clearFileState(uri);
+    this.#failedUris.delete(uri);
+    this.#unversionedPushSyncMoments.delete(uri);
+    this.#closedVersionedBarrier.add(uri);
+    clearTrackedDocumentState(this.#openDocs, this.#diagnosticStore, this.#waiters, uri);
 
     if (wasOpen && this.host.isOperational()) {
-      this.#sendDidClose(uri);
+      sendDidCloseNotification(this.host, uri);
     }
   }
 
-  /** Remove missing open documents and diagnostics, and return their file paths. */
   pruneMissingFiles(): string[] {
     const uris = new Set([...this.#openDocs.keys(), ...this.#diagnosticStore.keys()]);
     const removedFiles: string[] = [];
 
     for (const uri of uris) {
       const filePath = uriToFile(uri);
-      if (existsSync(filePath)) continue;
+      if (getDiagnosticFileState(filePath) !== "removed") continue;
 
       const wasOpen = this.#openDocs.has(uri);
-      this.#clearFileState(uri);
+      this.#failedUris.add(uri);
+      this.#unversionedPushSyncMoments.delete(uri);
+      this.#closedVersionedBarrier.add(uri);
+      clearTrackedDocumentState(this.#openDocs, this.#diagnosticStore, this.#waiters, uri);
       removedFiles.push(filePath);
-      if (wasOpen && this.host.isOperational()) this.#sendDidClose(uri);
+      if (wasOpen && this.host.isOperational()) sendDidCloseNotification(this.host, uri);
     }
 
     return removedFiles;
   }
+  /** Retain a failed document outcome when a replacement cannot reopen it. */
+  markFailedFile(filePath: string): void {
+    const uri = fileToUri(filePath);
+    this.#failedUris.add(uri);
+    this.#unversionedPushSyncMoments.delete(uri);
+    this.#closedVersionedBarrier.add(uri);
+  }
 
+  getOpenDocumentVersion(filePath: string): number | null {
+    return this.#openDocs.get(fileToUri(filePath))?.version ?? null;
+  }
   getDiagnostics(filePath: string): Diagnostic[] {
     return this.#diagnosticStore.get(fileToUri(filePath))?.diagnostics ?? [];
   }
-
-  /** Return non-empty diagnostics for files that still exist. */
+  getDiagnosticSnapshot(): ClientDiagnosticSnapshot {
+    return buildClientDiagnosticSnapshot({
+      store: this.#diagnosticStore,
+      openDocuments: this.#openDocs,
+      failedDocuments: this.#failedUris,
+      evidenceRevision: this.#evidenceRevision,
+    });
+  }
   getAllDiagnostics(): DiagnosticEntry[] {
-    const result: DiagnosticEntry[] = [];
-    for (const [uri, entry] of this.#diagnosticStore) {
-      if (entry.diagnostics.length === 0 || !existsSync(uriToFile(uri))) continue;
-      result.push({ uri, diagnostics: entry.diagnostics });
-    }
-    return result;
+    return this.getDiagnosticSnapshot().entries;
   }
-
-  /** Force the next pull refresh to request complete diagnostic reports. */
   clearPullResultIds(): void {
     for (const entry of this.#diagnosticStore.values()) delete entry.resultId;
   }
-
-  /** Apply diagnostics received through `textDocument/publishDiagnostics`. */
-  handlePublishDiagnostics(params: PublishDiagnosticsParams): void {
-    if (params.version !== undefined && params.version !== null) {
-      const openDoc = this.#openDocs.get(params.uri);
-      if (openDoc && params.version < openDoc.version) return;
+  /** Invalidate cache proof while retaining its data as partial fallback. */
+  invalidateCachedEvidence(): void {
+    this.#evidenceRevision++;
+    const knownUris = new Set([
+      ...this.#openDocs.keys(),
+      ...this.#diagnosticStore.keys(),
+      ...this.#versionHistory.keys(),
+      ...this.#failedUris,
+    ]);
+    // A watched-file notification is sent immediately after this call, so the
+    // recorded moment gates unversioned pushes around the invalidation: only
+    // pushes the server sends after the change can become fresh evidence.
+    const moment = Date.now();
+    for (const uri of knownUris) {
+      this.#unversionedPushSyncMoments.set(uri, moment);
+      this.#closedVersionedBarrier.add(uri);
     }
-
-    this.#diagnosticStore.set(params.uri, {
-      diagnostics: params.diagnostics,
-      receivedAt: Date.now(),
-      version: params.version ?? undefined,
-    });
-    this.#releaseDiagnosticWaiters(params.uri);
   }
 
-  /** Re-read open documents, then collect pull diagnostics or wait for push diagnostics. */
-  async refreshOpenDiagnostics(
-    options: { maxWaitMs?: number; quietMs?: number } = {},
-  ): Promise<void> {
-    if (!this.host.isOperational()) return;
-
-    const maxWaitMs = options.maxWaitMs ?? 3_000;
-    const quietMs = options.quietMs ?? 200;
-    const syncStart = Date.now();
-
-    this.#resyncOpenDocuments();
-    if (this.#openDocs.size === 0) return;
-
-    if (this.host.supportsPullDiagnostics()) {
-      try {
-        await this.#pullDiagnosticsForOpenDocuments(syncStart, maxWaitMs);
-        return;
-      } catch {
-        // Pull diagnostics failed. Wait for push diagnostics instead.
-      }
+  handlePublishDiagnostics(params: unknown): void {
+    if (!isValidPublishDiagnosticsParams(params)) return;
+    if (
+      !applyPushDiagnostics({
+        store: this.#diagnosticStore,
+        openDocuments: this.#openDocs,
+        params,
+        evidenceRevision: this.#evidenceRevision,
+        unversionedSyncMoment: this.#unversionedPushSyncMoments.get(params.uri),
+        closedVersionedBarrier: this.#closedVersionedBarrier.has(params.uri),
+      })
+    ) {
+      return;
     }
-
-    await this.#waitForDiagnosticSettle(syncStart, maxWaitMs, quietMs);
+    this.#waiters.releaseFile(params.uri, "published");
+    this.#waiters.notifySettle();
+  }
+  async refreshOpenDiagnostics(
+    options: { maxWaitMs?: number; quietMs?: number } & CodeRequestControl = {},
+  ): Promise<DiagnosticEvidenceSummary> {
+    const requestedFiles = Array.from(
+      new Set([...this.#openDocs.keys(), ...this.#diagnosticStore.keys(), ...this.#failedUris]),
+    ).map(uriToFile);
+    return refreshClientOpenDiagnostics({
+      host: this.host,
+      openDocuments: this.#openDocs,
+      diagnosticStore: this.#diagnosticStore,
+      waiters: this.#waiters,
+      versionHistory: this.#versionHistory,
+      requestedFiles,
+      evidenceRevision: () => this.#evidenceRevision,
+      failedFiles: () => new Set(Array.from(this.#failedUris).map(uriToFile)),
+      isRelatedUriTracked: (uri) => this.#openDocs.has(uri) || this.#versionHistory.has(uri),
+      nextSynchronizationId: () => ++this.#nextSynchronizationId,
+      invalidateEvidence: (uri) => {
+        this.#failedUris.add(uri);
+        const document = this.#openDocs.get(uri);
+        if (document) document.evidenceRevision = -1;
+      },
+      clearFile: (uri) => {
+        this.#failedUris.add(uri);
+        this.#unversionedPushSyncMoments.delete(uri);
+        this.#closedVersionedBarrier.add(uri);
+        clearTrackedDocumentState(this.#openDocs, this.#diagnosticStore, this.#waiters, uri);
+      },
+      markUnversionedSyncMoment: (uri) => this.#unversionedPushSyncMoments.set(uri, Date.now()),
+      clearFailedFile: (uri) => this.#failedUris.delete(uri),
+      options,
+    });
   }
 
-  /** Sync one file and return its diagnostics after pull or push collection. */
-  async syncAndWaitForDiagnostics(filePath: string, content: string): Promise<Diagnostic[]> {
+  async syncAndWaitForDiagnostics(
+    filePath: string,
+    content: string,
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<Diagnostic[]>> {
+    // Reject immediately when the request was already cancelled: no document
+    // synchronization or protocol traffic may start for a caller that no
+    // longer awaits a result.
+    throwIfCodeRequestInterrupted(control);
+    const supportsPull = this.host.supportsPullDiagnostics();
+    const observer = new DiagnosticObserver("sync-file", supportsPull, control, {
+      server: this.host.server,
+      cwd: this.host.cwd,
+      file: relativeDiagnosticFile(this.host.cwd, filePath),
+    });
     const uri = fileToUri(filePath);
+    const cached = this.#diagnosticStore.get(uri);
+    const cachedDiagnostics = cached ? [...cached.diagnostics] : null;
     const syncStart = Date.now();
-    this.didChange(filePath, content);
-
-    if (this.host.supportsPullDiagnostics()) {
-      const remaining = DIAGNOSTIC_WAIT_MS - (Date.now() - syncStart);
-      if (remaining > 0) {
-        try {
-          const pulled = await this.#pullDiagnosticsForUri(uri, remaining);
-          if (pulled) return this.getDiagnostics(filePath);
-        } catch {
-          // Pull diagnostics failed. Wait for push diagnostics instead.
-        }
-      }
-    }
-
-    await this.#waitForDiagnostics(uri, Math.max(0, DIAGNOSTIC_WAIT_MS - (Date.now() - syncStart)));
-    return this.getDiagnostics(filePath);
-  }
-
-  #resyncOpenDocuments(): void {
-    for (const [uri, doc] of this.#openDocs) {
-      const filePath = uriToFile(uri);
-      try {
-        if (!existsSync(filePath)) {
-          this.#clearFileState(uri);
-          this.#sendDidClose(uri);
-          continue;
-        }
-        const content = readFileSync(filePath, "utf-8");
-        doc.version++;
-        this.#sendDidChange(uri, doc.version, content);
-      } catch {
-        // Keep the document open when a transient read fails.
-      }
-    }
-  }
-
-  async #pullDiagnosticsForOpenDocuments(syncStart: number, maxWaitMs: number): Promise<void> {
-    const deadline = syncStart + maxWaitMs;
-    const uris = Array.from(this.#openDocs.keys());
-    const results = await Promise.allSettled(
-      uris.map(async (uri) => {
-        const remaining = deadline - Date.now();
-        if (remaining <= 0) throw new Error("pull diagnostic timeout");
-        return this.#pullDiagnosticsForUri(uri, remaining);
-      }),
-    );
-
-    const anySuccess = results.some((result) => result.status === "fulfilled" && result.value);
-    const hadFailure = results.some((result) => result.status === "rejected");
-    if ((hadFailure || !anySuccess) && uris.length > 0) {
-      throw new Error("pull diagnostics incomplete");
-    }
-  }
-
-  async #pullDiagnosticsForUri(uri: string, timeoutMs: number): Promise<boolean> {
-    const previousResultId = this.#diagnosticStore.get(uri)?.resultId;
-    const report = await this.host.pullDocumentDiagnostics(uri, previousResultId, timeoutMs);
-    if (!report) return false;
-    this.#applyPullReport(uri, report);
-    return true;
-  }
-
-  #applyPullReport(uri: string, report: DocumentDiagnosticReport): void {
-    if (report.kind === "full") {
-      this.#diagnosticStore.set(uri, {
-        diagnostics: report.items,
-        receivedAt: Date.now(),
-        resultId: report.resultId,
-      });
-    } else {
-      const current = this.#diagnosticStore.get(uri);
-      if (current) current.resultId = report.resultId;
-    }
-
-    for (const [relatedUri, relatedReport] of Object.entries(report.relatedDocuments ?? {})) {
-      if (relatedReport.kind !== "full") continue;
-      this.#diagnosticStore.set(relatedUri, {
-        diagnostics: relatedReport.items,
-        receivedAt: Date.now(),
-        resultId: relatedReport.resultId,
+    const openDocument = this.#openDocs.get(uri);
+    const contentUnchanged =
+      openDocument?.contentFingerprint === fingerprintDocumentContent(content);
+    const synchronizationCurrent = openDocument?.evidenceRevision === this.#evidenceRevision;
+    const cacheCurrent = hasCurrentDiagnosticEvidence(openDocument, cached, this.#evidenceRevision);
+    if (!contentUnchanged || !synchronizationCurrent || (cached !== undefined && !cacheCurrent)) {
+      synchronizeTrackedDocument({
+        uri,
+        content,
+        document: this.#openDocs.get(uri),
+        nextVersion: () => nextDocumentVersion(this.#versionHistory, uri),
+        nextSynchronizationId: () => ++this.#nextSynchronizationId,
+        evidenceRevision: this.#evidenceRevision,
+        waiters: this.#waiters,
+        sendNotification: (method, params) => this.host.sendNotification(method, params),
+        markUnversionedSyncMoment: () => this.#unversionedPushSyncMoments.set(uri, Date.now()),
+        clearFailedFile: () => this.#failedUris.delete(uri),
+        open: () => this.didOpen(filePath, content),
       });
     }
-  }
-
-  async #waitForDiagnosticSettle(
-    syncStart: number,
-    maxWaitMs: number,
-    quietMs: number,
-  ): Promise<void> {
-    const deadline = syncStart + maxWaitMs;
-    while (Date.now() < deadline) {
-      const lastReceived = this.#lastDiagnosticReceivedAfter(syncStart) || syncStart;
-      const elapsed = Date.now() - lastReceived;
-      if (elapsed >= quietMs) return;
-      await new Promise((resolve) =>
-        setTimeout(resolve, Math.min(quietMs - elapsed, deadline - Date.now(), 50)),
-      );
+    const synchronization = this.#openDocs.get(uri);
+    observer.synchronized();
+    if (!synchronization) {
+      return unavailableCodeQuery("The document could not be synchronized for diagnostics.");
     }
-  }
-
-  #lastDiagnosticReceivedAfter(afterTime: number): number {
-    let latest = 0;
-    for (const entry of this.#diagnosticStore.values()) {
-      if (entry.receivedAt > afterTime && entry.receivedAt > latest) latest = entry.receivedAt;
+    if (
+      contentUnchanged &&
+      hasCurrentDiagnosticEvidence(synchronization, cached, this.#evidenceRevision)
+    ) {
+      observer.cacheReused(1);
+      return completedCodeQuery(cachedDiagnostics ?? []);
     }
-    return latest;
-  }
-
-  #sendDidChange(uri: string, version: number, content: string): void {
-    this.host.sendNotification("textDocument/didChange", {
-      textDocument: { uri, version } satisfies VersionedTextDocumentIdentifier,
-      contentChanges: [{ text: content }],
-    });
-  }
-
-  #sendDidClose(uri: string): void {
-    this.host.sendNotification("textDocument/didClose", {
-      textDocument: { uri } satisfies TextDocumentIdentifier,
-    });
-  }
-
-  #clearFileState(uri: string): void {
-    this.#openDocs.delete(uri);
-    this.#diagnosticStore.delete(uri);
-    this.#releaseDiagnosticWaiters(uri);
+    const request = {
+      uri,
+      synchronizationId: synchronization.synchronizationId,
+      evidenceRevision: synchronization.evidenceRevision,
+    };
+    return this.#collectFileDiagnosticsWithReopenRetry(
+      {
+        filePath,
+        content,
+        uri,
+        supportsPull,
+        syncStart,
+        request,
+        cachedDiagnostics,
+        observer,
+      },
+      control,
+    );
   }
 
-  #waitForDiagnostics(uri: string, timeoutMs: number): Promise<void> {
-    if (timeoutMs <= 0) return Promise.resolve();
-
-    return new Promise<void>((resolve) => {
-      const waiter = () => {
-        clearTimeout(timer);
-        this.#removeDiagnosticWaiter(uri, waiter);
-        resolve();
+  /**
+   * Collect diagnostics for one synchronized document, retrying once through
+   * a reopen-resync on push-only routes when the first wait times out.
+   */
+  async #collectFileDiagnosticsWithReopenRetry(
+    options: {
+      filePath: string;
+      content: string;
+      uri: string;
+      supportsPull: boolean;
+      syncStart: number;
+      request: DiagnosticSynchronization;
+      cachedDiagnostics: Diagnostic[] | null;
+      observer: DiagnosticObserver;
+    },
+    control?: CodeRequestControl,
+  ): Promise<CodeQueryResult<Diagnostic[]>> {
+    const {
+      filePath,
+      content,
+      uri,
+      supportsPull,
+      syncStart,
+      request,
+      cachedDiagnostics,
+      observer,
+    } = options;
+    let pushOutcome: DiagnosticPushWaitOutcome | undefined;
+    let attemptRequest = request;
+    let attemptSyncStart = syncStart;
+    let attemptMaxWaitMs = DIAGNOSTIC_WAIT_MS;
+    let reopenedOnce = false;
+    let result: CodeQueryResult<Diagnostic[]>;
+    for (;;) {
+      result = await collectSynchronizedFileDiagnostics(
+        {
+          supportsPull,
+          syncStart: attemptSyncStart,
+          maxWaitMs: attemptMaxWaitMs,
+          request: attemptRequest,
+          cachedDiagnostics,
+          observer,
+          waiters: this.#waiters,
+          current: () => isCurrentSynchronization(this.#openDocs, attemptRequest),
+          freshPush: () =>
+            hasFreshPush(this.#diagnosticStore, attemptRequest, this.#evidenceRevision),
+          diagnostics: () => this.getDiagnostics(filePath),
+          pullDiagnostics: (timeoutMs, signal) =>
+            pullClientDiagnosticEvidenceFromHost({
+              host: this.host,
+              store: this.#diagnosticStore,
+              openDocuments: this.#openDocs,
+              currentEvidenceRevision: () => this.#evidenceRevision,
+              isRelatedUriTracked: (relatedUri) =>
+                this.#openDocs.has(relatedUri) || this.#versionHistory.has(relatedUri),
+              request: {
+                uri,
+                timeoutMs,
+                synchronizationId: attemptRequest.synchronizationId,
+                evidenceRevision: attemptRequest.evidenceRevision ?? this.#evidenceRevision,
+                signal,
+                deadline: control?.deadline,
+                operationId: control?.operationId,
+              },
+            }),
+          onPushWait: (outcome) => {
+            pushOutcome = outcome;
+          },
+        },
+        control,
+      );
+      // Reopen-resync fallback (R2): on push-only routes a document that
+      // timed out with no push stays unconfirmed — a clean file gets no
+      // push on didChange at all. Close and reopen it over the protocol so
+      // the server publishes on didOpen, then wait once more with a bounded
+      // budget. The cache entry and version history survive the reopen.
+      const document = this.#openDocs.get(uri);
+      if (
+        supportsPull ||
+        reopenedOnce ||
+        result.kind === "completed" ||
+        pushOutcome !== "timed-out" ||
+        !document ||
+        !isCurrentSynchronization(this.#openDocs, attemptRequest)
+      ) {
+        break;
+      }
+      reopenDocument({
+        uri,
+        content,
+        document,
+        languageId: detectLanguageId(filePath),
+        nextVersion: () => nextDocumentVersion(this.#versionHistory, uri),
+        nextSynchronizationId: () => ++this.#nextSynchronizationId,
+        evidenceRevision: this.#evidenceRevision,
+        waiters: this.#waiters,
+        sendNotification: (method, params) => this.host.sendNotification(method, params),
+        markUnversionedSyncMoment: () => this.#unversionedPushSyncMoments.set(uri, Date.now()),
+      });
+      observer.reopened(1);
+      reopenedOnce = true;
+      attemptRequest = {
+        uri,
+        synchronizationId: document.synchronizationId,
+        evidenceRevision: document.evidenceRevision,
       };
-      const timer = setTimeout(() => {
-        this.#removeDiagnosticWaiter(uri, waiter);
-        resolve();
-      }, timeoutMs);
-      const waiters = this.#diagnosticWaiters.get(uri) ?? [];
-      waiters.push(waiter);
-      this.#diagnosticWaiters.set(uri, waiters);
-    });
-  }
-
-  #removeDiagnosticWaiter(uri: string, waiter: () => void): void {
-    const waiters = this.#diagnosticWaiters.get(uri);
-    if (!waiters) return;
-    const next = waiters.filter((entry) => entry !== waiter);
-    if (next.length > 0) this.#diagnosticWaiters.set(uri, next);
-    else this.#diagnosticWaiters.delete(uri);
-  }
-
-  #releaseAllDiagnosticWaiters(): void {
-    for (const uri of Array.from(this.#diagnosticWaiters.keys())) {
-      this.#releaseDiagnosticWaiters(uri);
+      attemptSyncStart = Date.now();
+      attemptMaxWaitMs = REOPEN_EVIDENCE_WAIT_MS;
     }
+    observer.pushWaitCompleted(1, pushOutcome ?? "timed-out");
+    return result;
   }
+}
 
-  #releaseDiagnosticWaiters(uri: string): void {
-    const waiters = this.#diagnosticWaiters.get(uri);
-    if (!waiters) return;
-    this.#diagnosticWaiters.delete(uri);
-    for (const waiter of waiters) waiter();
-  }
+/** Return a workspace-relative diagnostic file path for telemetry identity. */
+function relativeDiagnosticFile(cwd: string | undefined, filePath: string): string | undefined {
+  if (cwd === undefined) return undefined;
+  return path.relative(cwd, path.resolve(cwd, filePath));
 }