@mrclrchtr/supi-code-intelligence 11.1.0 → 11.3.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 (199) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +41 -6
  3. package/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  4. package/node_modules/@mrclrchtr/supi-code-runtime/src/capability/types.ts +3 -1
  5. package/node_modules/@mrclrchtr/supi-code-runtime/src/query-result.ts +9 -0
  6. package/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  7. package/node_modules/@mrclrchtr/supi-core/src/child-web-tools.ts +110 -0
  8. package/node_modules/@mrclrchtr/supi-core/src/session.ts +11 -0
  9. package/node_modules/@mrclrchtr/supi-lsp/README.md +81 -7
  10. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  11. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/capability/types.ts +3 -1
  12. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/src/query-result.ts +9 -0
  13. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  14. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/src/child-web-tools.ts +110 -0
  15. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/src/session.ts +11 -0
  16. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/LICENSE +15 -0
  17. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/README.md +680 -0
  18. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/bin/semver.js +195 -0
  19. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/classes/comparator.js +143 -0
  20. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/classes/index.js +7 -0
  21. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/classes/range.js +577 -0
  22. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/classes/semver.js +350 -0
  23. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/clean.js +8 -0
  24. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/cmp.js +54 -0
  25. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/coerce.js +62 -0
  26. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/compare-build.js +9 -0
  27. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/compare-loose.js +5 -0
  28. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/compare.js +7 -0
  29. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/diff.js +60 -0
  30. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/eq.js +5 -0
  31. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/gt.js +5 -0
  32. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/gte.js +5 -0
  33. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/inc.js +21 -0
  34. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/lt.js +5 -0
  35. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/lte.js +5 -0
  36. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/major.js +5 -0
  37. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/minor.js +5 -0
  38. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/neq.js +5 -0
  39. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/parse.js +18 -0
  40. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/patch.js +5 -0
  41. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/prerelease.js +8 -0
  42. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/rcompare.js +5 -0
  43. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/rsort.js +5 -0
  44. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/satisfies.js +12 -0
  45. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/sort.js +5 -0
  46. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/truncate.js +48 -0
  47. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/functions/valid.js +8 -0
  48. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/index.js +93 -0
  49. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/internal/constants.js +37 -0
  50. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/internal/debug.js +11 -0
  51. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/internal/identifiers.js +29 -0
  52. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/internal/lrucache.js +42 -0
  53. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/internal/parse-options.js +17 -0
  54. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/internal/re.js +223 -0
  55. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/package.json +78 -0
  56. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/preload.js +4 -0
  57. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/range.bnf +17 -0
  58. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/ranges/gtr.js +6 -0
  59. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/ranges/intersects.js +9 -0
  60. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/ranges/ltr.js +6 -0
  61. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/ranges/max-satisfying.js +27 -0
  62. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/ranges/min-satisfying.js +26 -0
  63. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/ranges/min-version.js +63 -0
  64. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/ranges/outside.js +82 -0
  65. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/ranges/simplify.js +49 -0
  66. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/ranges/subset.js +249 -0
  67. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/ranges/to-comparators.js +10 -0
  68. package/node_modules/@mrclrchtr/supi-lsp/node_modules/semver/ranges/valid.js +13 -0
  69. package/node_modules/@mrclrchtr/supi-lsp/package.json +5 -3
  70. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostic-collection.ts +11 -4
  71. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostics.ts +77 -6
  72. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-input-admission.ts +149 -0
  73. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-typescript-project.ts +40 -0
  74. package/node_modules/@mrclrchtr/supi-lsp/src/client/client.ts +174 -49
  75. package/node_modules/@mrclrchtr/supi-lsp/src/config/config.ts +53 -2
  76. package/node_modules/@mrclrchtr/supi-lsp/src/config/operation-support.ts +19 -4
  77. package/node_modules/@mrclrchtr/supi-lsp/src/config/server-config.ts +22 -0
  78. package/node_modules/@mrclrchtr/supi-lsp/src/config/typescript-launch.ts +276 -0
  79. package/node_modules/@mrclrchtr/supi-lsp/src/diagnostics/evidence.ts +2 -2
  80. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-project-info.ts +22 -10
  81. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-workspace-symbol.ts +157 -23
  82. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager.ts +306 -75
  83. package/node_modules/@mrclrchtr/supi-lsp/src/provider/refactor-planning.ts +4 -3
  84. package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-controller.ts +2 -2
  85. package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-registry.ts +19 -2
  86. package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-rename.ts +1 -0
  87. package/node_modules/@mrclrchtr/supi-lsp/src/session/scanner.ts +27 -15
  88. package/node_modules/@mrclrchtr/supi-lsp/src/session/workspace-lsp-runtime.ts +5 -1
  89. package/node_modules/@mrclrchtr/supi-tree-sitter/README.md +2 -2
  90. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  91. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/capability/types.ts +3 -1
  92. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/query-result.ts +9 -0
  93. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  94. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/child-web-tools.ts +110 -0
  95. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/session.ts +11 -0
  96. package/node_modules/@mrclrchtr/supi-tree-sitter/package.json +3 -3
  97. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/tsx/tree-sitter-tsx.wasm +0 -0
  98. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/tsx/tree-sitter-tsx.wasm.json +5 -1
  99. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/typescript/tree-sitter-typescript.wasm +0 -0
  100. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/typescript/tree-sitter-typescript.wasm.json +5 -1
  101. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/call-sites.ts +40 -25
  102. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/callees.ts +2 -0
  103. package/node_modules/@mrclrchtr/supi-tree-sitter/src/worker/call-context.ts +44 -0
  104. package/package.json +6 -5
  105. package/src/analysis/capability/capability-warnings.ts +18 -12
  106. package/src/analysis/health/check.ts +115 -0
  107. package/src/analysis/health/diagnostics.ts +3 -0
  108. package/src/analysis/health/file-scope.ts +2 -3
  109. package/src/analysis/health/semantic-state.ts +38 -0
  110. package/src/analysis/health/server-status.ts +14 -2
  111. package/src/analysis/health/signals.ts +2 -0
  112. package/src/analysis/health/status.ts +82 -0
  113. package/src/analysis/refactor/apply.ts +17 -8
  114. package/src/analysis/search/exclusions.ts +47 -0
  115. package/src/analysis/search/paths.ts +32 -9
  116. package/src/analysis/target/anchored-structural.ts +3 -8
  117. package/src/analysis/target/anchored.ts +4 -20
  118. package/src/analysis/target/identity.ts +1 -1
  119. package/src/analysis/target/latex-label-container.ts +6 -6
  120. package/src/analysis/target/latex-section-anchor.ts +6 -6
  121. package/src/analysis/target/resolution.ts +18 -0
  122. package/src/analysis/target/symbol.ts +39 -11
  123. package/src/analysis/target/types.ts +6 -1
  124. package/src/extension.ts +17 -11
  125. package/src/session/graph/collect.ts +1 -10
  126. package/src/session/graph-types.ts +2 -0
  127. package/src/session/graph-workflow.ts +1 -0
  128. package/src/session/health-types.ts +7 -0
  129. package/src/session/health-workflow.ts +8 -43
  130. package/src/session/inspect/collect.ts +8 -2
  131. package/src/session/inspect/file-point.ts +2 -3
  132. package/src/session/inspect-workflow.ts +1 -1
  133. package/src/session/orientation/collect.ts +184 -20
  134. package/src/session/orientation/context-facts.ts +27 -2
  135. package/src/session/orientation/context-sections.ts +49 -3
  136. package/src/session/orientation/facts.ts +132 -0
  137. package/src/session/orientation/gather.ts +98 -11
  138. package/src/session/orientation/workspace-context.ts +16 -6
  139. package/src/session/orientation-types.ts +8 -0
  140. package/src/session/orientation-workflow.ts +20 -6
  141. package/src/session/refactor-identity.ts +76 -0
  142. package/src/session/refactor-plans.ts +5 -2
  143. package/src/session/refactor-workflow.ts +15 -17
  144. package/src/session/target-store.ts +3 -18
  145. package/src/session/target-workflow.ts +33 -16
  146. package/src/substrate/lsp/recovery.ts +5 -5
  147. package/src/tool/code_find/guidance.ts +1 -1
  148. package/src/tool/code_find/render.ts +8 -4
  149. package/src/tool/code_find/result.ts +78 -6
  150. package/src/tool/code_find/spec.ts +4 -3
  151. package/src/tool/code_find/structured.ts +25 -9
  152. package/src/tool/code_graph/details.ts +1 -0
  153. package/src/tool/code_graph/display.ts +1 -1
  154. package/src/tool/code_graph/guidance.ts +1 -1
  155. package/src/tool/code_graph/markdown.ts +11 -6
  156. package/src/tool/code_graph/read-next.ts +38 -9
  157. package/src/tool/code_graph/reference-selection.ts +30 -0
  158. package/src/tool/code_graph/result.ts +25 -118
  159. package/src/tool/code_graph/section.ts +133 -0
  160. package/src/tool/code_graph/spec.ts +3 -3
  161. package/src/tool/code_graph/structured.ts +17 -6
  162. package/src/tool/code_health/display-paths.ts +92 -0
  163. package/src/tool/code_health/file-scope-markdown.ts +3 -2
  164. package/src/tool/code_health/markdown.ts +12 -2
  165. package/src/tool/code_health/result.ts +18 -3
  166. package/src/tool/code_health/spec.ts +5 -3
  167. package/src/tool/code_health/structured-schema.ts +250 -0
  168. package/src/tool/code_health/structured.ts +256 -0
  169. package/src/tool/code_inspect/result.ts +11 -5
  170. package/src/tool/code_inspect/spec.ts +7 -1
  171. package/src/tool/code_inspect/structured.ts +231 -0
  172. package/src/tool/code_orientation/execute.ts +1 -1
  173. package/src/tool/code_orientation/result.ts +31 -8
  174. package/src/tool/code_orientation/spec.ts +2 -0
  175. package/src/tool/code_orientation/structured-schema.ts +617 -0
  176. package/src/tool/code_orientation/structured-workspace.ts +194 -0
  177. package/src/tool/code_orientation/structured.ts +189 -0
  178. package/src/tool/code_orientation/workspace-format.ts +2 -5
  179. package/src/tool/code_orientation/workspace-observations.ts +81 -0
  180. package/src/tool/code_orientation/workspace-output.ts +5 -0
  181. package/src/tool/code_orientation/workspace-projects.ts +16 -31
  182. package/src/tool/code_orientation/workspace-sections.ts +46 -32
  183. package/src/tool/code_refactor_apply/execute.ts +1 -1
  184. package/src/tool/code_refactor_apply/result.ts +14 -6
  185. package/src/tool/code_refactor_apply/spec.ts +2 -0
  186. package/src/tool/code_refactor_apply/structured.ts +49 -0
  187. package/src/tool/code_refactor_plan/result.ts +18 -9
  188. package/src/tool/code_refactor_plan/spec.ts +2 -0
  189. package/src/tool/code_refactor_plan/structured.ts +127 -0
  190. package/src/tool/code_resolve/markdown.ts +6 -30
  191. package/src/tool/code_resolve/result.ts +24 -11
  192. package/src/tool/code_resolve/structured.ts +7 -9
  193. package/src/tool/result/refactor.ts +8 -5
  194. package/src/tool/result/structured.ts +8 -5
  195. package/src/tool/result/types.ts +18 -14
  196. package/src/tool/schemas.ts +12 -6
  197. package/src/ui/status-command.ts +147 -322
  198. package/src/ui/status-overlay.ts +584 -421
  199. package/src/ui/status-presentation.ts +108 -0
@@ -22,6 +22,7 @@ import type {
22
22
  TargetCandidateCompleteness,
23
23
  TargetOutcome,
24
24
  } from "../analysis/target/types.ts";
25
+ import type { AnchoredResolutionMetadata } from "../types/index.ts";
25
26
  import type { CapabilityAdapter } from "./capability-adapter.ts";
26
27
  import { parseTargetInput } from "./input/common.ts";
27
28
  import { resolveWorkspaceSemanticDemand } from "./semantic-demand.ts";
@@ -49,7 +50,13 @@ export interface TargetWorkflowPolicy {
49
50
 
50
51
  /** Typed Target workflow outcome. */
51
52
  export type TargetWorkflowOutcome =
52
- | { kind: "resolved"; entry: Readonly<TargetStoreEntry>; notes: readonly string[] }
53
+ | {
54
+ kind: "resolved";
55
+ entry: Readonly<TargetStoreEntry>;
56
+ /** Immutable observation of this anchored request, never stored with the target. */
57
+ readonly resolution?: AnchoredResolutionMetadata;
58
+ notes: readonly string[];
59
+ }
53
60
  | {
54
61
  kind: "target-group";
55
62
  file: string;
@@ -301,10 +308,12 @@ function toWorkflowOutcome(
301
308
  };
302
309
  }
303
310
  const registered = registerFromTargetData(outcome.target, deps);
311
+ const resolution = immutableResolution(outcome.target.resolution);
304
312
  return {
305
313
  kind: "resolved",
306
314
  entry: immutableEntry(registered.entry),
307
- notes: buildResolutionNotes(outcome.target),
315
+ ...(resolution ? { resolution } : {}),
316
+ notes: [...buildResolutionNotes(resolution), ...(outcome.notes ?? [])],
308
317
  };
309
318
  }
310
319
 
@@ -358,15 +367,18 @@ function registerTargetGroup(
358
367
  });
359
368
  }
360
369
 
361
- function buildResolutionNotes(target: ResolvedTargetData): readonly string[] {
370
+ function buildResolutionNotes(
371
+ resolution: AnchoredResolutionMetadata | undefined,
372
+ ): readonly string[] {
362
373
  const notes: string[] = [];
363
- if (target.resolution?.snapped) {
374
+ if (resolution?.snapped) {
375
+ const requested = `${resolution.requested.line}:${resolution.requested.character}`;
376
+ const resolved = `${resolution.resolved.line}:${resolution.resolved.character}`;
364
377
  notes.push(
365
- `Resolved from a declaration header and snapped to the identifier (${target.resolution.source}).`,
378
+ `Requested coordinate snapped from ${requested} to name anchor ${resolved} (evidence: ${resolution.source}).`,
366
379
  );
367
- }
368
- if (target.resolution?.source === "structural-identifier") {
369
- notes.push("Resolved from provider-backed structural identifier evidence.");
380
+ } else if (resolution && resolution.source !== "semantic") {
381
+ notes.push(`Resolved from ${resolution.source} evidence.`);
370
382
  }
371
383
  return Object.freeze(notes);
372
384
  }
@@ -394,7 +406,6 @@ function registerFromTargetData(
394
406
  provenance: target.provenance,
395
407
  anchorKind: target.anchorKind,
396
408
  container: target.container,
397
- resolution: target.resolution,
398
409
  fileFingerprint,
399
410
  });
400
411
  }
@@ -407,12 +418,18 @@ function immutableEntry(entry: TargetStoreEntry): Readonly<TargetStoreEntry> {
407
418
  declarationPosition: entry.declarationPosition
408
419
  ? Object.freeze({ ...entry.declarationPosition })
409
420
  : entry.declarationPosition,
410
- resolution: entry.resolution
411
- ? Object.freeze({
412
- ...entry.resolution,
413
- requested: Object.freeze({ ...entry.resolution.requested }),
414
- resolved: Object.freeze({ ...entry.resolution.resolved }),
415
- })
416
- : undefined,
417
421
  });
418
422
  }
423
+
424
+ /** Keep the current request observation independent of provider and target-store state. */
425
+ function immutableResolution(
426
+ resolution: AnchoredResolutionMetadata | undefined,
427
+ ): AnchoredResolutionMetadata | undefined {
428
+ return resolution
429
+ ? Object.freeze({
430
+ ...resolution,
431
+ requested: Object.freeze({ ...resolution.requested }),
432
+ resolved: Object.freeze({ ...resolution.resolved }),
433
+ })
434
+ : undefined;
435
+ }
@@ -62,16 +62,16 @@ function getFilePathFromToolResult(event: ToolResultEvent): string | null {
62
62
  return pathValue;
63
63
  }
64
64
 
65
- /** Extract changed file paths emitted by a successful code_refactor_apply result. */
65
+ /** Extract original document identities, never display paths, from a successful Apply. */
66
66
  function getRefactorApplyPaths(event: ToolResultEvent): string[] {
67
67
  const details = (event as { details?: unknown }).details as
68
- | { data?: { changedFiles?: unknown } }
68
+ | { data?: { recoveryFiles?: unknown } }
69
69
  | undefined;
70
- const changedFiles = details?.data?.changedFiles;
71
- if (!Array.isArray(changedFiles)) return [];
70
+ const recoveryFiles = details?.data?.recoveryFiles;
71
+ if (!Array.isArray(recoveryFiles)) return [];
72
72
  return [
73
73
  ...new Set(
74
- changedFiles.filter((file): file is string => typeof file === "string" && file.length > 0),
74
+ recoveryFiles.filter((file): file is string => typeof file === "string" && file.length > 0),
75
75
  ),
76
76
  ];
77
77
  }
@@ -1,5 +1,5 @@
1
1
  export const toolDescription =
2
- "Search workspace symbols in semantic mode, or declaration, import, export, and call names in AST mode. Use PI grep for literal or regular-expression file-content search. The selected mode does not switch to another search method.";
2
+ "Search workspace symbols in semantic mode, or declaration, import, export, and call names in AST mode. Use grep for literal or regular-expression file-content search. The selected mode does not switch to another search method.";
3
3
 
4
4
  export const promptSnippet = "search code structure or workspace symbols";
5
5
 
@@ -4,6 +4,10 @@ import {
4
4
  type EvidenceListMetadata,
5
5
  renderEvidenceListMetadataDisclosure,
6
6
  } from "../../analysis/evidence.ts";
7
+ import {
8
+ type AutomaticPathExclusionDisplay,
9
+ describeExcludedPath,
10
+ } from "../../analysis/search/exclusions.ts";
7
11
  import { renderStructuredEmptyState, renderStructuredMatches } from "./markdown.ts";
8
12
  import type { FindResultAssembly } from "./result.ts";
9
13
 
@@ -52,19 +56,19 @@ function renderSemantic(assembly: FindResultAssembly, evidence: EvidenceListMeta
52
56
  const disclosure = renderEvidenceListMetadataDisclosure(evidence);
53
57
  if (disclosure) lines.push(disclosure);
54
58
  const exclusionDisclosure = renderAutomaticPathExclusionDisclosure(
55
- outcome.data.partialMetadata?.automaticPathExclusion,
59
+ assembly.details.automaticPathExclusion,
56
60
  );
57
61
  if (exclusionDisclosure) lines.push(exclusionDisclosure);
58
62
  return lines.join("\n");
59
63
  }
60
64
 
61
65
  function renderAutomaticPathExclusionDisclosure(
62
- exclusion: { readonly excludedCount: number; readonly examples: readonly string[] } | undefined,
66
+ exclusion: AutomaticPathExclusionDisplay | undefined,
63
67
  ): string | null {
64
68
  if (!exclusion || exclusion.excludedCount <= 0) return null;
65
69
  const noun = `workspace-symbol result${exclusion.excludedCount === 1 ? "" : "s"}`;
66
70
  const examples = exclusion.examples.length
67
- ? ` Examples: ${exclusion.examples.map((file) => `\`${file}\``).join(", ")}.`
71
+ ? ` Excluded path examples: ${exclusion.examples.map(describeExcludedPath).join(", ")}.`
68
72
  : "";
69
73
  return `_Automatic path policy excluded ${exclusion.excludedCount} ${noun}.${examples}_`;
70
74
  }
@@ -82,7 +86,7 @@ function renderEmptySemantic(assembly: FindResultAssembly, evidence: EvidenceLis
82
86
  const disclosure = renderEvidenceListMetadataDisclosure(evidence);
83
87
  if (disclosure) lines.push("", disclosure);
84
88
  const exclusionDisclosure = renderAutomaticPathExclusionDisclosure(
85
- outcome.data.partialMetadata?.automaticPathExclusion,
89
+ assembly.details.automaticPathExclusion,
86
90
  );
87
91
  if (exclusionDisclosure) lines.push("", exclusionDisclosure);
88
92
  lines.push("", "Document-level semantic symbols can differ from the workspace index.");
@@ -4,6 +4,12 @@ import {
4
4
  createPartialEvidenceList,
5
5
  type EvidenceListMetadata,
6
6
  } from "../../analysis/evidence.ts";
7
+ import {
8
+ describeExcludedPath,
9
+ describePartialQuery,
10
+ displayAutomaticPathExclusion,
11
+ } from "../../analysis/search/exclusions.ts";
12
+ import { toDisplayPath } from "../../analysis/search/paths.ts";
7
13
  import type { FindMode, FindWorkflowOutcome } from "../../session/find-types.ts";
8
14
  import {
9
15
  assembledNextQueries,
@@ -24,8 +30,14 @@ export interface FindResultAssembly {
24
30
 
25
31
  /** Assemble one completed code-aware search outcome before presentation. */
26
32
  export function assembleFindWorkflowResult(
27
- outcome: Extract<FindWorkflowOutcome, { kind: "completed" }>,
33
+ input: Extract<FindWorkflowOutcome, { kind: "completed" }>,
34
+ cwd: string,
28
35
  ): FindResultAssembly {
36
+ const outcome = withDisplayPaths(input, cwd);
37
+ const exclusion =
38
+ outcome.data.kind === "semantic"
39
+ ? displayAutomaticPathExclusion(outcome.data.partialMetadata?.automaticPathExclusion, cwd)
40
+ : undefined;
29
41
  const evidence = createFindEvidence(outcome);
30
42
  const confidence: ConfidenceMode = outcome.data.kind === "semantic" ? "semantic" : "structural";
31
43
  const nextQueries = findNextQueries(outcome);
@@ -61,6 +73,19 @@ export function assembleFindWorkflowResult(
61
73
  }),
62
74
  ];
63
75
 
76
+ if (exclusion?.examples.length) {
77
+ displaySections.push(
78
+ createToolDisplaySection({
79
+ key: "find.excludedPaths",
80
+ title: "Excluded path examples",
81
+ items: exclusion.examples,
82
+ totalCount: exclusion.examples.length,
83
+ omittedCount: 0,
84
+ format: describeExcludedPath,
85
+ }),
86
+ );
87
+ }
88
+
64
89
  return {
65
90
  outcome,
66
91
  assembled,
@@ -79,9 +104,52 @@ export function assembleFindWorkflowResult(
79
104
  structuralFailures: [...outcome.data.result.failures],
80
105
  }
81
106
  : {}),
82
- ...(outcome.data.kind === "semantic" && outcome.data.partialMetadata?.automaticPathExclusion
83
- ? { automaticPathExclusion: outcome.data.partialMetadata.automaticPathExclusion }
84
- : {}),
107
+ ...(exclusion ? { automaticPathExclusion: exclusion } : {}),
108
+ },
109
+ };
110
+ }
111
+
112
+ /** Clone source-path projections for all output adapters without changing workflow facts. */
113
+ function withDisplayPaths(
114
+ outcome: Extract<FindWorkflowOutcome, { kind: "completed" }>,
115
+ cwd: string,
116
+ ): Extract<FindWorkflowOutcome, { kind: "completed" }> {
117
+ const display = (file: string) => toDisplayPath(cwd, file);
118
+ const { data } = outcome;
119
+ if (data.kind === "semantic") {
120
+ return {
121
+ ...outcome,
122
+ data: {
123
+ ...data,
124
+ symbols: data.symbols.map((symbol) => ({ ...symbol, file: display(symbol.file) })),
125
+ partialReason: data.partialReason
126
+ ? describePartialQuery(data.partialReason, data.partialMetadata, cwd)
127
+ : null,
128
+ },
129
+ };
130
+ }
131
+ const { result } = data;
132
+ return {
133
+ ...outcome,
134
+ data: {
135
+ ...data,
136
+ result: {
137
+ ...result,
138
+ matches: result.matches.map((match) => ({ ...match, file: display(match.file) })),
139
+ failures: result.failures.map((failure) => ({ ...failure, file: display(failure.file) })),
140
+ scan: {
141
+ ...result.scan,
142
+ roots: result.scan.roots.map(display),
143
+ exclusions: result.scan.exclusions.map((entry) => ({
144
+ ...entry,
145
+ examples: entry.examples.map(display),
146
+ })),
147
+ limitations: result.scan.limitations.map((entry) => ({
148
+ ...entry,
149
+ examples: entry.examples.map(display),
150
+ })),
151
+ },
152
+ },
85
153
  },
86
154
  };
87
155
  }
@@ -105,7 +173,11 @@ function createFindEvidence(outcome: Extract<FindWorkflowOutcome, { kind: "compl
105
173
  items: [...outcome.data.symbols],
106
174
  maxResults: outcome.maxResults,
107
175
  };
108
- const evidence = outcome.data.partialReason
176
+ // Exclusion-only results counted every in-policy row; the separate
177
+ // exclusion disclosure still reports the dropped paths.
178
+ const providerLimited =
179
+ outcome.data.partialReason !== null && outcome.data.partialMetadata?.exclusionOnly !== true;
180
+ const evidence = providerLimited
109
181
  ? createPartialEvidenceList({ ...params, partialReason: "provider-limited" })
110
182
  : createEvidenceList(params);
111
183
  return { total: outcome.data.symbols.length, metadata: evidence.metadata };
@@ -207,7 +279,7 @@ export function finishFindResult(
207
279
  };
208
280
  }
209
281
 
210
- const assembly = assembleFindWorkflowResult(outcome);
282
+ const assembly = assembleFindWorkflowResult(outcome, cwd);
211
283
  return {
212
284
  content: renderFindResult(assembly),
213
285
  structuredContent: structuredFindResult(assembly, cwd),
@@ -1,4 +1,3 @@
1
- import { StringEnum } from "@earendil-works/pi-ai";
2
1
  import { Type } from "typebox";
3
2
  import type { CodeIntelToolExecCtx } from "../../types/index.ts";
4
3
  import { FindQueryParam, FindScopeParam, MaxResultsParam } from "../schemas.ts";
@@ -20,12 +19,14 @@ export const codeFindSpec = {
20
19
  {
21
20
  query: FindQueryParam,
22
21
  scope: Type.Optional(FindScopeParam),
23
- mode: StringEnum(CODE_FIND_MODES, {
22
+ mode: Type.Enum(CODE_FIND_MODES, {
23
+ type: "string",
24
24
  description:
25
25
  "Required code-aware search mode. AST mode requires `kind`; semantic mode rejects `kind`.",
26
26
  }),
27
27
  kind: Type.Optional(
28
- StringEnum(CODE_FIND_AST_KINDS, {
28
+ Type.Enum(CODE_FIND_AST_KINDS, {
29
+ type: "string",
29
30
  description: 'AST structure kind; required only for mode:"ast".',
30
31
  }),
31
32
  ),
@@ -1,4 +1,3 @@
1
- import { StringEnum } from "@earendil-works/pi-ai";
2
1
  import { type Static, Type } from "typebox";
3
2
  import { toDisplayPath } from "../../analysis/search/paths.ts";
4
3
  import { ConfidenceSchema, EvidenceListSchema, RecoveryRangeSchema } from "../result/structured.ts";
@@ -13,8 +12,8 @@ const ScanPathSummary = Type.Object({
13
12
  /** Codemode search evidence, including scan-universe limits independently of match counts. */
14
13
  export const FindOutputSchema = Type.Object(
15
14
  {
16
- kind: StringEnum(["completed", "invalid-input"]),
17
- mode: Type.Optional(StringEnum(["semantic", "ast"])),
15
+ kind: Type.Enum(["completed", "invalid-input"], { type: "string" }),
16
+ mode: Type.Optional(Type.Enum(["semantic", "ast"], { type: "string" })),
18
17
  confidence: ConfidenceSchema,
19
18
  matches: Type.Array(
20
19
  Type.Object(
@@ -26,7 +25,7 @@ export const FindOutputSchema = Type.Object(
26
25
  character: Type.Integer(),
27
26
  endLine: Type.Optional(Type.Integer()),
28
27
  endCharacter: Type.Optional(Type.Integer()),
29
- anchorKind: Type.Optional(StringEnum(["name", "declaration"])),
28
+ anchorKind: Type.Optional(Type.Enum(["name", "declaration"], { type: "string" })),
30
29
  container: Type.Optional(Type.Union([Type.String(), Type.Null()])),
31
30
  },
32
31
  { additionalProperties: false },
@@ -35,9 +34,25 @@ export const FindOutputSchema = Type.Object(
35
34
  evidenceLists: Type.Array(EvidenceListSchema),
36
35
  nextQueries: Type.Array(Type.String()),
37
36
  message: Type.Optional(Type.String()),
38
- partialReason: Type.Optional(Type.Union([Type.String(), Type.Null()])),
37
+ partialReason: Type.Optional(
38
+ Type.Union([Type.String(), Type.Null()], {
39
+ description:
40
+ "Why semantic results may be incomplete; null when complete. Policy exclusions alone are reported in automaticPathExclusion, not here.",
41
+ }),
42
+ ),
39
43
  automaticPathExclusion: Type.Optional(
40
- Type.Object({ excludedCount: Type.Integer(), examples: Type.Array(Type.String()) }),
44
+ Type.Object({
45
+ excludedCount: Type.Integer(),
46
+ examples: Type.Array(
47
+ Type.Object({
48
+ observedPath: Type.String({
49
+ description:
50
+ "Original path observed by the exclusion policy, not a canonical navigation path.",
51
+ }),
52
+ canonicalPath: Type.String({ description: "Canonical source navigation path." }),
53
+ }),
54
+ ),
55
+ }),
41
56
  ),
42
57
  scan: Type.Optional(
43
58
  Type.Object({
@@ -93,7 +108,7 @@ export function structuredFindResult(
93
108
  nextQueries: assembly.details.nextQueries,
94
109
  };
95
110
  if (data.kind === "semantic") {
96
- const exclusion = data.partialMetadata?.automaticPathExclusion;
111
+ const exclusion = assembly.details.automaticPathExclusion;
97
112
  return {
98
113
  ...base,
99
114
  matches: data.symbols.slice(0, shown).map((symbol) => {
@@ -108,12 +123,13 @@ export function structuredFindResult(
108
123
  container: symbol.container ?? null,
109
124
  };
110
125
  }),
111
- partialReason: data.partialReason,
126
+ // Exclusion-only evidence is complete; automaticPathExclusion carries it.
127
+ partialReason: data.partialMetadata?.exclusionOnly === true ? null : data.partialReason,
112
128
  ...(exclusion
113
129
  ? {
114
130
  automaticPathExclusion: {
115
131
  excludedCount: exclusion.excludedCount,
116
- examples: [...exclusion.examples],
132
+ examples: exclusion.examples.map((example) => ({ ...example })),
117
133
  },
118
134
  }
119
135
  : {}),
@@ -14,6 +14,7 @@ export interface GraphFileGroup {
14
14
  export interface GraphSectionDetails {
15
15
  rel: GraphRelationKind;
16
16
  source: "semantic" | "structural";
17
+ /** Collection completeness; display caps are disclosed by the evidence-list counts. */
17
18
  status: "complete" | "partial" | "unavailable";
18
19
  message: string | null;
19
20
  externalCount: number;
@@ -4,7 +4,7 @@ import { createToolDisplaySection } from "../result/display.ts";
4
4
  import type { ToolDisplaySection } from "../result/types.ts";
5
5
  import type { GraphFileGroup } from "./details.ts";
6
6
  import { compactGraphLabel } from "./format.ts";
7
- import type { AssembledGraphSection } from "./result.ts";
7
+ import type { AssembledGraphSection } from "./section.ts";
8
8
 
9
9
  /** Bound sites before grouping them. Each file group partitions the display rows. */
10
10
  export function graphDisplaySection(
@@ -1,5 +1,5 @@
1
1
  export const toolDescription =
2
- "Find semantic references and implementations, or non-symbol-aware structural calls written inside a target's enclosing scope.";
2
+ "Find semantic references and implementations, or non-symbol-aware structural calls written inside a target's enclosing scope. To find relationships for a known symbol or source position, pass it directly as the target.";
3
3
 
4
4
  export const promptSnippet = "trace code relationships";
5
5
 
@@ -10,7 +10,8 @@ import {
10
10
  formatGraphRange,
11
11
  graphCodeSpan,
12
12
  } from "./format.ts";
13
- import type { AssembledGraphSection, GraphResultAssembly } from "./result.ts";
13
+ import type { GraphResultAssembly } from "./result.ts";
14
+ import type { AssembledGraphSection } from "./section.ts";
14
15
 
15
16
  /** Render one target and one summary per requested relation. */
16
17
  export function renderGraphResult(assembly: GraphResultAssembly): string {
@@ -18,6 +19,7 @@ export function renderGraphResult(assembly: GraphResultAssembly): string {
18
19
  `Target: ${graphCodeSpan(assembly.displayName)} — ${graphCodeSpan(assembly.resolvedDisplayFile)}`,
19
20
  "",
20
21
  ];
22
+ for (const note of assembly.notes) lines.push(`_Note: ${note}_`, "");
21
23
  for (const section of assembly.sections) lines.push(...renderSection(section, assembly), "");
22
24
  lines.push(...renderReadNextSection(assembledReadNext(assembly.assembled)));
23
25
  return lines.join("\n");
@@ -28,12 +30,15 @@ function renderSection(section: AssembledGraphSection, assembly: GraphResultAsse
28
30
  const depth = section.kind === "ok" && section.rel === "callees" ? `, ${section.data.depth}` : "";
29
31
  const lines = [`## ${section.rel} (${source}${depth})`];
30
32
  if (section.kind === "unavailable") return [...lines, `Unavailable — ${section.message}`];
33
+ const summary = formatGraphEvidence(
34
+ section.evidence.metadata,
35
+ section.rel === "callees" ? "call sites" : "locations",
36
+ section.rel === "callees" ? 0 : section.data.externalCount,
37
+ );
31
38
  lines.push(
32
- formatGraphEvidence(
33
- section.evidence.metadata,
34
- section.rel === "callees" ? "call sites" : "locations",
35
- section.rel === "callees" ? 0 : section.data.externalCount,
36
- ),
39
+ section.rel === "references" && section.selectionNote
40
+ ? `${summary} — ${section.selectionNote}`
41
+ : summary,
37
42
  "",
38
43
  );
39
44
  if (section.rel !== "callees") return [...lines, ...formatLocations(section, assembly.cwd)];
@@ -1,8 +1,12 @@
1
- import { type ReadNextItem, readNextRange } from "../../analysis/read-next.ts";
2
- import type { GraphSection } from "../../session/graph-types.ts";
1
+ import { type ReadNextItem, readNextRange, readNextTopSites } from "../../analysis/read-next.ts";
2
+ import { toDisplayPath } from "../../analysis/search/paths.ts";
3
+ import type { AssembledGraphSection } from "./section.ts";
3
4
 
4
5
  /** Prefer the known enclosing scope, then alternate relation sites before the display cap. */
5
- export function graphReadNext(sections: readonly GraphSection[]): ReadNextItem[] {
6
+ export function graphReadNext(
7
+ sections: readonly AssembledGraphSection[],
8
+ cwd: string,
9
+ ): ReadNextItem[] {
6
10
  const calls = sections.find((section) => section.kind === "ok" && section.rel === "callees");
7
11
  const scopeReads =
8
12
  calls?.kind === "ok"
@@ -10,12 +14,11 @@ export function graphReadNext(sections: readonly GraphSection[]): ReadNextItem[]
10
14
  : [];
11
15
  const queues = sections.flatMap((section) => {
12
16
  if (section.kind !== "ok" || section.rel === "callees") return [];
13
- // Reference collection puts the approximate target range first. The known scope replaces it.
14
- return [
15
- section.rel === "references" && scopeReads.length > 0
16
- ? section.readNext.slice(1)
17
- : section.readNext,
18
- ];
17
+ if (section.rel !== "references") return [section.readNext];
18
+ // Collection supplies the target range; reference sites come only from selected evidence.
19
+ const target = section.readNext[0];
20
+ const sites = referenceReadNext(section, cwd, scopeReads[0]?.file ?? target?.file);
21
+ return [scopeReads.length > 0 || !target ? sites : [target, ...sites]];
19
22
  });
20
23
  const candidates = [...scopeReads];
21
24
  const maxLength = Math.max(0, ...queues.map((queue) => queue.length));
@@ -30,6 +33,32 @@ export function graphReadNext(sections: readonly GraphSection[]): ReadNextItem[]
30
33
  .map((item) => readNextRange(item));
31
34
  }
32
35
 
36
+ /** Prefer new files, then the target file, before filling remaining slots with repeated files. */
37
+ function referenceReadNext(
38
+ section: Extract<AssembledGraphSection, { kind: "ok"; rel: "references" }>,
39
+ cwd: string,
40
+ targetFile: string | undefined,
41
+ ): ReadNextItem[] {
42
+ const sites = section.evidence.items.map((site) => ({
43
+ file: toDisplayPath(cwd, site.file),
44
+ line: site.line,
45
+ }));
46
+ const firstByFile = new Map<string, (typeof sites)[number]>();
47
+ for (const site of sites) {
48
+ if (!firstByFile.has(site.file)) firstByFile.set(site.file, site);
49
+ }
50
+ const distinct = [...firstByFile.values()];
51
+ return readNextTopSites(
52
+ [
53
+ ...distinct.filter((site) => site.file !== targetFile),
54
+ ...distinct.filter((site) => site.file === targetFile),
55
+ ...sites.filter((site) => firstByFile.get(site.file) !== site),
56
+ ],
57
+ 2,
58
+ "reference",
59
+ );
60
+ }
61
+
33
62
  /** Merge connected ranges before bounding them, including ranges that bridge two earlier reads. */
34
63
  function mergeRanges(items: readonly ReadNextItem[]): ReadNextItem[] {
35
64
  const result: ReadNextItem[] = [];
@@ -0,0 +1,30 @@
1
+ import type { ReferenceEntry } from "../../analysis/relations/types.ts";
2
+
3
+ /**
4
+ * Select one site per file per round from normalized, file/source-ordered references.
5
+ * Preserve that order for display; callers retain completeness from the full collected list.
6
+ */
7
+ export function selectReferenceLocations(
8
+ references: readonly ReferenceEntry[],
9
+ limit: number,
10
+ ): ReferenceEntry[] {
11
+ if (references.length <= limit) return [...references];
12
+ const byFile = new Map<string, number[]>();
13
+ for (const [index, reference] of references.entries()) {
14
+ const indices = byFile.get(reference.file) ?? [];
15
+ indices.push(index);
16
+ byFile.set(reference.file, indices);
17
+ }
18
+ const selected = new Set<number>();
19
+ let activeFiles = [...byFile.values()];
20
+ for (let round = 0; selected.size < limit && activeFiles.length > 0; round++) {
21
+ const remaining: number[][] = [];
22
+ for (const indices of activeFiles) {
23
+ if (selected.size === limit) break;
24
+ selected.add(indices[round]);
25
+ if (indices.length > round + 1) remaining.push(indices);
26
+ }
27
+ activeFiles = remaining;
28
+ }
29
+ return references.filter((_, index) => selected.has(index));
30
+ }