@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

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

@@ -0,0 +1,245 @@
+import type { PublishDiagnosticsParams } from "../config/types.ts";
+import { uriToFile } from "../utils.ts";
+import {
+  type DiagnosticCacheEntry,
+  isTentativePushEntry,
+  isValidPublishDiagnosticsParams,
+} from "./client-diagnostic-evidence.ts";
+import type { ClientDiagnosticSnapshot, OpenDocumentState } from "./client-document-state.ts";
+import { hasCurrentDiagnosticEvidence } from "./client-document-state.ts";
+import { getDiagnosticFileState } from "./client-file-state.ts";
+
+interface ApplyPushOptions {
+  store: Map<string, DiagnosticCacheEntry>;
+  openDocuments: ReadonlyMap<string, OpenDocumentState>;
+  params: PublishDiagnosticsParams;
+  evidenceRevision: number;
+  /** Client-side sync moment for the URI, or undefined when never synchronized. */
+  unversionedSyncMoment: number | undefined;
+  /** Whether a lifecycle close marked this URI fail-closed for versioned pushes. */
+  closedVersionedBarrier: boolean;
+}
+
+/**
+ * Apply one valid push publication.
+ *
+ * Returns whether the publication was accepted and whether it promoted a
+ * tentative entry to confirmed. Fail-closed policy (ADR 0020): unversioned
+ * pushes are rejected for closed and untracked URIs and for arrivals before
+ * the URI's sync moment; versioned pushes for a URI closed by a lifecycle
+ * operation are rejected because their version cannot be verified. An
+ * unversioned push that arrives after the sync moment of an open document
+ * is accepted and re-stamped with that document's current synchronization
+ * state. The first valid publication for a synchronization is tentative; a
+ * later valid publication for the same synchronization ID and evidence
+ * revision promotes the cache to confirmed (ADR 0021).
+ */
+export function applyPushDiagnostics(options: ApplyPushOptions): {
+  accepted: boolean;
+  promoted: boolean;
+} {
+  if (!isValidPublishDiagnosticsParams(options.params)) return { accepted: false, promoted: false };
+  const openDocument = options.openDocuments.get(options.params.uri);
+  if (options.params.version !== undefined) {
+    if (!Number.isInteger(options.params.version)) return { accepted: false, promoted: false };
+    if (openDocument && options.params.version !== openDocument.version) {
+      return { accepted: false, promoted: false };
+    }
+    if (!openDocument && options.closedVersionedBarrier)
+      return { accepted: false, promoted: false };
+  }
+  if (!Array.isArray(options.params.diagnostics)) return { accepted: false, promoted: false };
+  if (!acceptUnversionedPush(options, openDocument)) return { accepted: false, promoted: false };
+  const entry = buildPushCacheEntry(options, openDocument);
+  const previous = options.store.get(options.params.uri);
+  const promoted =
+    entry.source === "push" &&
+    entry.publications !== undefined &&
+    entry.publications >= 2 &&
+    isTentativePushEntry(previous);
+  options.store.set(options.params.uri, entry);
+  return { accepted: true, promoted };
+}
+
+/** Gate one unversioned push publication against the sync-moment policy. */
+function acceptUnversionedPush(
+  options: ApplyPushOptions,
+  openDocument: OpenDocumentState | undefined,
+): boolean {
+  if (options.params.version !== undefined) return true;
+  if (!openDocument) return false;
+  return !(
+    options.unversionedSyncMoment !== undefined && Date.now() < options.unversionedSyncMoment
+  );
+}
+
+/**
+ * Build the stored entry for one accepted push publication.
+ *
+ * Time-gated unversioned acceptance re-stamps the entry with the open
+ * document's current synchronization state, so the push proves that
+ * document's synchronization. Versioned pushes keep the current-revision
+ * check: a version match alone does not prove a current generation.
+ */
+function buildPushCacheEntry(
+  options: ApplyPushOptions,
+  openDocument: OpenDocumentState | undefined,
+): DiagnosticCacheEntry {
+  const currentRevision = openDocument?.evidenceRevision === options.evidenceRevision;
+  const unversioned = options.params.version === undefined && openDocument !== undefined;
+  const synchronizationId =
+    unversioned || currentRevision ? openDocument?.synchronizationId : undefined;
+  const evidenceRevision = openDocument?.evidenceRevision;
+  const previous = options.store.get(options.params.uri);
+  // A later valid publication for the same synchronization ID and evidence
+  // revision continues the entry's publication count: a confirmed pull
+  // entry keeps the synchronization confirmed, and a tentative push entry
+  // is promoted. Any other publication starts a fresh count.
+  const sameSynchronization =
+    synchronizationId !== undefined &&
+    previous?.synchronizationId === synchronizationId &&
+    previous.evidenceRevision === evidenceRevision;
+  const publications = sameSynchronization ? Math.min((previous.publications ?? 1) + 1, 2) : 1;
+  return {
+    diagnostics: options.params.diagnostics,
+    receivedAt: Date.now(),
+    source: "push",
+    synchronizationId,
+    evidenceRevision,
+    version: options.params.version,
+    publications,
+  };
+}
+
+/** Build one client snapshot without dropping empty-cache freshness. */
+export function buildClientDiagnosticSnapshot(options: {
+  store: ReadonlyMap<string, DiagnosticCacheEntry>;
+  openDocuments: ReadonlyMap<string, OpenDocumentState>;
+  failedDocuments: ReadonlySet<string>;
+  evidenceRevision: number;
+}): ClientDiagnosticSnapshot {
+  const documents = collectDocumentFreshness(options);
+  const cache = collectCachedDiagnostics(options);
+  return {
+    entries: cache.entries,
+    documents,
+    current: cache.current && documents.every((document) => document.current),
+  };
+}
+
+function collectDocumentFreshness(options: {
+  openDocuments: ReadonlyMap<string, OpenDocumentState>;
+  failedDocuments: ReadonlySet<string>;
+  store: ReadonlyMap<string, DiagnosticCacheEntry>;
+  evidenceRevision: number;
+}): ClientDiagnosticSnapshot["documents"] {
+  const open = collectOpenDocumentFreshness(options);
+  return [
+    ...open.documents,
+    ...collectFailedDocumentFreshness(options.failedDocuments, open.uris),
+    ...collectUntrackedCacheFreshness(options.store, open.uris, options.failedDocuments),
+  ];
+}
+
+function collectOpenDocumentFreshness(options: {
+  openDocuments: ReadonlyMap<string, OpenDocumentState>;
+  failedDocuments: ReadonlySet<string>;
+  store: ReadonlyMap<string, DiagnosticCacheEntry>;
+  evidenceRevision: number;
+}): { documents: ClientDiagnosticSnapshot["documents"]; uris: ReadonlySet<string> } {
+  const documents: ClientDiagnosticSnapshot["documents"] = [];
+  const uris = new Set<string>();
+  for (const [uri, document] of options.openDocuments) {
+    uris.add(uri);
+    const entry = options.store.get(uri);
+    const fileState = getDiagnosticFileState(uriToFile(uri));
+    const current = hasCurrentDiagnosticEvidence(document, entry, options.evidenceRevision);
+    const failed = options.failedDocuments.has(uri);
+    // A current tentative push maps to unconfirmed, not to a new public
+    // status: it matches the synchronization but cannot confirm it yet, so
+    // it must not claim current snapshot or document state (issue #351).
+    const tentative = current && isTentativePushEntry(entry);
+    documents.push({
+      uri,
+      current: fileState === "present" && current && !failed && !tentative,
+      status: statusForDocument(fileState, current, failed, tentative),
+    });
+  }
+  return { documents, uris };
+}
+
+function collectFailedDocumentFreshness(
+  failedDocuments: ReadonlySet<string>,
+  openUris: ReadonlySet<string>,
+): ClientDiagnosticSnapshot["documents"] {
+  return Array.from(failedDocuments)
+    .filter((uri) => !openUris.has(uri))
+    .map((uri) => ({
+      uri,
+      current: false,
+      status:
+        getDiagnosticFileState(uriToFile(uri)) === "removed"
+          ? ("removed" as const)
+          : ("failed" as const),
+    }));
+}
+
+function collectUntrackedCacheFreshness(
+  store: ReadonlyMap<string, DiagnosticCacheEntry>,
+  openUris: ReadonlySet<string>,
+  failedDocuments: ReadonlySet<string>,
+): ClientDiagnosticSnapshot["documents"] {
+  return Array.from(store.keys())
+    .filter((uri) => !openUris.has(uri) && !failedDocuments.has(uri))
+    .map((uri) => ({
+      uri,
+      current: false,
+      status:
+        getDiagnosticFileState(uriToFile(uri)) === "removed"
+          ? ("removed" as const)
+          : getDiagnosticFileState(uriToFile(uri)) === "unreadable"
+            ? ("failed" as const)
+            : ("unconfirmed" as const),
+    }));
+}
+
+function statusForDocument(
+  fileState: ReturnType<typeof getDiagnosticFileState>,
+  current: boolean,
+  failed: boolean,
+  tentative: boolean,
+): "confirmed" | "unconfirmed" | "failed" | "removed" {
+  if (fileState === "removed") return "removed";
+  if (fileState === "unreadable" || failed) return "failed";
+  if (tentative || !current) return "unconfirmed";
+  return "confirmed";
+}
+
+function collectCachedDiagnostics(options: {
+  store: ReadonlyMap<string, DiagnosticCacheEntry>;
+  openDocuments: ReadonlyMap<string, OpenDocumentState>;
+  evidenceRevision: number;
+}): {
+  entries: ClientDiagnosticSnapshot["entries"];
+  current: boolean;
+} {
+  const entries: ClientDiagnosticSnapshot["entries"] = [];
+  let current = true;
+  for (const [uri, entry] of options.store) {
+    if (getDiagnosticFileState(uriToFile(uri)) === "removed") continue;
+    const entryCurrent = hasCurrentDiagnosticEvidence(
+      options.openDocuments.get(uri),
+      entry,
+      options.evidenceRevision,
+    );
+    // A current tentative error is useful partial evidence. Keep its entry
+    // non-current so it cannot establish a clean or settled result (ADR 0021).
+    const tentative = entryCurrent && isTentativePushEntry(entry);
+    const confirmed = entryCurrent && !tentative;
+    current &&= confirmed;
+    if (entry.diagnostics.length > 0) {
+      entries.push({ uri, diagnostics: entry.diagnostics, current: confirmed });
+    }
+  }
+  return { entries, current };
+}

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

@@ -0,0 +1,78 @@
+// Client-side diagnostic capability state — static (initialize result) and
+// dynamic (client/registerCapability) tracking with fail-closed validation.
+//
+// Static state lives on the client's initialize-result capabilities; dynamic
+// state lives in the per-instance `ClientDynamicRegistrations` below. Pull
+// support is enabled only while the static provider shape is valid or the
+// dynamic set for `textDocument/diagnostic` is non-empty.
+
+/** LSP method for document diagnostic pulls. */
+export const DOCUMENT_DIAGNOSTIC_METHOD = "textDocument/diagnostic";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validate one untrusted `DiagnosticOptions` / `DiagnosticRegistrationOptions`
+ * value from a static initialize result or a dynamic registration.
+ *
+ * Required per the LSP specification: boolean `interFileDependencies` and
+ * `workspaceDiagnostics`. Optional: string `identifier`, and `documentSelector`
+ * (absent, null, or an array of string selectors / document-filter records).
+ * Unknown fields such as kotlin-lsp's `workDoneProgress` are tolerated.
+ */
+export function isValidDiagnosticOptions(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  if (typeof value.interFileDependencies !== "boolean") return false;
+  if (typeof value.workspaceDiagnostics !== "boolean") return false;
+  if (value.identifier !== undefined && typeof value.identifier !== "string") return false;
+  if (value.documentSelector !== undefined && value.documentSelector !== null) {
+    if (!Array.isArray(value.documentSelector)) return false;
+    if (!value.documentSelector.every((entry) => typeof entry === "string" || isRecord(entry))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Dynamic capability registrations for one client instance.
+ *
+ * A replacement client starts with an empty instance, so late registrations
+ * on a superseded instance never affect the replacement. Unregistration
+ * removes one id; pull stays enabled until the last id is removed.
+ */
+export class ClientDynamicRegistrations {
+  private readonly idsByMethod = new Map<string, Set<string>>();
+
+  /** Record one registration id for a method. Duplicate ids are harmless. */
+  register(method: string, id: string): void {
+    let ids = this.idsByMethod.get(method);
+    if (ids === undefined) {
+      ids = new Set();
+      this.idsByMethod.set(method, ids);
+    }
+    ids.add(id);
+  }
+
+  /** Remove one registration id; unknown ids are harmless no-ops. */
+  unregister(method: string, id: string): void {
+    this.idsByMethod.get(method)?.delete(id);
+  }
+
+  /** Whether any registration id remains active for a method. */
+  has(method: string): boolean {
+    return (this.idsByMethod.get(method)?.size ?? 0) > 0;
+  }
+
+  /** Snapshot of the active registration ids for a method. */
+  ids(method: string): readonly string[] {
+    return [...(this.idsByMethod.get(method) ?? [])];
+  }
+
+  /** Drop all registrations — capability loss on shutdown, crash, or disposal. */
+  clear(): void {
+    this.idsByMethod.clear();
+  }
+}

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

@@ -0,0 +1,171 @@
+import {
+  type CodeQueryResult,
+  type CodeRequestControl,
+  completedCodeQuery,
+  isCodeRequestInterruption,
+  partialCodeQuery,
+  throwIfCodeRequestInterrupted,
+  unavailableCodeQuery,
+} from "@mrclrchtr/supi-code-runtime/api";
+import type { Diagnostic } from "../config/types.ts";
+import { TENTATIVE_PUSH_UNAVAILABLE_REASON } from "../diagnostics/evidence.ts";
+import {
+  type DiagnosticSynchronization,
+  incompleteDiagnosticResult,
+  raceDiagnosticPull,
+} from "./client-diagnostic-evidence.ts";
+import type { DiagnosticObserver, DiagnosticPushWaitOutcome } from "./client-diagnostic-timing.ts";
+import type { DiagnosticWaitRegistry } from "./client-diagnostic-waiters.ts";
+
+interface FileDiagnosticCollectionOptions {
+  readonly supportsPull: boolean;
+  readonly syncStart: number;
+  readonly maxWaitMs: number;
+  readonly request: DiagnosticSynchronization;
+  readonly cachedDiagnostics: Diagnostic[] | null;
+  readonly observer: DiagnosticObserver;
+  readonly waiters: DiagnosticWaitRegistry;
+  readonly current: () => boolean;
+  readonly freshPush: () => boolean;
+  /** Receive time of a current tentative push that is already cached. */
+  readonly currentPushReceivedAt: () => number | undefined;
+  readonly diagnostics: () => Diagnostic[];
+  readonly pullDiagnostics: (timeoutMs: number, signal: AbortSignal) => Promise<boolean>;
+  /** Observe the push wait outcome without finishing the observer; the caller finishes once. */
+  readonly onPushWait?: (outcome: DiagnosticPushWaitOutcome) => void;
+}
+
+type PullCollectionOutcome = "failed" | "pull" | "push" | "released";
+
+/** Collect fresh pull or push evidence for one synchronized document. */
+export async function collectSynchronizedFileDiagnostics(
+  options: FileDiagnosticCollectionOptions,
+  control?: CodeRequestControl,
+): Promise<CodeQueryResult<Diagnostic[]>> {
+  throwIfCodeRequestInterrupted(control);
+  if (options.supportsPull) {
+    const pullOutcome = await collectPullEvidence(options, control);
+    if (pullOutcome === "pull" || pullOutcome === "push") {
+      return completedCodeQuery(options.diagnostics());
+    }
+  }
+
+  throwIfCodeRequestInterrupted(control);
+  if (!options.current()) {
+    options.observer.pushWaitCompleted(1, "released");
+    return unavailableCodeQuery(
+      "Diagnostic collection ended before the current document synchronization was confirmed.",
+    );
+  }
+  if (options.freshPush()) {
+    options.observer.pushWaitCompleted(1, "published");
+    return completedCodeQuery(options.diagnostics());
+  }
+
+  const push = await waitForConfirmedPush(options, control);
+  if (options.onPushWait) options.onPushWait(push);
+  else options.observer.pushWaitCompleted(1, push);
+  if (push === "published") {
+    return completedCodeQuery(options.diagnostics());
+  }
+  if (push === "tentative") {
+    // A current tentative error is useful partial evidence, but an empty
+    // publication cannot establish that the document is clean (ADR 0021).
+    const diagnostics = options.diagnostics();
+    return diagnostics.length > 0
+      ? partialCodeQuery(diagnostics, TENTATIVE_PUSH_UNAVAILABLE_REASON)
+      : unavailableCodeQuery(TENTATIVE_PUSH_UNAVAILABLE_REASON);
+  }
+  return incompleteDiagnosticResult(
+    options.cachedDiagnostics,
+    push === "released" ? "released" : "timed-out",
+  );
+}
+
+/**
+ * Wait until a confirmed push publication settles the synchronization.
+ *
+ * Every accepted publication releases the waiter. A confirmed push ends the
+ * wait as "published". A publication that stays tentative (no republish
+ * arrived for the same synchronization) ends as "tentative" when the budget
+ * expires. A wait with no publication at all keeps the waiter's
+ * "timed-out", and a lifecycle release stays "released".
+ */
+async function waitForConfirmedPush(
+  options: FileDiagnosticCollectionOptions,
+  control?: CodeRequestControl,
+): Promise<DiagnosticPushWaitOutcome> {
+  // A tentative publication may already sit in the cache when the wait
+  // starts (ADR 0021). Do not grant repeated callers a new full wait window:
+  // bound them by the first operation window or the cached publication age.
+  const initialPushReceivedAt = options.currentPushReceivedAt();
+  const waitDeadline = Math.min(
+    options.syncStart + options.maxWaitMs,
+    initialPushReceivedAt === undefined
+      ? Number.POSITIVE_INFINITY
+      : initialPushReceivedAt + options.maxWaitMs,
+  );
+  let observedPublication = initialPushReceivedAt !== undefined;
+  for (;;) {
+    throwIfCodeRequestInterrupted(control);
+    // A republish can arrive after the previous wait released but before the
+    // next waiter registers; re-check the store on every loop pass.
+    if (options.freshPush()) return "published";
+    const push = await options.waiters.waitForPush(
+      options.request.uri,
+      Math.max(0, waitDeadline - Date.now()),
+      control,
+    );
+    // A lifecycle release ends the wait definitively: a tentative
+    // publication observed earlier must not reclassify the release.
+    if (push === "released") return "released";
+    // A promotion can land while the timed-out waiter tears down; the cache
+    // must complete the wait before the timeout classifies the outcome.
+    if (options.freshPush()) return "published";
+    if (push === "timed-out") {
+      return observedPublication || options.currentPushReceivedAt() !== undefined
+        ? "tentative"
+        : "timed-out";
+    }
+    observedPublication = true;
+  }
+}
+
+async function collectPullEvidence(
+  options: FileDiagnosticCollectionOptions,
+  control?: CodeRequestControl,
+): Promise<PullCollectionOutcome> {
+  const remaining = options.maxWaitMs - (Date.now() - options.syncStart);
+  if (remaining <= 0) {
+    options.observer.pullTimedOut();
+    return "failed";
+  }
+
+  try {
+    const controller = new AbortController();
+    // Link the caller's cancellation to the local pull controller so an
+    // in-flight pull receives protocol cancellation and stops promptly.
+    const onAbort = () => controller.abort(control?.signal?.reason);
+    if (control?.signal?.aborted) onAbort();
+    else control?.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      const outcome = await raceDiagnosticPull({
+        pull: options.pullDiagnostics(remaining, controller.signal),
+        waitForChange: () => options.waiters.waitForChange(),
+        freshPush: options.freshPush,
+        current: options.current,
+      });
+      if (outcome !== "pull") controller.abort();
+      if (outcome === "pull") options.observer.pullCompleted(1);
+      else options.observer.pullFailed(undefined);
+      if (outcome === "push") options.observer.pushWaitCompleted(1, "published");
+      return outcome;
+    } finally {
+      control?.signal?.removeEventListener("abort", onAbort);
+    }
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
+    options.observer.pullFailed(error);
+    return "failed";
+  }
+}