@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

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

@@ -1,21 +1,35 @@
+import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { startDebugTimer } from "@mrclrchtr/supi-core/debug";
+import { boundCwd, truncateIdentity } from "../debug-telemetry.ts";
 
-type DiagnosticCollection = "fallback" | "none" | "pull" | "push";
+type DiagnosticCollection = "cache" | "fallback" | "none" | "pull" | "push";
 type DiagnosticFreshness = "not-observed" | "observed";
-type DiagnosticOutcome = "completed" | "skipped" | "timed-out";
+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. */
 export interface DiagnosticSettleResult {
-  readonly outcome: "quiet" | "timed-out";
+  readonly outcome: "quiet" | "released" | "timed-out";
   readonly freshness: DiagnosticFreshness;
 }
 
 /** 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;
@@ -25,30 +39,47 @@ interface DiagnosticTimingData {
   readonly outcome: DiagnosticOutcome;
   readonly pull: DiagnosticPullOutcome;
   readonly push: DiagnosticPushOutcome;
+  readonly reopen: number;
   readonly settle: DiagnosticSettleOutcome;
   readonly timedOut: boolean;
 }
 
-/** Internal pull failure that retains only whether a timeout occurred. */
+/** Internal pull failure that retains timeout state and failed document URIs. */
 export class DiagnosticPullError extends Error {
-  constructor(readonly timedOut: boolean) {
+  constructor(
+    readonly timedOut: boolean,
+    readonly failedUris: readonly string[] = [],
+  ) {
     super("pull diagnostics incomplete");
   }
 }
 
+/** Bounded identity for one diagnostic timing observation. */
+export interface DiagnosticTimingIdentity {
+  /** Configured server name. */
+  readonly server?: string;
+  /** Absolute workspace root. */
+  readonly cwd?: string;
+  /** Workspace-relative file path; sync-file operations only. */
+  readonly file?: string;
+}
+
 /**
- * Record one diagnostic operation without document identifiers or diagnostic text.
+ * Record one diagnostic operation without diagnostic text or document content.
  *
  * The observer owns result classification so diagnostic control flow does not
- * duplicate the event shape.
+ * duplicate the event shape. Identity is bounded and workspace-relative.
  */
 export class DiagnosticObserver {
   readonly #timer = startDebugTimer();
   #pull: "failed" | "not-supported" | "timed-out";
+  #reopened = 0;
 
   constructor(
     readonly operation: DiagnosticTimingOperation,
     readonly supportsPull: boolean,
+    readonly control?: CodeRequestControl,
+    readonly identity?: DiagnosticTimingIdentity,
   ) {
     this.#pull = supportsPull ? "failed" : "not-supported";
   }
@@ -66,6 +97,22 @@ export class DiagnosticObserver {
       outcome: "skipped",
       pull: "not-used",
       push: "not-used",
+      reopen: 0,
+      settle: "not-used",
+      timedOut: false,
+    });
+  }
+
+  cacheReused(documentCount: number): void {
+    this.#finish({
+      collection: "cache",
+      documentCount,
+      fallback: false,
+      freshness: "observed",
+      outcome: "completed",
+      pull: "not-used",
+      push: "not-used",
+      reopen: 0,
       settle: "not-used",
       timedOut: false,
     });
@@ -81,6 +128,7 @@ export class DiagnosticObserver {
         outcome: "completed",
         pull: "completed",
         push: "not-used",
+        reopen: 0,
         settle: "not-used",
         timedOut: false,
       },
@@ -98,17 +146,30 @@ export class DiagnosticObserver {
     this.#timer.mark("pull");
   }
 
+  /**
+   * 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("first-settle");
+  }
+
   pushSettled(documentCount: number, settle: DiagnosticSettleResult): void {
     const timedOut = settle.outcome === "timed-out";
+    const completed = settle.outcome === "quiet" && settle.freshness === "observed";
     this.#finish(
       {
         collection: this.supportsPull ? "fallback" : "push",
         documentCount,
         fallback: this.supportsPull,
         freshness: settle.freshness,
-        outcome: timedOut ? "timed-out" : "completed",
+        outcome: completed ? "completed" : timedOut ? "timed-out" : "incomplete",
         pull: this.#pull,
-        push: timedOut ? "timed-out" : "settled",
+        push: timedOut ? "timed-out" : settle.outcome === "released" ? "released" : "settled",
+        reopen: this.#reopened,
         settle: settle.outcome,
         timedOut: timedOut || this.#pull === "timed-out",
       },
@@ -117,16 +178,21 @@ 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: timedOut ? "timed-out" : "completed",
+        freshness: observed ? "observed" : "not-observed",
+        outcome: confirmed ? "completed" : timedOut ? "timed-out" : "incomplete",
         pull: this.#pull,
         push,
+        reopen: this.#reopened,
         settle: push,
         timedOut: timedOut || this.#pull === "timed-out",
       },
@@ -135,13 +201,28 @@ export class DiagnosticObserver {
   }
 
   #finish(data: DiagnosticTimingData, finalPhase?: "pull" | "push-settle" | "synchronize"): void {
+    const { reopen, ...observation } = data;
     this.#timer.finish(
       () => ({
+        operationId: this.control?.operationId,
         source: "lsp",
         level: "debug",
         category: "diagnostics.timing",
         message: `LSP diagnostic ${this.operation} ${data.outcome}`,
-        data: { operation: this.operation, ...data },
+        cwd: boundCwd(this.identity?.cwd),
+        data: {
+          operation: this.operation,
+          ...observation,
+          // Reopen fallback usage is recorded only when it happened; the
+          // default event shape stays stable for consumers of #322 telemetry.
+          ...(reopen > 0 ? { reopen } : {}),
+          ...(this.identity?.server !== undefined
+            ? { server: truncateIdentity(this.identity.server) }
+            : {}),
+          ...(this.identity?.file !== undefined
+            ? { file: truncateIdentity(this.identity.file) }
+            : {}),
+        },
       }),
       finalPhase,
     );

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

@@ -0,0 +1,206 @@
+import {
+  type CodeRequestControl,
+  CodeRequestDeadlineError,
+  throwIfCodeRequestInterrupted,
+} from "@mrclrchtr/supi-code-runtime/api";
+import type {
+  DiagnosticPushWaitOutcome,
+  DiagnosticSettleResult,
+} from "./client-diagnostic-timing.ts";
+
+type DiagnosticWaiter = (outcome: "published" | "released") => void;
+
+/** One cancellable wait for diagnostic state change. */
+export interface DiagnosticStateWait {
+  readonly promise: Promise<void>;
+  cancel(): void;
+}
+
+interface DiagnosticSettleOptions {
+  readonly syncStart: number;
+  readonly maxWaitMs: number;
+  readonly quietMs: number;
+  readonly settleEpoch: number;
+  readonly isComplete: () => boolean;
+  readonly latestReceived: () => number;
+}
+
+/** Own diagnostic waiters and their timers for one LSP client. */
+export class DiagnosticWaitRegistry {
+  readonly #pushWaiters = new Map<string, DiagnosticWaiter[]>();
+  readonly #stateWaiters = new Set<() => void>();
+  readonly #settleWaiters = new Set<() => void>();
+  #settleEpoch = 0;
+
+  get settleEpoch(): number {
+    return this.#settleEpoch;
+  }
+
+  /** Wait for a diagnostic publication or a lifecycle release for one URI. */
+  waitForPush(
+    uri: string,
+    timeoutMs: number,
+    control?: CodeRequestControl,
+  ): Promise<DiagnosticPushWaitOutcome> {
+    const deadlineRemaining =
+      control?.deadline === undefined ? undefined : control.deadline - Date.now();
+    const bindMs =
+      deadlineRemaining === undefined ? timeoutMs : Math.min(timeoutMs, deadlineRemaining);
+    if (control?.signal?.aborted) {
+      return Promise.reject(control.signal.reason ?? new Error("Diagnostic push wait cancelled"));
+    }
+    if (bindMs <= 0) {
+      if (deadlineRemaining !== undefined && deadlineRemaining < timeoutMs) {
+        return Promise.reject(new CodeRequestDeadlineError());
+      }
+      return Promise.resolve("timed-out");
+    }
+
+    return new Promise<DiagnosticPushWaitOutcome>((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timer);
+        if (abortHandler) control?.signal?.removeEventListener("abort", abortHandler);
+      };
+      const waiter: DiagnosticWaiter = (outcome) => {
+        cleanup();
+        this.#removePushWaiter(uri, waiter);
+        resolve(outcome);
+      };
+      const timer = setTimeout(() => {
+        this.#removePushWaiter(uri, waiter);
+        cleanup();
+        if (deadlineRemaining !== undefined && deadlineRemaining < timeoutMs) {
+          reject(new CodeRequestDeadlineError());
+        } else {
+          resolve("timed-out");
+        }
+      }, bindMs);
+      let abortHandler: (() => void) | undefined;
+      abortHandler = () => {
+        cleanup();
+        this.#removePushWaiter(uri, waiter);
+        reject(control?.signal?.reason ?? new Error("Diagnostic push wait cancelled"));
+      };
+      if (control?.signal?.aborted) abortHandler();
+      else control?.signal?.addEventListener("abort", abortHandler, { once: true });
+      const waiters = this.#pushWaiters.get(uri) ?? [];
+      waiters.push(waiter);
+      this.#pushWaiters.set(uri, waiters);
+    });
+  }
+
+  /** Wait until any diagnostic or lifecycle state changes. */
+  waitForChange(): DiagnosticStateWait {
+    let finish = () => {};
+    const promise = new Promise<void>((resolve) => {
+      finish = () => {
+        this.#stateWaiters.delete(finish);
+        resolve();
+      };
+      this.#stateWaiters.add(finish);
+    });
+    return { promise, cancel: finish };
+  }
+
+  /** Release pending push waiters for one URI. */
+  releaseFile(uri: string, outcome: "published" | "released" = "released"): void {
+    const waiters = this.#pushWaiters.get(uri);
+    if (waiters) {
+      this.#pushWaiters.delete(uri);
+      for (const waiter of waiters) waiter(outcome);
+    }
+    this.#notifyStateWaiters();
+  }
+
+  /** Release all pending push waiters. */
+  releaseAll(): void {
+    for (const uri of Array.from(this.#pushWaiters.keys())) this.releaseFile(uri);
+  }
+
+  /** Cancel the active settle generation and release its timers. */
+  cancelSettle(): void {
+    this.#settleEpoch++;
+    this.notifySettle();
+  }
+
+  /** Notify settle operations that diagnostic state changed. */
+  notifySettle(): void {
+    for (const release of Array.from(this.#settleWaiters)) release();
+    this.#notifyStateWaiters();
+  }
+
+  /** Wait for fresh diagnostic state to become quiet or reach its deadline. */
+  async waitForSettle(
+    options: DiagnosticSettleOptions,
+    control?: CodeRequestControl,
+  ): Promise<DiagnosticSettleResult> {
+    const { syncStart, maxWaitMs, quietMs, settleEpoch, isComplete, latestReceived } = options;
+    const deadlineRemaining =
+      control?.deadline === undefined ? undefined : control.deadline - Date.now();
+    const deadline =
+      deadlineRemaining === undefined
+        ? syncStart + maxWaitMs
+        : Math.min(syncStart + maxWaitMs, control?.deadline ?? syncStart + maxWaitMs);
+    while (Date.now() < deadline) {
+      throwIfCodeRequestInterrupted(control);
+      if (this.#settleEpoch !== settleEpoch) {
+        return { outcome: "released", freshness: "not-observed" };
+      }
+      const observedAt = latestReceived();
+      const elapsed = Date.now() - observedAt;
+      const complete = isComplete();
+      if (observedAt > 0 && complete && elapsed >= quietMs) {
+        return { outcome: "quiet", freshness: "observed" };
+      }
+      const waitMs =
+        observedAt > 0 && complete
+          ? Math.min(quietMs - elapsed, deadline - Date.now())
+          : deadline - Date.now();
+      await this.#waitForStateChange(waitMs, control);
+    }
+    // A bound absolute deadline makes the settle outcome a deadline
+    // interruption instead of an ordinary relative timeout.
+    throwIfCodeRequestInterrupted(control);
+    return {
+      outcome: "timed-out",
+      freshness: latestReceived() > 0 ? "observed" : "not-observed",
+    };
+  }
+
+  /** Wait until diagnostic state changes or the timeout expires. */
+  #waitForStateChange(timeoutMs: number, control?: CodeRequestControl): Promise<void> {
+    if (timeoutMs <= 0) return Promise.resolve();
+    if (control?.signal?.aborted) {
+      return Promise.reject(control.signal.reason ?? new Error("Settle wait cancelled"));
+    }
+    return new Promise((resolve, reject) => {
+      let abortHandler: (() => void) | undefined;
+      const finish = () => {
+        clearTimeout(timer);
+        if (abortHandler) control?.signal?.removeEventListener("abort", abortHandler);
+        this.#settleWaiters.delete(finish);
+        resolve();
+      };
+      const timer = setTimeout(finish, timeoutMs);
+      abortHandler = () => {
+        clearTimeout(timer);
+        this.#settleWaiters.delete(finish);
+        reject(control?.signal?.reason ?? new Error("Settle wait cancelled"));
+      };
+      control?.signal?.addEventListener("abort", abortHandler, { once: true });
+      this.#settleWaiters.add(finish);
+    });
+  }
+
+  #notifyStateWaiters(): void {
+    for (const release of Array.from(this.#stateWaiters)) release();
+  }
+
+  #removePushWaiter(uri: string, waiter: DiagnosticWaiter): void {
+    const waiters = this.#pushWaiters.get(uri);
+    if (!waiters) return;
+    const next = waiters.filter((entry) => entry !== waiter);
+    if (next.length > 0) this.#pushWaiters.set(uri, next);
+    else this.#pushWaiters.delete(uri);
+  }
+}