@mrclrchtr/supi-code-intelligence 4.9.0 → 5.0.0

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

@@ -3,15 +3,22 @@
 // and notification/request dispatching through vscode-jsonrpc's MessageConnection.
 
 import type { Readable, Writable } from "node:stream";
+import {
+  type CodeRequestControl,
+  CodeRequestDeadlineError,
+} from "@mrclrchtr/supi-code-runtime/api";
+import { startDebugTimer } from "@mrclrchtr/supi-core/debug";
 import {
   CancellationTokenSource,
   createMessageConnection,
+  ErrorCodes,
   type MessageConnection,
   NullLogger,
   ResponseError,
   StreamMessageReader,
   StreamMessageWriter,
 } from "vscode-jsonrpc/node";
+import { boundCwd, LSP_REQUEST_TIMEOUT_ERROR_CODE, truncateIdentity } from "../debug-telemetry.ts";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 
@@ -20,6 +27,9 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 export type NotificationHandler = (method: string, params: unknown) => void;
 export type RequestHandler = (method: string, params: unknown) => Promise<unknown> | unknown;
 
+type RequestMethodClass = "diagnostic" | "lifecycle" | "other" | "refactor" | "semantic";
+type RequestOutcome = "cancelled" | "completed" | "failed" | "timed-out";
+
 /** Re-export ResponseError so callers don't need a separate vscode-jsonrpc import. */
 const JsonRpcRequestError = ResponseError;
 
@@ -33,13 +43,19 @@ export class JsonRpcClient {
   private requestHandler: RequestHandler | null = null;
   private closed = false;
   private readonly timeoutMs: number;
+  private readonly server: string | undefined;
+  private readonly cwd: string | undefined;
+  /** Failures that signal a stalled protocol: repeated errors and local timeouts. */
+  private protocolFailureCount = 0;
 
   constructor(
     private readonly input: Readable,
     private readonly output: Writable,
-    options?: { timeoutMs?: number },
+    options?: { timeoutMs?: number; server?: string; cwd?: string },
   ) {
     this.timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.server = options?.server;
+    this.cwd = options?.cwd;
 
     const reader = new StreamMessageReader(this.input);
     const writer = new StreamMessageWriter(this.output);
@@ -51,6 +67,13 @@ export class JsonRpcClient {
       this.notificationHandler?.(method, params);
     });
 
+    // vscode-jsonrpc registers an internal $/progress handler that never
+    // reaches the catch-all handler. Route it explicitly so LSP progress
+    // notifications reach the client's readiness state machine.
+    this.connection.onNotification("$/progress", (params) => {
+      this.notificationHandler?.("$/progress", params);
+    });
+
     // Register catch-all request handler for server-initiated requests
     this.connection.onRequest(async (method, params, _token) => {
       if (!this.requestHandler) {
@@ -81,17 +104,53 @@ export class JsonRpcClient {
   sendRequest(
     method: string,
     params?: unknown,
-    options?: { timeoutMs?: number },
+    options?: { timeoutMs?: number } & CodeRequestControl,
   ): Promise<unknown> {
+    const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
+    const signal = options?.signal;
+    const deadlineMs = options?.deadline === undefined ? undefined : options.deadline - Date.now();
+    const methodClass = classifyRequestMethod(method);
+    const boundedMethod = truncateIdentity(method);
+    const timer = startDebugTimer();
+    // An expired absolute deadline must not even send the request: the caller
+    // no longer awaits a result, so no protocol traffic may start.
+    if (deadlineMs !== undefined && deadlineMs <= 0) {
+      recordRequestTiming(
+        timer,
+        options?.operationId,
+        {
+          method: boundedMethod,
+          methodClass,
+          outcome: "timed-out",
+          errorCode: LSP_REQUEST_TIMEOUT_ERROR_CODE,
+        },
+        { server: this.server, cwd: this.cwd },
+      );
+      return Promise.reject(new CodeRequestDeadlineError());
+    }
     if (this.closed || !this.connection) {
+      recordRequestTiming(
+        timer,
+        options?.operationId,
+        {
+          method: boundedMethod,
+          methodClass,
+          outcome: "cancelled",
+        },
+        { server: this.server, cwd: this.cwd },
+      );
       return Promise.reject(new Error("JSON-RPC client is closed"));
     }
-
-    const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
     const tokenSource = new CancellationTokenSource();
-
     let timeout: ReturnType<typeof setTimeout> | undefined;
-    const timeoutError = new Error(`Request ${method} timed out after ${timeoutMs}ms`);
+    let timedOut = false;
+    let aborted = false;
+    const timerDelayMs = deadlineMs === undefined ? timeoutMs : Math.min(timeoutMs, deadlineMs);
+    const timeoutError = Object.assign(
+      new Error(`Request ${method} timed out after ${timerDelayMs}ms`),
+      { code: LSP_REQUEST_TIMEOUT_ERROR_CODE },
+    );
+    const abortError = new Error(`Request ${method} was cancelled`);
 
     const request = this.connection.sendRequest(method, params, tokenSource.token);
     // Catch the raw request promise to prevent unhandled rejections when
@@ -102,17 +161,80 @@ export class JsonRpcClient {
     // the JSON-RPC token and rejects the caller. Using one timer avoids
     // a leak where the rejecting timer in a second Promise stays alive
     // after a successful response.
+    let abortHandler: (() => void) | undefined;
+    const abort = new Promise<never>((_resolve, reject) => {
+      abortHandler = () => {
+        aborted = true;
+        tokenSource.cancel();
+        // Reject with the caller's abort reason when one exists, matching the
+        // canonical throwIfCodeRequestInterrupted() behavior.
+        reject(signal?.reason ?? abortError);
+      };
+      if (signal?.aborted) abortHandler();
+      else signal?.addEventListener("abort", abortHandler, { once: true });
+    });
     const promise = Promise.race([
       request,
       new Promise<never>((_resolve, reject) => {
         timeout = setTimeout(() => {
+          timedOut = true;
           tokenSource.cancel();
-          reject(timeoutError);
-        }, timeoutMs);
+          // A deadline that binds earlier than the timeout is a deadline
+          // outcome, distinct from an ordinary per-request timeout.
+          reject(
+            deadlineMs !== undefined && deadlineMs < timeoutMs
+              ? new CodeRequestDeadlineError()
+              : timeoutError,
+          );
+        }, timerDelayMs);
       }),
-    ]).finally(() => {
-      if (timeout !== undefined) clearTimeout(timeout);
-    });
+      abort,
+    ])
+      .then(
+        (result) => {
+          recordRequestTiming(
+            timer,
+            options?.operationId,
+            {
+              method: boundedMethod,
+              methodClass,
+              outcome: "completed",
+            },
+            { server: this.server, cwd: this.cwd },
+          );
+          return result;
+        },
+        (error: unknown) => {
+          const cancelled = timedOut || aborted || this.closed || isCancellationError(error);
+          const outcome: RequestOutcome = timedOut
+            ? "timed-out"
+            : cancelled
+              ? "cancelled"
+              : "failed";
+          const errorCode = requestErrorCode(outcome, error);
+          this.countProtocolStallFailure(outcome, errorCode, error);
+          recordRequestTiming(
+            timer,
+            options?.operationId,
+            {
+              method: boundedMethod,
+              methodClass,
+              outcome,
+              // Failed requests record the server-reported JSON-RPC error code
+              // when the error carries one; timed-out requests record the
+              // defined timeout code (also for deadline expiries, whose error
+              // carries none); cancellations carry no error code.
+              errorCode,
+            },
+            { server: this.server, cwd: this.cwd },
+          );
+          throw error;
+        },
+      )
+      .finally(() => {
+        if (timeout !== undefined) clearTimeout(timeout);
+        if (abortHandler) signal?.removeEventListener("abort", abortHandler);
+      });
 
     // Prevent unhandled rejection when dispose() cancels requests
     promise.catch(() => {});
@@ -141,4 +263,109 @@ export class JsonRpcClient {
       this.connection = null;
     }
   }
+
+  /**
+   * Count one protocol-stall failure: a local timeout (not a caller-imposed
+   * deadline expiry) or a repeated server-reported protocol error. A deadline
+   * expiry is not a stall: the request may be perfectly healthy (ADR 0020).
+   */
+  private countProtocolStallFailure(
+    outcome: RequestOutcome,
+    errorCode: number | undefined,
+    error: unknown,
+  ): void {
+    if (
+      (outcome === "timed-out" && !(error instanceof CodeRequestDeadlineError)) ||
+      errorCode === ErrorCodes.ServerNotInitialized ||
+      errorCode === ErrorCodes.InvalidRequest
+    ) {
+      this.protocolFailureCount++;
+    }
+  }
+
+  /** Number of protocol-stall failures observed on this connection. */
+  getProtocolFailureCount(): number {
+    return this.protocolFailureCount;
+  }
+}
+
+const SEMANTIC_REQUESTS = new Set([
+  "textDocument/definition",
+  "textDocument/documentSymbol",
+  "textDocument/hover",
+  "textDocument/implementation",
+  "textDocument/references",
+  "workspace/symbol",
+]);
+
+/** Classify requests into bounded groups without retaining the raw method. */
+function classifyRequestMethod(method: string): RequestMethodClass {
+  if (method === "initialize" || method === "shutdown") return "lifecycle";
+  if (method === "textDocument/diagnostic" || method === "workspace/diagnostic") {
+    return "diagnostic";
+  }
+  if (method === "textDocument/codeAction" || method === "textDocument/rename") {
+    return "refactor";
+  }
+  return SEMANTIC_REQUESTS.has(method) ? "semantic" : "other";
+}
+
+function isCancellationError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const code = (error as Error & { code?: unknown }).code;
+  return (
+    code === -32_800 ||
+    code === -32_802 ||
+    error.name === "CancellationError" ||
+    /\bcancell?ed\b/i.test(error.message)
+  );
+}
+
+/** One bounded request-timing observation with exact method identity. */
+interface RequestTimingObservation {
+  readonly method: string;
+  readonly methodClass: RequestMethodClass;
+  readonly outcome: RequestOutcome;
+  /** JSON-RPC error code reported by the server for a failed request. */
+  readonly errorCode?: number;
+}
+
+/** Return the JSON-RPC error code for one request outcome. */
+function requestErrorCode(outcome: RequestOutcome, error: unknown): number | undefined {
+  if (outcome === "failed") return jsonRpcErrorCode(error);
+  if (outcome === "timed-out") return jsonRpcErrorCode(error) ?? LSP_REQUEST_TIMEOUT_ERROR_CODE;
+  return undefined;
+}
+
+/** Return the numeric JSON-RPC error code carried by an error, if any. */
+function jsonRpcErrorCode(error: unknown): number | undefined {
+  if (typeof error !== "object" || error === null) return undefined;
+  const code = (error as { code?: unknown }).code;
+  return typeof code === "number" && Number.isInteger(code) ? code : undefined;
+}
+
+function recordRequestTiming(
+  timer: ReturnType<typeof startDebugTimer>,
+  operationId: string | undefined,
+  observation: RequestTimingObservation,
+  identity: { server?: string; cwd?: string },
+): void {
+  timer.finish(
+    () => ({
+      operationId,
+      source: "lsp",
+      level: "debug",
+      category: "request.timing",
+      message: `LSP ${observation.methodClass} request ${observation.outcome} for ${observation.method}`,
+      cwd: boundCwd(identity.cwd),
+      data: {
+        method: observation.method,
+        methodClass: observation.methodClass,
+        outcome: observation.outcome,
+        ...(identity.server !== undefined ? { server: identity.server } : {}),
+        ...(observation.errorCode !== undefined ? { errorCode: observation.errorCode } : {}),
+      },
+    }),
+    "request",
+  );
 }

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

@@ -3,6 +3,9 @@
 import type { ClientCapabilities } from "./types.ts";
 
 export const CLIENT_CAPABILITIES: ClientCapabilities = {
+  general: {
+    positionEncodings: ["utf-16"],
+  },
   textDocument: {
     synchronization: {
       didSave: true,
@@ -49,7 +52,10 @@ export const CLIENT_CAPABILITIES: ClientCapabilities = {
       versionSupport: true,
     },
     diagnostic: {
-      dynamicRegistration: false,
+      // Dynamic registration lets servers such as pyright-langserver register
+      // `textDocument/diagnostic` support after initialization. Probes show
+      // only Pyright acts on this global flag among the built-in servers.
+      dynamicRegistration: true,
       relatedDocumentSupport: true,
     },
   },
@@ -58,6 +64,9 @@ export const CLIENT_CAPABILITIES: ClientCapabilities = {
   },
   workspace: {
     workspaceFolders: false,
+    workspaceEdit: {
+      documentChanges: true,
+    },
     diagnostics: {
       refreshSupport: false,
     },

package/node_modules/@mrclrchtr/supi-lsp/src/config/defaults.json

@@ -50,7 +50,7 @@
     },
     "kotlin": {
       "command": "kotlin-lsp",
-      "args": [],
+      "args": ["--stdio"],
       "fileTypes": ["kt", "kts"],
       "rootMarkers": ["build.gradle.kts", "pom.xml"]
     },

package/node_modules/@mrclrchtr/supi-lsp/src/debug-telemetry.ts

@@ -0,0 +1,45 @@
+// Bounded identity vocabulary for LSP debug telemetry.
+//
+// LSP debug events may carry server, workspace, file, method, and root
+// identity for local protocol diagnosis. Every emitted identity string is
+// bounded to MAX_IDENTITY_STRING UTF-16 code units (truncation marker
+// included) and every identity list is bounded to MAX_SERVERS entries.
+
+/** Maximum number of server entries in one bounded LSP debug payload. */
+export const MAX_SERVERS = 16;
+
+/** Maximum UTF-16 code-unit length of one emitted identity string in an LSP debug payload. */
+export const MAX_IDENTITY_STRING = 512;
+
+/** Marker appended to an identity string truncated to MAX_IDENTITY_STRING. */
+export const IDENTITY_TRUNCATION_MARKER = "…";
+
+/**
+ * JSON-RPC error code recorded for client-local request timeouts.
+ *
+ * The JSON-RPC and LSP vocabularies define no timeout code. This constant
+ * uses the JSON-RPC implementation-defined error range (-32099..-32000) at a
+ * value that vscode-jsonrpc transport codes (-32099, -32098, -32097, -32096,
+ * -32002, -32001) and LSP error codes never use.
+ */
+export const LSP_REQUEST_TIMEOUT_ERROR_CODE = -32_095;
+
+/**
+ * Truncate one identity string so the emitted value (marker included) never
+ * exceeds MAX_IDENTITY_STRING UTF-16 code units.
+ */
+export function truncateIdentity(value: string): string {
+  if (value.length <= MAX_IDENTITY_STRING) return value;
+  return `${value.slice(0, MAX_IDENTITY_STRING - 1)}${IDENTITY_TRUNCATION_MARKER}`;
+}
+
+/** Bound an optional workspace root for event-level identity; undefined stays absent. */
+export function boundCwd(cwd: string | undefined): string | undefined {
+  if (cwd === undefined) return undefined;
+  return truncateIdentity(cwd);
+}
+
+/** Bound a server-name list to MAX_SERVERS entries, truncating each name. */
+export function boundServerNames(names: readonly string[]): string[] {
+  return names.slice(0, MAX_SERVERS).map(truncateIdentity);
+}

package/node_modules/@mrclrchtr/supi-lsp/src/diagnostics/evidence.ts

@@ -0,0 +1,38 @@
+/** A final evidence state for one tracked document. */
+export type DiagnosticEvidenceStatus = "confirmed" | "unconfirmed" | "failed" | "removed";
+
+/** Freshness evidence for one tracked document. */
+export interface DiagnosticEvidenceDocument {
+  readonly file: string;
+  readonly status: DiagnosticEvidenceStatus;
+}
+
+/** Exact document coverage from a diagnostic snapshot or refresh attempt. */
+export interface DiagnosticEvidenceSummary {
+  readonly requested: number;
+  readonly confirmed: number;
+  readonly unconfirmed: number;
+  readonly failed: number;
+  readonly removed: number;
+  readonly documents: readonly DiagnosticEvidenceDocument[];
+}
+
+/** Build exact coverage counts from one document outcome per requested document. */
+export function summarizeDiagnosticEvidence(
+  documents: readonly DiagnosticEvidenceDocument[],
+): DiagnosticEvidenceSummary {
+  const counts = {
+    requested: documents.length,
+    confirmed: 0,
+    unconfirmed: 0,
+    failed: 0,
+    removed: 0,
+  };
+  for (const document of documents) counts[document.status]++;
+  return { ...counts, documents: [...documents] };
+}
+
+/** Return an empty evidence summary for a refresh with no tracked documents. */
+export function emptyDiagnosticEvidence(): DiagnosticEvidenceSummary {
+  return summarizeDiagnosticEvidence([]);
+}

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-client-state.ts

@@ -1,5 +1,16 @@
 import * as path from "node:path";
+import {
+  type CodeRequestControl,
+  isCodeRequestInterruption,
+} from "@mrclrchtr/supi-code-runtime/api";
 import type { LspClient } from "../client/client.ts";
+import { getDiagnosticFileState } from "../client/client-file-state.ts";
+import {
+  type DiagnosticEvidenceDocument,
+  type DiagnosticEvidenceSummary,
+  summarizeDiagnosticEvidence,
+} from "../diagnostics/evidence.ts";
+import { uriToFile } from "../utils.ts";
 
 export function closeFileAcrossClients(clients: Iterable<LspClient>, filePath: string): void {
   const resolvedPath = path.resolve(filePath);
@@ -21,14 +32,73 @@ export function pruneMissingFilesFromClients(clients: Iterable<LspClient>): stri
 
 export async function refreshOpenDiagnosticsForClients(
   clients: Iterable<LspClient>,
-  options?: { maxWaitMs?: number; quietMs?: number },
-): Promise<void> {
-  const refreshes = Array.from(clients)
-    .filter((client) => client.status === "running")
-    .map((client) =>
-      client.refreshOpenDiagnostics(options).catch(() => {
-        // Soft-fail: LSP errors must not prevent agent startup
-      }),
-    );
+  options?: { maxWaitMs?: number; quietMs?: number } & CodeRequestControl,
+): Promise<DiagnosticEvidenceSummary> {
+  const documents: DiagnosticEvidenceDocument[] = [];
+  const refreshes = Array.from(clients).map(async (client) => {
+    const trackedFiles = [...client.openFiles];
+    if (client.status !== "running") {
+      documents.push(...failedCoverageForClient(client, trackedFiles));
+      return;
+    }
+
+    try {
+      const result = await client.refreshOpenDiagnostics(options);
+      const reportedFiles = new Set(result.documents.map((document) => document.file));
+      documents.push(...result.documents);
+      documents.push(
+        ...trackedFiles
+          .filter((file) => !reportedFiles.has(file))
+          .map((file) => ({ file, status: "failed" as const })),
+      );
+    } catch (error) {
+      // A cancelled refresh must not degrade into failed coverage evidence.
+      if (isCodeRequestInterruption(error, options)) throw error;
+      // Keep failed coverage for every document requested by the client.
+      documents.push(...failedCoverageForClient(client, trackedFiles));
+    }
+  });
   await Promise.all(refreshes);
+  return summarizeDiagnosticEvidence(deduplicateEvidenceDocuments(documents));
+}
+
+function failedCoverageForClient(
+  client: LspClient,
+  trackedFiles: readonly string[],
+): DiagnosticEvidenceDocument[] {
+  const snapshot = client.getDiagnosticSnapshot();
+  const files = new Set([
+    ...trackedFiles,
+    ...snapshot.documents.map((document) => uriToFile(document.uri)),
+  ]);
+  return Array.from(files).map((file) => ({
+    file,
+    status: getDiagnosticFileState(file) === "removed" ? ("removed" as const) : ("failed" as const),
+  }));
+}
+
+function deduplicateEvidenceDocuments(
+  documents: readonly DiagnosticEvidenceDocument[],
+): DiagnosticEvidenceDocument[] {
+  const byFile = new Map<string, DiagnosticEvidenceDocument>();
+  for (const document of documents) {
+    const existing = byFile.get(document.file);
+    if (!existing || evidenceStatusRank(document.status) > evidenceStatusRank(existing.status)) {
+      byFile.set(document.file, document);
+    }
+  }
+  return Array.from(byFile.values()).sort((a, b) => a.file.localeCompare(b.file));
+}
+
+function evidenceStatusRank(status: DiagnosticEvidenceDocument["status"]): number {
+  switch (status) {
+    case "confirmed":
+      return 1;
+    case "unconfirmed":
+      return 2;
+    case "failed":
+      return 3;
+    case "removed":
+      return 4;
+  }
 }

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-diagnostics.ts

@@ -1,4 +1,9 @@
 import { readFileSync } from "node:fs";
+import {
+  type CodeQueryResult,
+  type CodeRequestControl,
+  mapCodeQueryResult,
+} from "@mrclrchtr/supi-code-runtime/api";
 import type { LspClient } from "../client/client.ts";
 import type { Diagnostic } from "../config/types.ts";
 import { relativeFilePathFromUri } from "../diagnostics/diagnostic-summary.ts";
@@ -10,10 +15,14 @@ export async function syncClientFileAndGetDiagnostics(
   client: Pick<LspClient, "syncAndWaitForDiagnostics">,
   filePath: string,
   maxSeverity: number,
-): Promise<Diagnostic[]> {
-  return filterDiagnosticsBySeverity(
-    await client.syncAndWaitForDiagnostics(filePath, readFileSync(filePath, "utf-8")),
-    maxSeverity,
+  control?: CodeRequestControl,
+): Promise<CodeQueryResult<Diagnostic[]>> {
+  const content = readFileSync(filePath, "utf-8");
+  const result = control
+    ? await client.syncAndWaitForDiagnostics(filePath, content, control)
+    : await client.syncAndWaitForDiagnostics(filePath, content);
+  return mapCodeQueryResult(result, (diagnostics) =>
+    filterDiagnosticsBySeverity(diagnostics, maxSeverity),
   );
 }