@mrclrchtr/supi-code-intelligence 5.0.0 → 6.0.1

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

@@ -14,14 +14,19 @@ import { detectLanguageId, fileToUri, uriToFile } from "../utils.ts";
 import {
   type DiagnosticCacheEntry,
   type DiagnosticSynchronization,
+  hasCurrentEvidence,
   hasFreshEvidence,
   hasFreshPush,
   isCurrentSynchronization,
-  latestFreshEvidenceReceivedAt,
+  latestCurrentEvidenceReceivedAt,
   nextDocumentVersion,
   raceDiagnosticPull,
 } from "./client-diagnostic-evidence.ts";
 import type { ClientDiagnosticsHost } from "./client-diagnostic-host.ts";
+import type {
+  DiagnosticPublicationIdentity,
+  DiagnosticPublicationSynchronization,
+} from "./client-diagnostic-publication.ts";
 import { pullDiagnosticEvidence } from "./client-diagnostic-pull.ts";
 import type { DiagnosticPullRequest } from "./client-diagnostic-request.ts";
 import {
@@ -30,7 +35,11 @@ import {
   isDiagnosticTimeout,
 } from "./client-diagnostic-timing.ts";
 import type { DiagnosticStateWait, DiagnosticWaitRegistry } from "./client-diagnostic-waiters.ts";
-import type { OpenDocumentState } from "./client-document-state.ts";
+import {
+  fingerprintDocumentContent,
+  hasConfirmedDiagnosticEvidence,
+  type OpenDocumentState,
+} from "./client-document-state.ts";
 import {
   type ResynchronizeDocumentsResult,
   reopenDocument,
@@ -60,12 +69,15 @@ export function buildDiagnosticRefreshEvidence(options: {
   currentEvidenceRevision: number;
   openDocuments: ReadonlyMap<string, unknown>;
   diagnosticStore: ReadonlyMap<string, DiagnosticCacheEntry>;
+  /** Required quiet time after the latest push for this refresh result. */
+  pushQuietMs?: number;
 }): DiagnosticEvidenceSummary {
   const synchronizationByFile = new Map(
     options.synchronizations.map((item) => [uriToFile(item.uri), item]),
   );
   const removedFiles = new Set(options.resynchronization.removedFiles);
   const failedFiles = new Set(options.resynchronization.failedFiles);
+  const observedAt = Date.now();
   const documents = options.requestedFiles.map((file) => {
     const uri = fileToUri(file);
     const synchronization = synchronizationByFile.get(file);
@@ -84,7 +96,13 @@ export function buildDiagnosticRefreshEvidence(options: {
     }
     if (
       synchronization &&
-      hasFreshEvidence(options.diagnosticStore, synchronization, options.currentEvidenceRevision)
+      hasSettledRefreshEvidence({
+        store: options.diagnosticStore,
+        synchronization,
+        currentEvidenceRevision: options.currentEvidenceRevision,
+        pushQuietMs: options.pushQuietMs,
+        observedAt,
+      })
     ) {
       return { file, status: "confirmed" as const };
     }
@@ -96,6 +114,25 @@ export function buildDiagnosticRefreshEvidence(options: {
   return summarizeDiagnosticEvidence(documents);
 }
 
+/** Test whether fresh evidence can confirm this refresh result. */
+function hasSettledRefreshEvidence(options: {
+  store: ReadonlyMap<string, DiagnosticCacheEntry>;
+  synchronization: DiagnosticSynchronization;
+  currentEvidenceRevision: number;
+  pushQuietMs: number | undefined;
+  observedAt: number;
+}): boolean {
+  if (!hasFreshEvidence(options.store, options.synchronization, options.currentEvidenceRevision)) {
+    return false;
+  }
+  const entry = options.store.get(options.synchronization.uri);
+  return (
+    options.pushQuietMs === undefined ||
+    entry?.source !== "push" ||
+    options.observedAt - entry.receivedAt >= options.pushQuietMs
+  );
+}
+
 /** Pull one document and reject evidence from a stale client generation. */
 export function pullClientDiagnosticEvidence(
   options: Omit<DiagnosticPullRequest, "previousResultId"> & {
@@ -214,6 +251,70 @@ export async function pullDiagnosticsForOpenDocuments(options: {
   }
 }
 
+/**
+ * Classify open documents for a refresh by disk content.
+ *
+ * A document whose disk content still matches its open fingerprint stays in
+ * the server's current state:
+ * - with current evidence it is reusable without document synchronization;
+ * - without current evidence it is retained: it keeps its synchronization and
+ *   collection waits for the server's existing pipeline instead of forcing a
+ *   no-op didChange. Large push-only servers (typescript-language-server)
+ *   skip empty-to-empty publishes, so a no-op didChange of a clean file can
+ *   never confirm — it only invalidates in-progress evidence and restarts
+ *   full-program checks (#344).
+ *
+ * Documents outside the current evidence revision were invalidated by a
+ * workspace change and must resynchronize: their stale revision cannot
+ * produce fresh evidence without an explicit sync (ADR 0020).
+ */
+function classifyReusableDocuments(options: {
+  openDocuments: ReadonlyMap<string, OpenDocumentState>;
+  diagnosticStore: ReadonlyMap<string, DiagnosticCacheEntry>;
+  evidenceRevision: number;
+  failedFiles: ReadonlySet<string>;
+}): {
+  reusableUris: Set<string>;
+  retainedUris: Set<string>;
+  preloadedContent: Map<string, string>;
+} {
+  const reusableUris = new Set<string>();
+  const retainedUris = new Set<string>();
+  const preloadedContent = new Map<string, string>();
+  for (const [uri, document] of options.openDocuments) {
+    const filePath = uriToFile(uri);
+    if (options.failedFiles.has(filePath)) continue;
+    let content: string;
+    try {
+      content = readFileSync(filePath, "utf-8");
+    } catch {
+      // The resynchronization path classifies removed and unreadable files.
+      continue;
+    }
+    if (document.evidenceRevision !== options.evidenceRevision) {
+      // Invalidated generation: the resync didChange re-establishes proof.
+      preloadedContent.set(uri, content);
+      continue;
+    }
+    if (fingerprintDocumentContent(content) !== document.contentFingerprint) {
+      preloadedContent.set(uri, content);
+      continue;
+    }
+    if (
+      hasConfirmedDiagnosticEvidence(
+        document,
+        options.diagnosticStore.get(uri),
+        options.evidenceRevision,
+      )
+    ) {
+      reusableUris.add(uri);
+    } else {
+      retainedUris.add(uri);
+    }
+  }
+  return { reusableUris, retainedUris, preloadedContent };
+}
+
 interface ClientDiagnosticRefreshOptions {
   readonly host: ClientDiagnosticsHost;
   readonly openDocuments: Map<string, OpenDocumentState>;
@@ -229,7 +330,98 @@ interface ClientDiagnosticRefreshOptions {
   readonly invalidateEvidence: (uri: string) => void;
   readonly markUnversionedSyncMoment: (uri: string) => void;
   readonly clearFailedFile: (uri: string) => void;
+  /** Server-requested refreshes bypass normal push-only evidence reuse. */
+  readonly forceResynchronize?: boolean;
   readonly options: { maxWaitMs?: number; quietMs?: number } & CodeRequestControl;
+  /** Push-publication telemetry surface for this client. */
+  readonly publications: {
+    emitSummary(options: {
+      readonly operation: "refresh-open";
+      readonly identity: DiagnosticPublicationIdentity;
+      readonly synchronizations: readonly DiagnosticPublicationSynchronization[];
+      readonly operationId?: string;
+    }): void;
+  };
+}
+
+interface PreparedRefreshDocuments {
+  readonly resynchronization: ResynchronizeDocumentsResult;
+  readonly synchronizations: DiagnosticSynchronization[];
+  readonly fullyReusable: boolean;
+}
+
+/** Classify reusable documents, then resynchronize only the remaining set. */
+function prepareRefreshDocuments(
+  options: ClientDiagnosticRefreshOptions,
+  supportsPull: boolean,
+  evidenceRevision: number,
+): PreparedRefreshDocuments {
+  const reuseEnabled = !options.forceResynchronize;
+  const classification = reuseEnabled
+    ? classifyReusableDocuments({
+        openDocuments: options.openDocuments,
+        diagnosticStore: options.diagnosticStore,
+        evidenceRevision,
+        failedFiles: options.failedFiles(),
+      })
+    : undefined;
+  const reusableUris = classification?.reusableUris ?? new Set<string>();
+  const retainedUris = classification?.retainedUris ?? new Set<string>();
+  const documentsToResynchronize = new Map(
+    Array.from(options.openDocuments).filter(
+      ([uri]) => !reusableUris.has(uri) && !retainedUris.has(uri),
+    ),
+  );
+  const resynchronization = resynchronizeOpenDocuments({
+    openDocuments: documentsToResynchronize,
+    waiters: options.waiters,
+    nextVersion: (uri) => nextDocumentVersion(options.versionHistory, uri),
+    nextSynchronizationId: options.nextSynchronizationId,
+    evidenceRevision,
+    incrementalSync: options.host.usesIncrementalDocumentSync(),
+    sendNotification: (method, params) => options.host.sendNotification(method, params),
+    uriToFile,
+    preloadedContent: classification?.preloadedContent,
+    clearFile: options.clearFile,
+    invalidateEvidence: options.invalidateEvidence,
+    markUnversionedSyncMoment: options.markUnversionedSyncMoment,
+    clearFailedFile: options.clearFailedFile,
+  });
+  const reusableSynchronizations: DiagnosticSynchronization[] = [];
+  for (const uri of reusableUris) {
+    const document = options.openDocuments.get(uri);
+    if (!document) continue;
+    reusableSynchronizations.push({
+      uri,
+      synchronizationId: document.synchronizationId,
+      evidenceRevision: document.evidenceRevision,
+    });
+  }
+  // Retained documents keep their current synchronization: settle waits for
+  // the server's existing pipeline without any protocol work.
+  const retainedSynchronizations: DiagnosticSynchronization[] = [];
+  for (const uri of retainedUris) {
+    const document = options.openDocuments.get(uri);
+    if (!document) continue;
+    retainedSynchronizations.push({
+      uri,
+      synchronizationId: document.synchronizationId,
+      evidenceRevision: document.evidenceRevision,
+    });
+  }
+  const synchronizations = [
+    ...reusableSynchronizations,
+    ...retainedSynchronizations,
+    ...resynchronization.synchronizations,
+  ];
+  // Pull-capable routes still request current diagnostics even when every
+  // document synchronization is reusable.
+  const fullyReusable =
+    reuseEnabled &&
+    !supportsPull &&
+    options.openDocuments.size > 0 &&
+    reusableUris.size === options.openDocuments.size;
+  return { resynchronization, synchronizations, fullyReusable };
 }
 
 /** Refresh one client and return exact document evidence for that attempt. */
@@ -259,25 +451,11 @@ export async function refreshClientOpenDiagnostics(
   const maxWaitMs = options.options.maxWaitMs ?? 3_000;
   const quietMs = options.options.quietMs ?? 200;
   const syncStart = Date.now();
-  const resynchronization = resynchronizeOpenDocuments({
-    openDocuments: options.openDocuments,
-    waiters: options.waiters,
-    nextVersion: (uri) => nextDocumentVersion(options.versionHistory, uri),
-    nextSynchronizationId: options.nextSynchronizationId,
-    evidenceRevision: options.evidenceRevision(),
-    sendNotification: (method, params) => options.host.sendNotification(method, params),
-    uriToFile,
-    clearFile: options.clearFile,
-    invalidateEvidence: options.invalidateEvidence,
-    markUnversionedSyncMoment: options.markUnversionedSyncMoment,
-    clearFailedFile: options.clearFailedFile,
-  });
-  let synchronizations = resynchronization.synchronizations;
-  const settleEpoch = options.waiters.settleEpoch;
-  observer.synchronized();
-  const documentCount = synchronizations.length;
+  const prepared = prepareRefreshDocuments(options, supportsPull, options.evidenceRevision());
+  const resynchronization = prepared.resynchronization;
+  let synchronizations = prepared.synchronizations;
   let failedPullUris: ReadonlySet<string> = new Set();
-  const buildEvidence = () =>
+  const buildEvidence = (pushQuietMs?: number) =>
     buildDiagnosticRefreshEvidence({
       requestedFiles: options.requestedFiles,
       resynchronization,
@@ -288,8 +466,19 @@ export async function refreshClientOpenDiagnostics(
       currentEvidenceRevision: options.evidenceRevision(),
       openDocuments: options.openDocuments,
       diagnosticStore: options.diagnosticStore,
+      pushQuietMs,
     });
-  if (documentCount === 0) {
+
+  // A fully reusable push-only refresh has no protocol work to collect.
+  // Preserve the existing cache timing event format and return current evidence.
+  if (prepared.fullyReusable) {
+    observer.cacheReused(synchronizations.length);
+    return buildEvidence();
+  }
+
+  const settleEpoch = options.waiters.settleEpoch;
+  observer.synchronized();
+  if (synchronizations.length === 0) {
     observer.skipped(0);
     return buildEvidence();
   }
@@ -306,60 +495,64 @@ export async function refreshClientOpenDiagnostics(
     if (pull.completed) return buildEvidence();
   }
 
-  let finalSettle = await options.waiters.waitForSettle(
-    {
-      syncStart,
-      maxWaitMs,
-      quietMs,
-      settleEpoch,
-      isComplete: () =>
-        synchronizations.every((item) =>
-          hasFreshEvidence(options.diagnosticStore, item, options.evidenceRevision()),
-        ),
-      latestReceived: () =>
-        latestFreshEvidenceReceivedAt(
-          options.diagnosticStore,
-          synchronizations,
-          options.evidenceRevision(),
-        ),
-    },
-    options.options,
-  );
+  const waitForDiagnosticSettle = (settleStart: number, settleGeneration: number) =>
+    options.waiters.waitForSettle(
+      {
+        syncStart: settleStart,
+        maxWaitMs,
+        quietMs,
+        settleEpoch: settleGeneration,
+        isComplete: () =>
+          synchronizations.every((item) =>
+            hasFreshEvidence(options.diagnosticStore, item, options.evidenceRevision()),
+          ),
+        latestReceived: () =>
+          latestCurrentEvidenceReceivedAt(
+            options.diagnosticStore,
+            synchronizations,
+            options.evidenceRevision(),
+          ),
+      },
+      options.options,
+    );
+
+  let finalSettle = await waitForDiagnosticSettle(syncStart, settleEpoch);
   if (!supportsPull && finalSettle.outcome === "timed-out") {
     const reopen = await reopenUnconfirmedDocuments({
       options,
       synchronizations,
-      maxWaitMs,
-      quietMs,
+      reopenCandidates: resynchronization.resynchronizedUris,
       observer,
     });
     if (reopen.performed) {
       synchronizations = reopen.synchronizations;
-      finalSettle = await options.waiters.waitForSettle(
-        {
-          syncStart: reopen.startedAt,
-          maxWaitMs: reopen.budgetMs,
-          quietMs,
-          settleEpoch: options.waiters.settleEpoch,
-          isComplete: () =>
-            synchronizations.every((item) =>
-              hasFreshEvidence(options.diagnosticStore, item, options.evidenceRevision()),
-            ),
-          latestReceived: () =>
-            latestFreshEvidenceReceivedAt(
-              options.diagnosticStore,
-              synchronizations,
-              options.evidenceRevision(),
-            ),
-        },
-        options.options,
-      );
+      // A large push-only project may still be processing the reopen batch.
+      // The replacement pass uses the same collection budget as the initial pass.
+      finalSettle = await waitForDiagnosticSettle(reopen.startedAt, options.waiters.settleEpoch);
     }
   }
-  observer.pushSettled(documentCount, finalSettle);
+  observer.pushSettled(synchronizations.length, finalSettle);
   // A cancelled settle must not publish evidence the caller no longer awaits.
   throwIfCodeRequestInterrupted(options.options);
-  return buildEvidence();
+  options.publications.emitSummary({
+    operation: "refresh-open",
+    identity: {
+      server: options.host.server,
+      cwd: options.host.cwd,
+    },
+    synchronizations: synchronizations.map((synchronization) => ({
+      uri: synchronization.uri,
+      synchronizationId: synchronization.synchronizationId,
+      evidenceRevision: synchronization.evidenceRevision ?? options.evidenceRevision(),
+      confirmed: hasFreshEvidence(
+        options.diagnosticStore,
+        synchronization,
+        options.evidenceRevision(),
+      ),
+    })),
+    operationId: options.options.operationId,
+  });
+  return buildEvidence(quietMs);
 }
 
 /**
@@ -420,31 +613,38 @@ async function collectPullEvidenceForRefresh(options: {
 }
 
 /**
- * Reopen-resync fallback (R2): on push-only routes an open document that
-
- * stays unconfirmed after the settle window receives no further push — a
- * clean file gets no push on didChange at all. Close and reopen each
- * unconfirmed document so the server publishes on didOpen, then settle
- * again within a bounded second window. The cache entry and version
- * history survive the reopen; other documents keep their server state.
+ * Reopen-resync fallback (R2): on push-only routes a document that was
+ * didChange-synchronized and stays unconfirmed after the settle window may
+ * have been skipped by the server — a clean file gets no push on didChange
+ * at all, but the server publishes on didOpen. Close and reopen each such
+ * document so the server publishes, then settle again within a bounded
+ * second window. The cache entry and version history survive the reopen;
+ * other documents keep their server state.
+ *
+ * Only documents this pass resynchronized are candidates: retained documents
+ * wait for the server's existing pipeline, and reopening them would cancel
+ * in-progress server work without fixing any publish gap (#344).
  */
 async function reopenUnconfirmedDocuments(options: {
   options: ClientDiagnosticRefreshOptions;
   synchronizations: readonly DiagnosticSynchronization[];
-  maxWaitMs: number;
-  quietMs: number;
+  /** URIs that received a didChange in this pass and may need a reopen push. */
+  reopenCandidates: ReadonlySet<string>;
   observer: DiagnosticObserver;
 }): Promise<{
   performed: boolean;
   startedAt: number;
-  budgetMs: number;
   synchronizations: DiagnosticSynchronization[];
 }> {
-  const { options: refresh, synchronizations, maxWaitMs, quietMs, observer } = options;
+  const { options: refresh, synchronizations, reopenCandidates, observer } = options;
   const startedAt = Date.now();
-  const budgetMs = Math.min(maxWaitMs, quietMs * 4);
   const unconfirmed = synchronizations.filter(
-    (item) => !hasFreshEvidence(refresh.diagnosticStore, item, refresh.evidenceRevision()),
+    (item) =>
+      reopenCandidates.has(item.uri) &&
+      // A document with any current publication — tentative included — is
+      // not a reopen candidate: its server pipeline is alive and a republish
+      // can still promote the retained cache (ADR 0021).
+      !hasCurrentEvidence(refresh.diagnosticStore, item, refresh.evidenceRevision()),
   );
   const reopenedSynchronizations: DiagnosticSynchronization[] = [];
   for (const item of unconfirmed) {
@@ -478,14 +678,13 @@ async function reopenUnconfirmedDocuments(options: {
     });
   }
   if (reopenedSynchronizations.length === 0) {
-    return { performed: false, startedAt, budgetMs, synchronizations: [...synchronizations] };
+    return { performed: false, startedAt, synchronizations: [...synchronizations] };
   }
   observer.reopened(reopenedSynchronizations.length);
   const reopenedByUri = new Map(reopenedSynchronizations.map((item) => [item.uri, item]));
   return {
     performed: true,
     startedAt,
-    budgetMs,
     synchronizations: synchronizations.map((item) => reopenedByUri.get(item.uri) ?? item),
   };
 }

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

@@ -6,8 +6,20 @@ type DiagnosticCollection = "cache" | "fallback" | "none" | "pull" | "push";
 type DiagnosticFreshness = "not-observed" | "observed";
 type DiagnosticOutcome = "completed" | "incomplete" | "skipped" | "timed-out";
 type DiagnosticPullOutcome = "completed" | "failed" | "not-supported" | "not-used" | "timed-out";
-type DiagnosticPushOutcome = "not-used" | "published" | "released" | "settled" | "timed-out";
-type DiagnosticSettleOutcome = "not-used" | "published" | "quiet" | "released" | "timed-out";
+type DiagnosticPushOutcome =
+  | "not-used"
+  | "published"
+  | "tentative"
+  | "released"
+  | "settled"
+  | "timed-out";
+type DiagnosticSettleOutcome =
+  | "not-used"
+  | "published"
+  | "tentative"
+  | "quiet"
+  | "released"
+  | "timed-out";
 type DiagnosticTimingOperation = "refresh-open" | "sync-file";
 
 /** Result of waiting for a quiet push-diagnostic window. */
@@ -17,7 +29,7 @@ export interface DiagnosticSettleResult {
 }
 
 /** Result of waiting for one file's push diagnostics. */
-export type DiagnosticPushWaitOutcome = "published" | "released" | "timed-out";
+export type DiagnosticPushWaitOutcome = "published" | "tentative" | "released" | "timed-out";
 
 interface DiagnosticTimingData {
   readonly collection: DiagnosticCollection;
@@ -134,10 +146,15 @@ export class DiagnosticObserver {
     this.#timer.mark("pull");
   }
 
-  /** Record that the reopen-resync fallback re-opened unconfirmed documents. */
+  /**
+   * Record that the reopen-resync fallback re-opened unconfirmed documents.
+   *
+   * The mark fires when the second settle window starts, so the measured
+   * phase is the preceding first settle window, not the reopen work.
+   */
   reopened(count: number): void {
     this.#reopened += count;
-    this.#timer.mark("reopen");
+    this.#timer.mark("first-settle");
   }
 
   pushSettled(documentCount: number, settle: DiagnosticSettleResult): void {
@@ -161,14 +178,18 @@ export class DiagnosticObserver {
   }
 
   pushWaitCompleted(documentCount: number, push: DiagnosticPushWaitOutcome): void {
-    const timedOut = push === "timed-out";
+    const confirmed = push === "published";
+    // A tentative result used the full wait budget without a confirming
+    // republish. Keep its distinct push value and report the budget expiry.
+    const timedOut = push === "tentative" || push === "timed-out";
+    const observed = push === "published" || push === "tentative";
     this.#finish(
       {
         collection: this.supportsPull ? "fallback" : "push",
         documentCount,
         fallback: this.supportsPull,
-        freshness: push === "published" ? "observed" : "not-observed",
-        outcome: push === "published" ? "completed" : timedOut ? "timed-out" : "incomplete",
+        freshness: observed ? "observed" : "not-observed",
+        outcome: confirmed ? "completed" : timedOut ? "timed-out" : "incomplete",
         pull: this.#pull,
         push,
         reopen: this.#reopened,