@mrclrchtr/supi-code-intelligence 6.3.0 → 7.0.0

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

@@ -23,42 +23,51 @@ interface ApplyPushOptions {
 /**
  * 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).
+ * Ambient pushes are observations, not confirmation evidence. 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. Publication counts remain telemetry only.
  */
-export function applyPushDiagnostics(options: ApplyPushOptions): {
-  accepted: boolean;
-  promoted: boolean;
-} {
-  if (!isValidPublishDiagnosticsParams(options.params)) return { accepted: false, promoted: false };
+export function applyPushDiagnostics(options: ApplyPushOptions): { accepted: boolean } {
+  if (!isValidPublishDiagnosticsParams(options.params)) return { accepted: 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 (!Number.isInteger(options.params.version)) return { accepted: false };
     if (openDocument && options.params.version !== openDocument.version) {
-      return { accepted: false, promoted: false };
+      return { accepted: false };
     }
-    if (!openDocument && options.closedVersionedBarrier)
-      return { accepted: false, promoted: false };
+    if (!openDocument && options.closedVersionedBarrier) return { accepted: 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);
+  if (!Array.isArray(options.params.diagnostics)) return { accepted: false };
+  if (!acceptUnversionedPush(options, openDocument)) return { accepted: false };
   const previous = options.store.get(options.params.uri);
-  const promoted =
-    entry.source === "push" &&
-    entry.publications !== undefined &&
-    entry.publications >= 2 &&
-    isTentativePushEntry(previous);
+  // A request-confirmed result owns the synchronization. Ambient pushes may
+  // still release waiters and telemetry, but they must not replace that result.
+  if (isCurrentRequestEvidence(previous, openDocument, options.evidenceRevision)) {
+    return { accepted: true };
+  }
+  const entry = buildPushCacheEntry(options, openDocument);
   options.store.set(options.params.uri, entry);
-  return { accepted: true, promoted };
+  return { accepted: true };
+}
+
+/** Test whether a request result still owns the current document generation. */
+function isCurrentRequestEvidence(
+  entry: DiagnosticCacheEntry | undefined,
+  document: OpenDocumentState | undefined,
+  evidenceRevision: number,
+): boolean {
+  return Boolean(
+    entry &&
+      entry.source !== "push" &&
+      document &&
+      entry.synchronizationId === document.synchronizationId &&
+      entry.evidenceRevision === evidenceRevision &&
+      document.evidenceRevision === evidenceRevision,
+  );
 }
 
 /** Gate one unversioned push publication against the sync-moment policy. */
@@ -77,9 +86,9 @@ function acceptUnversionedPush(
  * 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.
+ * document's current synchronization state. Versioned pushes keep the
+ * current-revision check: a version match alone does not prove a current
+ * generation.
  */
 function buildPushCacheEntry(
   options: ApplyPushOptions,
@@ -92,9 +101,8 @@ function buildPushCacheEntry(
   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.
+  // revision continues the entry's publication count for telemetry. Any
+  // other publication starts a fresh count.
   const sameSynchronization =
     synchronizationId !== undefined &&
     previous?.synchronizationId === synchronizationId &&
@@ -233,7 +241,7 @@ function collectCachedDiagnostics(options: {
       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).
+    // non-current so it cannot establish a clean or settled result.
     const tentative = entryCurrent && isTentativePushEntry(entry);
     const confirmed = entryCurrent && !tentative;
     current &&= confirmed;

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

@@ -6,6 +6,10 @@
 // support is enabled only while the static provider shape is valid or the
 // dynamic set for `textDocument/diagnostic` is non-empty.
 
+import { posix as posixPath } from "node:path";
+import { uriToFile } from "@mrclrchtr/supi-core/path";
+import { detectLanguageId } from "../utils.ts";
+
 /** LSP method for document diagnostic pulls. */
 export const DOCUMENT_DIAGNOSTIC_METHOD = "textDocument/diagnostic";
 
@@ -27,13 +31,67 @@ export function isValidDiagnosticOptions(value: unknown): boolean {
   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 isValidDocumentSelector(value.documentSelector);
+}
+
+/** Test whether an optional LSP document selector has a valid shape. */
+export function isValidDocumentSelector(value: unknown): boolean {
+  if (value === undefined || value === null) return true;
+  return (
+    Array.isArray(value) &&
+    value.every((entry) => {
+      if (typeof entry === "string") return entry.length > 0;
+      if (!isRecord(entry)) return false;
+      return (
+        (entry.language === undefined || typeof entry.language === "string") &&
+        (entry.scheme === undefined || typeof entry.scheme === "string") &&
+        (entry.pattern === undefined || typeof entry.pattern === "string")
+      );
+    })
+  );
+}
+
+/** Match one valid document selector against a file URI. */
+export function isDocumentSelectorApplicable(selector: unknown, uri: string): boolean {
+  if (selector === undefined || selector === null) return true;
+  if (!isValidDocumentSelector(selector)) return false;
+  if (!Array.isArray(selector) || selector.length === 0) return false;
+  const language = detectLanguageId(uriToFile(uri));
+  const scheme = readUriScheme(uri);
+  const filePath = uriToFile(uri).replaceAll("\\", "/");
+  return selector.some((entry) => {
+    if (typeof entry === "string") return entry === language;
+    if (!isRecord(entry)) return false;
+    if (entry.language !== undefined && entry.language !== language) return false;
+    if (entry.scheme !== undefined && entry.scheme !== scheme) return false;
+    const pattern = entry.pattern;
+    if (pattern === undefined) return true;
+    if (typeof pattern !== "string") return false;
+    const basename = filePath.slice(filePath.lastIndexOf("/") + 1);
+    return globMatches(pattern, filePath) || globMatches(pattern, basename);
+  });
+}
+
+function readUriScheme(uri: string): string | undefined {
+  try {
+    return new URL(uri).protocol.replace(/:$/, "");
+  } catch {
+    return undefined;
   }
-  return true;
+}
+
+function globMatches(pattern: string, value: string): boolean {
+  try {
+    return posixPath.matchesGlob(value, pattern);
+  } catch {
+    return false;
+  }
+}
+
+/** One validated diagnostic registration retained for selector matching. */
+export interface DiagnosticRegistration {
+  readonly id: string;
+  readonly options: Record<string, unknown>;
 }
 
 /**
@@ -44,30 +102,38 @@ export function isValidDiagnosticOptions(value: unknown): boolean {
  * removes one id; pull stays enabled until the last id is removed.
  */
 export class ClientDynamicRegistrations {
-  private readonly idsByMethod = new Map<string, Set<string>>();
+  private readonly registrationsByMethod = new Map<string, Map<string, Record<string, unknown>>>();
 
-  /** 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);
+  /** Record one registration id for a method. Duplicate ids replace options. */
+  register(method: string, id: string, options: Record<string, unknown> = {}): void {
+    let registrations = this.registrationsByMethod.get(method);
+    if (registrations === undefined) {
+      registrations = new Map();
+      this.registrationsByMethod.set(method, registrations);
     }
-    ids.add(id);
+    registrations.set(id, options);
   }
 
   /** Remove one registration id; unknown ids are harmless no-ops. */
   unregister(method: string, id: string): void {
-    this.idsByMethod.get(method)?.delete(id);
+    this.registrationsByMethod.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;
+    return (this.registrationsByMethod.get(method)?.size ?? 0) > 0;
+  }
+
+  /** Return active registration options for one method. */
+  get(method: string): readonly DiagnosticRegistration[] {
+    return Array.from(this.registrationsByMethod.get(method) ?? [], ([id, options]) => ({
+      id,
+      options,
+    }));
   }
 
   /** Drop all registrations — capability loss on shutdown, crash, or disposal. */
   clear(): void {
-    this.idsByMethod.clear();
+    this.registrationsByMethod.clear();
   }
 }

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

@@ -2,23 +2,37 @@ import {
   type CodeQueryResult,
   type CodeRequestControl,
   completedCodeQuery,
-  isCodeRequestInterruption,
+  isCodeRequestDeadlineError,
   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 { raceRequestControl } from "../session/readiness.ts";
 import {
   type DiagnosticSynchronization,
   incompleteDiagnosticResult,
-  raceDiagnosticPull,
 } from "./client-diagnostic-evidence.ts";
-import type { DiagnosticObserver, DiagnosticPushWaitOutcome } from "./client-diagnostic-timing.ts";
+import {
+  type DiagnosticRequestSource,
+  isDiagnosticRequestInvalidated,
+} from "./client-diagnostic-request.ts";
+import {
+  type DiagnosticObserver,
+  type DiagnosticPushWaitOutcome,
+  isDiagnosticTimeout,
+} from "./client-diagnostic-timing.ts";
 import type { DiagnosticWaitRegistry } from "./client-diagnostic-waiters.ts";
 
 interface FileDiagnosticCollectionOptions {
-  readonly supportsPull: boolean;
+  /** Request-based evidence takes priority over all ambient push waits. */
+  readonly requestDiagnostics?: (
+    timeoutMs: number,
+    deadline: number,
+    control?: CodeRequestControl,
+  ) => Promise<boolean>;
+  readonly requestSource?: DiagnosticRequestSource;
   readonly syncStart: number;
   readonly maxWaitMs: number;
   readonly request: DiagnosticSynchronization;
@@ -26,30 +40,46 @@ interface FileDiagnosticCollectionOptions {
   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;
+  /** Current ambient push observation for this synchronization, when present. */
+  readonly currentPushObservation: () =>
+    | { receivedAt: number; hasDiagnostics: boolean }
+    | 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());
-    }
+  return options.requestDiagnostics
+    ? collectRequestBasedEvidence(options, control)
+    : collectPushOnlyEvidence(options, control);
+}
+
+async function collectRequestBasedEvidence(
+  options: FileDiagnosticCollectionOptions,
+  control?: CodeRequestControl,
+): Promise<CodeQueryResult<Diagnostic[]>> {
+  const requestOutcome = await collectRequestEvidence(options, control);
+  if (requestOutcome === "completed") return completedCodeQuery(options.diagnostics());
+  if (requestOutcome === "released") {
+    return incompleteDiagnosticResult(options.cachedDiagnostics, "released");
+  }
+  if (options.currentPushObservation()?.hasDiagnostics) {
+    return partialCodeQuery(
+      options.diagnostics(),
+      "Fresh diagnostic requests failed; ambient diagnostics are partial evidence.",
+    );
   }
+  return incompleteDiagnosticResult(options.cachedDiagnostics, "timed-out");
+}
 
+async function collectPushOnlyEvidence(
+  options: FileDiagnosticCollectionOptions,
+  control?: CodeRequestControl,
+): Promise<CodeQueryResult<Diagnostic[]>> {
   throwIfCodeRequestInterrupted(control);
   if (!options.current()) {
     options.observer.pushWaitCompleted(1, "released");
@@ -57,20 +87,9 @@ export async function collectSynchronizedFileDiagnostics(
       "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());
-  }
+  const push = await waitForPushObservation(options, control);
+  options.observer.pushWaitCompleted(1, push);
   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)
@@ -82,90 +101,87 @@ export async function collectSynchronizedFileDiagnostics(
   );
 }
 
+/** Collect one request report without using an ambient push as confirmation. */
+async function collectRequestEvidence(
+  options: FileDiagnosticCollectionOptions,
+  control?: CodeRequestControl,
+): Promise<"completed" | "failed" | "released"> {
+  const deadline = Math.min(
+    options.syncStart + options.maxWaitMs,
+    control?.deadline ?? Number.POSITIVE_INFINITY,
+  );
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) {
+    options.observer.requestTimedOut(options.requestSource);
+    return "failed";
+  }
+  try {
+    const requestDiagnostics = options.requestDiagnostics;
+    if (!requestDiagnostics) return "released";
+    const completed = await raceRequestControl(
+      requestDiagnostics(remaining, deadline, control),
+      control,
+    );
+    if (!completed) {
+      options.observer.requestIncomplete(options.requestSource);
+      return "released";
+    }
+    options.observer.requestCompleted(options.requestSource ?? "pull", 1);
+    return "completed";
+  } catch (error) {
+    if (isDiagnosticRequestInvalidated(error)) {
+      options.observer.requestIncomplete(options.requestSource);
+      return "released";
+    }
+    if (
+      control?.signal?.aborted ||
+      (control?.deadline !== undefined && Date.now() >= control.deadline)
+    ) {
+      throw error;
+    }
+    const timedOut = isDiagnosticCollectionTimeout(error);
+    options.observer.requestFailed(options.requestSource, error);
+    options.observer.requestIncomplete(options.requestSource, timedOut);
+    return "failed";
+  }
+}
+
+function isDiagnosticCollectionTimeout(error: unknown): boolean {
+  return isCodeRequestDeadlineError(error) || isDiagnosticTimeout(error);
+}
+
 /**
- * Wait until a confirmed push publication settles the synchronization.
+ * Wait for ambient push observations within the file collection budget.
  *
- * 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".
+ * A publication is useful partial evidence, but it does not confirm a
+ * synchronization. Continue to the budget so delayed publications can still
+ * improve the partial result; a lifecycle release remains definitive.
  */
-async function waitForConfirmedPush(
+async function waitForPushObservation(
   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 initialObservation = options.currentPushObservation();
   const waitDeadline = Math.min(
     options.syncStart + options.maxWaitMs,
-    initialPushReceivedAt === undefined
+    initialObservation === undefined
       ? Number.POSITIVE_INFINITY
-      : initialPushReceivedAt + options.maxWaitMs,
+      : initialObservation.receivedAt + options.maxWaitMs,
   );
-  let observedPublication = initialPushReceivedAt !== undefined;
+  let observedPublication = initialObservation !== 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
+      return observedPublication || options.currentPushObservation() !== 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";
-  }
-}