@mrclrchtr/supi-code-intelligence 11.2.0 → 11.4.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 (145) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +19 -9
  3. package/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  4. package/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +2 -1
  5. package/node_modules/@mrclrchtr/supi-code-runtime/src/capability/types.ts +3 -1
  6. package/node_modules/@mrclrchtr/supi-code-runtime/src/declaration-level.ts +34 -0
  7. package/node_modules/@mrclrchtr/supi-code-runtime/src/query-result.ts +9 -0
  8. package/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts +13 -5
  9. package/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  10. package/node_modules/@mrclrchtr/supi-core/src/child-web-tools.ts +110 -0
  11. package/node_modules/@mrclrchtr/supi-core/src/session.ts +11 -0
  12. package/node_modules/@mrclrchtr/supi-lsp/README.md +40 -3
  13. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  14. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +2 -1
  15. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/capability/types.ts +3 -1
  16. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/declaration-level.ts +34 -0
  17. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/query-result.ts +9 -0
  18. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts +13 -5
  19. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  20. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/src/child-web-tools.ts +110 -0
  21. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/src/session.ts +11 -0
  22. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/classes/range.js +2 -2
  23. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/internal/constants.js +30 -0
  24. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/internal/trim-comparator-whitespace.js +438 -0
  25. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/package.json +1 -1
  26. package/node_modules/@mrclrchtr/supi-lsp/package.json +3 -3
  27. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostic-collection.ts +11 -4
  28. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostics.ts +77 -6
  29. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-input-admission.ts +149 -0
  30. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-typescript-project.ts +40 -0
  31. package/node_modules/@mrclrchtr/supi-lsp/src/client/client.ts +151 -44
  32. package/node_modules/@mrclrchtr/supi-lsp/src/config/tsconfig-scope.ts +10 -0
  33. package/node_modules/@mrclrchtr/supi-lsp/src/diagnostics/evidence.ts +2 -2
  34. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-typescript-coverage.ts +118 -0
  35. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-workspace-symbol.ts +157 -23
  36. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager.ts +318 -58
  37. package/node_modules/@mrclrchtr/supi-lsp/src/manager/typescript-file-local.ts +87 -0
  38. package/node_modules/@mrclrchtr/supi-lsp/src/provider/semantic-symbol-mapper.ts +22 -17
  39. package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-registry.ts +68 -6
  40. package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-rename.ts +1 -0
  41. package/node_modules/@mrclrchtr/supi-lsp/src/session/workspace-lsp-runtime.ts +5 -1
  42. package/node_modules/@mrclrchtr/supi-tree-sitter/README.md +2 -2
  43. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  44. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/api.ts +2 -1
  45. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/capability/types.ts +3 -1
  46. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/declaration-level.ts +34 -0
  47. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/query-result.ts +9 -0
  48. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/types.ts +13 -5
  49. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  50. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/child-web-tools.ts +110 -0
  51. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/session.ts +11 -0
  52. package/node_modules/@mrclrchtr/supi-tree-sitter/package.json +3 -3
  53. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/tsx/tree-sitter-tsx.wasm +0 -0
  54. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/tsx/tree-sitter-tsx.wasm.json +9 -1
  55. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/typescript/tree-sitter-typescript.wasm +0 -0
  56. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/typescript/tree-sitter-typescript.wasm.json +9 -1
  57. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/call-sites.ts +40 -25
  58. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/callees.ts +2 -0
  59. package/node_modules/@mrclrchtr/supi-tree-sitter/src/worker/call-context.ts +44 -0
  60. package/package.json +6 -5
  61. package/src/analysis/health/server-status.ts +6 -2
  62. package/src/analysis/helpers.ts +0 -7
  63. package/src/analysis/relations/implementations.ts +5 -0
  64. package/src/analysis/relations/references.ts +5 -0
  65. package/src/analysis/search/exclusions.ts +47 -0
  66. package/src/analysis/search/paths.ts +32 -9
  67. package/src/analysis/target/anchored-structural.ts +3 -8
  68. package/src/analysis/target/anchored.ts +4 -20
  69. package/src/analysis/target/file-merge.ts +162 -0
  70. package/src/analysis/target/file-outline-omissions.ts +146 -0
  71. package/src/analysis/target/file-refinement.ts +7 -7
  72. package/src/analysis/target/file.ts +44 -156
  73. package/src/analysis/target/identity.ts +1 -1
  74. package/src/analysis/target/latex-label-container.ts +6 -6
  75. package/src/analysis/target/latex-section-anchor.ts +6 -6
  76. package/src/analysis/target/resolution.ts +18 -0
  77. package/src/analysis/target/symbol.ts +44 -12
  78. package/src/analysis/target/types.ts +38 -7
  79. package/src/api.ts +1 -1
  80. package/src/app/app.ts +9 -3
  81. package/src/extension.ts +17 -11
  82. package/src/session/graph/collect.ts +3 -10
  83. package/src/session/graph-types.ts +5 -1
  84. package/src/session/graph-workflow.ts +6 -4
  85. package/src/session/inspect/collect.ts +8 -2
  86. package/src/session/inspect/file-point.ts +2 -3
  87. package/src/session/inspect-workflow.ts +1 -1
  88. package/src/session/orientation/collect.ts +54 -16
  89. package/src/session/orientation/context-sections.ts +2 -3
  90. package/src/session/orientation/facts.ts +9 -1
  91. package/src/session/orientation/workspace-context.ts +3 -0
  92. package/src/session/orientation-types.ts +3 -0
  93. package/src/session/orientation-workflow.ts +24 -8
  94. package/src/session/refactor-identity.ts +76 -0
  95. package/src/session/refactor-workflow.ts +14 -16
  96. package/src/session/session.ts +87 -12
  97. package/src/session/target-store.ts +3 -18
  98. package/src/session/target-workflow.ts +56 -37
  99. package/src/substrate/lsp/recovery.ts +5 -5
  100. package/src/tool/code_find/render.ts +8 -4
  101. package/src/tool/code_find/result.ts +78 -6
  102. package/src/tool/code_find/spec.ts +4 -3
  103. package/src/tool/code_find/structured.ts +25 -9
  104. package/src/tool/code_graph/details.ts +1 -0
  105. package/src/tool/code_graph/display.ts +1 -1
  106. package/src/tool/code_graph/guidance.ts +1 -1
  107. package/src/tool/code_graph/markdown.ts +11 -6
  108. package/src/tool/code_graph/read-next.ts +38 -9
  109. package/src/tool/code_graph/reference-selection.ts +30 -0
  110. package/src/tool/code_graph/result.ts +25 -118
  111. package/src/tool/code_graph/section.ts +137 -0
  112. package/src/tool/code_graph/spec.ts +3 -3
  113. package/src/tool/code_graph/structured.ts +17 -6
  114. package/src/tool/code_health/display-paths.ts +92 -0
  115. package/src/tool/code_health/file-scope-markdown.ts +3 -2
  116. package/src/tool/code_health/result.ts +4 -2
  117. package/src/tool/code_health/spec.ts +3 -3
  118. package/src/tool/code_health/structured-schema.ts +44 -44
  119. package/src/tool/code_inspect/spec.ts +5 -1
  120. package/src/tool/code_inspect/structured.ts +1 -2
  121. package/src/tool/code_orientation/directory-navigation.ts +20 -31
  122. package/src/tool/code_orientation/execute.ts +1 -1
  123. package/src/tool/code_orientation/result.ts +22 -5
  124. package/src/tool/code_orientation/structured-schema.ts +46 -36
  125. package/src/tool/code_orientation/structured-workspace.ts +2 -1
  126. package/src/tool/code_orientation/structured.ts +6 -12
  127. package/src/tool/code_orientation/workspace-format.ts +2 -5
  128. package/src/tool/code_orientation/workspace-output.ts +40 -13
  129. package/src/tool/code_orientation/workspace-sections.ts +48 -4
  130. package/src/tool/code_refactor_apply/result.ts +1 -1
  131. package/src/tool/code_refactor_plan/result.ts +2 -1
  132. package/src/tool/code_refactor_plan/structured.ts +2 -3
  133. package/src/tool/code_resolve/guidance.ts +1 -1
  134. package/src/tool/code_resolve/markdown.ts +127 -64
  135. package/src/tool/code_resolve/result.ts +41 -25
  136. package/src/tool/code_resolve/structured.ts +49 -18
  137. package/src/tool/result/model-budget.ts +2 -2
  138. package/src/tool/result/refactor.ts +8 -5
  139. package/src/tool/result/structured.ts +8 -5
  140. package/src/tool/result/types.ts +31 -24
  141. package/src/tool/schemas.ts +5 -5
  142. package/src/ui/status-command.ts +37 -1
  143. package/src/ui/status-overlay.ts +70 -51
  144. package/src/ui/status-presentation.ts +108 -0
  145. package/src/ui/tui/common.ts +10 -10
@@ -0,0 +1,87 @@
1
+ import * as fs from "node:fs";
2
+ import ts from "typescript";
3
+
4
+ /**
5
+ * Whether the identifier at `position` names a top-level declaration that only
6
+ * its own file can reference: the file is an ES module and the declaration is
7
+ * neither exported by a modifier nor by an export clause or assignment.
8
+ *
9
+ * Other TypeScript projects can then hold no references or implementations,
10
+ * so a project coverage gap cannot apply. Script files (no import or export),
11
+ * members, unreadable files, and non-declaration positions return false.
12
+ *
13
+ * @param position Zero-based LSP position.
14
+ */
15
+ export function isFileLocalTopLevelDeclaration(
16
+ filePath: string,
17
+ position: { readonly line: number; readonly character: number },
18
+ ): boolean {
19
+ let text: string;
20
+ try {
21
+ text = fs.readFileSync(filePath, "utf8");
22
+ } catch {
23
+ return false;
24
+ }
25
+ const sourceFile = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true);
26
+ if (!ts.isExternalModule(sourceFile)) return false;
27
+ let offset: number;
28
+ try {
29
+ offset = ts.getPositionOfLineAndCharacter(sourceFile, position.line, position.character);
30
+ } catch {
31
+ return false;
32
+ }
33
+ const statement = sourceFile.statements.find(
34
+ (candidate) => candidate.getStart(sourceFile) <= offset && offset < candidate.end,
35
+ );
36
+ if (!statement) return false;
37
+ const name = topLevelDeclarationNameAt(statement, offset, sourceFile);
38
+ return name !== null && !hasExportModifier(statement) && !exportedByName(sourceFile, name);
39
+ }
40
+
41
+ /** Name of the declaration `statement` declares at `offset`, or null. */
42
+ function topLevelDeclarationNameAt(
43
+ statement: ts.Statement,
44
+ offset: number,
45
+ sourceFile: ts.SourceFile,
46
+ ): string | null {
47
+ const names: ts.Identifier[] = [];
48
+ if (
49
+ ts.isFunctionDeclaration(statement) ||
50
+ ts.isClassDeclaration(statement) ||
51
+ ts.isInterfaceDeclaration(statement) ||
52
+ ts.isTypeAliasDeclaration(statement) ||
53
+ ts.isEnumDeclaration(statement)
54
+ ) {
55
+ if (statement.name) names.push(statement.name);
56
+ } else if (ts.isVariableStatement(statement)) {
57
+ for (const declaration of statement.declarationList.declarations) {
58
+ if (ts.isIdentifier(declaration.name)) names.push(declaration.name);
59
+ }
60
+ }
61
+ const hit = names.find((name) => name.getStart(sourceFile) <= offset && offset <= name.end);
62
+ return hit ? hit.text : null;
63
+ }
64
+
65
+ function hasExportModifier(statement: ts.Statement): boolean {
66
+ return (
67
+ ts.canHaveModifiers(statement) &&
68
+ (ts.getModifiers(statement) ?? []).some(
69
+ (modifier) =>
70
+ modifier.kind === ts.SyntaxKind.ExportKeyword ||
71
+ modifier.kind === ts.SyntaxKind.DeclareKeyword,
72
+ )
73
+ );
74
+ }
75
+
76
+ /** `export { name }`, `export default name`, or `export = name` in this file. */
77
+ function exportedByName(sourceFile: ts.SourceFile, name: string): boolean {
78
+ return sourceFile.statements.some((statement) => {
79
+ if (ts.isExportAssignment(statement)) {
80
+ return ts.isIdentifier(statement.expression) && statement.expression.text === name;
81
+ }
82
+ if (!ts.isExportDeclaration(statement) || statement.moduleSpecifier) return false;
83
+ const clause = statement.exportClause;
84
+ if (!clause || !ts.isNamedExports(clause)) return false;
85
+ return clause.elements.some((element) => (element.propertyName ?? element.name).text === name);
86
+ });
87
+ }
@@ -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;
@@ -1,11 +1,13 @@
1
1
  // Shared session-scoped LSP service registry reused by peer extensions.
2
2
 
3
3
  // biome-ignore lint/style/noExcessiveLinesPerFile: session registry, runtime recovery, and telemetry stay in one file; splitting would hide the recovery contract.
4
+ import { fileURLToPath } from "node:url";
4
5
  import {
5
6
  type CodeQueryResult,
6
7
  type CodeRequestControl,
7
8
  isCodeRequestInterruption,
8
9
  mapCodeQueryResult,
10
+ partialCodeQuery,
9
11
  throwIfCodeRequestInterrupted,
10
12
  unavailableCodeQuery,
11
13
  } from "@mrclrchtr/supi-code-runtime/api";
@@ -139,6 +141,8 @@ function recordScopeDecisionEvent(manager: LspManager): void {
139
141
  }
140
142
  }
141
143
 
144
+ const FILE_STARTUP_FAILURE_REASON = "The routed LSP client could not be started for this file";
145
+
142
146
  class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
143
147
  constructor(private readonly manager: LspManager) {}
144
148
 
@@ -157,6 +161,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
157
161
  const resolvedPath = this.resolveFilePath(filePath);
158
162
  const client = await this.manager.ensureFileOpen(resolvedPath, {
159
163
  recoverProcessCrash: true,
164
+ protectInputs: true,
160
165
  control,
161
166
  });
162
167
  if (!client) return unavailableFileQuery("hover", resolvedPath);
@@ -171,6 +176,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
171
176
  const resolvedPath = this.resolveFilePath(filePath);
172
177
  const client = await this.manager.ensureFileOpen(resolvedPath, {
173
178
  recoverProcessCrash: true,
179
+ protectInputs: true,
174
180
  control,
175
181
  });
176
182
  if (!client) return unavailableFileQuery("definition", resolvedPath);
@@ -185,12 +191,18 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
185
191
  const resolvedPath = this.resolveFilePath(filePath);
186
192
  const client = await this.manager.ensureFileOpen(resolvedPath, {
187
193
  recoverProcessCrash: true,
194
+ protectInputs: true,
188
195
  control,
189
196
  });
190
197
  if (!client) return unavailableFileQuery("references", resolvedPath);
191
- return mapCodeQueryResult(
192
- await client.references(resolvedPath, position, control),
193
- (data) => data ?? [],
198
+ return this.withProjectCoverage(
199
+ client,
200
+ { file: resolvedPath, position },
201
+ "references",
202
+ mapCodeQueryResult(
203
+ await client.references(resolvedPath, position, control),
204
+ (data) => data ?? [],
205
+ ),
194
206
  );
195
207
  }
196
208
 
@@ -202,10 +214,34 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
202
214
  const resolvedPath = this.resolveFilePath(filePath);
203
215
  const client = await this.manager.ensureFileOpen(resolvedPath, {
204
216
  recoverProcessCrash: true,
217
+ protectInputs: true,
205
218
  control,
206
219
  });
207
220
  if (!client) return unavailableFileQuery("implementation", resolvedPath);
208
- return client.implementation(resolvedPath, position, control);
221
+ return this.withProjectCoverage(
222
+ client,
223
+ { file: resolvedPath, position },
224
+ "implementation",
225
+ await client.implementation(resolvedPath, position, control),
226
+ );
227
+ }
228
+
229
+ /**
230
+ * Downgrade a completed project-wide answer to partial when the TypeScript
231
+ * server may not have searched every relevant project.
232
+ */
233
+ private withProjectCoverage<T extends Location[] | Location | LocationLink[] | null>(
234
+ client: NonNullable<Awaited<ReturnType<LspManager["ensureFileOpen"]>>>,
235
+ target: { readonly file: string; readonly position: Position },
236
+ request: "references" | "implementation",
237
+ result: CodeQueryResult<T>,
238
+ ): CodeQueryResult<T> {
239
+ if (result.kind !== "completed") return result;
240
+ const gap = this.manager.typeScriptProjectCoverageGap(client, target.file, request, {
241
+ resultFiles: locationFiles(result.data),
242
+ position: target.position,
243
+ });
244
+ return gap ? partialCodeQuery(result.data, gap) : result;
209
245
  }
210
246
 
211
247
  async documentSymbols(
@@ -215,6 +251,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
215
251
  const resolvedPath = this.resolveFilePath(filePath);
216
252
  const client = await this.manager.ensureFileOpen(resolvedPath, {
217
253
  recoverProcessCrash: true,
254
+ protectInputs: true,
218
255
  control,
219
256
  });
220
257
  if (!client) return unavailableFileQuery("document symbols", resolvedPath);
@@ -260,6 +297,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
260
297
  const resolvedPath = this.resolveFilePath(filePath);
261
298
  const client = await this.manager.ensureFileOpen(resolvedPath, {
262
299
  recoverProcessCrash: true,
300
+ protectInputs: true,
263
301
  control,
264
302
  });
265
303
  if (!client) return null;
@@ -309,7 +347,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
309
347
  const processCrashRecovery = this.manager.getProcessCrashRecoveryReportForFile(resolvedPath);
310
348
  return {
311
349
  kind: "unavailable",
312
- reason: "No LSP client can serve this file",
350
+ reason: this.fileUnavailableReason(resolvedPath, "No LSP client can serve this file"),
313
351
  ...(processCrashRecovery ? { processCrashRecovery } : {}),
314
352
  };
315
353
  }
@@ -347,7 +385,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
347
385
  if (!client) {
348
386
  return {
349
387
  kind: "unavailable",
350
- reason: "The routed LSP client could not be started for this file",
388
+ reason: this.fileUnavailableReason(resolvedPath, FILE_STARTUP_FAILURE_REASON),
351
389
  ...startup,
352
390
  ...recovery,
353
391
  };
@@ -355,6 +393,15 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
355
393
  return { kind: "ready", ...startup, ...recovery };
356
394
  }
357
395
 
396
+ private fileUnavailableReason(filePath: string, configuredRouteReason: string): string {
397
+ if (!this.manager.hasConfiguredServerForFile(filePath)) {
398
+ return "No compatible LSP server is configured for this file";
399
+ }
400
+ return this.manager.hasFailedStartupForFile(filePath)
401
+ ? FILE_STARTUP_FAILURE_REASON
402
+ : configuredRouteReason;
403
+ }
404
+
358
405
  /**
359
406
  * Wait until all started LSP clients are ready for semantic queries.
360
407
  * Performs one representative warm-up probe per client/root.
@@ -588,6 +635,21 @@ export async function waitForWorkspaceLspRuntime(
588
635
  return state;
589
636
  }
590
637
 
638
+ /** Local file paths of LSP locations or location links; non-file URIs are skipped. */
639
+ function locationFiles(data: Location[] | Location | LocationLink[] | null): string[] {
640
+ const items: (Location | LocationLink)[] =
641
+ data === null ? [] : Array.isArray(data) ? data : [data];
642
+ return items.flatMap((item) => {
643
+ const uri = "targetUri" in item ? item.targetUri : item.uri;
644
+ if (!uri.startsWith("file:")) return [];
645
+ try {
646
+ return [fileURLToPath(uri)];
647
+ } catch {
648
+ return [];
649
+ }
650
+ });
651
+ }
652
+
591
653
  /** Remove the LSP service state for a session cwd. */
592
654
  export function clearWorkspaceLspRuntime(cwd: string): void {
593
655
  registry.clear(cwd);
@@ -21,6 +21,7 @@ export async function runRoutedRename(options: {
21
21
  const { manager, file, position, newName, control } = options;
22
22
  const client = await manager.ensureFileOpen(file, {
23
23
  recoverProcessCrash: true,
24
+ protectInputs: true,
24
25
  control,
25
26
  });
26
27
  if (!client) return null;
@@ -143,7 +143,11 @@ export interface WorkspaceLspRuntime extends WorkspaceLspDiagnosticSurface {
143
143
  filePath: string,
144
144
  control?: CodeRequestControl,
145
145
  ): Promise<CodeQueryResult<DocumentSymbol[] | SymbolInformation[]>>;
146
- /** Collect symbols from routes that can contribute within the optional path scopes. */
146
+ /**
147
+ * Collect symbols from contributing routes; completeness is relative to scopes.
148
+ * Data may include out-of-scope rows, which callers must filter themselves.
149
+ * Only policy exclusions proven outside every scope are irrelevant to completeness.
150
+ */
147
151
  workspaceSymbol(
148
152
  query: string,
149
153
  control?: CodeRequestControl,
@@ -82,11 +82,11 @@ The `type` filter accepts `class`, `interface`, `type`, `enum`, `struct`, `union
82
82
  ### Extraction limits
83
83
 
84
84
  - TS/JS, Python, Java, Go, Rust, and C/C++ outlines include nested named declarations and members. They are not complete indexes of local variables, parameters, or anonymous expressions. Other languages retain their existing extraction depth. HTML outlines list only elements with non-empty `id` attributes. SQL outlines list supported `CREATE` declarations and first-level table/type members. LaTeX outlines list section headings and selected command, environment, label, acronym, glossary-entry, and color definitions.
85
- - TypeScript and TSX use [checked build-time grammar patches](scripts/generate-typescript-wasm.mjs) for type-only star re-exports and arrays of qualified import types such as `import("node:fs").Dirent[]`. Runtime parsing retains the original source and coordinates; other grammar gaps still report recovered syntax.
85
+ - TypeScript and TSX use [checked build-time grammar patches](scripts/generate-typescript-wasm.mjs) for type-only star re-exports, arrays of qualified import types such as `import("node:fs").Dirent[]`, import types in generic calls such as `read<import("./api").Value>()` or `read<typeof import("./api")>()`, and import types with type arguments such as `import("typebox").Static<T>`. Runtime parsing retains the original source and coordinates; other grammar gaps still report recovered syntax.
86
86
  - JavaScript-family imports collect `import` statements, not CommonJS `require()` calls. Exports collect file-level `export` statements, including TypeScript `export =`; they do not collect `module.exports` assignments or nested namespace exports. An eligible `.cjs` file can therefore return no imports or exports.
87
87
  - Python imports retain `import`/`from` module targets, including relative prefixes. Java imports retain ordinary/static targets. Go imports retain single/grouped paths. Rust imports retain explicit `use` paths, `extern crate`, and external `mod` names; inline module bodies are not imports. C/C++ imports retain literal quoted and angle-bracket include targets. Grouped paths use explicit syntax only; no files or bindings are resolved. Conditional directives are written evidence, not proof of active dependencies. Dynamic loaders, computed targets, and C++20 module imports remain outside extraction support.
88
88
  - LaTeX imports include package, class, source, and bibliography directives. Bibliography directives can refer to `.bib` files, but the grammar does not parse those files.
89
- - Call-site and callee queries use syntax, not resolved symbol identity. Distinct sites have source ranges; repeated names on one line are not merged. Rust macro invocations are syntax evidence, not expanded calls. JSX tags are not call expressions. Library callee queries work without LSP, but new `code_graph` targets require semantic readiness in Code Intelligence.
89
+ - Call-site and callee queries use syntax, not resolved symbol identity. Distinct sites have source ranges; repeated names on one line are not merged. Rust macro invocations are syntax evidence, not expanded calls. JSX tags and TypeScript/TSX import references in type syntax are excluded; dynamic import expressions remain call sites. Library callee queries work without LSP, but new `code_graph` targets require semantic readiness in Code Intelligence.
90
90
  - `.jsx` uses JavaScript; `.tsx` uses the separate TSX grammar. `.h` uses C by default. An explicit session association can select C++ without changing the supported suffix set. `.zsh` and `.ksh` use Bash; this is not complete support for those shell dialects.
91
91
  - Go module manifests (`.mod`), Ruby ERB templates (`.erb`), and BibTeX (`.bib`) have [built-in LSP routes](../supi-lsp/README.md#built-in-route-matrix), but no AST grammar. Unlisted extensions, including JSON, YAML, TOML, and CSS, have no grammar. Custom LSP configuration does not add one.
92
92
 
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-code-runtime",
3
- "version": "11.2.0",
3
+ "version": "11.4.0",
4
4
  "description": "Shared workspace context and capability contracts for code intelligence",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -14,6 +14,7 @@ export type {
14
14
  StructuralProvider,
15
15
  StructuralResult,
16
16
  } from "./capability/types.ts";
17
+ export { childDeclarationLevel } from "./declaration-level.ts";
17
18
  export type {
18
19
  CFamilyExtension,
19
20
  CFamilyFileAssociationResolver,
@@ -50,7 +51,7 @@ export type {
50
51
  CodeResult,
51
52
  CodeSymbol,
52
53
  ConfidenceMode,
53
- DeclarationNesting,
54
+ DeclarationLevel,
54
55
  DisambiguationCandidate,
55
56
  DocumentCodeSymbol,
56
57
  DocumentEditPrecondition,
@@ -77,7 +77,9 @@ export interface SemanticProvider {
77
77
  ): Promise<CodeQueryResult<DocumentCodeSymbol[]>>;
78
78
  /**
79
79
  * Collect workspace symbols from routes that can contribute within the
80
- * optional canonical path scopes.
80
+ * optional path scopes. Completeness is relative to those scopes, but data
81
+ * may include out-of-scope rows; consumers must filter rows themselves.
82
+ * Policy exclusions proven outside every scope do not make the query partial.
81
83
  */
82
84
  workspaceSymbols(
83
85
  query: string,
@@ -0,0 +1,34 @@
1
+ import type { DeclarationLevel } from "./types.ts";
2
+
3
+ /** Declarations whose body holds statements, so nested declarations are local to it. */
4
+ const FUNCTION_LIKE_KINDS = new Set(["function", "method", "constructor"]);
5
+ /** Bindings whose value may be a function (locals) or an object literal (members). */
6
+ const VALUE_BINDING_KINDS = new Set(["variable", "constant", "property", "field"]);
7
+ /** Kinds that name an entry of an object, type, or enum rather than a statement-level binding. */
8
+ const MEMBER_ENTRY_KINDS = new Set(["property", "field", "method", "enummember", "key", "event"]);
9
+
10
+ /**
11
+ * Level of a declaration reported directly inside `parent`.
12
+ *
13
+ * Inside a local declaration everything stays local. A function, method, or
14
+ * constructor makes its nested declarations local. A variable, constant,
15
+ * property, or field holds either a function body (nested bindings are local)
16
+ * or an object literal (nested properties and methods are members). Every
17
+ * other container — class, interface, enum, struct, namespace, module, or a
18
+ * document section — makes its nested declarations members.
19
+ *
20
+ * Kinds compare case-insensitively, so LSP SymbolKind names and Tree-sitter
21
+ * outline kinds share one rule.
22
+ */
23
+ export function childDeclarationLevel(
24
+ parent: { readonly kind: string | null; readonly level: DeclarationLevel },
25
+ childKind: string | null,
26
+ ): Exclude<DeclarationLevel, "top-level" | "unknown"> {
27
+ if (parent.level === "local") return "local";
28
+ const parentKind = parent.kind?.toLowerCase() ?? "";
29
+ if (FUNCTION_LIKE_KINDS.has(parentKind)) return "local";
30
+ if (VALUE_BINDING_KINDS.has(parentKind)) {
31
+ return MEMBER_ENTRY_KINDS.has(childKind?.toLowerCase() ?? "") ? "member" : "local";
32
+ }
33
+ return "member";
34
+ }
@@ -3,8 +3,17 @@ export interface CodeQueryPartialMetadata {
3
3
  /** Automatic path-policy evidence removed from a collected result. */
4
4
  readonly automaticPathExclusion?: {
5
5
  readonly excludedCount: number;
6
+ /** Observed policy paths, not canonical navigation paths; retain aliases when presenting exclusions. */
6
7
  readonly examples: readonly string[];
7
8
  };
9
+ /**
10
+ * True when automatic path-policy exclusions are the only reason the result
11
+ * is partial: every contributing provider branch completed and no coverage
12
+ * gap was observed. Excluded rows matched paths the workspace policy treats
13
+ * as out of automatic scope, so the retained rows are the complete in-policy
14
+ * answer.
15
+ */
16
+ readonly exclusionOnly?: boolean;
8
17
  }
9
18
 
10
19
  /**
@@ -34,8 +34,16 @@ export interface SymbolAnchor {
34
34
  character: number;
35
35
  }
36
36
 
37
- /** Provider-backed nesting evidence for a declaration reported within one document. */
38
- export type DeclarationNesting = "top-level" | "nested" | "unknown";
37
+ /**
38
+ * Where a declaration sits within its file, as reported by a provider.
39
+ *
40
+ * - `top-level`: directly in the file, not inside another declaration.
41
+ * - `member`: directly inside a class, interface, enum, struct, namespace,
42
+ * module, or object literal (methods, fields, properties, enum members).
43
+ * - `local`: inside the body of a function, method, or constructor.
44
+ * - `unknown`: the provider reported a flat symbol list without hierarchy.
45
+ */
46
+ export type DeclarationLevel = "top-level" | "member" | "local" | "unknown";
39
47
 
40
48
  /**
41
49
  * A discovered symbol / declaration.
@@ -54,7 +62,7 @@ export interface CodeSymbol {
54
62
  file: string;
55
63
  declarationAnchor: SymbolAnchor;
56
64
  nameAnchor?: SymbolAnchor;
57
- /** Named symbolic container when reported; absence does not prove top-level nesting. */
65
+ /** Named enclosing declaration when reported; absence does not prove a top-level declaration. */
58
66
  container?: string | null;
59
67
  }
60
68
 
@@ -63,10 +71,10 @@ export interface CodeSymbol {
63
71
  *
64
72
  * `unknown` means the provider returned a flat observation without an actual
65
73
  * hierarchy. A reported container name remains metadata and does not promote
66
- * a flat observation to known nesting.
74
+ * a flat observation to a known level.
67
75
  */
68
76
  export interface DocumentCodeSymbol extends CodeSymbol {
69
- nesting: DeclarationNesting;
77
+ level: DeclarationLevel;
70
78
  }
71
79
 
72
80
  // ── Result types ───────────────────────────────────────────────────────
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-core",
3
- "version": "11.2.0",
3
+ "version": "11.4.0",
4
4
  "description": "Shared settings, configuration, reporting, and session infrastructure",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -0,0 +1,110 @@
1
+ // Session-provided Web tools for SuPi child sessions (Agent Runs and Reviewer Sessions).
2
+ //
3
+ // The loaded supi-web extension answers a synchronous request on the parent event bus.
4
+ // Consumers never depend on supi-web; when it is absent or provides no tools, the
5
+ // request returns undefined and the child simply lacks Web tools.
6
+
7
+ import type { ExtensionAPI, ExtensionFactory } from "@earendil-works/pi-coding-agent";
8
+
9
+ /** Web tools that child sessions may receive when the containing session provides them. */
10
+ export const CHILD_WEB_TOOL_NAMES = [
11
+ "web_fetch_md",
12
+ "web_search",
13
+ "web_docs_search",
14
+ "web_docs_fetch",
15
+ ] as const;
16
+
17
+ /** One session-provided Web tool name. */
18
+ export type ChildWebToolName = (typeof CHILD_WEB_TOOL_NAMES)[number];
19
+
20
+ /**
21
+ * Web tools currently callable in the containing session plus a child-only extension
22
+ * factory that registers them. The factory must not capture the parent session; it may
23
+ * capture plain data such as the containing session's configuration directory.
24
+ */
25
+ export interface ChildWebToolProvision {
26
+ readonly toolNames: readonly ChildWebToolName[];
27
+ /** Register the requested subset of `toolNames` in a child session. */
28
+ readonly createFactory: (toolNames: readonly ChildWebToolName[]) => ExtensionFactory;
29
+ }
30
+
31
+ /** Plain containing-session data supplied with a child Web tool request. */
32
+ export interface ChildWebToolsRequestContext {
33
+ /**
34
+ * Working directory whose SuPi configuration governs Web settings such as Firecrawl.
35
+ * Children with a different cwd (for example a frozen Review Workspace) keep this policy.
36
+ */
37
+ readonly configCwd: string;
38
+ }
39
+
40
+ type EventBusLike = Pick<ExtensionAPI["events"], "on" | "emit">;
41
+
42
+ const REQUEST_CHANNEL = "supi:child-web-tools:request";
43
+ const RESPONSE_CHANNEL = "supi:child-web-tools:response";
44
+
45
+ interface ChildWebToolsRequest extends ChildWebToolsRequestContext {
46
+ readonly requestId: string;
47
+ }
48
+
49
+ interface ChildWebToolsResponse {
50
+ readonly requestId: string;
51
+ readonly provision: ChildWebToolProvision;
52
+ }
53
+
54
+ let nextRequestId = 0;
55
+
56
+ /**
57
+ * Answer child Web tool requests on the parent event bus. The callback must be synchronous
58
+ * because Pi's event bus does not await listeners. Returns an unsubscribe function.
59
+ */
60
+ export function provideChildWebTools(
61
+ events: EventBusLike,
62
+ resolve: (context: ChildWebToolsRequestContext) => ChildWebToolProvision | undefined,
63
+ ): () => void {
64
+ return events.on(REQUEST_CHANNEL, (data) => {
65
+ const request = data as Partial<ChildWebToolsRequest> | undefined;
66
+ if (typeof request?.requestId !== "string" || typeof request.configCwd !== "string") return;
67
+ const { requestId, configCwd } = request;
68
+ const provision = resolve({ configCwd });
69
+ if (!provision || provision.toolNames.length === 0) return;
70
+ events.emit(RESPONSE_CHANNEL, { requestId, provision } satisfies ChildWebToolsResponse);
71
+ });
72
+ }
73
+
74
+ /** Capture the Web tools the containing session currently provides, if any. */
75
+ export function requestChildWebTools(
76
+ events: EventBusLike,
77
+ context: ChildWebToolsRequestContext,
78
+ ): ChildWebToolProvision | undefined {
79
+ const requestId = `child-web-${process.pid}-${++nextRequestId}`;
80
+ let provision: ChildWebToolProvision | undefined;
81
+ const unsubscribe = events.on(RESPONSE_CHANNEL, (data) => {
82
+ const response = data as Partial<ChildWebToolsResponse> | undefined;
83
+ if (response?.requestId === requestId && response.provision) provision = response.provision;
84
+ });
85
+ try {
86
+ events.emit(REQUEST_CHANNEL, { requestId, ...context } satisfies ChildWebToolsRequest);
87
+ } finally {
88
+ unsubscribe();
89
+ }
90
+ return provision;
91
+ }
92
+
93
+ /**
94
+ * Return the Web tools callable in a session under Pi's exposure rules: active `direct`
95
+ * tools, plus registered `codemode` and `deferred` tools. `model-only` and `hidden`
96
+ * tools are not callable.
97
+ */
98
+ export function callableChildWebToolNames(
99
+ pi: Pick<ExtensionAPI, "getAllTools" | "getActiveTools">,
100
+ ): ChildWebToolName[] {
101
+ const active = new Set(pi.getActiveTools());
102
+ const exposures = new Map(
103
+ pi.getAllTools().map((tool) => [tool.name, tool.exposure ?? "direct"] as const),
104
+ );
105
+ return CHILD_WEB_TOOL_NAMES.filter((name) => {
106
+ const exposure = exposures.get(name);
107
+ if (exposure === "direct") return active.has(name);
108
+ return exposure === "codemode" || exposure === "deferred";
109
+ });
110
+ }
@@ -1,5 +1,16 @@
1
1
  // supi-core session domain — session utilities and registries.
2
2
 
3
+ export type {
4
+ ChildWebToolName,
5
+ ChildWebToolProvision,
6
+ ChildWebToolsRequestContext,
7
+ } from "./child-web-tools.ts";
8
+ export {
9
+ CHILD_WEB_TOOL_NAMES,
10
+ callableChildWebToolNames,
11
+ provideChildWebTools,
12
+ requestChildWebTools,
13
+ } from "./child-web-tools.ts";
3
14
  export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
4
15
  export type {
5
16
  SessionCapabilitySkill,