@mrclrchtr/supi-lsp 6.4.0 → 7.0.0

package/src/session/runtime-diagnostic-surface.ts

@@ -14,6 +14,8 @@ import type {
  */
 export interface ProcessCrashDiagnosticDemand {
   readonly scopes?: readonly string[];
+  /** Allow one bounded retry for failed routes during explicit health refresh. */
+  readonly explicit?: boolean;
 }
 
 /** Diagnostic and recovery operations owned by a workspace LSP runtime. */
@@ -45,7 +47,7 @@ export interface WorkspaceLspDiagnosticSurface {
     quietMs?: number;
     /** Evidence from a refresh the caller already completed; skips this pass's own refresh when no watched-file changes apply. */
     initialEvidence?: DiagnosticEvidenceSummary;
-    /** Explicit demand to recover crashed routes with tracked files in scope. */
+    /** Explicit demand to retry crashed and failed routes in scope. */
     processCrashDemand?: ProcessCrashDiagnosticDemand;
     control?: CodeRequestControl;
   }): Promise<RecoverDiagnosticsResult>;

package/src/session/runtime-diagnostics.ts

@@ -52,8 +52,8 @@ export type ProcessCrashRecoveryOutcome =
   | "recovery-failed"
   | "recovery-exhausted";
 
-/** Typed next action for a non-recovered process-crash route. */
-export type ProcessCrashRecoveryNextAction = "use-exact-file" | "reload-workspace";
+/** Typed next action for a route that needs another explicit health refresh. */
+export type ProcessCrashRecoveryNextAction = "use-exact-file" | "refresh";
 
 /** One bounded route entry in a process-crash recovery report. */
 export interface ProcessCrashRecoveryEntry {
@@ -84,6 +84,29 @@ export interface ProcessCrashRecoveryReport {
   readonly omittedEntries: number;
 }
 
+/** Stable outcome for one initial-start route handled by explicit refresh. */
+export type StartupRetryOutcome = "recovered" | "retry-failed";
+
+/** Typed next action for a failed initial-start retry. */
+export type StartupRetryNextAction = "refresh";
+
+/** One bounded route entry in an initial-start retry report. */
+export interface StartupRetryEntry {
+  readonly name: string;
+  readonly root: string;
+  readonly outcome: StartupRetryOutcome;
+  readonly nextAction?: StartupRetryNextAction;
+  readonly failureMessage?: string;
+}
+
+/** Bounded result of explicit retries for initial-start routes. */
+export interface StartupRetryReport {
+  readonly recoveredRoutes: number;
+  readonly failedRoutes: number;
+  readonly entries: readonly StartupRetryEntry[];
+  readonly omittedEntries: number;
+}
+
 /** Create the empty outcome for a pass with no process-crash demand. */
 export function emptyProcessCrashRecoveryReport(): ProcessCrashRecoveryReport {
   return {
@@ -96,6 +119,11 @@ export function emptyProcessCrashRecoveryReport(): ProcessCrashRecoveryReport {
   };
 }
 
+/** Create the empty outcome for a pass with no initial-start retry. */
+export function emptyStartupRetryReport(): StartupRetryReport {
+  return { recoveredRoutes: 0, failedRoutes: 0, entries: [], omittedEntries: 0 };
+}
+
 /** Result from a workspace diagnostic recovery pass. */
 export interface RecoverDiagnosticsResult {
   /** Active clients targeted by the best-effort refresh, not confirmed successful refreshes. */
@@ -104,6 +132,8 @@ export interface RecoverDiagnosticsResult {
   restartedClients: number;
   /** Separate outcome for process-crash route recovery selected by this pass. */
   processCrashRecovery: ProcessCrashRecoveryReport;
+  /** Separate outcome for explicit retries of failed initial-start routes. */
+  startupRetry: StartupRetryReport;
   /** Evidence collected by the refresh and recovery operations. */
   diagnosticEvidence: DiagnosticEvidenceSummary;
   /** Final diagnostic report captured after all refresh and recovery work. */
@@ -128,7 +158,10 @@ export interface ScopeDecisionEntry {
   basis: string | null;
 }
 
-/** Aggregate tsconfig scope decisions for all tracked files, for debug telemetry. */
+/**
+ * Aggregate tsconfig scope decisions for automatic-scope TypeScript/JavaScript-family
+ * tracked files, for debug telemetry.
+ */
 export interface ScopeDecisionSummary {
   caseSensitiveFileNames: boolean;
   counts: {
@@ -141,6 +174,6 @@ export interface ScopeDecisionSummary {
   basisCounts: Record<string, number>;
   /** Bounded workspace-relative entries (oldest first), not the full set. */
   entries: ScopeDecisionEntry[];
-  /** Total number of tracked files the summary was computed over. */
+  /** Total number of automatic-scope TypeScript/JavaScript-family tracked files covered. */
   totalFiles: number;
 }

package/src/session/runtime-registry.ts

@@ -41,6 +41,7 @@ import type {
   DiagnosticEvidenceSummary,
   ProcessCrashRecoveryReport,
   RecoverDiagnosticsResult,
+  StartupRetryReport,
 } from "./runtime-diagnostics.ts";
 import type {
   BulkTrackFilesResult,
@@ -59,6 +60,7 @@ export {
   type DiagnosticEvidenceStatus,
   type DiagnosticEvidenceSummary,
   emptyProcessCrashRecoveryReport,
+  emptyStartupRetryReport,
   MAX_PROCESS_CRASH_RECOVERY_ENTRIES,
   type OutstandingDiagnosticSummaryEntry,
   type ProcessCrashRecoveryEntry,
@@ -66,6 +68,10 @@ export {
   type ProcessCrashRecoveryOutcome,
   type ProcessCrashRecoveryReport,
   type RecoverDiagnosticsResult,
+  type StartupRetryEntry,
+  type StartupRetryNextAction,
+  type StartupRetryOutcome,
+  type StartupRetryReport,
   type WorkspaceDiagnosticReport,
   type WorkspaceDiagnosticSnapshot,
   type WorkspaceDiagnosticSummaryEntry,
@@ -270,11 +276,11 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
    */
   async waitUntilReadyForFile(
     filePath: string,
-    options: { timeoutMs?: number } = {},
+    options: { timeoutMs?: number; retryFailedRoute?: boolean } = {},
     control?: CodeRequestControl,
   ): Promise<SemanticReadinessResult> {
     const resolvedPath = this.resolveFilePath(filePath);
-    if (!this.manager.canServeFile(resolvedPath)) {
+    if (!options.retryFailedRoute && !this.manager.canServeFile(resolvedPath)) {
       const processCrashRecovery = this.manager.getProcessCrashRecoveryReportForFile(resolvedPath);
       return {
         kind: "unavailable",
@@ -284,31 +290,44 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     }
 
     let eagerProcessCrashRecovery: ProcessCrashRecoveryReport | undefined;
+    let eagerStartupRetry: StartupRetryReport | undefined;
     const readiness = await raceReadinessValue(
-      this.manager.waitUntilFileReady(resolvedPath, control, (report) => {
-        eagerProcessCrashRecovery = report;
+      this.manager.waitUntilFileReady(resolvedPath, control, {
+        retryFailedRoute: options.retryFailedRoute === true,
+        onProcessCrashRecovery: (report) => {
+          eagerProcessCrashRecovery = report;
+        },
+        onStartupRetry: (report) => {
+          eagerStartupRetry = report;
+        },
       }),
       options.timeoutMs,
       control,
     );
     if (readiness.kind !== "resolved") {
-      // A timeout can happen before shared recovery settles. Do not create a
-      // route outcome for work that has no final result yet.
+      // A timeout can happen before shared recovery settles. Keep only route
+      // outcomes that completed before the timeout.
       const currentProcessCrashRecovery =
         this.manager.getProcessCrashRecoveryReportForFile(resolvedPath);
       const processCrashRecovery = currentProcessCrashRecovery ?? eagerProcessCrashRecovery;
-      return processCrashRecovery ? { ...readiness, processCrashRecovery } : readiness;
+      return {
+        ...readiness,
+        ...(eagerStartupRetry ? { startupRetry: eagerStartupRetry } : {}),
+        ...(processCrashRecovery ? { processCrashRecovery } : {}),
+      };
     }
-    const { client, processCrashRecovery } = readiness.value;
+    const { client, processCrashRecovery, startupRetry } = readiness.value;
     const recovery = hasProcessCrashRecovery(processCrashRecovery) ? { processCrashRecovery } : {};
+    const startup = startupRetry && startupRetry.entries.length > 0 ? { startupRetry } : {};
     if (!client) {
       return {
         kind: "unavailable",
         reason: "The routed LSP client could not be started for this file",
+        ...startup,
         ...recovery,
       };
     }
-    return { kind: "ready", ...recovery };
+    return { kind: "ready", ...startup, ...recovery };
   }
 
   /**
@@ -433,14 +452,14 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     return this.manager.getOutstandingDiagnosticSummarySnapshot(maxSeverity);
   }
 
-  /** Trigger a workspace-wide diagnostics refresh and stale-state recovery pass. */
+  /** Retry failed routes and run a workspace-wide diagnostic recovery pass. */
   async recoverDiagnostics(options?: {
     restartIfStillStale?: boolean;
     maxWaitMs?: number;
     quietMs?: number;
     /** Evidence from a refresh the caller already completed; skips this pass's own refresh when no watched-file changes apply. */
     initialEvidence?: DiagnosticEvidenceSummary;
-    /** Explicit demand to recover crashed routes with tracked files in scope. */
+    /** Explicit demand to retry failed startup and crashed routes in scope. */
     processCrashDemand?: import("./runtime-diagnostic-surface.ts").ProcessCrashDiagnosticDemand;
     control?: CodeRequestControl;
   }): Promise<RecoverDiagnosticsResult> {
@@ -460,6 +479,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
           attemptedClients: result.attemptedClients,
           restartedClients: result.restartedClients,
           processCrashRecovery: result.processCrashRecovery,
+          startupRetry: result.startupRetry,
           attemptedServers: boundServerNames(result.attemptedServers ?? []),
           restartedServers: boundServerNames(result.restartedServers ?? []),
           ...(result.restartReason ? { reason: result.restartReason } : {}),

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

@@ -19,7 +19,7 @@ import type {
 } from "../diagnostics/workspace-sentinels.ts";
 import type { WorkspaceSourceInventory } from "../diagnostics/workspace-sources.ts";
 import type { WorkspaceLspDiagnosticSurface } from "./runtime-diagnostic-surface.ts";
-import type { ProcessCrashRecoveryReport } from "./runtime-diagnostics.ts";
+import type { ProcessCrashRecoveryReport, StartupRetryReport } from "./runtime-diagnostics.ts";
 
 /** Maximum number of files processed by one automatic bulk-tracking call. */
 export const MAX_BULK_TRACK_FILES = 256;
@@ -34,17 +34,23 @@ export type WorkspaceLspRuntimeState =
 export type SemanticReadinessResult =
   | {
       kind: "ready";
+      /** Initial-start retry observed while establishing file readiness. */
+      startupRetry?: StartupRetryReport;
       /** Process-crash route recovery observed while establishing file readiness. */
       processCrashRecovery?: ProcessCrashRecoveryReport;
     }
   | {
       kind: "timeout";
+      /** Initial-start retry observed before the readiness timeout. */
+      startupRetry?: StartupRetryReport;
       /** Process-crash route recovery observed before the readiness timeout. */
       processCrashRecovery?: ProcessCrashRecoveryReport;
     }
   | {
       kind: "unavailable";
       reason: string;
+      /** Initial-start retry observed before readiness became unavailable. */
+      startupRetry?: StartupRetryReport;
       /** Process-crash route recovery observed before readiness became unavailable. */
       processCrashRecovery?: ProcessCrashRecoveryReport;
     };
@@ -61,9 +67,15 @@ export interface RoutedMutationResponse<T> {
 export type BulkTrackFileOutcome =
   | { readonly file: string; readonly kind: "tracked" }
   | { readonly file: string; readonly kind: "already-tracked" }
+  /**
+   * Automatic tracking skipped this candidate. This includes policy-excluded
+   * paths, unsupported automatic routes, missing paths, and paths that are no
+   * longer regular. The coarse reason does not prove one cause or that an
+   * explicit request cannot be served.
+   */
   | {
       readonly file: string;
-      readonly kind: "unsupported";
+      readonly kind: "skipped";
       readonly reason: "missing" | "not-automatic-source";
     }
   | { readonly file: string; readonly kind: "unavailable"; readonly reason: string };
@@ -124,9 +136,13 @@ export interface WorkspaceLspRuntime extends WorkspaceLspDiagnosticSurface {
     control?: CodeRequestControl,
   ): Promise<RoutedMutationResponse<CodeAction[] | null> | null>;
   getOpenDocumentVersion(filePath: string): number | null;
+  /**
+   * Wait for file readiness; an explicit refresh may make one shared route
+   * retry for this call without changing ordinary request recovery limits.
+   */
   waitUntilReadyForFile(
     filePath: string,
-    options?: { timeoutMs?: number },
+    options?: { timeoutMs?: number; retryFailedRoute?: boolean },
     control?: CodeRequestControl,
   ): Promise<SemanticReadinessResult>;
   waitUntilReadyForWorkspace(