@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
@@ -11,6 +11,7 @@ import {
11
11
  type DeclarationOccurrenceCandidate,
12
12
  declarationOccurrenceFor,
13
13
  } from "./identity.ts";
14
+ import { createAnchoredResolution } from "./resolution.ts";
14
15
  import type { ResolvedTargetData, TargetOutcome } from "./types.ts";
15
16
 
16
17
  type LabelOutlineCandidate = DeclarationOccurrenceCandidate & {
@@ -110,12 +111,11 @@ export async function resolveLatexLabelTargetAtAnchor(input: {
110
111
  provenance: ["structural"],
111
112
  anchorKind: "name",
112
113
  container: label.container,
113
- resolution: {
114
- requested: { line: input.line, character: input.character },
115
- resolved: { line: anchor.line, character: anchor.character },
116
- snapped: anchor.line !== input.line || anchor.character !== input.character,
117
- source: "structural-identifier",
118
- },
114
+ resolution: createAnchoredResolution(
115
+ { line: input.line, character: input.character },
116
+ anchor,
117
+ "structural-identifier",
118
+ ),
119
119
  };
120
120
  }
121
121
 
@@ -10,6 +10,7 @@ import {
10
10
  type DeclarationOccurrenceCandidate,
11
11
  declarationOccurrenceFor,
12
12
  } from "./identity.ts";
13
+ import { createAnchoredResolution } from "./resolution.ts";
13
14
  import type { ResolvedTargetData } from "./types.ts";
14
15
 
15
16
  interface SectionCandidate extends DeclarationOccurrenceCandidate {
@@ -67,12 +68,11 @@ export async function resolveLatexSectionTargetAtAnchor(input: {
67
68
  provenance: ["structural"],
68
69
  anchorKind: "name",
69
70
  container: selected.container,
70
- resolution: {
71
- requested: { line: input.line, character: input.character },
72
- resolved: { line: anchor.line, character: anchor.character },
73
- snapped: anchor.line !== input.line || anchor.character !== input.character,
74
- source: "structural",
75
- },
71
+ resolution: createAnchoredResolution(
72
+ { line: input.line, character: input.character },
73
+ anchor,
74
+ "structural",
75
+ ),
76
76
  };
77
77
  } catch (error) {
78
78
  if (isCodeRequestInterruption(error, input.control)) throw error;
@@ -0,0 +1,18 @@
1
+ import type { AnchoredResolutionMetadata, AnchoredResolutionSource } from "../../types/index.ts";
2
+
3
+ /**
4
+ * Record one coordinate request independently of the provider's symbol-match category.
5
+ * An exact identifier hit still snaps when normalized to a different name-anchor position.
6
+ */
7
+ export function createAnchoredResolution(
8
+ requested: AnchoredResolutionMetadata["requested"],
9
+ resolved: AnchoredResolutionMetadata["resolved"],
10
+ source: AnchoredResolutionSource,
11
+ ): AnchoredResolutionMetadata {
12
+ return {
13
+ requested: { line: requested.line, character: requested.character },
14
+ resolved: { line: resolved.line, character: resolved.character },
15
+ snapped: requested.line !== resolved.line || requested.character !== resolved.character,
16
+ source,
17
+ };
18
+ }
@@ -17,6 +17,7 @@ import {
17
17
  import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
18
18
  import type { TargetSymbolKind } from "../../session/target-input.ts";
19
19
  import type { AnchorKind } from "../../session/target-store.ts";
20
+ import { describePartialQuery } from "../search/exclusions.ts";
20
21
  import { normalizePath } from "../search/paths.ts";
21
22
  import type {
22
23
  DisambiguationCandidateData,
@@ -131,7 +132,7 @@ export async function resolveSymbolTarget(
131
132
  reason: `Symbol discovery for \`${symbol}\` is unavailable: ${result.reason}`,
132
133
  };
133
134
  }
134
- if (result.data.length === 0) return emptySymbolOutcome(symbol, result, options?.path);
135
+ if (result.data.length === 0) return emptySymbolOutcome(symbol, result, cwd, options?.path);
135
136
 
136
137
  const scoped = result.data
137
138
  .filter((candidate) => (scopePath ? isWithinOrEqual(scopePath, candidate.file) : true))
@@ -139,7 +140,7 @@ export async function resolveSymbolTarget(
139
140
  const eligible = options?.exportedOnly
140
141
  ? scoped.filter((candidate) => !NON_EXPORTED_KINDS.has(candidate.kind))
141
142
  : scoped;
142
- if (eligible.length === 0) return emptySymbolOutcome(symbol, result, options?.path);
143
+ if (eligible.length === 0) return emptySymbolOutcome(symbol, result, cwd, options?.path);
143
144
 
144
145
  const requestedKind = options?.kind;
145
146
  if (requestedKind) {
@@ -150,7 +151,7 @@ export async function resolveSymbolTarget(
150
151
  return buildCandidateOutcome({
151
152
  kind: "kind-mismatch",
152
153
  candidates: eligible,
153
- ...candidateCompleteness(result, eligible.length),
154
+ ...candidateCompleteness(result, eligible.length, cwd),
154
155
  semantic,
155
156
  cwd,
156
157
  maxResults: options.maxResults,
@@ -160,7 +161,8 @@ export async function resolveSymbolTarget(
160
161
  }
161
162
  return resolveCandidates({
162
163
  candidates: exactKind,
163
- ...candidateCompleteness(result, exactKind.length),
164
+ ...candidateCompleteness(result, exactKind.length, cwd),
165
+ exclusionNote: exclusionOnlyNote(result, cwd),
164
166
  semantic,
165
167
  cwd,
166
168
  maxResults: options.maxResults,
@@ -170,7 +172,8 @@ export async function resolveSymbolTarget(
170
172
 
171
173
  return resolveCandidates({
172
174
  candidates: eligible,
173
- ...candidateCompleteness(result, eligible.length),
175
+ ...candidateCompleteness(result, eligible.length, cwd),
176
+ exclusionNote: exclusionOnlyNote(result, cwd),
174
177
  semantic,
175
178
  cwd,
176
179
  maxResults: options?.maxResults,
@@ -187,7 +190,11 @@ function normalizeProviderKind(kind: string): string {
187
190
  }
188
191
 
189
192
  async function resolveCandidates(
190
- options: CandidateOutcomeBase & Omit<TargetCandidateCompleteness, "omittedCount">,
193
+ options: CandidateOutcomeBase &
194
+ Omit<TargetCandidateCompleteness, "omittedCount"> & {
195
+ /** Disclosure for a unique match beside policy-excluded rows. */
196
+ exclusionNote?: string;
197
+ },
191
198
  ): Promise<TargetOutcome> {
192
199
  const {
193
200
  candidates,
@@ -198,13 +205,16 @@ async function resolveCandidates(
198
205
  totalCount,
199
206
  partialReason,
200
207
  partialMessage,
208
+ exclusionNote,
201
209
  } = options;
202
210
  const ranged = candidates.filter(
203
211
  (candidate) =>
204
212
  candidate.declarationAnchor.line > 0 || candidate.declarationAnchor.character > 0,
205
213
  );
206
214
  if (ranged.length === 1 && totalCount !== null) {
207
- return resolvedTarget(await refineResolvedSymbolAnchor(ranged[0], semantic, control));
215
+ const resolved = resolvedTarget(await refineResolvedSymbolAnchor(ranged[0], semantic, control));
216
+ // Exclusion-only evidence resolves, but the excluded rows stay disclosed.
217
+ return exclusionNote ? { ...resolved, notes: [exclusionNote] } : resolved;
208
218
  }
209
219
  return buildCandidateOutcome({
210
220
  kind: "disambiguation",
@@ -219,7 +229,7 @@ async function resolveCandidates(
219
229
  });
220
230
  }
221
231
 
222
- function resolvedTarget(candidate: CodeSymbol): TargetOutcome {
232
+ function resolvedTarget(candidate: CodeSymbol): Extract<TargetOutcome, { kind: "resolved" }> {
223
233
  const anchor = anchorOf(candidate);
224
234
  return {
225
235
  kind: "resolved",
@@ -251,12 +261,29 @@ interface CandidateOutcomeBase {
251
261
  function candidateCompleteness(
252
262
  result: Exclude<CodeQueryResult<CodeSymbol[]>, { kind: "unavailable" }>,
253
263
  totalCount: number,
264
+ cwd: string,
254
265
  ): Omit<TargetCandidateCompleteness, "omittedCount"> {
255
- return result.kind === "partial"
256
- ? { totalCount: null, partialReason: "provider-limited", partialMessage: result.reason }
266
+ // Policy exclusions alone remove only rows the workspace marked out of
267
+ // automatic scope; the retained in-policy rows are complete. Failures and
268
+ // coverage gaps keep the total unknown.
269
+ return result.kind === "partial" && result.metadata?.exclusionOnly !== true
270
+ ? {
271
+ totalCount: null,
272
+ partialReason: "provider-limited",
273
+ partialMessage: describePartialQuery(result.reason, result.metadata, cwd),
274
+ }
257
275
  : { totalCount, partialReason: null };
258
276
  }
259
277
 
278
+ /** Describe exclusion-only evidence so a resolved target still discloses dropped rows. */
279
+ function exclusionOnlyNote(
280
+ result: Exclude<CodeQueryResult<CodeSymbol[]>, { kind: "unavailable" }>,
281
+ cwd: string,
282
+ ): string | undefined {
283
+ if (result.kind !== "partial" || result.metadata?.exclusionOnly !== true) return undefined;
284
+ return describePartialQuery(result.reason, result.metadata, cwd);
285
+ }
286
+
260
287
  type CandidateOutcomeOptions = CandidateOutcomeBase &
261
288
  Omit<TargetCandidateCompleteness, "omittedCount"> &
262
289
  (
@@ -272,17 +299,22 @@ type CandidateOutcomeOptions = CandidateOutcomeBase &
272
299
  function emptySymbolOutcome(
273
300
  symbol: string,
274
301
  result: Exclude<CodeQueryResult<CodeSymbol[]>, { kind: "unavailable" }>,
302
+ cwd: string,
275
303
  scope?: string,
276
304
  ): TargetOutcome {
277
305
  if (result.kind === "partial") {
278
306
  return {
279
307
  kind: "unavailable",
280
- reason: `Symbol discovery for \`${symbol}\` is incomplete: ${result.reason}`,
308
+ reason: `Symbol discovery for \`${symbol}\` is incomplete: ${describePartialQuery(result.reason, result.metadata, cwd)}`,
281
309
  };
282
310
  }
283
311
  return {
284
312
  kind: "error",
285
- message: `Symbol not found: \`${symbol}\`${scope ? ` in path \`${scope}\`` : ""}. Try \`code_resolve\` to search for it, or use an anchor target (file/line/character) if you know the location.`,
313
+ message: [
314
+ `Symbol not found: \`${symbol}\`${scope ? ` in path \`${scope}\`` : ""}.`,
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.',
317
+ ].join(" "),
286
318
  };
287
319
  }
288
320
 
@@ -101,21 +101,47 @@ export interface ResolvedTargetData {
101
101
  resolution?: import("../../types/index.ts").AnchoredResolutionMetadata;
102
102
  }
103
103
 
104
+ /** Names left out of a File outline that sit on a contiguous span of lines. */
105
+ export interface FileOutlineNameSpan {
106
+ readonly count: number;
107
+ /** 1-based first and last line holding such a name. */
108
+ readonly startLine: number;
109
+ readonly endLine: number;
110
+ }
111
+
112
+ /**
113
+ * Declarations discovered in a file but left out of its File outline, counted
114
+ * so an agent can request them explicitly.
115
+ */
116
+ export interface FileOutlineNotListed {
117
+ /** Names bound by import statements; the file does not declare them. */
118
+ readonly importedNames: FileOutlineNameSpan | null;
119
+ /** Names inside `export { … }` lists, including re-exports `export { … } from`. */
120
+ readonly exportListNames: FileOutlineNameSpan | null;
121
+ /** `export … from` statements; they only forward names declared in other modules. */
122
+ readonly reExportStatements: FileOutlineNameSpan | null;
123
+ /** Declarations inside function, method, or constructor bodies. */
124
+ readonly localDeclarations: number;
125
+ }
126
+
104
127
  /**
105
- * A file-derived Target group with zero or more evidence-backed declarations.
128
+ * The File outline of one file: its top-level declarations and members,
129
+ * without imported names, export-list names, and local declarations.
106
130
  */
107
- export interface ResolvedTargetGroupData {
131
+ export interface FileOutlineData {
108
132
  file: string;
109
133
  displayName: string;
110
134
  targets: ResolvedTargetData[];
111
135
  /** Providers that successfully enumerated the selected file. */
112
136
  discoveryProvenance: readonly TargetProviderProvenance[];
113
- /** Conservative confidence across the complete group, before display capping. */
137
+ /** Conservative confidence across the complete outline, before display capping. */
114
138
  confidence: "semantic" | "structural" | "heuristic" | "unavailable";
115
- /** Complete-group declarations whose provider observations could not establish hierarchy. */
116
- unknownNestingCount: number;
139
+ /** Declarations in the complete outline whose provider reported no enclosing declaration. */
140
+ unknownLevelCount: number;
117
141
  /** Partial provider collection; targets remain usable and exact absence is not claimed. */
118
142
  partial?: { reason: string; errorRanges: readonly SourceRange[] };
143
+ /** Discovered declarations left out of `targets`, with exact counts. */
144
+ notListed: FileOutlineNotListed;
119
145
  }
120
146
 
121
147
  /**
@@ -160,8 +186,13 @@ export interface TargetCandidateCompleteness {
160
186
  * the resolution pipeline itself stays presentation-agnostic.
161
187
  */
162
188
  export type TargetOutcome =
163
- | { kind: "resolved"; target: ResolvedTargetData }
164
- | { kind: "group"; group: ResolvedTargetGroupData }
189
+ | {
190
+ kind: "resolved";
191
+ target: ResolvedTargetData;
192
+ /** Request-scoped evidence notes, such as policy exclusions beside a unique match. */
193
+ notes?: readonly string[];
194
+ }
195
+ | { kind: "file-outline"; outline: FileOutlineData }
165
196
  | ({
166
197
  kind: "disambiguation";
167
198
  candidates: DisambiguationCandidateData[];
package/src/api.ts CHANGED
@@ -40,8 +40,8 @@ export type {
40
40
  export type { CodeProvider, CodeProviderState } from "./analysis/provider.ts";
41
41
  // Target resolution types.
42
42
  export type {
43
+ FileOutlineData,
43
44
  ResolvedTargetData,
44
- ResolvedTargetGroupData,
45
45
  TargetOutcome,
46
46
  TargetProviderProvenance,
47
47
  } from "./analysis/target/types.ts";
package/src/app/app.ts CHANGED
@@ -72,8 +72,10 @@ export function createSessionCache(): {
72
72
  * Create the code-intelligence app and wire it to pi lifecycle events.
73
73
  *
74
74
  * Registers:
75
- * - `session_start` — creates a session for the new cwd, checks branch
76
- * for existing overview
75
+ * - `session_start` / `session_tree` — create or restore the session for the
76
+ * cwd from the active branch (overview and instruction dedup state)
77
+ * - `tool_result` — records full `read` results for instruction dedup
78
+ * - `session_compact` — resets instruction dedup state
77
79
  * - `session_shutdown` — releases all sessions and clears per-session stores
78
80
  */
79
81
  export function createCodeIntelligenceApp(pi: ExtensionAPI): CodeIntelligenceApp {
@@ -91,8 +93,12 @@ export function createCodeIntelligenceApp(pi: ExtensionAPI): CodeIntelligenceApp
91
93
  restoreBranchOverviewState(session, ctx.sessionManager.getBranch());
92
94
  });
93
95
 
96
+ pi.on("tool_result", (event, ctx) => {
97
+ sessions.get(ctx.cwd)?.recordToolResult(event);
98
+ });
99
+
94
100
  pi.on("session_compact", (_event, ctx) => {
95
- sessions.get(ctx.cwd)?.resetSurfacedInstructionDirs();
101
+ sessions.get(ctx.cwd)?.resetInstructionDedup();
96
102
  });
97
103
 
98
104
  pi.on("session_shutdown", () => {
package/src/extension.ts CHANGED
@@ -47,7 +47,7 @@ export default function codeIntelligenceExtension(
47
47
  );
48
48
  registerWorkspaceRecoveryHandler(pi, lspState);
49
49
 
50
- registerCodeIntelligenceTools(pi, (cwd) => {
50
+ const resolveSession = (cwd: string) => {
51
51
  const session = getOrCreateSession?.(cwd) ?? app.getSession(cwd) ?? app.createSession(cwd);
52
52
  const lease = lspState.providerLease;
53
53
  if (lease?.cwd === cwd) {
@@ -56,17 +56,23 @@ export default function codeIntelligenceExtension(
56
56
  }
57
57
  session.setHomeDir(homeDir);
58
58
  return session;
59
- });
59
+ };
60
+ registerCodeIntelligenceTools(pi, resolveSession);
60
61
 
61
- registerCiStatusCommand(pi, homeDir, {
62
- get: (cwd) =>
63
- lspState.providerLease?.cwd === cwd
64
- ? {
65
- lspController: lspState.controller,
66
- automaticPathPolicy: lspState.providerLease.automaticPathPolicy,
67
- }
68
- : { lspController: null, automaticPathPolicy: null },
69
- });
62
+ registerCiStatusCommand(
63
+ pi,
64
+ homeDir,
65
+ {
66
+ get: (cwd) =>
67
+ lspState.providerLease?.cwd === cwd
68
+ ? {
69
+ lspController: lspState.controller,
70
+ automaticPathPolicy: lspState.providerLease.automaticPathPolicy,
71
+ }
72
+ : { lspController: null, automaticPathPolicy: null },
73
+ },
74
+ (ctx) => resolveSession(ctx.cwd),
75
+ );
70
76
  const lspFooter = registerLspFooterContribution(pi, lspState);
71
77
 
72
78
  pi.on("session_shutdown", () => {
@@ -10,7 +10,6 @@ import {
10
10
  readNextAround,
11
11
  readNextEnclosingScope,
12
12
  readNextTarget,
13
- readNextTopSites,
14
13
  } from "../../analysis/read-next.ts";
15
14
  import { collectCallees } from "../../analysis/relations/callees.ts";
16
15
  import { collectImplementations } from "../../analysis/relations/implementations.ts";
@@ -89,6 +88,7 @@ async function collectReferences(options: CollectRelationOptions): Promise<Graph
89
88
  externalCount: result.externalCount,
90
89
  invalidLocationCount: result.invalidLocationCount,
91
90
  partialReason: result.partialReason,
91
+ partialMessage: result.partialMessage,
92
92
  confidence: "semantic",
93
93
  },
94
94
  readNext: [
@@ -97,14 +97,6 @@ async function collectReferences(options: CollectRelationOptions): Promise<Graph
97
97
  targetLine,
98
98
  "inspect the resolved target before editing",
99
99
  ),
100
- ...readNextTopSites(
101
- references.slice(0, options.maxResults).map((reference) => ({
102
- file: toDisplayPath(options.cwd, reference.file),
103
- line: reference.line,
104
- })),
105
- 2,
106
- "reference",
107
- ),
108
100
  ],
109
101
  };
110
102
  }
@@ -115,7 +107,7 @@ async function collectCalleesRelation(options: CollectRelationOptions): Promise<
115
107
  kind: "unavailable",
116
108
  rel: "callees",
117
109
  message:
118
- "Callees require a name anchor. Resolve an identifier coordinate with code_resolve and retry.",
110
+ "Callees require a name anchor. To inspect callees, retry code_graph with target.anchor at the symbol's identifier.",
119
111
  };
120
112
  }
121
113
  if (!options.provider?.calleesAt) {
@@ -198,6 +190,7 @@ async function collectImplementationsRelation(
198
190
  externalCount: result.externalCount,
199
191
  invalidLocationCount: result.invalidLocationCount,
200
192
  partialReason: result.partialReason,
193
+ partialMessage: result.partialMessage,
201
194
  },
202
195
  readNext: result.implementations
203
196
  .slice(0, Math.min(options.maxResults, 2))
@@ -32,6 +32,7 @@ export type GraphSection =
32
32
  readonly externalCount: number;
33
33
  readonly invalidLocationCount: number;
34
34
  readonly partialReason: RelationLocationPartialReason | null;
35
+ readonly partialMessage: string | null;
35
36
  readonly confidence: "semantic";
36
37
  };
37
38
  readonly readNext: readonly ReadNextItem[];
@@ -59,6 +60,7 @@ export type GraphSection =
59
60
  readonly externalCount: number;
60
61
  readonly invalidLocationCount: number;
61
62
  readonly partialReason: RelationLocationPartialReason | null;
63
+ readonly partialMessage: string | null;
62
64
  };
63
65
  readonly readNext: readonly ReadNextItem[];
64
66
  }
@@ -75,9 +77,11 @@ export interface CompletedGraphWorkflow {
75
77
  readonly resolvedDisplayFile: string;
76
78
  readonly maxResults: number;
77
79
  readonly sections: readonly GraphSection[];
80
+ /** Target-resolution notes, such as anchor snaps or policy exclusions beside a unique match. */
81
+ readonly notes: readonly string[];
78
82
  }
79
83
 
80
84
  /** Graph workflow outcome, preserving target disambiguation and failure states. */
81
85
  export type GraphWorkflowOutcome =
82
86
  | CompletedGraphWorkflow
83
- | Exclude<TargetWorkflowOutcome, { kind: "resolved" } | { kind: "target-group" }>;
87
+ | Exclude<TargetWorkflowOutcome, { kind: "resolved" } | { kind: "file-outline" }>;
@@ -57,10 +57,11 @@ export async function runGraphWorkflow(
57
57
  control,
58
58
  );
59
59
  throwIfAborted(control);
60
- if (targetOutcome.kind === "target-group") {
60
+ if (targetOutcome.kind === "file-outline") {
61
61
  return {
62
62
  kind: "invalid-input",
63
- message: "Graph analysis requires one member handle from a Target group.",
63
+ message:
64
+ "Graph analysis requires one declaration, not a whole file. Pass one handle from the file outline as target.handle.",
64
65
  };
65
66
  }
66
67
  if (targetOutcome.kind !== "resolved") return targetOutcome;
@@ -116,6 +117,7 @@ export async function runGraphWorkflow(
116
117
  resolvedDisplayFile: toDisplayPath(deps.cwd, entry.file),
117
118
  maxResults,
118
119
  sections: Object.freeze(sections),
120
+ notes: Object.freeze([...targetOutcome.notes]),
119
121
  });
120
122
  }
121
123
 
@@ -154,6 +156,6 @@ async function getSemanticReadinessError(options: {
154
156
  /** Narrow helper retained for session method typing. */
155
157
  export function isTargetFailure(
156
158
  outcome: TargetWorkflowOutcome,
157
- ): outcome is Exclude<TargetWorkflowOutcome, { kind: "resolved" } | { kind: "target-group" }> {
158
- return outcome.kind !== "resolved" && outcome.kind !== "target-group";
159
+ ): outcome is Exclude<TargetWorkflowOutcome, { kind: "resolved" } | { kind: "file-outline" }> {
160
+ return outcome.kind !== "resolved" && outcome.kind !== "file-outline";
159
161
  }
@@ -76,7 +76,10 @@ async function collectNode(
76
76
  kind: "partial",
77
77
  data,
78
78
  reason: result.reason,
79
- recovery: { file: result.file, errorRanges: result.errorRanges },
79
+ recovery: {
80
+ file: relativeDisplayPath(input.cwd, result.file),
81
+ errorRanges: result.errorRanges,
82
+ },
80
83
  }
81
84
  : { kind: "completed", data };
82
85
  } catch (error) {
@@ -103,7 +106,10 @@ async function collectEnclosingSymbol(
103
106
  kind: "partial",
104
107
  data: symbol,
105
108
  reason: result.reason,
106
- recovery: { file: result.file, errorRanges: result.errorRanges },
109
+ recovery: {
110
+ file: relativeDisplayPath(input.cwd, result.file),
111
+ errorRanges: result.errorRanges,
112
+ },
107
113
  }
108
114
  : { kind: "completed", data: symbol };
109
115
  } catch (error) {
@@ -1,8 +1,7 @@
1
1
  /** Filesystem and UTF-16 validation for exact point inspection. */
2
2
 
3
3
  import { existsSync, readFileSync, statSync } from "node:fs";
4
- import { relative } from "node:path";
5
- import { normalizePath } from "../../analysis/search/paths.ts";
4
+ import { normalizePath, toDisplayPath } from "../../analysis/search/paths.ts";
6
5
  import type { InputValidation } from "../input/common.ts";
7
6
  import type { SourcePointInput } from "../target-input.ts";
8
7
 
@@ -60,7 +59,7 @@ export function validateInspectPoint(
60
59
  kind: "valid",
61
60
  value: {
62
61
  file,
63
- relPath: relative(cwd, file) || point.file,
62
+ relPath: toDisplayPath(cwd, file),
64
63
  line: point.line,
65
64
  character: point.character,
66
65
  lineCount: lines.length,
@@ -112,7 +112,7 @@ function buildInspectNextQueries(
112
112
  character: definition.character,
113
113
  });
114
114
  queries.push(
115
- `Use code_resolve with target.anchor ${anchor}, then code_graph with the returned handle`,
115
+ `To explore this definition's relationships, call code_graph with target.anchor ${anchor}`,
116
116
  );
117
117
  } else if (!semanticReady) {
118
118
  queries.push(