@mrclrchtr/supi-code-intelligence 11.3.0 → 12.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +15 -9
  3. package/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  4. package/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +3 -1
  5. package/node_modules/@mrclrchtr/supi-code-runtime/src/declaration-level.ts +34 -0
  6. package/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts +64 -28
  7. package/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  8. package/node_modules/@mrclrchtr/supi-lsp/README.md +22 -17
  9. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  10. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +3 -1
  11. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/declaration-level.ts +34 -0
  12. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts +64 -28
  13. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  14. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/classes/range.js +2 -2
  15. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/internal/constants.js +30 -0
  16. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/internal/trim-comparator-whitespace.js +438 -0
  17. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/package.json +1 -1
  18. package/node_modules/@mrclrchtr/supi-lsp/package.json +3 -3
  19. package/node_modules/@mrclrchtr/supi-lsp/src/api.ts +2 -2
  20. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostic-capabilities.ts +13 -3
  21. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostics.ts +25 -9
  22. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-document-sync.ts +7 -5
  23. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-edit-capture.ts +258 -0
  24. package/node_modules/@mrclrchtr/supi-lsp/src/client/client.ts +64 -11
  25. package/node_modules/@mrclrchtr/supi-lsp/src/config/capabilities.ts +8 -0
  26. package/node_modules/@mrclrchtr/supi-lsp/src/config/operation-support.ts +48 -79
  27. package/node_modules/@mrclrchtr/supi-lsp/src/config/tsconfig-scope.ts +10 -0
  28. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-typescript-coverage.ts +118 -0
  29. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager.ts +67 -3
  30. package/node_modules/@mrclrchtr/supi-lsp/src/manager/typescript-file-local.ts +87 -0
  31. package/node_modules/@mrclrchtr/supi-lsp/src/provider/lsp-refactor-provider.ts +21 -35
  32. package/node_modules/@mrclrchtr/supi-lsp/src/provider/refactor-command-capture.ts +139 -0
  33. package/node_modules/@mrclrchtr/supi-lsp/src/provider/refactor-planning.ts +202 -47
  34. package/node_modules/@mrclrchtr/supi-lsp/src/provider/semantic-symbol-mapper.ts +22 -17
  35. package/node_modules/@mrclrchtr/supi-lsp/src/session/route-boundary.ts +26 -0
  36. package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-registry.ts +106 -16
  37. package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-rename.ts +3 -0
  38. package/node_modules/@mrclrchtr/supi-lsp/src/session/workspace-lsp-runtime.ts +22 -1
  39. package/node_modules/@mrclrchtr/supi-tree-sitter/README.md +1 -1
  40. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  41. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +3 -1
  42. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/declaration-level.ts +34 -0
  43. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts +64 -28
  44. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  45. package/node_modules/@mrclrchtr/supi-tree-sitter/package.json +3 -3
  46. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/tsx/tree-sitter-tsx.wasm +0 -0
  47. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/tsx/tree-sitter-tsx.wasm.json +5 -1
  48. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/typescript/tree-sitter-typescript.wasm +0 -0
  49. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/typescript/tree-sitter-typescript.wasm.json +5 -1
  50. package/node_modules/@mrclrchtr/supi-tree-sitter/src/coordinates.ts +16 -2
  51. package/node_modules/@mrclrchtr/supi-tree-sitter/src/session/structural-worker-client.ts +3 -2
  52. package/node_modules/@mrclrchtr/supi-tree-sitter/src/syntax-errors.ts +2 -0
  53. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/call-range.ts +94 -0
  54. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/call-sites.ts +26 -6
  55. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/callees.ts +6 -3
  56. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/exports.ts +13 -4
  57. package/node_modules/@mrclrchtr/supi-tree-sitter/src/worker/runtime.ts +1 -9
  58. package/package.json +5 -5
  59. package/src/analysis/health/server-status.ts +41 -12
  60. package/src/analysis/helpers.ts +0 -7
  61. package/src/analysis/relations/implementations.ts +5 -0
  62. package/src/analysis/relations/references.ts +5 -0
  63. package/src/analysis/target/anchored-structural.ts +4 -1
  64. package/src/analysis/target/file-merge.ts +162 -0
  65. package/src/analysis/target/file-outline-omissions.ts +146 -0
  66. package/src/analysis/target/file-refinement.ts +7 -7
  67. package/src/analysis/target/file.ts +44 -156
  68. package/src/analysis/target/symbol.ts +5 -1
  69. package/src/analysis/target/types.ts +32 -6
  70. package/src/api.ts +1 -1
  71. package/src/app/app.ts +9 -3
  72. package/src/session/find-types.ts +8 -4
  73. package/src/session/find-workflow.ts +11 -16
  74. package/src/session/graph/collect.ts +2 -0
  75. package/src/session/graph-types.ts +3 -1
  76. package/src/session/graph-workflow.ts +5 -4
  77. package/src/session/input/health-refactor.ts +48 -34
  78. package/src/session/input/workflows.ts +45 -46
  79. package/src/session/inspect/file-point.ts +2 -2
  80. package/src/session/inspect-types.ts +1 -1
  81. package/src/session/inspect-workflow.ts +3 -3
  82. package/src/session/orientation/workspace-context.ts +3 -0
  83. package/src/session/orientation-workflow.ts +6 -3
  84. package/src/session/refactor-file-actions.ts +122 -0
  85. package/src/session/refactor-plan-pipeline.ts +152 -0
  86. package/src/session/refactor-plans.ts +18 -15
  87. package/src/session/refactor-types.ts +24 -12
  88. package/src/session/refactor-workflow.ts +70 -244
  89. package/src/session/session.ts +87 -12
  90. package/src/session/target-workflow.ts +23 -21
  91. package/src/tool/code_find/execute.ts +6 -7
  92. package/src/tool/code_find/spec.ts +9 -16
  93. package/src/tool/code_find/tui.ts +12 -6
  94. package/src/tool/code_graph/section.ts +4 -0
  95. package/src/tool/code_graph/spec.ts +6 -0
  96. package/src/tool/code_health/spec.ts +6 -0
  97. package/src/tool/code_health/structured-schema.ts +4 -4
  98. package/src/tool/code_health/structured.ts +15 -17
  99. package/src/tool/code_inspect/execute.ts +1 -1
  100. package/src/tool/code_inspect/markdown.ts +33 -6
  101. package/src/tool/code_inspect/result.ts +1 -1
  102. package/src/tool/code_inspect/spec.ts +14 -6
  103. package/src/tool/code_inspect/structured.ts +2 -2
  104. package/src/tool/code_inspect/tui.ts +2 -2
  105. package/src/tool/code_orientation/directory-navigation.ts +20 -31
  106. package/src/tool/code_orientation/spec.ts +8 -0
  107. package/src/tool/code_orientation/workspace-output.ts +40 -13
  108. package/src/tool/code_orientation/workspace-sections.ts +45 -2
  109. package/src/tool/code_refactor_apply/result.ts +2 -1
  110. package/src/tool/code_refactor_apply/spec.ts +7 -0
  111. package/src/tool/code_refactor_plan/execute.ts +0 -2
  112. package/src/tool/code_refactor_plan/result.ts +23 -13
  113. package/src/tool/code_refactor_plan/spec.ts +8 -2
  114. package/src/tool/code_refactor_plan/structured.ts +59 -12
  115. package/src/tool/code_refactor_plan/tui.ts +14 -17
  116. package/src/tool/code_resolve/guidance.ts +1 -1
  117. package/src/tool/code_resolve/markdown.ts +121 -34
  118. package/src/tool/code_resolve/result.ts +18 -15
  119. package/src/tool/code_resolve/spec.ts +6 -0
  120. package/src/tool/code_resolve/structured.ts +43 -10
  121. package/src/tool/namespace.ts +14 -0
  122. package/src/tool/refactor-markdown.ts +55 -15
  123. package/src/tool/register.ts +3 -0
  124. package/src/tool/result/model-budget.ts +2 -2
  125. package/src/tool/result/refactor-preview.ts +118 -0
  126. package/src/tool/result/refactor-unavailable.ts +16 -0
  127. package/src/tool/result/refactor.ts +8 -2
  128. package/src/tool/result/types.ts +13 -10
  129. package/src/tool/schemas.ts +63 -20
  130. package/src/tool/specs.ts +3 -0
  131. package/src/ui/status-overlay.ts +1 -1
  132. package/src/ui/tui/common.ts +10 -10
@@ -0,0 +1,139 @@
1
+ /**
2
+ * Plan command-only code actions by capturing the edit their command pushes.
3
+ *
4
+ * Only `refactor*`, `source.organizeImports*`, and `source.fixAll*` commands
5
+ * may run, and only when the server lists the command (if it lists any). Other
6
+ * source commands can have side effects outside the editor, so they never run.
7
+ * Several eligible actions stay ambiguous without running any command.
8
+ */
9
+
10
+ import type {
11
+ CodeRequestControl,
12
+ DisambiguationCandidate,
13
+ DocumentEditPrecondition,
14
+ RefactorResult,
15
+ } from "@mrclrchtr/supi-code-runtime/api";
16
+ import { isCodeActionKindWithin } from "../config/operation-support.ts";
17
+ import type { CodeAction, Command } from "../config/types.ts";
18
+ import type { WorkspaceLspRuntime } from "../session/workspace-lsp-runtime.ts";
19
+ import { normalizeSemanticEdit } from "./semantic-edit-normalizer.ts";
20
+
21
+ const CAPTURE_ELIGIBLE_KINDS = ["refactor", "source.organizeImports", "source.fixAll"] as const;
22
+
23
+ /**
24
+ * Stable reason for command-only actions SuPi will not run: an ineligible kind
25
+ * or a command the server does not list.
26
+ */
27
+ export const COMMAND_ONLY_ACTION_REASON =
28
+ "Matching code actions only run a server command that SuPi does not run for preview.";
29
+
30
+ /** A code action whose only effect is a server command. */
31
+ export type CommandOnlyAction = CodeAction & { command: Command; kind: string };
32
+
33
+ /** Whether a code action has a command and no edit. */
34
+ export function isCommandOnlyAction(action: CodeAction): boolean {
35
+ return Object.hasOwn(action, "command") && !action.edit;
36
+ }
37
+
38
+ /**
39
+ * Select the command-only actions SuPi may run to capture an edit: an eligible
40
+ * kind, and a command the server lists when it lists any.
41
+ */
42
+ export function captureEligibleActions(
43
+ actions: readonly CodeAction[],
44
+ advertisedCommands: readonly string[] | undefined,
45
+ ): CommandOnlyAction[] {
46
+ return actions.filter((action): action is CommandOnlyAction => {
47
+ const command = action.command;
48
+ return (
49
+ isCommandOnlyAction(action) &&
50
+ typeof action.kind === "string" &&
51
+ typeof command?.command === "string" &&
52
+ CAPTURE_ELIGIBLE_KINDS.some((kind) => isCodeActionKindWithin(action.kind, kind)) &&
53
+ (advertisedCommands === undefined || advertisedCommands.includes(command.command))
54
+ );
55
+ });
56
+ }
57
+
58
+ /** Candidates for several eligible command-only actions; no command has run. */
59
+ export function commandCandidates(actions: readonly CommandOnlyAction[]): RefactorResult {
60
+ return {
61
+ kind: "ambiguous",
62
+ candidates: actions.map(
63
+ (action): DisambiguationCandidate => ({
64
+ description: action.title,
65
+ kind: action.kind,
66
+ title: action.title,
67
+ }),
68
+ ),
69
+ };
70
+ }
71
+
72
+ /**
73
+ * Run one action's command, capture its single pushed edit, and normalize it
74
+ * like a direct edit. Versioned preconditions move to the resynced versions,
75
+ * which hold the same content.
76
+ */
77
+ export async function captureCommandAction(options: {
78
+ lsp: WorkspaceLspRuntime;
79
+ file: string;
80
+ action: CommandOnlyAction;
81
+ control?: CodeRequestControl;
82
+ }): Promise<RefactorResult> {
83
+ const { lsp, file, action, control } = options;
84
+ const response = await lsp.captureCodeActionEdit(file, action, control);
85
+ if (!response) {
86
+ return { kind: "unavailable", reason: "No routed LSP client could run the command." };
87
+ }
88
+ const roots = [...response.authorizedMutationRoots];
89
+ const capture = response.value;
90
+ if (!capture || capture.kind === "unavailable") {
91
+ return {
92
+ kind: "unavailable",
93
+ reason: `Command for "${action.title}" is unavailable: ${capture?.reason ?? response.reason ?? "no result."}`,
94
+ authorizedMutationRoots: roots,
95
+ };
96
+ }
97
+
98
+ const before = new Map(capture.resynced.map((entry) => [entry.file, entry]));
99
+ const result = normalizeSemanticEdit(
100
+ { kind: "workspace-edit", edit: capture.edit },
101
+ {
102
+ // Captured edits target the versions from before the resync.
103
+ getOpenDocumentVersion: (candidate) => {
104
+ const current = lsp.getOpenDocumentVersion(candidate);
105
+ const versions = before.get(candidate);
106
+ return versions && current === versions.to ? versions.from : current;
107
+ },
108
+ authorizedMutationRoots: response.authorizedMutationRoots,
109
+ },
110
+ );
111
+ if (result.kind !== "precise") {
112
+ return result.kind === "unavailable"
113
+ ? {
114
+ kind: "unavailable",
115
+ reason: `Captured edit for "${action.title}" could not produce precise edits: ${result.reason}`,
116
+ authorizedMutationRoots: roots,
117
+ }
118
+ : result;
119
+ }
120
+ const preconditions = result.edits.documentPreconditions?.map((precondition) =>
121
+ rebase(precondition, before),
122
+ );
123
+ return {
124
+ ...result,
125
+ edits: { ...result.edits, ...(preconditions ? { documentPreconditions: preconditions } : {}) },
126
+ action: { kind: action.kind, title: action.title, provenance: "captured-command" },
127
+ };
128
+ }
129
+
130
+ function rebase(
131
+ precondition: DocumentEditPrecondition,
132
+ resynced: ReadonlyMap<string, { from: number; to: number }>,
133
+ ): DocumentEditPrecondition {
134
+ if (precondition.kind === "disk-content") return precondition;
135
+ const versions = resynced.get(precondition.file);
136
+ return versions && precondition.version === versions.from
137
+ ? { ...precondition, version: versions.to }
138
+ : precondition;
139
+ }
@@ -1,14 +1,28 @@
1
+ import { readFileSync } from "node:fs";
1
2
  import * as path from "node:path";
2
3
  import type {
3
4
  CodePosition,
4
5
  CodeRequestControl,
6
+ DisambiguationCandidate,
7
+ RefactorActionIdentity,
5
8
  RefactorResult,
6
9
  SourceRange,
7
10
  } from "@mrclrchtr/supi-code-runtime/api";
8
11
  import { CodeActionTriggerKind } from "vscode-languageserver-types";
9
- import { codeActionKindsForOperation } from "../config/operation-support.ts";
12
+ import { isCodeActionKindInRange, isCodeActionKindWithin } from "../config/operation-support.ts";
10
13
  import type { CodeAction } from "../config/types.ts";
11
- import type { WorkspaceLspRuntime } from "../session/runtime-registry.ts";
14
+ import { raceRequestControl } from "../session/readiness.ts";
15
+ import type { RoutedCodeActionResponse, WorkspaceLspRuntime } from "../session/runtime-registry.ts";
16
+ import {
17
+ COMMAND_ONLY_ACTION_REASON,
18
+ captureCommandAction,
19
+ captureEligibleActions,
20
+ commandCandidates,
21
+ isCommandOnlyAction,
22
+ } from "./refactor-command-capture.ts";
23
+
24
+ export { COMMAND_ONLY_ACTION_REASON };
25
+
12
26
  import {
13
27
  normalizeSemanticEdit,
14
28
  type SemanticEditNormalizationContext,
@@ -70,48 +84,135 @@ export function collectCodeActionResults(
70
84
  return results;
71
85
  }
72
86
 
73
- export async function runFilteredCodeActionRefactor(options: {
87
+ /** Options for one code- or source-action planning request. */
88
+ export interface CodeActionRefactorOptions {
74
89
  lsp: WorkspaceLspRuntime;
75
90
  file: string;
76
- position: CodePosition;
77
- operation: "update_imports" | "delete_dead_code";
78
- range?: SourceRange;
79
- matches: (action: CodeAction) => boolean;
91
+ range: SourceRange;
92
+ kind: string;
93
+ title?: string;
94
+ /** Operation label used in unavailable reasons. */
95
+ label: "Code action" | "Source action";
80
96
  control?: CodeRequestControl;
81
- }): Promise<RefactorResult> {
82
- const { lsp, file, position, operation, matches } = options;
83
- const response = await lsp.codeActions(file, options.range ?? position, options.control, {
84
- only: codeActionKindsForOperation(operation),
97
+ }
98
+
99
+ /**
100
+ * Plan one code action of the requested kind over a file range.
101
+ *
102
+ * `kind` matches itself and its dotted sub-kinds, per the LSP CodeActionKind
103
+ * hierarchy. Disabled actions never match. `title` narrows matches to one exact
104
+ * title. Distinct precise plans stay ambiguous. One eligible command-only
105
+ * action runs once so its pushed edit can be captured; see
106
+ * `refactor-command-capture.ts`.
107
+ */
108
+ export async function runCodeActionRefactor(
109
+ options: CodeActionRefactorOptions,
110
+ ): Promise<RefactorResult> {
111
+ return (await attemptCodeActionRefactor(options)).result;
112
+ }
113
+
114
+ /** Delays before re-requesting a source action that returned no action of the kind. */
115
+ const SOURCE_ACTION_RETRY_DELAYS_MS = [500, 1000] as const;
116
+
117
+ /**
118
+ * Plan a whole-file source action, retrying briefly when a server that
119
+ * advertises the requested kind returns no action of it.
120
+ *
121
+ * typescript-language-server returns no fix-all or unused-code source actions
122
+ * while diagnostics for a just-opened or just-changed file are pending, and
123
+ * waits itself about 500 ms in the equivalent quick-fix path.
124
+ */
125
+ export async function runSourceActionRefactor(
126
+ options: CodeActionRefactorOptions,
127
+ ): Promise<RefactorResult> {
128
+ let attempt = await attemptCodeActionRefactor(options);
129
+ for (const delayMs of SOURCE_ACTION_RETRY_DELAYS_MS) {
130
+ if (!attempt.retryable) break;
131
+ await raceRequestControl(
132
+ new Promise((resolve) => setTimeout(resolve, delayMs)),
133
+ options.control,
134
+ );
135
+ attempt = await attemptCodeActionRefactor(options);
136
+ }
137
+ return attempt.result;
138
+ }
139
+
140
+ /**
141
+ * One planning attempt. `retryable` marks a zero-match response from a server
142
+ * that advertises the requested kind, so a later request may still return it.
143
+ */
144
+ async function attemptCodeActionRefactor(
145
+ options: CodeActionRefactorOptions,
146
+ ): Promise<{ result: RefactorResult; retryable: boolean }> {
147
+ const { lsp, file, range, kind, title, label } = options;
148
+ const response = await lsp.codeActions(file, range, options.control, {
149
+ only: [kind],
85
150
  triggerKind: CodeActionTriggerKind.Invoked,
86
151
  });
87
- if (!response || response.reason) {
152
+ if (!response) {
88
153
  return {
89
- kind: "unavailable",
90
- reason: `Refactor operation "${operation}" is unavailable: ${response?.reason ?? "No code actions are available."}`,
154
+ result: {
155
+ kind: "unavailable",
156
+ reason: `${label} "${kind}" is unavailable: no routed LSP client.`,
157
+ },
158
+ retryable: false,
91
159
  };
92
160
  }
93
- const actions = response.value;
94
- if (!actions || actions.length === 0) {
95
- return {
96
- kind: "unavailable",
97
- reason: `No code actions are available for refactor operation "${operation}".`,
98
- };
161
+ const roots = [...response.authorizedMutationRoots];
162
+ const unavailable = (reason: string, retryable = false) => ({
163
+ result: { kind: "unavailable" as const, reason, authorizedMutationRoots: roots },
164
+ retryable,
165
+ });
166
+ if (response.reason || !response.value) {
167
+ return unavailable(
168
+ `${label} "${kind}" is unavailable: ${response.reason ?? "no code actions were returned."}`,
169
+ );
99
170
  }
100
171
 
101
- const matching = actions.filter(matches);
172
+ const ofKind = response.value
173
+ .filter(isTitledCodeAction)
174
+ .filter(
175
+ (action) => isCodeActionKindWithin(action.kind, kind) && !Object.hasOwn(action, "disabled"),
176
+ );
177
+ if (ofKind.length === 0) {
178
+ const advertised = advertisedFamilyKinds(response.advertisedKinds, kind);
179
+ return unavailable(
180
+ noKindMatchReason(kind, advertised),
181
+ advertised.kinds.some((candidate) => isCodeActionKindInRange(candidate, kind)),
182
+ );
183
+ }
184
+ const matching = title === undefined ? ofKind : ofKind.filter((action) => action.title === title);
102
185
  if (matching.length === 0) {
103
- return {
104
- kind: "unavailable",
105
- reason: `No matching precise code action is available for refactor operation "${operation}".`,
106
- };
186
+ const titles = [...new Set(ofKind.map((action) => `"${action.title}"`))].join(", ");
187
+ return unavailable(
188
+ `No "${kind}" code action has the title "${title}". Available titles: ${titles}.`,
189
+ );
107
190
  }
108
191
 
109
- const context: SemanticEditNormalizationContext = {
192
+ return { result: await planMatchingActions(options, matching, response), retryable: false };
193
+ }
194
+
195
+ /** Turn the matching actions into one plan, candidates, or an unavailable reason. */
196
+ async function planMatchingActions(
197
+ options: CodeActionRefactorOptions,
198
+ matching: CodeAction[],
199
+ response: RoutedCodeActionResponse,
200
+ ): Promise<RefactorResult> {
201
+ const { lsp, file, kind } = options;
202
+ const roots = [...response.authorizedMutationRoots];
203
+ const unavailable = (reason: string): RefactorResult => ({
204
+ kind: "unavailable",
205
+ reason,
206
+ authorizedMutationRoots: roots,
207
+ });
208
+ const plans = collectPrecisePlans(matching, {
110
209
  getOpenDocumentVersion: (candidate) => lsp.getOpenDocumentVersion(candidate),
111
210
  authorizedMutationRoots: response.authorizedMutationRoots,
112
- };
113
- const plans = collectPrecisePlans(matching, context);
114
- if (plans.precise.length === 1) return plans.precise[0].result;
211
+ });
212
+ const [single] = plans.precise;
213
+ if (plans.precise.length === 1 && single) {
214
+ return { ...single.result, action: { ...actionIdentity(single.action), provenance: "edit" } };
215
+ }
115
216
  if (plans.precise.length > 1) {
116
217
  return {
117
218
  kind: "ambiguous",
@@ -120,26 +221,84 @@ export async function runFilteredCodeActionRefactor(options: {
120
221
  ),
121
222
  };
122
223
  }
123
- return {
124
- kind: "unavailable",
125
- reason: plans.unavailableReason
224
+ if (matching.every(isCommandOnlyAction)) {
225
+ const eligible = captureEligibleActions(matching, response.advertisedCommands);
226
+ const [only] = eligible;
227
+ if (eligible.length === 1 && only) {
228
+ return captureCommandAction({ lsp, file, action: only, control: options.control });
229
+ }
230
+ return eligible.length > 1
231
+ ? commandCandidates(eligible)
232
+ : unavailable(COMMAND_ONLY_ACTION_REASON);
233
+ }
234
+ return unavailable(
235
+ plans.unavailableReason
126
236
  ? `Matching code action is unavailable: ${plans.unavailableReason}`
127
- : `Matching code actions for refactor operation "${operation}" did not produce precise edits.`,
128
- };
237
+ : `Matching "${kind}" code actions did not produce precise edits.`,
238
+ );
129
239
  }
130
240
 
131
- export function isUpdateImportsCodeAction(action: CodeAction): boolean {
132
- const kind = typeof action?.kind === "string" ? action.kind : "";
133
- return kind === "source.organizeImports" || kind.startsWith("source.organizeImports.");
241
+ /** Compute the zero-based UTF-16 range that covers a file's full current disk text. */
242
+ export function wholeDocumentRange(file: string): SourceRange | null {
243
+ let text: string;
244
+ try {
245
+ text = readFileSync(file, "utf-8");
246
+ } catch {
247
+ return null;
248
+ }
249
+ const lines = text.split(/\r\n|\r|\n/);
250
+ return {
251
+ start: { line: 0, character: 0 },
252
+ end: { line: lines.length - 1, character: lines.at(-1)?.length ?? 0 },
253
+ };
134
254
  }
135
255
 
136
- export function isDeleteDeadCodeCodeAction(action: CodeAction): boolean {
137
- const kind = typeof action?.kind === "string" ? action.kind : "";
138
- return codeActionKindsForOperation("delete_dead_code").some(
139
- (requested) => kind === requested || kind.startsWith(`${requested}.`),
256
+ function isTitledCodeAction(value: unknown): value is CodeAction {
257
+ return (
258
+ typeof value === "object" &&
259
+ value !== null &&
260
+ typeof (value as { title?: unknown }).title === "string"
140
261
  );
141
262
  }
142
263
 
264
+ /** Advertised kinds in one CodeActionKind family, such as `source*`. */
265
+ interface AdvertisedFamilyKinds {
266
+ /** Listed non-empty kinds in the requested kind's top-level family. */
267
+ readonly kinds: readonly string[];
268
+ /** The server lists CodeActionKind.Empty or no kinds, so it may return any kind. */
269
+ readonly anyKind: boolean;
270
+ }
271
+
272
+ function advertisedFamilyKinds(
273
+ advertised: readonly string[] | undefined,
274
+ kind: string,
275
+ ): AdvertisedFamilyKinds {
276
+ const family = kind.split(".")[0] ?? kind;
277
+ return {
278
+ kinds: (advertised ?? []).filter(
279
+ (candidate) => candidate !== "" && isCodeActionKindWithin(candidate, family),
280
+ ),
281
+ anyKind: !advertised || advertised.includes(""),
282
+ };
283
+ }
284
+
285
+ function noKindMatchReason(kind: string, advertised: AdvertisedFamilyKinds): string {
286
+ const parts = [`No code action matches kind "${kind}" here.`];
287
+ if (advertised.kinds.length > 0) {
288
+ parts.push(`Server-advertised kinds: ${advertised.kinds.join(", ")}.`);
289
+ }
290
+ if (advertised.anyKind) {
291
+ parts.push("The server may return any code-action kind but returned none of this kind.");
292
+ } else if (advertised.kinds.length === 0) {
293
+ parts.push("The server advertises no kinds in this family.");
294
+ }
295
+ return parts.join(" ");
296
+ }
297
+
298
+ function actionIdentity(action: CodeAction): RefactorActionIdentity {
299
+ return { kind: typeof action.kind === "string" ? action.kind : "", title: action.title };
300
+ }
301
+
143
302
  interface PreciseCodeActionPlan {
144
303
  action: CodeAction;
145
304
  result: Extract<RefactorResult, { kind: "precise" }>;
@@ -187,18 +346,14 @@ function refactorCandidate(
187
346
  result: Extract<RefactorResult, { kind: "precise" }>,
188
347
  index: number,
189
348
  plans: readonly { action: CodeAction }[],
190
- ): {
191
- description: string;
192
- file?: string;
193
- line?: number;
194
- character?: number;
195
- } {
349
+ ): DisambiguationCandidate {
196
350
  const firstEdit = result.edits.edits[0];
197
351
  const sameTitleCount = plans.filter((plan) => plan.action.title === action.title).length;
198
352
  const description =
199
353
  sameTitleCount > 1 ? `${action.title} (alternative ${index + 1})` : action.title;
200
354
  return {
201
355
  description,
356
+ ...actionIdentity(action),
202
357
  ...(firstEdit
203
358
  ? {
204
359
  file: firstEdit.file,
@@ -2,10 +2,11 @@ import { readFile } from "node:fs/promises";
2
2
  import type {
3
3
  CodeLocation,
4
4
  CodeSymbol,
5
- DeclarationNesting,
5
+ DeclarationLevel,
6
6
  DocumentCodeSymbol,
7
7
  SourceRange,
8
8
  } from "@mrclrchtr/supi-code-runtime/api";
9
+ import { childDeclarationLevel } from "@mrclrchtr/supi-code-runtime/api";
9
10
  import { uriToFile } from "@mrclrchtr/supi-core/path";
10
11
  import type {
11
12
  DocumentSymbol,
@@ -100,15 +101,26 @@ export async function mapDocumentSymbols(
100
101
  ): Promise<DocumentCodeSymbol[]> {
101
102
  return flattenDocumentSymbols(symbols, filePath, null, {
102
103
  sourceLines: await readSourceLines(filePath),
103
- nesting: "top-level",
104
+ parent: null,
104
105
  });
105
106
  }
106
107
 
108
+ /** Level of a symbol reported inside `parent`, or top-level without one. */
109
+ function levelWithin(
110
+ parent: { readonly kind: string; readonly level: DeclarationLevel } | null,
111
+ kind: string,
112
+ ): DeclarationLevel {
113
+ return parent ? childDeclarationLevel(parent, kind) : "top-level";
114
+ }
115
+
107
116
  function flattenDocumentSymbols(
108
117
  symbols: DocumentSymbol[] | SymbolInformation[],
109
118
  filePath: string,
110
119
  container: string | null,
111
- context: { sourceLines: readonly string[] | null; nesting: DeclarationNesting },
120
+ context: {
121
+ sourceLines: readonly string[] | null;
122
+ parent: { readonly kind: string; readonly level: DeclarationLevel } | null;
123
+ },
112
124
  ): DocumentCodeSymbol[] {
113
125
  const result: DocumentCodeSymbol[] = [];
114
126
  for (const sym of symbols) {
@@ -116,15 +128,13 @@ function flattenDocumentSymbols(
116
128
  let document: DocumentSymbol | null = null;
117
129
  if (isSymbolInformation(sym)) information = sym;
118
130
  else document = sym;
131
+ const kind = symbolKindName(sym.kind);
132
+ const level = information ? "unknown" : levelWithin(context.parent, kind);
133
+ const childContext = { sourceLines: context.sourceLines, parent: { kind, level } };
119
134
  const declarationRange = toValidRange(document?.range ?? information?.location.range);
120
135
  if (!declarationRange) {
121
136
  if (document?.children?.length) {
122
- result.push(
123
- ...flattenDocumentSymbols(document.children, filePath, sym.name, {
124
- sourceLines: context.sourceLines,
125
- nesting: "nested",
126
- }),
127
- );
137
+ result.push(...flattenDocumentSymbols(document.children, filePath, sym.name, childContext));
128
138
  }
129
139
  continue;
130
140
  }
@@ -134,23 +144,18 @@ function flattenDocumentSymbols(
134
144
  : null;
135
145
  const symbol: DocumentCodeSymbol = {
136
146
  name: sym.name,
137
- kind: symbolKindName(sym.kind),
147
+ kind,
138
148
  file: filePath,
139
149
  declarationAnchor: { line: declStart.line + 1, character: declStart.character + 1 },
140
150
  container: information?.containerName ?? container,
141
- nesting: information ? "unknown" : context.nesting,
151
+ level,
142
152
  };
143
153
  if (nameStart) {
144
154
  symbol.nameAnchor = { line: nameStart.line + 1, character: nameStart.character + 1 };
145
155
  }
146
156
  result.push(symbol);
147
157
  if (document?.children?.length) {
148
- result.push(
149
- ...flattenDocumentSymbols(document.children, filePath, sym.name, {
150
- sourceLines: context.sourceLines,
151
- nesting: "nested",
152
- }),
153
- );
158
+ result.push(...flattenDocumentSymbols(document.children, filePath, sym.name, childContext));
154
159
  }
155
160
  }
156
161
  return result;
@@ -0,0 +1,26 @@
1
+ /** Project-root boundary for mutation requests on one routed client. */
2
+
3
+ import { realpathSync } from "node:fs";
4
+ import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
5
+
6
+ /**
7
+ * Return why a file cannot be refactored by the client routed to it, or null.
8
+ *
9
+ * A file without its own project markers routes to a server rooted at the
10
+ * session directory. Its edits would fail the apply-time root check, so refuse
11
+ * before the request. Real paths are compared, so a link inside the root
12
+ * cannot reach an outside file.
13
+ */
14
+ export function outsideRouteRootReason(file: string, root: string): string | null {
15
+ return isWithinOrEqual(canonical(root), canonical(file))
16
+ ? null
17
+ : `File ${file} is outside the language server's project root ${root}.`;
18
+ }
19
+
20
+ function canonical(file: string): string {
21
+ try {
22
+ return realpathSync(file);
23
+ } catch {
24
+ return file;
25
+ }
26
+ }