@mrclrchtr/supi-lsp 10.0.0 → 11.0.0

package/src/manager/manager.ts

@@ -3,6 +3,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import {
+  type CFamilyFileAssociationResolver,
   type CodeQueryResult,
   type CodeRequestControl,
   isCodeRequestInterruption,
@@ -69,6 +70,7 @@ import {
   scanWorkspaceSources as scanAutomaticWorkspaceSources,
   type WorkspaceSourceInventory,
 } from "../diagnostics/workspace-sources.ts";
+import { MAX_RENAME_DOCUMENTS } from "../provider/semantic-edit-discovery.ts";
 import { raceRequestControl } from "../session/readiness.ts";
 import {
   emptyProcessCrashRecoveryReport,
@@ -175,6 +177,57 @@ type FileRoute = {
   key: string;
 };
 
+function validateRenameEnrollmentFiles(
+  client: LspClient,
+  files: readonly string[],
+  routeKey: string,
+  routeForFile: (file: string) => string | null,
+): string | null {
+  if (files.length > MAX_RENAME_DOCUMENTS) {
+    return "Rename affects too many files to synchronize safely.";
+  }
+  if (files.length === 0) return "Rename returned no text-edit documents.";
+  let canonicalRoot: string;
+  try {
+    canonicalRoot = fs.realpathSync(client.root);
+    if (!fs.statSync(canonicalRoot).isDirectory()) throw new Error("not a directory");
+  } catch {
+    return "The semantic route root is not available.";
+  }
+  for (const file of files) {
+    if (!path.isAbsolute(file) || path.normalize(file) !== file) {
+      return `Rename target "${file}" is not a normalized path.`;
+    }
+    const pathError = validateRenameTargetFile(file, canonicalRoot);
+    if (pathError) return pathError;
+    if (routeForFile(file) !== routeKey) {
+      return `Rename target "${file}" uses another semantic route.`;
+    }
+  }
+  return null;
+}
+
+function validateRenameTargetFile(file: string, canonicalRoot: string): string | null {
+  let canonicalFile: string;
+  try {
+    const canonicalParent = fs.realpathSync(path.dirname(file));
+    if (!fs.lstatSync(file).isFile()) {
+      return `Rename target "${file}" is not a regular file.`;
+    }
+    canonicalFile = fs.realpathSync(file);
+    if (
+      path.resolve(canonicalFile) !== path.resolve(path.join(canonicalParent, path.basename(file)))
+    ) {
+      return `Rename target "${file}" resolves through a file link.`;
+    }
+  } catch {
+    return `Rename target "${file}" is not a readable file.`;
+  }
+  return projectRoots.isWithinOrEqual(canonicalRoot, canonicalFile)
+    ? null
+    : `Rename target "${file}" is outside the semantic route root.`;
+}
+
 type ClientRestartResult = {
   key: string;
   serverName: string;
@@ -182,7 +235,10 @@ type ClientRestartResult = {
   restarted: boolean;
 };
 
-export type ManagerLifecycleTransitionKind = LspClientLifecycleTransitionKind | "recovery";
+export type ManagerLifecycleTransitionKind =
+  | LspClientLifecycleTransitionKind
+  | "recovery"
+  | "retirement";
 
 /** Package-internal aggregate lifecycle snapshot for the runtime controller. */
 export interface ManagerLifecycleTransition {
@@ -324,6 +380,12 @@ export class LspManager {
   private commandAvailability = new Map<string, boolean>();
   /** Guards against concurrent client creation for the same server:root key. */
   private pendingStarts = new Map<string, Promise<LspClient | null>>();
+  /** Prevent retired route owners from publishing work after root removal. */
+  private routeRetirementGenerations = new Map<string, number>();
+  /** Retired route keys stay blocked until the same path is again a directory. */
+  private retiredRoutes = new Set<string>();
+  /** Runtime-owned cleanup for clients removed by route retirement. */
+  private retiredClientShutdowns = new Set<Promise<void>>();
   /** Shared diagnostic-recovery restart for each replaceable client route. */
   private pendingRestarts = new Map<string, Promise<{ files: string[]; restarted: boolean }>>();
   /** Monotonic ownership generation for each replaceable client route. */
@@ -351,6 +413,7 @@ export class LspManager {
   /** Coalesce per-file tracking transitions into one bulk transition. */
   private trackedFilesBatchDepth = 0;
   private trackedFilesBatchChanged = false;
+  // biome-ignore lint/complexity/useMaxParams: the host passes one fixed association snapshot with the existing runtime dependencies
   constructor(
     private readonly config: LspConfig,
     private readonly cwd: string,
@@ -358,6 +421,7 @@ export class LspManager {
     private readonly automaticPathPolicy: AutomaticLspPathPolicy = createDefaultAutomaticLspPathPolicy(
       cwd,
     ),
+    private readonly fileAssociations?: CFamilyFileAssociationResolver,
   ) {}
   getCwd(): string {
     return this.cwd;
@@ -480,6 +544,7 @@ export class LspManager {
   ): Promise<LspClient | null> {
     throwIfCodeRequestInterrupted(options.control);
     if (this.shuttingDown) return null;
+    if (options.recoverProcessCrash) this.retireMissingProjectRoots();
     const route = this.resolveFileRoute(filePath);
     if (!route) return null;
 
@@ -505,6 +570,8 @@ export class LspManager {
     if (!serverConfig) return null;
     const key = clientKey(serverName, root);
     const retryFailedStart = options.retryFailedStart === true;
+    if (this.shouldBlockRetiredRoute(key, root, retryFailedStart)) return null;
+    const routeGeneration = this.getRouteRetirementGeneration(key);
     if (retryFailedStart) this.unavailable.delete(key);
     if (!retryFailedStart && this.getUnavailableReason(key, serverConfig.command)) return null;
 
@@ -540,7 +607,10 @@ export class LspManager {
     const pending = this.pendingStarts.get(key);
     if (pending) return raceRequestControl(pending, control);
 
-    const startPromise = this.performStart(serverName, serverConfig, root, key);
+    const startPromise = this.performStart(
+      { serverName, serverConfig, root, key },
+      routeGeneration,
+    );
     this.pendingStarts.set(key, startPromise);
     // Keep the shared startup registered until it settles. A cancelled
     // caller only stops waiting; it must not allow a duplicate route start.
@@ -569,6 +639,7 @@ export class LspManager {
         this.handleClientLifecycle(key, generation, client, kind);
       },
       this.cwd,
+      this.fileAssociations,
     );
     return client;
   }
@@ -672,6 +743,7 @@ export class LspManager {
     control?: CodeRequestControl,
   ): Promise<ProcessCrashDemandResult> {
     throwIfCodeRequestInterrupted(control);
+    this.retireMissingProjectRoots();
     const scopes = this.processCrashDiagnosticScopes(demand);
     const candidates = this.selectExplicitRouteCandidates(scopes);
     return this.withExplicitRouteAttempts(candidates, control, async (results) => {
@@ -850,7 +922,7 @@ export class LspManager {
     callback: (results: ExplicitRouteAttemptResult[]) => Promise<T>,
   ): Promise<T> {
     throwIfCodeRequestInterrupted(control);
-    const leased: string[] = [];
+    const leased: Array<{ key: string; lease: ExplicitRouteAttemptLease }> = [];
     try {
       const promises = candidates.map((candidate) => {
         throwIfCodeRequestInterrupted(control);
@@ -858,7 +930,7 @@ export class LspManager {
         const existing = this.explicitRouteAttempts.get(key);
         if (existing) {
           existing.users++;
-          leased.push(key);
+          leased.push({ key, lease: existing });
           return raceRequestControl(existing.promise, control);
         }
         const promise = this.performExplicitRouteAttempt(candidate);
@@ -872,17 +944,17 @@ export class LspManager {
             }
           })
           .catch(() => {});
-        leased.push(key);
+        leased.push({ key, lease });
         return raceRequestControl(promise, control);
       });
       const results = await Promise.all(promises);
       return await callback(results);
     } finally {
-      for (const key of leased) {
-        const lease = this.explicitRouteAttempts.get(key);
-        if (!lease) continue;
+      for (const { key, lease } of leased) {
         lease.users--;
-        if (lease.users === 0 && lease.settled) this.explicitRouteAttempts.delete(key);
+        if (lease.users === 0 && lease.settled && this.explicitRouteAttempts.get(key) === lease) {
+          this.explicitRouteAttempts.delete(key);
+        }
       }
     }
   }
@@ -891,11 +963,15 @@ export class LspManager {
     candidate: ExplicitRouteCandidate,
   ): Promise<ExplicitRouteAttemptResult> {
     const { route } = candidate;
+    const routeGeneration = this.getRouteRetirementGeneration(route.key);
     const recovery = this.processCrashRecoveries.get(route.key) ?? candidate.processCrashRecovery;
     if (recovery?.statusReason) {
       const client = await this.acquireProcessCrashReplacement(recovery, route, undefined, {
         allowExhausted: true,
       });
+      if (this.getRouteRetirementGeneration(route.key) !== routeGeneration) {
+        return { candidate, kind: "none", client: null, attempted: false };
+      }
       return {
         candidate,
         kind: "process-crash",
@@ -913,6 +989,9 @@ export class LspManager {
     const client = await this.startServerForRoot(route.serverName, route.root, undefined, {
       retryFailedStart: true,
     });
+    if (this.getRouteRetirementGeneration(route.key) !== routeGeneration) {
+      return { candidate, kind: "none", client: null, attempted: false };
+    }
     const failureMessage =
       this.failedStarts.get(route.key)?.failureMessage ?? candidate.startupFailure?.failureMessage;
     return {
@@ -975,18 +1054,20 @@ export class LspManager {
     control?: CodeRequestControl,
     options: { skipWhenNoRetainedFile?: boolean } = {},
   ): Promise<ProcessCrashDemandResult> {
+    throwIfCodeRequestInterrupted(control);
+    this.retireMissingProjectRoots();
     const { immediate, required } = this.selectProcessCrashDemandRoutes(
       this.snapshotProcessCrashRoutes(),
       selectFiles,
       options,
     );
-    const hasSupport = immediate.length > 0 || required.length > 0;
+    const hasSelectedSupport = immediate.length > 0 || required.length > 0;
     if (required.length === 0) {
       const failures = immediate
         .filter((entry) => !entry.reportOnly)
         .map((entry) => this.formatProcessCrashDemandFailure(entry.route, entry.route.outcome));
       return {
-        hasSupport,
+        hasSupport: hasSelectedSupport,
         requiresFreshEvidence: false,
         startupRetry: emptyStartupRetryReport(),
         processCrashRecovery: buildProcessCrashRecoveryReport(
@@ -1039,7 +1120,7 @@ export class LspManager {
     );
     const failedImmediate = immediate.filter((entry) => !entry.reportOnly);
     return {
-      hasSupport,
+      hasSupport: immediate.length > 0 || observedRequired.length > 0,
       requiresFreshEvidence: observedRequired.length > 0,
       startupRetry: emptyStartupRetryReport(),
       processCrashRecovery: buildProcessCrashRecoveryReport(
@@ -1383,12 +1464,8 @@ export class LspManager {
    * Perform the actual server start — extracted so the public method can
    * deduplicate via pendingStarts without wrapping the entire body.
    */
-  private async performStart(
-    serverName: string,
-    serverConfig: ServerConfig,
-    root: string,
-    key: string,
-  ): Promise<LspClient | null> {
+  private async performStart(route: FileRoute, routeGeneration: number): Promise<LspClient | null> {
+    const { serverName, serverConfig, root, key } = route;
     // Validate command exists
     if (!commandExists(serverConfig.command)) {
       this.unavailable.set(key, "missing-command");
@@ -1409,7 +1486,7 @@ export class LspManager {
     rememberKnownRoot(this.knownRoots, serverName, root);
     try {
       await client.start();
-      if (this.shuttingDown) {
+      if (!this.ownsCurrentStart(key, routeGeneration, client)) {
         await client.forceKill().catch(() => {});
         if (this.clients.get(key) === client) this.clients.delete(key);
         return null;
@@ -1418,6 +1495,11 @@ export class LspManager {
       this.failedStarts.delete(key);
       return client;
     } catch (error) {
+      if (!this.ownsCurrentStart(key, routeGeneration, client)) {
+        await client.forceKill().catch(() => {});
+        if (this.clients.get(key) === client) this.clients.delete(key);
+        return null;
+      }
       this.unavailable.set(key, "start-failed");
       this.failedStarts.set(key, {
         serverName,
@@ -1483,8 +1565,11 @@ export class LspManager {
     key: string,
   ): Promise<{ files: string[]; restarted: boolean }> {
     const restartEpoch = this.invalidationEpoch;
+    const routeGeneration = this.getRouteRetirementGeneration(key);
     const restartPromise = this.restartClient(client).then((result) => {
-      this.recoveryRestartEpochs.set(key, restartEpoch);
+      if (this.getRouteRetirementGeneration(key) === routeGeneration) {
+        this.recoveryRestartEpochs.set(key, restartEpoch);
+      }
       return result;
     });
     this.pendingRestarts.set(key, restartPromise);
@@ -1646,6 +1731,7 @@ export class LspManager {
     throwIfCodeRequestInterrupted(control);
     const resolvedPath = resolveSessionPath(this.cwd, filePath);
     if (options.retryFailedRoute) {
+      this.retireMissingProjectRoots();
       const route = this.resolveFileRoute(resolvedPath);
       if (!route || !this.automaticPathPolicy.isEligible(route.root, "directory")) {
         return {
@@ -2092,7 +2178,119 @@ export class LspManager {
   }
   /** Remove any missing files from open-document and diagnostic state. */
   pruneMissingFiles(): string[] {
-    return pruneMissingFilesFromClients(this.clients.values());
+    const removed = pruneMissingFilesFromClients(this.clients.values());
+    this.retireMissingProjectRoots();
+    return removed;
+  }
+
+  /** Remove route-owned state only when filesystem evidence confirms root removal. */
+  private retireMissingProjectRoots(): void {
+    if (this.shuttingDown) return;
+    const routes = new Map<string, { serverName: string; root: string }>();
+    const addRoute = (serverName: string, root: string): void => {
+      routes.set(clientKey(serverName, root), { serverName, root });
+    };
+
+    for (const [serverName, roots] of this.knownRoots) {
+      for (const root of roots) addRoute(serverName, root);
+    }
+    for (const [key, client] of this.clients) {
+      if (this.clientGenerations.has(key)) addRoute(client.name, client.root);
+    }
+    for (const failure of this.failedStarts.values()) {
+      addRoute(failure.serverName, failure.root);
+    }
+    for (const recovery of this.processCrashRecoveries.values()) {
+      addRoute(recovery.failedClient.name, recovery.failedClient.root);
+    }
+
+    let retired = false;
+    for (const [key, route] of routes) {
+      if (!this.isMissingProjectRoot(route.root)) continue;
+      this.retireProjectRoute(key, route.serverName, route.root);
+      retired = true;
+    }
+    if (retired) this.publishLifecycle("retirement");
+  }
+
+  private shouldBlockRetiredRoute(key: string, root: string, retryFailedStart: boolean): boolean {
+    if (retryFailedStart) this.retireMissingProjectRoots();
+    return this.isRetiredRoute(key, root);
+  }
+
+  private ownsCurrentStart(key: string, generation: number, client: LspClient): boolean {
+    return (
+      !this.shuttingDown &&
+      this.getRouteRetirementGeneration(key) === generation &&
+      this.clients.get(key) === client
+    );
+  }
+
+  private isMissingProjectRoot(root: string): boolean {
+    try {
+      return !fs.statSync(root).isDirectory();
+    } catch (error) {
+      return isMissingFileError(error);
+    }
+  }
+
+  private isRetiredRoute(key: string, root: string): boolean {
+    if (!this.retiredRoutes.has(key)) return false;
+    try {
+      if (fs.statSync(root).isDirectory()) {
+        this.retiredRoutes.delete(key);
+        return false;
+      }
+    } catch {
+      // Keep the retirement marker until a directory is confirmed at this path.
+    }
+    return true;
+  }
+
+  private getRouteRetirementGeneration(key: string): number {
+    return this.routeRetirementGenerations.get(key) ?? 0;
+  }
+
+  private retireProjectRoute(key: string, serverName: string, root: string): void {
+    this.routeRetirementGenerations.set(key, this.getRouteRetirementGeneration(key) + 1);
+    this.retiredRoutes.add(key);
+    // Detach old work from key-based joins. Promise observers still own cleanup.
+    // Identity checks keep old finalizers from removing replacement entries.
+    this.pendingStarts.delete(key);
+    this.explicitRouteAttempts.delete(key);
+    this.pendingRestarts.delete(key);
+    const roots = this.knownRoots.get(serverName)?.filter((knownRoot) => knownRoot !== root) ?? [];
+    if (roots.length > 0) this.knownRoots.set(serverName, roots);
+    else this.knownRoots.delete(serverName);
+
+    const client = this.clients.get(key);
+    if (client) this.clients.delete(key);
+    this.unavailable.delete(key);
+    this.failedStarts.delete(key);
+    this.processCrashRecoveries.delete(key);
+    this.recoveryRestartEpochs.delete(key);
+    this.clearWarmedWorkspaceSymbolFiles(serverName, root);
+    this.clearWarmedSemanticProjects(serverName, root);
+    this.clearPendingWarmProbes(serverName, root);
+
+    if (client) {
+      const shutdown = this.shutdownRetiredClient(client);
+      this.retiredClientShutdowns.add(shutdown);
+      void shutdown.finally(() => this.retiredClientShutdowns.delete(shutdown)).catch(() => {});
+    }
+  }
+
+  private async shutdownRetiredClient(client: LspClient): Promise<void> {
+    try {
+      await client.shutdown();
+    } catch {
+      try {
+        await client.forceKill();
+      } catch {
+        // Retired-route cleanup is best-effort.
+      }
+    }
+    client.dispose();
   }
   /** Re-sync all open documents across active clients and return exact evidence coverage. */
   async refreshOpenDiagnostics(
@@ -2189,6 +2387,8 @@ export class LspManager {
     processCrashDemand?: { scopes?: readonly string[]; explicit?: boolean };
     control?: CodeRequestControl;
   }): Promise<WorkspaceRecoveryResult> {
+    throwIfCodeRequestInterrupted(options?.control);
+    this.pruneMissingFiles();
     const processCrashDemand = options?.processCrashDemand;
     const demand = processCrashDemand?.explicit
       ? await this.recoverExplicitRouteDemand(processCrashDemand, options?.control)
@@ -2293,7 +2493,8 @@ export class LspManager {
     this.shuttingDown = true;
     const clients = Array.from(this.clients.values());
     const shutdowns = clients.map((client) => client.shutdown().catch(() => {}));
-    await Promise.all(shutdowns);
+    await Promise.all([...shutdowns, ...this.retiredClientShutdowns]);
+    this.retiredClientShutdowns.clear();
     // Dispose every client so pending or active progress tokens and
     // readiness promises cannot outlive the manager.
     for (const client of clients) client.dispose();
@@ -2303,6 +2504,8 @@ export class LspManager {
     this.handledCrashGenerations.clear();
     this.processCrashRecoveries.clear();
     this.failedStarts.clear();
+    this.routeRetirementGenerations.clear();
+    this.retiredRoutes.clear();
     this.explicitRouteAttempts.clear();
     this.recoveryRestartEpochs.clear();
     this.unavailable.clear();
@@ -2765,6 +2968,42 @@ export class LspManager {
       );
     });
   }
+  /** Enroll discovered rename documents only after one complete authority check. */
+  async enrollRenameDocuments(
+    client: LspClient,
+    filePaths: readonly string[],
+    control?: CodeRequestControl,
+  ): Promise<{ kind: "enrolled" } | { kind: "unavailable"; reason: string }> {
+    throwIfCodeRequestInterrupted(control);
+    const files = [...new Set(filePaths)].sort();
+    const routeKey = clientKey(client.name, client.root);
+    if (this.clients.get(routeKey) !== client) {
+      return { kind: "unavailable", reason: "The semantic route changed during rename planning." };
+    }
+    const validationError = validateRenameEnrollmentFiles(
+      client,
+      files,
+      routeKey,
+      (file) => this.resolveFileRoute(file)?.key ?? null,
+    );
+    if (validationError) return { kind: "unavailable", reason: validationError };
+
+    for (const file of files) {
+      throwIfCodeRequestInterrupted(control);
+      const openedClient = await this.ensureFileOpen(file, {
+        recoverProcessCrash: true,
+        control,
+      });
+      if (openedClient !== client) {
+        return {
+          kind: "unavailable",
+          reason: "The semantic route changed during rename enrollment.",
+        };
+      }
+    }
+    return { kind: "enrolled" };
+  }
+
   async ensureFileOpen(
     filePath: string,
     options: FileClientRequestOptions = {},

package/src/provider/refactor-planning.ts

@@ -1,3 +1,4 @@
+import * as path from "node:path";
 import type {
   CodePosition,
   CodeRequestControl,
@@ -38,6 +39,18 @@ export async function runRenameRefactor(options: {
     { kind: "workspace-edit", edit: response.value },
     {
       getOpenDocumentVersion: (candidate) => lsp.getOpenDocumentVersion(candidate),
+      getSynchronizedDocumentSnapshot: (candidate) => {
+        const snapshot = response.documentSnapshots?.find(
+          (document) => path.resolve(document.file) === path.resolve(candidate),
+        );
+        return snapshot
+          ? {
+              version: snapshot.version,
+              contentFingerprint: snapshot.contentFingerprint,
+              diskContentFingerprint: snapshot.diskContentFingerprint,
+            }
+          : null;
+      },
       authorizedMutationRoots: response.authorizedMutationRoots,
     },
   );

package/src/provider/semantic-edit-discovery.ts

@@ -0,0 +1,151 @@
+import {
+  asRecord,
+  getResourceOperationKind,
+  hasNoInheritedAllowedKeys,
+  hasOnlyKeys,
+  normalizeTextEdits,
+  parseTextDocumentEdit,
+  toFilePath,
+} from "./semantic-edit-protocol.ts";
+
+export const MAX_RENAME_DOCUMENTS = 64;
+
+type DiscoveryResult =
+  | { readonly kind: "valid"; readonly files: readonly string[] }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+type DiscoveredDocument =
+  | { readonly kind: "valid"; readonly file: string; readonly editCount: number }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+/** Validate a complete workspace edit and list its text-edit document paths. */
+export function discoverSemanticEditFiles(value: unknown): DiscoveryResult {
+  const workspaceEdit = parseWorkspaceEdit(value);
+  if (typeof workspaceEdit === "string") {
+    return { kind: "unavailable", reason: workspaceEdit };
+  }
+  return Object.hasOwn(workspaceEdit, "documentChanges")
+    ? discoverDocumentChanges(workspaceEdit.documentChanges)
+    : discoverChangesMap(workspaceEdit.changes);
+}
+
+function parseWorkspaceEdit(value: unknown): Record<string, unknown> | string {
+  const workspaceEdit = asRecord(value);
+  if (
+    !workspaceEdit ||
+    !hasOnlyKeys(workspaceEdit, ["changes", "documentChanges", "changeAnnotations"]) ||
+    !hasNoInheritedAllowedKeys(workspaceEdit, ["changes", "documentChanges", "changeAnnotations"])
+  ) {
+    return "LSP server returned a malformed workspace edit.";
+  }
+  if (Object.hasOwn(workspaceEdit, "changeAnnotations")) {
+    return "Workspace edit contains unsupported change annotations.";
+  }
+  return workspaceEdit;
+}
+
+function discoverDocumentChanges(value: unknown): DiscoveryResult {
+  if (!Array.isArray(value)) {
+    return { kind: "unavailable", reason: "Workspace edit has malformed documentChanges." };
+  }
+  const files = new Set<string>();
+  let editCount = 0;
+  for (const change of value) {
+    const result = discoverDocumentChange(change);
+    if (result.kind === "unavailable") return result;
+    if (result.editCount > 0) {
+      files.add(result.file);
+      if (files.size > MAX_RENAME_DOCUMENTS) {
+        return {
+          kind: "unavailable",
+          reason: "Rename affects too many files to synchronize safely.",
+        };
+      }
+      editCount += result.editCount;
+    }
+  }
+  return finishDiscovery(files, editCount);
+}
+
+function discoverDocumentChange(value: unknown): DiscoveredDocument {
+  const documentEdit = asRecord(value);
+  const resourceKind = getResourceOperationKind(documentEdit);
+  if (resourceKind) {
+    return {
+      kind: "unavailable",
+      reason: `Workspace edit contains the unsupported "${resourceKind}" resource operation.`,
+    };
+  }
+  const parsed = parseTextDocumentEdit(documentEdit);
+  if (!parsed) {
+    return { kind: "unavailable", reason: "Workspace edit has a malformed document change." };
+  }
+  const uri = parsed.textDocument.uri;
+  const file = typeof uri === "string" ? toFilePath(uri) : null;
+  if (!file) {
+    return { kind: "unavailable", reason: "Document change does not contain a valid file URI." };
+  }
+  if (!hasValidDocumentVersion(parsed.textDocument.version, parsed.textDocument)) {
+    return {
+      kind: "unavailable",
+      reason: `Document change for "${file}" has an invalid version.`,
+    };
+  }
+  const normalized = normalizeTextEdits(file, parsed.edit.edits);
+  if (normalized.kind === "unavailable") return normalized;
+  return { kind: "valid", file, editCount: normalized.edits.length };
+}
+
+function hasValidDocumentVersion(version: unknown, textDocument: Record<string, unknown>): boolean {
+  return (
+    Object.hasOwn(textDocument, "version") &&
+    (version === null || (Number.isInteger(version) && (version as number) >= 0))
+  );
+}
+
+function discoverChangesMap(value: unknown): DiscoveryResult {
+  const changes = asRecord(value);
+  if (!changes) {
+    return { kind: "unavailable", reason: "Workspace edit contains no supported changes." };
+  }
+  const files = new Set<string>();
+  let editCount = 0;
+  for (const uri of Object.keys(changes).sort((left, right) => left.localeCompare(right))) {
+    const result = discoverChangesEntry(uri, changes[uri]);
+    if (result.kind === "unavailable") return result;
+    if (result.editCount > 0) {
+      files.add(result.file);
+      if (files.size > MAX_RENAME_DOCUMENTS) {
+        return {
+          kind: "unavailable",
+          reason: "Rename affects too many files to synchronize safely.",
+        };
+      }
+      editCount += result.editCount;
+    }
+  }
+  return finishDiscovery(files, editCount);
+}
+
+function discoverChangesEntry(uri: string, value: unknown): DiscoveredDocument {
+  const file = toFilePath(uri);
+  if (!file) {
+    return { kind: "unavailable", reason: `Workspace edit URI "${uri}" is not a file URI.` };
+  }
+  if (!Array.isArray(value)) {
+    return { kind: "unavailable", reason: "Workspace edit contains malformed changes." };
+  }
+  const normalized = normalizeTextEdits(file, value);
+  if (normalized.kind === "unavailable") return normalized;
+  return { kind: "valid", file, editCount: normalized.edits.length };
+}
+
+function finishDiscovery(files: Set<string>, editCount: number): DiscoveryResult {
+  if (files.size > MAX_RENAME_DOCUMENTS) {
+    return { kind: "unavailable", reason: "Rename affects too many files to synchronize safely." };
+  }
+  if (editCount === 0) {
+    return { kind: "unavailable", reason: "Workspace edit contains no file edits." };
+  }
+  return { kind: "valid", files: [...files].sort((left, right) => left.localeCompare(right)) };
+}