@mrclrchtr/supi-code-intelligence 4.9.0 → 5.0.0

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

@@ -0,0 +1,215 @@
+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 = "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 DiagnosticTimingOperation = "refresh-open" | "sync-file";
+
+/** Result of waiting for a quiet push-diagnostic window. */
+export interface DiagnosticSettleResult {
+  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";
+
+interface DiagnosticTimingData {
+  readonly collection: DiagnosticCollection;
+  readonly documentCount: number;
+  readonly fallback: boolean;
+  readonly freshness: DiagnosticFreshness;
+  readonly outcome: DiagnosticOutcome;
+  readonly pull: DiagnosticPullOutcome;
+  readonly push: DiagnosticPushOutcome;
+  readonly reopen: number;
+  readonly settle: DiagnosticSettleOutcome;
+  readonly timedOut: boolean;
+}
+
+/** Internal pull failure that retains timeout state and failed document URIs. */
+export class DiagnosticPullError extends Error {
+  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 diagnostic text or document content.
+ *
+ * The observer owns result classification so diagnostic control flow does not
+ * 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";
+  }
+
+  synchronized(): void {
+    this.#timer.mark("synchronize");
+  }
+
+  skipped(documentCount: number): void {
+    this.#finish({
+      collection: "none",
+      documentCount,
+      fallback: false,
+      freshness: "not-observed",
+      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,
+    });
+  }
+
+  pullCompleted(documentCount: number): void {
+    this.#finish(
+      {
+        collection: "pull",
+        documentCount,
+        fallback: false,
+        freshness: "observed",
+        outcome: "completed",
+        pull: "completed",
+        push: "not-used",
+        reopen: 0,
+        settle: "not-used",
+        timedOut: false,
+      },
+      "pull",
+    );
+  }
+
+  pullFailed(error: unknown): void {
+    this.#pull = isDiagnosticTimeout(error) ? "timed-out" : "failed";
+    this.#timer.mark("pull");
+  }
+
+  pullTimedOut(): void {
+    this.#pull = "timed-out";
+    this.#timer.mark("pull");
+  }
+
+  /** Record that the reopen-resync fallback re-opened unconfirmed documents. */
+  reopened(count: number): void {
+    this.#reopened += count;
+    this.#timer.mark("reopen");
+  }
+
+  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: completed ? "completed" : timedOut ? "timed-out" : "incomplete",
+        pull: this.#pull,
+        push: timedOut ? "timed-out" : settle.outcome === "released" ? "released" : "settled",
+        reopen: this.#reopened,
+        settle: settle.outcome,
+        timedOut: timedOut || this.#pull === "timed-out",
+      },
+      "push-settle",
+    );
+  }
+
+  pushWaitCompleted(documentCount: number, push: DiagnosticPushWaitOutcome): void {
+    const timedOut = push === "timed-out";
+    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",
+        pull: this.#pull,
+        push,
+        reopen: this.#reopened,
+        settle: push,
+        timedOut: timedOut || this.#pull === "timed-out",
+      },
+      "push-settle",
+    );
+  }
+
+  #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}`,
+        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,
+    );
+  }
+}
+
+/** Return whether a diagnostic failure represents a timeout without retaining its message. */
+export function isDiagnosticTimeout(error: unknown): boolean {
+  if (error instanceof DiagnosticPullError) return error.timedOut;
+  return error instanceof Error && /\btimed? ?out\b|\btimeout\b/i.test(error.message);
+}

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);
+  }
+}