@mrclrchtr/supi-lsp 6.2.0 → 6.3.0

package/src/session/runtime-diagnostics.ts

@@ -45,26 +45,54 @@ export interface OutstandingDiagnosticSummaryEntry {
   hints: number;
 }
 
-/**
- * Outcome of explicit process-crash recovery demand in one diagnostic pass.
- *
- * Routes are counted rather than client generations because process-crash
- * recovery owns one budget per LSP route. `attemptedRoutes` is the number of
- * crashed routes selected by the demand; a route can be failed already or
- * have a shared replacement in progress when the demand observes it.
- */
-export interface ProcessCrashRecoverySummary {
-  attemptedRoutes: number;
-  recoveredRoutes: number;
-  failedRoutes: number;
+/** Stable outcome for one route in an explicit process-crash report. */
+export type ProcessCrashRecoveryOutcome =
+  | "recovered"
+  | "skipped-no-retained-file"
+  | "recovery-failed"
+  | "recovery-exhausted";
+
+/** Typed next action for a non-recovered process-crash route. */
+export type ProcessCrashRecoveryNextAction = "use-exact-file" | "reload-workspace";
+
+/** One bounded route entry in a process-crash recovery report. */
+export interface ProcessCrashRecoveryEntry {
+  /** Configured server name. */
+  readonly name: string;
+  /** Workspace-relative route root. */
+  readonly root: string;
+  readonly outcome: ProcessCrashRecoveryOutcome;
+  /** Available action when the route was not recovered. */
+  readonly nextAction?: ProcessCrashRecoveryNextAction;
+  /** Bounded caught Error.message for a failed recovery, when available. */
+  readonly failureMessage?: string;
+}
+
+/** Maximum number of route entries retained in a process-crash report. */
+export const MAX_PROCESS_CRASH_RECOVERY_ENTRIES = 16;
+
+/** Bounded, route-specific result of one explicit process-crash demand. */
+export interface ProcessCrashRecoveryReport {
+  /** Exact counts include entries omitted from the visible route list. */
+  readonly recoveredRoutes: number;
+  readonly skippedRoutes: number;
+  readonly failedRoutes: number;
+  readonly exhaustedRoutes: number;
+  /** At most 16 entries, ordered by action priority, root, and server name. */
+  readonly entries: readonly ProcessCrashRecoveryEntry[];
+  /** Exact number of route entries not included in {@link entries}. */
+  readonly omittedEntries: number;
 }
 
 /** Create the empty outcome for a pass with no process-crash demand. */
-export function emptyProcessCrashRecoverySummary(): ProcessCrashRecoverySummary {
+export function emptyProcessCrashRecoveryReport(): ProcessCrashRecoveryReport {
   return {
-    attemptedRoutes: 0,
     recoveredRoutes: 0,
+    skippedRoutes: 0,
     failedRoutes: 0,
+    exhaustedRoutes: 0,
+    entries: [],
+    omittedEntries: 0,
   };
 }
 
@@ -75,7 +103,7 @@ export interface RecoverDiagnosticsResult {
   /** Clients restarted by stale-diagnostic recovery, not process-crash recovery. */
   restartedClients: number;
   /** Separate outcome for process-crash route recovery selected by this pass. */
-  processCrashRecovery: ProcessCrashRecoverySummary;
+  processCrashRecovery: ProcessCrashRecoveryReport;
   /** Evidence collected by the refresh and recovery operations. */
   diagnosticEvidence: DiagnosticEvidenceSummary;
   /** Final diagnostic report captured after all refresh and recovery work. */

package/src/session/runtime-registry.ts

@@ -39,7 +39,7 @@ import type { LspManager } from "../manager/manager.ts";
 import { raceReadinessValue } from "./readiness.ts";
 import type {
   DiagnosticEvidenceSummary,
-  ProcessCrashRecoverySummary,
+  ProcessCrashRecoveryReport,
   RecoverDiagnosticsResult,
 } from "./runtime-diagnostics.ts";
 import type {
@@ -57,9 +57,13 @@ export {
   type DiagnosticEvidenceDocument,
   type DiagnosticEvidenceStatus,
   type DiagnosticEvidenceSummary,
-  emptyProcessCrashRecoverySummary,
+  emptyProcessCrashRecoveryReport,
+  MAX_PROCESS_CRASH_RECOVERY_ENTRIES,
   type OutstandingDiagnosticSummaryEntry,
-  type ProcessCrashRecoverySummary,
+  type ProcessCrashRecoveryEntry,
+  type ProcessCrashRecoveryNextAction,
+  type ProcessCrashRecoveryOutcome,
+  type ProcessCrashRecoveryReport,
   type RecoverDiagnosticsResult,
   type WorkspaceDiagnosticReport,
   type WorkspaceDiagnosticSnapshot,
@@ -80,27 +84,13 @@ function unavailableFileQuery<T>(operation: string, file: string): CodeQueryResu
   return unavailableCodeQuery(`No routed LSP client could complete ${operation} for ${file}.`);
 }
 
-function hasProcessCrashRecovery(summary: ProcessCrashRecoverySummary): boolean {
-  return summary.attemptedRoutes > 0 || summary.recoveredRoutes > 0 || summary.failedRoutes > 0;
-}
-
-/**
- * Combine the eager and current state for one readiness wait.
- * A current failure replaces the older pending view; max avoids double-counting
- * one route when both views describe the same recovery attempt.
- */
-function mergeProcessCrashRecoverySummaries(
-  eager: ProcessCrashRecoverySummary | undefined,
-  current: ProcessCrashRecoverySummary | null,
-): ProcessCrashRecoverySummary | undefined {
-  if (!eager) return current ?? undefined;
-  if (!current) return eager;
-  if (current.failedRoutes > 0) return current;
-  return {
-    attemptedRoutes: Math.max(eager.attemptedRoutes, current.attemptedRoutes),
-    recoveredRoutes: Math.max(eager.recoveredRoutes, current.recoveredRoutes),
-    failedRoutes: Math.max(eager.failedRoutes, current.failedRoutes),
-  };
+function hasProcessCrashRecovery(report: ProcessCrashRecoveryReport): boolean {
+  return (
+    report.recoveredRoutes > 0 ||
+    report.skippedRoutes > 0 ||
+    report.failedRoutes > 0 ||
+    report.exhaustedRoutes > 0
+  );
 }
 
 /** Emit one aggregate tsconfig scope-decision event after a recovery pass. */
@@ -282,7 +272,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
   ): Promise<SemanticReadinessResult> {
     const resolvedPath = this.resolveFilePath(filePath);
     if (!this.manager.canServeFile(resolvedPath)) {
-      const processCrashRecovery = this.manager.getProcessCrashRecoverySummaryForFile(resolvedPath);
+      const processCrashRecovery = this.manager.getProcessCrashRecoveryReportForFile(resolvedPath);
       return {
         kind: "unavailable",
         reason: "No LSP client can serve this file",
@@ -290,19 +280,20 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       };
     }
 
-    let eagerProcessCrashRecovery: ProcessCrashRecoverySummary | undefined;
+    let eagerProcessCrashRecovery: ProcessCrashRecoveryReport | undefined;
     const readiness = await raceReadinessValue(
-      this.manager.waitUntilFileReady(resolvedPath, control, (summary) => {
-        eagerProcessCrashRecovery = summary;
+      this.manager.waitUntilFileReady(resolvedPath, control, (report) => {
+        eagerProcessCrashRecovery = report;
       }),
       options.timeoutMs,
       control,
     );
     if (readiness.kind !== "resolved") {
-      const processCrashRecovery = mergeProcessCrashRecoverySummaries(
-        eagerProcessCrashRecovery,
-        this.manager.getProcessCrashRecoverySummaryForFile(resolvedPath),
-      );
+      // A timeout can happen before shared recovery settles. Do not create a
+      // route outcome for work that has no final result yet.
+      const currentProcessCrashRecovery =
+        this.manager.getProcessCrashRecoveryReportForFile(resolvedPath);
+      const processCrashRecovery = currentProcessCrashRecovery ?? eagerProcessCrashRecovery;
       return processCrashRecovery ? { ...readiness, processCrashRecovery } : readiness;
     }
     const { client, processCrashRecovery } = readiness.value;

package/src/session/workspace-lsp-runtime.ts

@@ -18,7 +18,7 @@ import type {
   WorkspaceSentinelSyncResult,
 } from "../diagnostics/workspace-sentinels.ts";
 import type { WorkspaceLspDiagnosticSurface } from "./runtime-diagnostic-surface.ts";
-import type { ProcessCrashRecoverySummary } from "./runtime-diagnostics.ts";
+import type { ProcessCrashRecoveryReport } from "./runtime-diagnostics.ts";
 
 export type WorkspaceLspRuntimeState =
   | { kind: "ready"; runtime: WorkspaceLspRuntime }
@@ -31,18 +31,18 @@ export type SemanticReadinessResult =
   | {
       kind: "ready";
       /** Process-crash route recovery observed while establishing file readiness. */
-      processCrashRecovery?: ProcessCrashRecoverySummary;
+      processCrashRecovery?: ProcessCrashRecoveryReport;
     }
   | {
       kind: "timeout";
       /** Process-crash route recovery observed before the readiness timeout. */
-      processCrashRecovery?: ProcessCrashRecoverySummary;
+      processCrashRecovery?: ProcessCrashRecoveryReport;
     }
   | {
       kind: "unavailable";
       reason: string;
       /** Process-crash route recovery observed before readiness became unavailable. */
-      processCrashRecovery?: ProcessCrashRecoverySummary;
+      processCrashRecovery?: ProcessCrashRecoveryReport;
     };
 
 /** One mutation response and the exact provider roots from its semantic route. */

package/src/summary.ts

@@ -94,7 +94,7 @@ import { isFileExcludedByTsconfig } from "./config/tsconfig-scope.ts";
 
 /** Check whether the supplied automatic path policy allows a file path. */
 export function isInProjectTree(filePath: string, policy: AutomaticLspPathPolicy): boolean {
-  return policy.isEligible(filePath);
+  return policy.isEligible(filePath, "file");
 }
 
 /** Check automatic and tsconfig diagnostic scope for one file path. */

package/src/workspace-path-policy.ts

@@ -26,7 +26,10 @@ const BUILT_IN_EXCLUSIONS = new Set(AUTOMATIC_LSP_EXCLUDED_DIRECTORIES);
 export interface AutomaticLspPathPolicy {
   /** Canonical absolute workspace root used for all matching. */
   readonly workspaceRoot: string;
-  /** True when automatic LSP work can use the path. */
+  /**
+   * True when automatic LSP work can use the path.
+   * The policy reads the path kind when the caller does not supply it.
+   */
   isEligible(candidate: string, kind?: "file" | "directory"): boolean;
 }
 
@@ -40,17 +43,14 @@ export function createAutomaticLspPathPolicy(
   const repositoryRules = compileRepositoryRules(canonicalRoot, configuredExclusions);
   return Object.freeze({
     workspaceRoot: canonicalRoot,
-    isEligible(candidate: string, kind: "file" | "directory" = "file"): boolean {
+    isEligible(candidate: string, kind?: "file" | "directory"): boolean {
       const relativePath = normalizeCandidate(canonicalRoot, workspaceRoot, candidate);
-      if (
-        relativePath === null ||
-        !isAutomaticCandidateAllowed(workspaceRoot, relativePath, kind)
-      ) {
-        return false;
-      }
+      if (relativePath === null) return false;
+      const candidateKind = kind ?? readCandidateKind(canonicalRoot, relativePath);
+      if (!isAutomaticCandidateAllowed(workspaceRoot, relativePath, candidateKind)) return false;
       return isEligibleRelativePath(
         relativePath,
-        kind === "directory",
+        candidateKind === "directory",
         configuredExclusions,
         repositoryRules,
       );
@@ -78,6 +78,7 @@ export function walkAutomaticLspTree(
   depth: number,
   onDirectory: (directory: string, entries: readonly Dirent[]) => boolean | undefined,
 ): void {
+  if (!policy.isEligible(directory, "directory")) return;
   walkDirectoryTree({
     directory,
     depth,
@@ -220,6 +221,14 @@ function relativeToRuleBase(base: string, relativePath: string): string | null {
   return relativePath.startsWith(`${base}/`) ? relativePath.slice(base.length + 1) : null;
 }
 
+function readCandidateKind(canonicalRoot: string, relativePath: string): "file" | "directory" {
+  try {
+    return statSync(path.resolve(canonicalRoot, relativePath)).isDirectory() ? "directory" : "file";
+  } catch {
+    return "file";
+  }
+}
+
 function isAutomaticCandidateAllowed(
   suppliedRoot: string,
   relativePath: string,