@mrclrchtr/supi-lsp 11.4.0 → 12.0.0

package/src/provider/refactor-planning.ts

@@ -1,14 +1,28 @@
+import { readFileSync } from "node:fs";
 import * as path from "node:path";
 import type {
   CodePosition,
   CodeRequestControl,
+  DisambiguationCandidate,
+  RefactorActionIdentity,
   RefactorResult,
   SourceRange,
 } from "@mrclrchtr/supi-code-runtime/api";
 import { CodeActionTriggerKind } from "vscode-languageserver-types";
-import { codeActionKindsForOperation } from "../config/operation-support.ts";
+import { isCodeActionKindInRange, isCodeActionKindWithin } from "../config/operation-support.ts";
 import type { CodeAction } from "../config/types.ts";
-import type { WorkspaceLspRuntime } from "../session/runtime-registry.ts";
+import { raceRequestControl } from "../session/readiness.ts";
+import type { RoutedCodeActionResponse, WorkspaceLspRuntime } from "../session/runtime-registry.ts";
+import {
+  COMMAND_ONLY_ACTION_REASON,
+  captureCommandAction,
+  captureEligibleActions,
+  commandCandidates,
+  isCommandOnlyAction,
+} from "./refactor-command-capture.ts";
+
+export { COMMAND_ONLY_ACTION_REASON };
+
 import {
   normalizeSemanticEdit,
   type SemanticEditNormalizationContext,
@@ -70,48 +84,135 @@ export function collectCodeActionResults(
   return results;
 }
 
-export async function runFilteredCodeActionRefactor(options: {
+/** Options for one code- or source-action planning request. */
+export interface CodeActionRefactorOptions {
   lsp: WorkspaceLspRuntime;
   file: string;
-  position: CodePosition;
-  operation: "update_imports" | "delete_dead_code";
-  range?: SourceRange;
-  matches: (action: CodeAction) => boolean;
+  range: SourceRange;
+  kind: string;
+  title?: string;
+  /** Operation label used in unavailable reasons. */
+  label: "Code action" | "Source action";
   control?: CodeRequestControl;
-}): Promise<RefactorResult> {
-  const { lsp, file, position, operation, matches } = options;
-  const response = await lsp.codeActions(file, options.range ?? position, options.control, {
-    only: codeActionKindsForOperation(operation),
+}
+
+/**
+ * Plan one code action of the requested kind over a file range.
+ *
+ * `kind` matches itself and its dotted sub-kinds, per the LSP CodeActionKind
+ * hierarchy. Disabled actions never match. `title` narrows matches to one exact
+ * title. Distinct precise plans stay ambiguous. One eligible command-only
+ * action runs once so its pushed edit can be captured; see
+ * `refactor-command-capture.ts`.
+ */
+export async function runCodeActionRefactor(
+  options: CodeActionRefactorOptions,
+): Promise<RefactorResult> {
+  return (await attemptCodeActionRefactor(options)).result;
+}
+
+/** Delays before re-requesting a source action that returned no action of the kind. */
+const SOURCE_ACTION_RETRY_DELAYS_MS = [500, 1000] as const;
+
+/**
+ * Plan a whole-file source action, retrying briefly when a server that
+ * advertises the requested kind returns no action of it.
+ *
+ * typescript-language-server returns no fix-all or unused-code source actions
+ * while diagnostics for a just-opened or just-changed file are pending, and
+ * waits itself about 500 ms in the equivalent quick-fix path.
+ */
+export async function runSourceActionRefactor(
+  options: CodeActionRefactorOptions,
+): Promise<RefactorResult> {
+  let attempt = await attemptCodeActionRefactor(options);
+  for (const delayMs of SOURCE_ACTION_RETRY_DELAYS_MS) {
+    if (!attempt.retryable) break;
+    await raceRequestControl(
+      new Promise((resolve) => setTimeout(resolve, delayMs)),
+      options.control,
+    );
+    attempt = await attemptCodeActionRefactor(options);
+  }
+  return attempt.result;
+}
+
+/**
+ * One planning attempt. `retryable` marks a zero-match response from a server
+ * that advertises the requested kind, so a later request may still return it.
+ */
+async function attemptCodeActionRefactor(
+  options: CodeActionRefactorOptions,
+): Promise<{ result: RefactorResult; retryable: boolean }> {
+  const { lsp, file, range, kind, title, label } = options;
+  const response = await lsp.codeActions(file, range, options.control, {
+    only: [kind],
     triggerKind: CodeActionTriggerKind.Invoked,
   });
-  if (!response || response.reason) {
+  if (!response) {
     return {
-      kind: "unavailable",
-      reason: `Refactor operation "${operation}" is unavailable: ${response?.reason ?? "No code actions are available."}`,
+      result: {
+        kind: "unavailable",
+        reason: `${label} "${kind}" is unavailable: no routed LSP client.`,
+      },
+      retryable: false,
     };
   }
-  const actions = response.value;
-  if (!actions || actions.length === 0) {
-    return {
-      kind: "unavailable",
-      reason: `No code actions are available for refactor operation "${operation}".`,
-    };
+  const roots = [...response.authorizedMutationRoots];
+  const unavailable = (reason: string, retryable = false) => ({
+    result: { kind: "unavailable" as const, reason, authorizedMutationRoots: roots },
+    retryable,
+  });
+  if (response.reason || !response.value) {
+    return unavailable(
+      `${label} "${kind}" is unavailable: ${response.reason ?? "no code actions were returned."}`,
+    );
   }
 
-  const matching = actions.filter(matches);
+  const ofKind = response.value
+    .filter(isTitledCodeAction)
+    .filter(
+      (action) => isCodeActionKindWithin(action.kind, kind) && !Object.hasOwn(action, "disabled"),
+    );
+  if (ofKind.length === 0) {
+    const advertised = advertisedFamilyKinds(response.advertisedKinds, kind);
+    return unavailable(
+      noKindMatchReason(kind, advertised),
+      advertised.kinds.some((candidate) => isCodeActionKindInRange(candidate, kind)),
+    );
+  }
+  const matching = title === undefined ? ofKind : ofKind.filter((action) => action.title === title);
   if (matching.length === 0) {
-    return {
-      kind: "unavailable",
-      reason: `No matching precise code action is available for refactor operation "${operation}".`,
-    };
+    const titles = [...new Set(ofKind.map((action) => `"${action.title}"`))].join(", ");
+    return unavailable(
+      `No "${kind}" code action has the title "${title}". Available titles: ${titles}.`,
+    );
   }
 
-  const context: SemanticEditNormalizationContext = {
+  return { result: await planMatchingActions(options, matching, response), retryable: false };
+}
+
+/** Turn the matching actions into one plan, candidates, or an unavailable reason. */
+async function planMatchingActions(
+  options: CodeActionRefactorOptions,
+  matching: CodeAction[],
+  response: RoutedCodeActionResponse,
+): Promise<RefactorResult> {
+  const { lsp, file, kind } = options;
+  const roots = [...response.authorizedMutationRoots];
+  const unavailable = (reason: string): RefactorResult => ({
+    kind: "unavailable",
+    reason,
+    authorizedMutationRoots: roots,
+  });
+  const plans = collectPrecisePlans(matching, {
     getOpenDocumentVersion: (candidate) => lsp.getOpenDocumentVersion(candidate),
     authorizedMutationRoots: response.authorizedMutationRoots,
-  };
-  const plans = collectPrecisePlans(matching, context);
-  if (plans.precise.length === 1) return plans.precise[0].result;
+  });
+  const [single] = plans.precise;
+  if (plans.precise.length === 1 && single) {
+    return { ...single.result, action: { ...actionIdentity(single.action), provenance: "edit" } };
+  }
   if (plans.precise.length > 1) {
     return {
       kind: "ambiguous",
@@ -120,26 +221,84 @@ export async function runFilteredCodeActionRefactor(options: {
       ),
     };
   }
-  return {
-    kind: "unavailable",
-    reason: plans.unavailableReason
+  if (matching.every(isCommandOnlyAction)) {
+    const eligible = captureEligibleActions(matching, response.advertisedCommands);
+    const [only] = eligible;
+    if (eligible.length === 1 && only) {
+      return captureCommandAction({ lsp, file, action: only, control: options.control });
+    }
+    return eligible.length > 1
+      ? commandCandidates(eligible)
+      : unavailable(COMMAND_ONLY_ACTION_REASON);
+  }
+  return unavailable(
+    plans.unavailableReason
       ? `Matching code action is unavailable: ${plans.unavailableReason}`
-      : `Matching code actions for refactor operation "${operation}" did not produce precise edits.`,
-  };
+      : `Matching "${kind}" code actions did not produce precise edits.`,
+  );
 }
 
-export function isUpdateImportsCodeAction(action: CodeAction): boolean {
-  const kind = typeof action?.kind === "string" ? action.kind : "";
-  return kind === "source.organizeImports" || kind.startsWith("source.organizeImports.");
+/** Compute the zero-based UTF-16 range that covers a file's full current disk text. */
+export function wholeDocumentRange(file: string): SourceRange | null {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf-8");
+  } catch {
+    return null;
+  }
+  const lines = text.split(/\r\n|\r|\n/);
+  return {
+    start: { line: 0, character: 0 },
+    end: { line: lines.length - 1, character: lines.at(-1)?.length ?? 0 },
+  };
 }
 
-export function isDeleteDeadCodeCodeAction(action: CodeAction): boolean {
-  const kind = typeof action?.kind === "string" ? action.kind : "";
-  return codeActionKindsForOperation("delete_dead_code").some(
-    (requested) => kind === requested || kind.startsWith(`${requested}.`),
+function isTitledCodeAction(value: unknown): value is CodeAction {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { title?: unknown }).title === "string"
   );
 }
 
+/** Advertised kinds in one CodeActionKind family, such as `source*`. */
+interface AdvertisedFamilyKinds {
+  /** Listed non-empty kinds in the requested kind's top-level family. */
+  readonly kinds: readonly string[];
+  /** The server lists CodeActionKind.Empty or no kinds, so it may return any kind. */
+  readonly anyKind: boolean;
+}
+
+function advertisedFamilyKinds(
+  advertised: readonly string[] | undefined,
+  kind: string,
+): AdvertisedFamilyKinds {
+  const family = kind.split(".")[0] ?? kind;
+  return {
+    kinds: (advertised ?? []).filter(
+      (candidate) => candidate !== "" && isCodeActionKindWithin(candidate, family),
+    ),
+    anyKind: !advertised || advertised.includes(""),
+  };
+}
+
+function noKindMatchReason(kind: string, advertised: AdvertisedFamilyKinds): string {
+  const parts = [`No code action matches kind "${kind}" here.`];
+  if (advertised.kinds.length > 0) {
+    parts.push(`Server-advertised kinds: ${advertised.kinds.join(", ")}.`);
+  }
+  if (advertised.anyKind) {
+    parts.push("The server may return any code-action kind but returned none of this kind.");
+  } else if (advertised.kinds.length === 0) {
+    parts.push("The server advertises no kinds in this family.");
+  }
+  return parts.join(" ");
+}
+
+function actionIdentity(action: CodeAction): RefactorActionIdentity {
+  return { kind: typeof action.kind === "string" ? action.kind : "", title: action.title };
+}
+
 interface PreciseCodeActionPlan {
   action: CodeAction;
   result: Extract<RefactorResult, { kind: "precise" }>;
@@ -187,18 +346,14 @@ function refactorCandidate(
   result: Extract<RefactorResult, { kind: "precise" }>,
   index: number,
   plans: readonly { action: CodeAction }[],
-): {
-  description: string;
-  file?: string;
-  line?: number;
-  character?: number;
-} {
+): DisambiguationCandidate {
   const firstEdit = result.edits.edits[0];
   const sameTitleCount = plans.filter((plan) => plan.action.title === action.title).length;
   const description =
     sameTitleCount > 1 ? `${action.title} (alternative ${index + 1})` : action.title;
   return {
     description,
+    ...actionIdentity(action),
     ...(firstEdit
       ? {
           file: firstEdit.file,

package/src/session/route-boundary.ts

@@ -0,0 +1,26 @@
+/** Project-root boundary for mutation requests on one routed client. */
+
+import { realpathSync } from "node:fs";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
+
+/**
+ * Return why a file cannot be refactored by the client routed to it, or null.
+ *
+ * A file without its own project markers routes to a server rooted at the
+ * session directory. Its edits would fail the apply-time root check, so refuse
+ * before the request. Real paths are compared, so a link inside the root
+ * cannot reach an outside file.
+ */
+export function outsideRouteRootReason(file: string, root: string): string | null {
+  return isWithinOrEqual(canonical(root), canonical(file))
+    ? null
+    : `File ${file} is outside the language server's project root ${root}.`;
+}
+
+function canonical(file: string): string {
+  try {
+    return realpathSync(file);
+  } catch {
+    return file;
+  }
+}

package/src/session/runtime-registry.ts

@@ -18,6 +18,8 @@ import {
 import { resolveToolPath as resolveSessionPath } from "@mrclrchtr/supi-core/path";
 import { createSessionStateRegistry } from "@mrclrchtr/supi-core/session";
 import { CodeActionTriggerKind } from "vscode-languageserver-types";
+import type { CommandEditCaptureResult } from "../client/client-edit-capture.ts";
+import { advertisedCodeActionKinds } from "../config/operation-support.ts";
 import type {
   CodeAction,
   Diagnostic,
@@ -39,7 +41,12 @@ import type {
   WorkspaceSentinelSyncResult,
 } from "../diagnostics/workspace-sentinels.ts";
 import type { LspManager } from "../manager/manager.ts";
+import {
+  COMMAND_ONLY_ACTION_REASON,
+  captureEligibleActions,
+} from "../provider/refactor-command-capture.ts";
 import { raceReadinessValue } from "./readiness.ts";
+import { outsideRouteRootReason } from "./route-boundary.ts";
 import type {
   DiagnosticEvidenceSummary,
   ProcessCrashRecoveryReport,
@@ -49,6 +56,7 @@ import type {
 import { runRoutedRename } from "./runtime-rename.ts";
 import type {
   BulkTrackFilesResult,
+  RoutedCodeActionResponse,
   RoutedMutationResponse,
   SemanticReadinessResult,
   WorkspaceCodeActionRequestOptions,
@@ -56,6 +64,9 @@ import type {
   WorkspaceLspRuntimeState,
 } from "./workspace-lsp-runtime.ts";
 
+/** Upper bound for a server command run to capture its pushed edit. */
+const COMMAND_CAPTURE_TIMEOUT_MS = 10_000;
+
 export type {
   ProcessCrashDiagnosticDemand,
   WorkspaceLspDiagnosticSurface,
@@ -84,6 +95,7 @@ export {
 export type {
   BulkTrackFileOutcome,
   BulkTrackFilesResult,
+  RoutedCodeActionResponse,
   RoutedMutationDocumentSnapshot,
   RoutedMutationResponse,
   SemanticReadinessResult,
@@ -288,12 +300,39 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     return this.manager.getOpenDocumentVersion(this.resolveFilePath(filePath));
   }
 
+  async captureCodeActionEdit(
+    filePath: string,
+    action: CodeAction,
+    control?: CodeRequestControl,
+  ): Promise<RoutedMutationResponse<CommandEditCaptureResult | null> | null> {
+    const resolvedPath = this.resolveFilePath(filePath);
+    const client = await this.manager.ensureFileOpen(resolvedPath, {
+      recoverProcessCrash: true,
+      protectInputs: true,
+      control,
+    });
+    if (!client) return null;
+    const authorizedMutationRoots = [client.root];
+    const outside = outsideRouteRootReason(resolvedPath, client.root);
+    if (outside) return { value: null, authorizedMutationRoots, reason: outside };
+    const listed = client.serverCapabilities?.executeCommandProvider?.commands;
+    const [eligible] = captureEligibleActions([action], Array.isArray(listed) ? listed : undefined);
+    if (!eligible) {
+      return { value: null, authorizedMutationRoots, reason: COMMAND_ONLY_ACTION_REASON };
+    }
+    const value = await client.captureCommandEdits(eligible.command, {
+      timeoutMs: COMMAND_CAPTURE_TIMEOUT_MS,
+      ...(control ? { control } : {}),
+    });
+    return { value, authorizedMutationRoots };
+  }
+
   async codeActions(
     filePath: string,
     positionOrRange: Position | Range,
     control?: CodeRequestControl,
     options?: WorkspaceCodeActionRequestOptions,
-  ): Promise<RoutedMutationResponse<CodeAction[] | null> | null> {
+  ): Promise<RoutedCodeActionResponse | null> {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
@@ -301,6 +340,10 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       control,
     });
     if (!client) return null;
+    const outside = outsideRouteRootReason(resolvedPath, client.root);
+    if (outside) {
+      return { value: null, authorizedMutationRoots: [client.root], reason: outside };
+    }
 
     const range = isRange(positionOrRange)
       ? positionOrRange
@@ -315,21 +358,23 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       triggerKind: options?.triggerKind ?? CodeActionTriggerKind.Invoked,
       ...(options?.only ? { only: [...options.only] } : {}),
     };
+    const advertisedKinds = advertisedCodeActionKinds(client.serverCapabilities ?? null);
+    const advertisedCommands = client.serverCapabilities?.executeCommandProvider?.commands;
+    const routed = {
+      authorizedMutationRoots: [client.root],
+      ...(advertisedKinds ? { advertisedKinds } : {}),
+      ...(Array.isArray(advertisedCommands) ? { advertisedCommands } : {}),
+    };
     if (typeof client.codeActionsDetailed === "function") {
       const result = await client.codeActionsDetailed(resolvedPath, range, context, control);
-      return {
-        value: result.kind === "completed" ? result.data : null,
-        authorizedMutationRoots: [client.root],
-        ...(result.kind === "unavailable"
-          ? { reason: result.reason }
-          : result.data === null
-            ? { reason: "LSP server returned no code actions." }
-            : {}),
-      };
+      // A completed `null` result means the server has no actions here (LSP spec).
+      return result.kind === "completed"
+        ? { ...routed, value: result.data ?? [] }
+        : { ...routed, value: null, reason: result.reason };
     }
     return {
-      value: await client.codeActions(resolvedPath, range, context, control),
-      authorizedMutationRoots: [client.root],
+      ...routed,
+      value: (await client.codeActions(resolvedPath, range, context, control)) ?? [],
     };
   }
 

package/src/session/runtime-rename.ts

@@ -5,6 +5,7 @@ import type { SemanticInputDocumentSnapshot } from "../client/client-semantic-in
 import type { Position, WorkspaceEdit } from "../config/types.ts";
 import type { LspManager } from "../manager/manager.ts";
 import { discoverSemanticEditFiles } from "../provider/semantic-edit-discovery.ts";
+import { outsideRouteRootReason } from "./route-boundary.ts";
 import type {
   RoutedMutationDocumentSnapshot,
   RoutedMutationResponse,
@@ -26,6 +27,8 @@ export async function runRoutedRename(options: {
   });
   if (!client) return null;
   const authorizedMutationRoots = [client.root];
+  const outside = outsideRouteRootReason(file, client.root);
+  if (outside) return { value: null, authorizedMutationRoots, reason: outside };
 
   if (typeof client.renameDetailedWithSnapshots === "function") {
     return renameWithSnapshots({

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

@@ -1,4 +1,5 @@
 import type { CodeQueryResult, CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
+import type { CommandEditCaptureResult } from "../client/client-edit-capture.ts";
 import type {
   CodeAction,
   CodeActionContext,
@@ -80,6 +81,14 @@ export interface RoutedMutationResponse<T> {
   readonly reason?: string;
 }
 
+/** One code-action response with the routed server's negotiated kinds. */
+export interface RoutedCodeActionResponse extends RoutedMutationResponse<CodeAction[] | null> {
+  /** Negotiated `codeActionProvider.codeActionKinds`; undefined when the server did not narrow them. */
+  readonly advertisedKinds?: readonly string[];
+  /** Negotiated `executeCommandProvider.commands`; undefined when the server lists none. */
+  readonly advertisedCommands?: readonly string[];
+}
+
 /** Extra protocol context for one explicit code-action request. */
 export interface WorkspaceCodeActionRequestOptions {
   /** Operation-specific CodeActionKind filters. */
@@ -164,7 +173,19 @@ export interface WorkspaceLspRuntime extends WorkspaceLspDiagnosticSurface {
     positionOrRange: Position | Range,
     control?: CodeRequestControl,
     options?: WorkspaceCodeActionRequestOptions,
-  ): Promise<RoutedMutationResponse<CodeAction[] | null> | null>;
+  ): Promise<RoutedCodeActionResponse | null>;
+  /**
+   * Run the command of one command-only code action on the client routed to
+   * `filePath` and capture the single edit the server pushes. No pushed edit is
+   * applied. The runtime enforces eligibility itself: a `refactor*`,
+   * `source.organizeImports*`, or `source.fixAll*` kind, and a command the
+   * server lists when it lists any; other actions are unavailable unrun.
+   */
+  captureCodeActionEdit(
+    filePath: string,
+    action: CodeAction,
+    control?: CodeRequestControl,
+  ): Promise<RoutedMutationResponse<CommandEditCaptureResult | null> | null>;
   getOpenDocumentVersion(filePath: string): number | null;
   /**
    * Wait for file readiness; an explicit refresh may make one shared route