@mrclrchtr/supi-code-intelligence 11.4.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 (89) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +13 -7
  3. package/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  4. package/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +1 -0
  5. package/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts +51 -23
  6. package/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  7. package/node_modules/@mrclrchtr/supi-lsp/README.md +21 -16
  8. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  9. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +1 -0
  10. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts +51 -23
  11. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  12. package/node_modules/@mrclrchtr/supi-lsp/package.json +3 -3
  13. package/node_modules/@mrclrchtr/supi-lsp/src/api.ts +2 -2
  14. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostic-capabilities.ts +13 -3
  15. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostics.ts +25 -9
  16. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-document-sync.ts +7 -5
  17. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-edit-capture.ts +258 -0
  18. package/node_modules/@mrclrchtr/supi-lsp/src/client/client.ts +64 -11
  19. package/node_modules/@mrclrchtr/supi-lsp/src/config/capabilities.ts +8 -0
  20. package/node_modules/@mrclrchtr/supi-lsp/src/config/operation-support.ts +48 -79
  21. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager.ts +3 -1
  22. package/node_modules/@mrclrchtr/supi-lsp/src/provider/lsp-refactor-provider.ts +21 -35
  23. package/node_modules/@mrclrchtr/supi-lsp/src/provider/refactor-command-capture.ts +139 -0
  24. package/node_modules/@mrclrchtr/supi-lsp/src/provider/refactor-planning.ts +202 -47
  25. package/node_modules/@mrclrchtr/supi-lsp/src/session/route-boundary.ts +26 -0
  26. package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-registry.ts +57 -12
  27. package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-rename.ts +3 -0
  28. package/node_modules/@mrclrchtr/supi-lsp/src/session/workspace-lsp-runtime.ts +22 -1
  29. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  30. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +1 -0
  31. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts +51 -23
  32. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  33. package/node_modules/@mrclrchtr/supi-tree-sitter/package.json +3 -3
  34. package/node_modules/@mrclrchtr/supi-tree-sitter/src/coordinates.ts +16 -2
  35. package/node_modules/@mrclrchtr/supi-tree-sitter/src/session/structural-worker-client.ts +3 -2
  36. package/node_modules/@mrclrchtr/supi-tree-sitter/src/syntax-errors.ts +2 -0
  37. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/call-range.ts +94 -0
  38. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/call-sites.ts +26 -6
  39. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/callees.ts +6 -3
  40. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/exports.ts +13 -4
  41. package/node_modules/@mrclrchtr/supi-tree-sitter/src/worker/runtime.ts +1 -9
  42. package/package.json +5 -5
  43. package/src/analysis/health/server-status.ts +41 -12
  44. package/src/analysis/target/anchored-structural.ts +4 -1
  45. package/src/analysis/target/symbol.ts +1 -1
  46. package/src/session/find-types.ts +8 -4
  47. package/src/session/find-workflow.ts +11 -16
  48. package/src/session/input/health-refactor.ts +48 -34
  49. package/src/session/input/workflows.ts +45 -46
  50. package/src/session/inspect/file-point.ts +2 -2
  51. package/src/session/inspect-types.ts +1 -1
  52. package/src/session/inspect-workflow.ts +3 -3
  53. package/src/session/refactor-file-actions.ts +122 -0
  54. package/src/session/refactor-plan-pipeline.ts +152 -0
  55. package/src/session/refactor-plans.ts +18 -15
  56. package/src/session/refactor-types.ts +24 -12
  57. package/src/session/refactor-workflow.ts +68 -243
  58. package/src/tool/code_find/execute.ts +6 -7
  59. package/src/tool/code_find/spec.ts +9 -16
  60. package/src/tool/code_find/tui.ts +12 -6
  61. package/src/tool/code_graph/spec.ts +6 -0
  62. package/src/tool/code_health/spec.ts +6 -0
  63. package/src/tool/code_health/structured-schema.ts +4 -4
  64. package/src/tool/code_health/structured.ts +15 -17
  65. package/src/tool/code_inspect/execute.ts +1 -1
  66. package/src/tool/code_inspect/markdown.ts +33 -6
  67. package/src/tool/code_inspect/result.ts +1 -1
  68. package/src/tool/code_inspect/spec.ts +14 -6
  69. package/src/tool/code_inspect/structured.ts +2 -2
  70. package/src/tool/code_inspect/tui.ts +2 -2
  71. package/src/tool/code_orientation/spec.ts +8 -0
  72. package/src/tool/code_refactor_apply/result.ts +2 -1
  73. package/src/tool/code_refactor_apply/spec.ts +7 -0
  74. package/src/tool/code_refactor_plan/execute.ts +0 -2
  75. package/src/tool/code_refactor_plan/result.ts +23 -13
  76. package/src/tool/code_refactor_plan/spec.ts +8 -2
  77. package/src/tool/code_refactor_plan/structured.ts +59 -12
  78. package/src/tool/code_refactor_plan/tui.ts +14 -17
  79. package/src/tool/code_resolve/markdown.ts +1 -1
  80. package/src/tool/code_resolve/spec.ts +6 -0
  81. package/src/tool/namespace.ts +14 -0
  82. package/src/tool/refactor-markdown.ts +55 -15
  83. package/src/tool/register.ts +3 -0
  84. package/src/tool/result/refactor-preview.ts +118 -0
  85. package/src/tool/result/refactor-unavailable.ts +16 -0
  86. package/src/tool/result/refactor.ts +8 -2
  87. package/src/tool/schemas.ts +63 -20
  88. package/src/tool/specs.ts +3 -0
  89. package/src/ui/status-overlay.ts +1 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-code-intelligence",
3
- "version": "11.4.0",
3
+ "version": "12.0.0",
4
4
  "description": "LSP and AST navigation, search, diagnostics, and refactoring",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -43,10 +43,10 @@
43
43
  "ignore": "^7.0.12",
44
44
  "smol-toml": "^1.9.1",
45
45
  "yaml": "^2.9.0",
46
- "@mrclrchtr/supi-lsp": "11.4.0",
47
- "@mrclrchtr/supi-tree-sitter": "11.4.0",
48
- "@mrclrchtr/supi-core": "11.4.0",
49
- "@mrclrchtr/supi-code-runtime": "11.4.0"
46
+ "@mrclrchtr/supi-code-runtime": "12.0.0",
47
+ "@mrclrchtr/supi-lsp": "12.0.0",
48
+ "@mrclrchtr/supi-tree-sitter": "12.0.0",
49
+ "@mrclrchtr/supi-core": "12.0.0"
50
50
  },
51
51
  "bundledDependencies": [
52
52
  "@mrclrchtr/supi-code-runtime",
@@ -79,20 +79,49 @@ export function formatProjectServerCompiler(
79
79
  return `${selection.backend}: TypeScript ${selection.compilerVersion ?? "(unknown version)"} via ${selection.packageName}${selection.wrapperVersion ? ` (wrapper ${selection.wrapperVersion})` : ""}`;
80
80
  }
81
81
 
82
- /** Render operation support without hiding server limits or SuPi limits. */
82
+ /**
83
+ * Render operation support without hiding server limits or SuPi limits.
84
+ *
85
+ * A server that does not advertise an operation already rules it out, so its
86
+ * SuPi limitation is omitted. Operations with identical details share one
87
+ * entry, so a shared limitation reason appears once.
88
+ */
83
89
  export function formatProjectServerOperationSupport(
84
90
  support: ServerOperationSupportMap | undefined,
85
91
  ): string | null {
86
92
  if (!support) return null;
87
- const entries = Object.entries(support).flatMap(([operation, value]) => {
88
- const details: string[] = [];
89
- if (value.server === "not-advertised") details.push("server unsupported");
90
- if (value.server === "unknown") details.push("not negotiated");
91
- if (value.supi === "limited") {
92
- details.push(`SuPi limitation${value.reason ? `: ${value.reason}` : ""}`);
93
- }
94
- if (value.supi === "unsupported") details.push("SuPi unsupported");
95
- return details.length > 0 ? [`${operation}: ${details.join("; ")}`] : [];
96
- });
97
- return entries.length > 0 ? `operation support: ${entries.join(", ")}` : null;
93
+ const operationsByDetail = new Map<string, string[]>();
94
+ for (const [operation, value] of Object.entries(support)) {
95
+ const detail = formatOperationSupportDetail(value);
96
+ if (!detail) continue;
97
+ const operations = operationsByDetail.get(detail);
98
+ if (operations) operations.push(operation);
99
+ else operationsByDetail.set(detail, [operation]);
100
+ }
101
+ const entries = Array.from(
102
+ operationsByDetail,
103
+ ([detail, operations]) => `${operations.join(", ")}: ${detail}`,
104
+ );
105
+ // Details already use ";" and grouped operations use ",", so entries need a third separator.
106
+ return entries.length > 0 ? `operation support: ${entries.join(" | ")}` : null;
107
+ }
108
+
109
+ type OperationSupport = NonNullable<ServerOperationSupportMap[keyof ServerOperationSupportMap]>;
110
+
111
+ /** Describe one operation's limits, or return null when nothing limits it. */
112
+ function formatOperationSupportDetail(value: OperationSupport): string | null {
113
+ if (value.server === "not-advertised") return "server unsupported";
114
+ const details: string[] = [];
115
+ if (value.server === "unknown") details.push("not negotiated");
116
+ if (value.supi === "limited") {
117
+ details.push(`SuPi limitation${value.reason ? `: ${value.reason}` : ""}`);
118
+ }
119
+ if (value.supi === "unsupported") details.push("SuPi unsupported");
120
+ if (value.kinds?.length) details.push(`kinds ${value.kinds.join(", ")}`);
121
+ if (value.anyKind) {
122
+ details.push(
123
+ value.kinds?.length ? "may return unlisted kinds" : "no kinds listed; may return any kind",
124
+ );
125
+ }
126
+ return details.length > 0 ? details.join("; ") : null;
98
127
  }
@@ -30,6 +30,9 @@ const DECLARATION_NODE_TYPES = new Set([
30
30
  "export_statement",
31
31
  ]);
32
32
 
33
+ /** Tree-sitter name tokens; Kotlin names its identifiers `simple_identifier`. */
34
+ const IDENTIFIER_NODE_TYPES = new Set(["identifier", "simple_identifier"]);
35
+
33
36
  /** Tree-sitter nodes that cannot identify a declaration name. */
34
37
  const NON_SYMBOL_NODE_TYPES = new Set([
35
38
  "comment",
@@ -94,7 +97,7 @@ export async function resolveFromStructural(
94
97
  ),
95
98
  };
96
99
  }
97
- if (node.type !== "identifier") {
100
+ if (!IDENTIFIER_NODE_TYPES.has(node.type)) {
98
101
  return {
99
102
  kind: "error",
100
103
  message: coordinateNotOnSymbolMessage(file, requested, node.type),
@@ -313,7 +313,7 @@ function emptySymbolOutcome(
313
313
  message: [
314
314
  `Symbol not found: \`${symbol}\`${scope ? ` in path \`${scope}\`` : ""}.`,
315
315
  "Workspace-symbol search covers only files in projects the language server has loaded; files outside them (e.g. excluded by tsconfig or in another toolchain's subtree) are not searched.",
316
- 'Next: `code_find` with `mode: "ast"` and `kind: "definition"` for a structural search, `code_resolve` with `target.file` if the file is known, or an anchor target (file/line/character) if the location is known.',
316
+ 'Next: `code_find` with `search.ast` and `kind: "definition"` for a structural search, `code_resolve` with `target.file` if the file is known, or an anchor target (file/line/character) if the location is known.',
317
317
  ].join(" "),
318
318
  };
319
319
  }
@@ -5,11 +5,15 @@ import type { CodeFindMode } from "../tool/code_find/modes.ts";
5
5
 
6
6
  export type FindMode = CodeFindMode;
7
7
 
8
+ /** Exactly one search mode; each branch carries only the fields that mode honors. */
9
+ export type FindSearchInput =
10
+ | { readonly ast: { readonly kind: CodeFindAstKind; readonly query: string } }
11
+ | { readonly semantic: { readonly query: string } };
12
+
13
+ /** Canonical code_find workflow input. */
8
14
  export interface FindWorkflowInput {
9
- readonly query: string;
10
- readonly scope?: readonly string[];
11
- readonly mode: FindMode;
12
- readonly kind?: CodeFindAstKind;
15
+ readonly search: FindSearchInput;
16
+ readonly scopes?: readonly string[];
13
17
  readonly maxResults?: number;
14
18
  }
15
19
 
@@ -6,7 +6,7 @@ import type { AutomaticLspPathPolicy } from "@mrclrchtr/supi-lsp/api";
6
6
  import { SEMANTIC_READINESS_TIMEOUT_REASON } from "../analysis/readiness.ts";
7
7
  import { resolveScopeSet } from "../analysis/search/paths.ts";
8
8
  import { getStructuredPatternMatches } from "../analysis/search/pattern.ts";
9
- import { isCodeFindAstKind } from "../tool/code_find/ast-kinds.ts";
9
+ import type { CodeFindAstKind } from "../tool/code_find/ast-kinds.ts";
10
10
  import type { CapabilityAdapter } from "./capability-adapter.ts";
11
11
  import type { FindWorkflowInput, FindWorkflowOutcome } from "./find-types.ts";
12
12
  import { parseFindWorkflowInput } from "./input/workflows.ts";
@@ -29,10 +29,9 @@ export async function runFindWorkflow(
29
29
  const parsed = parseFindWorkflowInput(input);
30
30
  if (parsed.kind === "invalid-input") return parsed;
31
31
  const request = parsed.value;
32
- const query = request.query;
33
- const mode = request.mode;
32
+ const mode = "ast" in request.search ? "ast" : "semantic";
34
33
 
35
- const scope = resolveScopeSet(request.scope ? [...request.scope] : undefined, deps.cwd);
34
+ const scope = resolveScopeSet(request.scopes ? [...request.scopes] : undefined, deps.cwd);
36
35
  if (scope.kind === "error") return { kind: "invalid-input", message: scope.reason };
37
36
 
38
37
  if (mode === "ast") control?.signal?.throwIfAborted();
@@ -45,9 +44,9 @@ export async function runFindWorkflow(
45
44
 
46
45
  const maxResults = request.maxResults ?? 8;
47
46
  const scopeLabel = scope.display ?? ".";
48
- if (mode === "semantic") {
47
+ if ("semantic" in request.search) {
49
48
  return runSemanticSearch({
50
- query,
49
+ query: request.search.semantic.query,
51
50
  scopePaths: scope.paths,
52
51
  scopeLabel,
53
52
  maxResults,
@@ -56,8 +55,7 @@ export async function runFindWorkflow(
56
55
  });
57
56
  }
58
57
  return runAstSearch({
59
- query,
60
- input: request,
58
+ search: request.search.ast,
61
59
  scopePaths: scope.paths,
62
60
  scopeLabel,
63
61
  maxResults,
@@ -108,25 +106,22 @@ async function runSemanticSearch(options: {
108
106
  }
109
107
 
110
108
  async function runAstSearch(options: {
111
- query: string;
112
- input: FindWorkflowInput;
109
+ search: { readonly kind: CodeFindAstKind; readonly query: string };
113
110
  scopePaths: readonly string[];
114
111
  scopeLabel: string;
115
112
  maxResults: number;
116
113
  deps: FindWorkflowDeps;
117
114
  control?: WorkflowControl;
118
115
  }): Promise<FindWorkflowOutcome> {
119
- const { query, input, scopePaths, scopeLabel, maxResults, deps, control } = options;
120
- if (!isCodeFindAstKind(input.kind)) {
121
- return { kind: "invalid-input", message: "Unsupported AST kind." };
122
- }
116
+ const { search, scopePaths, scopeLabel, maxResults, deps, control } = options;
117
+ const { kind, query } = search;
123
118
  const provider = deps.capability.getStructuralProvider(deps.cwd);
124
119
  if (!provider) {
125
120
  return { kind: "unavailable", reason: "No structural provider is active." };
126
121
  }
127
122
  control?.signal?.throwIfAborted();
128
123
  const outcome = await getStructuredPatternMatches({
129
- params: { pattern: query, kind: input.kind },
124
+ params: { pattern: query, kind },
130
125
  roots: scopePaths,
131
126
  cwd: deps.cwd,
132
127
  structural: provider,
@@ -145,6 +140,6 @@ async function runAstSearch(options: {
145
140
  mode: "ast",
146
141
  scopeLabel,
147
142
  maxResults,
148
- data: { kind: "ast", astKind: input.kind, result: outcome.result },
143
+ data: { kind: "ast", astKind: kind, result: outcome.result },
149
144
  };
150
145
  }
@@ -79,17 +79,11 @@ export function parseRefactorPlanWorkflowInput(
79
79
  ): InputValidation<RefactorPlanWorkflowInput> {
80
80
  const record = requireRecord(value, "code_refactor_plan input");
81
81
  if (record.kind === "invalid-input") return record;
82
- const keysError = requireOnlyKeys(
83
- record.value,
84
- ["target", "operation"],
85
- "code_refactor_plan input",
86
- );
82
+ const keysError = requireOnlyKeys(record.value, ["operation"], "code_refactor_plan input");
87
83
  if (keysError) return invalid(keysError);
88
- const target = parseTargetInput(record.value.target, ["handle", "anchor"]);
89
- if (target.kind === "invalid-input") return target;
90
84
  const operation = parseRefactorOperation(record.value.operation);
91
85
  if (operation.kind === "invalid-input") return operation;
92
- return valid({ target: target.value as RefactorTargetInput, operation: operation.value });
86
+ return valid({ operation: operation.value });
93
87
  }
94
88
 
95
89
  function parseRefactorOperation(value: unknown): InputValidation<RefactorOperationInput> {
@@ -104,56 +98,76 @@ function parseRefactorOperation(value: unknown): InputValidation<RefactorOperati
104
98
  const payload = requireRecord(record.value[name], `operation.${name}`);
105
99
  if (payload.kind === "invalid-input") return payload;
106
100
  if (name === "rename_symbol") return parseRenameOperation(payload.value);
107
- if (name === "extract_function" || name === "extract_variable") {
108
- return parseExtractOperation(name, payload.value);
109
- }
110
- const payloadError = requireOnlyKeys(payload.value, [], `operation.${name}`);
111
- if (payloadError) return invalid(payloadError);
112
- return name === "update_imports"
113
- ? valid({ update_imports: {} })
114
- : valid({ delete_dead_code: {} });
101
+ return parseActionOperation(name, payload.value);
115
102
  }
116
103
 
117
104
  function parseRenameOperation(
118
105
  payload: Record<string, unknown>,
119
106
  ): InputValidation<RefactorOperationInput> {
120
- const payloadError = requireOnlyKeys(payload, ["newName"], "operation.rename_symbol");
107
+ const payloadError = requireOnlyKeys(payload, ["target", "newName"], "operation.rename_symbol");
121
108
  if (payloadError) return invalid(payloadError);
109
+ const target = parseTargetInput(payload.target, ["handle", "anchor"]);
110
+ if (target.kind === "invalid-input") return target;
122
111
  const newName = requireString(payload.newName, "operation.rename_symbol.newName", {
123
112
  nonEmpty: true,
124
113
  });
125
- return newName.kind === "valid" ? valid({ rename_symbol: { newName: newName.value } }) : newName;
114
+ if (newName.kind === "invalid-input") return newName;
115
+ return valid({
116
+ rename_symbol: { target: target.value as RefactorTargetInput, newName: newName.value },
117
+ });
126
118
  }
127
119
 
128
- function parseExtractOperation(
129
- name: "extract_function" | "extract_variable",
120
+ /** Kind family each action operation accepts; `quickfix` and `notebook` kinds are never valid. */
121
+ const ACTION_KIND_FAMILY = { code_action: "refactor", source_action: "source" } as const;
122
+
123
+ function parseActionOperation(
124
+ name: "code_action" | "source_action",
130
125
  payload: Record<string, unknown>,
131
126
  ): InputValidation<RefactorOperationInput> {
132
- const payloadError = requireOnlyKeys(payload, ["newName", "range"], `operation.${name}`);
127
+ const label = `operation.${name}`;
128
+ const allowed =
129
+ name === "code_action" ? ["file", "range", "kind", "title"] : ["file", "kind", "title"];
130
+ const payloadError = requireOnlyKeys(payload, allowed, label);
133
131
  if (payloadError) return invalid(payloadError);
134
- const newName = requireString(payload.newName, `operation.${name}.newName`, { nonEmpty: true });
135
- if (newName.kind === "invalid-input") return newName;
136
- const range = parsePublicRange(payload.range);
132
+ const file = requireString(payload.file, `${label}.file`, { nonEmpty: true });
133
+ if (file.kind === "invalid-input") return file;
134
+ const kind = requireString(payload.kind, `${label}.kind`, { nonEmpty: true });
135
+ if (kind.kind === "invalid-input") return kind;
136
+ const family = ACTION_KIND_FAMILY[name];
137
+ if (kind.value !== family && !kind.value.startsWith(`${family}.`)) {
138
+ return invalid(`${label}.kind must be "${family}" or start with "${family}.".`);
139
+ }
140
+ const title =
141
+ payload.title === undefined
142
+ ? valid(undefined)
143
+ : requireString(payload.title, `${label}.title`, { nonEmpty: true });
144
+ if (title.kind === "invalid-input") return title;
145
+ const selection = {
146
+ file: file.value,
147
+ kind: kind.value,
148
+ ...(title.value === undefined ? {} : { title: title.value }),
149
+ };
150
+ if (name === "source_action") return valid({ source_action: selection });
151
+ const range = parsePublicRange(payload.range, `${label}.range`);
137
152
  if (range.kind === "invalid-input") return range;
138
- return name === "extract_function"
139
- ? valid({ extract_function: { newName: newName.value, range: range.value } })
140
- : valid({ extract_variable: { newName: newName.value, range: range.value } });
153
+ return valid({ code_action: { ...selection, range: range.value } });
141
154
  }
142
155
 
143
- function parsePublicRange(value: unknown): InputValidation<PublicSourceRange> {
144
- const record = requireRecord(value, "range");
156
+ /** Parse a one-based range; an empty range (`start` equal to `end`) marks a cursor position. */
157
+ function parsePublicRange(value: unknown, label: string): InputValidation<PublicSourceRange> {
158
+ const record = requireRecord(value, label);
145
159
  if (record.kind === "invalid-input") return record;
146
- const keysError = requireOnlyKeys(record.value, ["start", "end"], "range");
160
+ const keysError = requireOnlyKeys(record.value, ["start", "end"], label);
147
161
  if (keysError) return invalid(keysError);
148
- const start = parsePosition(record.value.start, "range.start");
162
+ const start = parsePosition(record.value.start, `${label}.start`);
149
163
  if (start.kind === "invalid-input") return start;
150
- const end = parsePosition(record.value.end, "range.end");
164
+ const end = parsePosition(record.value.end, `${label}.end`);
151
165
  if (end.kind === "invalid-input") return end;
152
166
  if (
153
167
  end.value.line < start.value.line ||
154
- (end.value.line === start.value.line && end.value.character <= start.value.character)
168
+ (end.value.line === start.value.line && end.value.character < start.value.character)
155
169
  ) {
156
- return invalid("range.end must be after range.start.");
170
+ return invalid(`${label}.end must not be before ${label}.start.`);
157
171
  }
158
172
  return valid({ start: start.value, end: end.value });
159
173
  }
@@ -1,8 +1,8 @@
1
1
  /** Runtime parsers for inspection, Orientation, graph, and find workflows. */
2
2
 
3
- import { type CodeFindAstKind, isCodeFindAstKind } from "../../tool/code_find/ast-kinds.ts";
3
+ import { isCodeFindAstKind } from "../../tool/code_find/ast-kinds.ts";
4
4
  import { CODE_FIND_MODES } from "../../tool/code_find/modes.ts";
5
- import type { FindMode, FindWorkflowInput } from "../find-types.ts";
5
+ import type { FindMode, FindSearchInput, FindWorkflowInput } from "../find-types.ts";
6
6
  import type { GraphWorkflowInput, RequestedGraphRelation } from "../graph-types.ts";
7
7
  import type { InspectWorkflowInput } from "../inspect-types.ts";
8
8
  import type { OrientationFocusInput, OrientationWorkflowInput } from "../orientation-types.ts";
@@ -19,7 +19,6 @@ import {
19
19
  valid,
20
20
  } from "./common.ts";
21
21
 
22
- const FIND_MODES = new Set<FindMode>(CODE_FIND_MODES);
23
22
  const GRAPH_RELATIONS = new Set<RequestedGraphRelation>([
24
23
  "all",
25
24
  "references",
@@ -30,14 +29,14 @@ const GRAPH_RELATIONS = new Set<RequestedGraphRelation>([
30
29
  export function parseInspectWorkflowInput(value: unknown): InputValidation<InspectWorkflowInput> {
31
30
  const record = requireRecord(value, "code_inspect input");
32
31
  if (record.kind === "invalid-input") return record;
33
- const keysError = requireOnlyKeys(record.value, ["point", "maxResults"], "code_inspect input");
32
+ const keysError = requireOnlyKeys(record.value, ["anchor", "maxResults"], "code_inspect input");
34
33
  if (keysError) return invalid(keysError);
35
- const point = parseSourcePoint(record.value.point);
36
- if (point.kind === "invalid-input") return point;
34
+ const anchor = parseSourcePoint(record.value.anchor, "anchor");
35
+ if (anchor.kind === "invalid-input") return anchor;
37
36
  const maxResults = optionalPositiveInteger(record.value.maxResults, "maxResults");
38
37
  if (maxResults.kind === "invalid-input") return maxResults;
39
38
  return valid({
40
- point: point.value,
39
+ anchor: anchor.value,
41
40
  ...(maxResults.value === undefined ? {} : { maxResults: maxResults.value }),
42
41
  });
43
42
  }
@@ -149,63 +148,63 @@ export function parseFindWorkflowInput(value: unknown): InputValidation<FindWork
149
148
  if (record.kind === "invalid-input") return record;
150
149
  const keysError = requireOnlyKeys(
151
150
  record.value,
152
- ["query", "scope", "mode", "kind", "maxResults"],
151
+ ["search", "scopes", "maxResults"],
153
152
  "code_find input",
154
153
  );
155
154
  if (keysError) return invalid(keysError);
156
- const query = requireString(record.value.query, "query", { nonEmpty: true });
157
- if (query.kind === "invalid-input") return query;
158
- const scope = parseFindScope(record.value.scope);
159
- if (scope.kind === "invalid-input") return scope;
160
- const mode = parseFindMode(record.value.mode);
161
- if (mode.kind === "invalid-input") return mode;
162
- const patternKind = parsePatternKind(record.value.kind);
163
- if (patternKind.kind === "invalid-input") return patternKind;
164
- const modeError = validateFindModeFields(mode.value, patternKind.value);
165
- if (modeError) return invalid(modeError);
155
+ const search = parseFindSearch(record.value.search);
156
+ if (search.kind === "invalid-input") return search;
157
+ const scopes = parseFindScopes(record.value.scopes);
158
+ if (scopes.kind === "invalid-input") return scopes;
166
159
  const maxResults = optionalPositiveInteger(record.value.maxResults, "maxResults");
167
160
  if (maxResults.kind === "invalid-input") return maxResults;
168
161
  return valid({
169
- query: query.value,
170
- ...(scope.value === undefined ? {} : { scope: scope.value }),
171
- mode: mode.value,
172
- ...(patternKind.value === undefined ? {} : { kind: patternKind.value }),
162
+ search: search.value,
163
+ ...(scopes.value === undefined ? {} : { scopes: scopes.value }),
173
164
  ...(maxResults.value === undefined ? {} : { maxResults: maxResults.value }),
174
165
  });
175
166
  }
176
167
 
177
- function parseFindScope(value: unknown): InputValidation<readonly string[] | undefined> {
168
+ function parseFindSearch(value: unknown): InputValidation<FindSearchInput> {
169
+ const record = requireRecord(value, "search");
170
+ if (record.kind === "invalid-input") return record;
171
+ const keysError = requireOnlyKeys(record.value, CODE_FIND_MODES, "search");
172
+ if (keysError) return invalid(keysError);
173
+ const selected = CODE_FIND_MODES.filter((mode) => record.value[mode] !== undefined);
174
+ if (selected.length !== 1) {
175
+ return invalid("search must contain exactly one of `ast` or `semantic`.");
176
+ }
177
+ const mode = selected[0] as FindMode;
178
+ const label = `search.${mode}`;
179
+ const branch = requireRecord(record.value[mode], label);
180
+ if (branch.kind === "invalid-input") return branch;
181
+ const branchKeysError = requireOnlyKeys(
182
+ branch.value,
183
+ mode === "ast" ? ["kind", "query"] : ["query"],
184
+ label,
185
+ );
186
+ if (branchKeysError) return invalid(branchKeysError);
187
+ const query = requireString(branch.value.query, `${label}.query`, { nonEmpty: true });
188
+ if (query.kind === "invalid-input") return query;
189
+ if (mode === "semantic") return valid({ semantic: { query: query.value } });
190
+ return isCodeFindAstKind(branch.value.kind)
191
+ ? valid({ ast: { kind: branch.value.kind, query: query.value } })
192
+ : invalid(
193
+ branch.value.kind === undefined ? "search.ast.kind is required." : "Unsupported AST kind.",
194
+ );
195
+ }
196
+
197
+ function parseFindScopes(value: unknown): InputValidation<readonly string[] | undefined> {
178
198
  if (value === undefined) return valid(undefined);
179
199
  if (
180
200
  !Array.isArray(value) ||
181
201
  value.length === 0 ||
182
202
  !value.every((item) => typeof item === "string")
183
203
  ) {
184
- return invalid("scope must be a non-empty array of workspace-relative paths.");
204
+ return invalid("scopes must be a non-empty array of workspace-relative paths.");
185
205
  }
186
206
  if (value.some((item) => item.trim().length === 0)) {
187
- return invalid("scope must not contain empty paths.");
207
+ return invalid("scopes must not contain empty paths.");
188
208
  }
189
209
  return valid(value);
190
210
  }
191
-
192
- function parseFindMode(value: unknown): InputValidation<FindMode> {
193
- return typeof value === "string" && FIND_MODES.has(value as FindMode)
194
- ? valid(value as FindMode)
195
- : invalid("mode is required and must be one of ast or semantic.");
196
- }
197
-
198
- function parsePatternKind(value: unknown): InputValidation<CodeFindAstKind | undefined> {
199
- if (value === undefined) return valid(undefined);
200
- return isCodeFindAstKind(value) ? valid(value) : invalid("Unsupported AST kind.");
201
- }
202
-
203
- function validateFindModeFields(
204
- mode: FindMode,
205
- patternKind: CodeFindAstKind | undefined,
206
- ): string | null {
207
- if (mode === "ast" && patternKind === undefined) return 'mode "ast" requires kind.';
208
- return mode !== "ast" && patternKind !== undefined
209
- ? `kind is not valid with mode "${mode}".`
210
- : null;
211
- }
@@ -42,7 +42,7 @@ export function validateInspectPoint(
42
42
  if (point.line > lines.length) {
43
43
  return {
44
44
  kind: "invalid-input",
45
- message: `Point line ${point.line} is beyond the end of \`${point.file}\` (${lines.length} lines).`,
45
+ message: `Anchor line ${point.line} is beyond the end of \`${point.file}\` (${lines.length} lines).`,
46
46
  };
47
47
  }
48
48
 
@@ -51,7 +51,7 @@ export function validateInspectPoint(
51
51
  if (point.character > maximumCharacter) {
52
52
  return {
53
53
  kind: "invalid-input",
54
- message: `Point character ${point.character} is beyond line ${point.line} of \`${point.file}\` (maximum ${maximumCharacter}, 1-based UTF-16).`,
54
+ message: `Anchor character ${point.character} is beyond line ${point.line} of \`${point.file}\` (maximum ${maximumCharacter}, 1-based UTF-16).`,
55
55
  };
56
56
  }
57
57
 
@@ -7,7 +7,7 @@ import type { SourcePointInput } from "./target-input.ts";
7
7
 
8
8
  /** Canonical code_inspect workflow input. */
9
9
  export interface InspectWorkflowInput {
10
- readonly point: SourcePointInput;
10
+ readonly anchor: SourcePointInput;
11
11
  readonly maxResults?: number;
12
12
  }
13
13
 
@@ -30,7 +30,7 @@ export async function runInspectWorkflow(
30
30
  const parsed = parseInspectWorkflowInput(input);
31
31
  if (parsed.kind === "invalid-input") return parsed;
32
32
  const request = parsed.value;
33
- const point = validateInspectPoint(request.point, deps.cwd);
33
+ const point = validateInspectPoint(request.anchor, deps.cwd);
34
34
  if (point.kind === "invalid-input") return point;
35
35
  throwIfAborted(control);
36
36
 
@@ -63,7 +63,7 @@ export async function runInspectWorkflow(
63
63
  structural: deps.capability.getStructuralProvider(deps.cwd),
64
64
  semantic,
65
65
  semanticUnavailableReason: semantic
66
- ? "Semantic point query unavailable."
66
+ ? "Semantic anchor query unavailable."
67
67
  : semanticReadinessReason(readiness),
68
68
  lspState,
69
69
  });
@@ -72,7 +72,7 @@ export async function runInspectWorkflow(
72
72
  if (everySectionUnavailable(sections)) {
73
73
  return {
74
74
  kind: "unavailable",
75
- reason: "No semantic, structural, or diagnostic provider could inspect this point.",
75
+ reason: "No semantic, structural, or diagnostic provider could inspect this anchor.",
76
76
  };
77
77
  }
78
78