@mrclrchtr/supi-code-intelligence 11.2.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 (112) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +16 -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 +39 -2
  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/package.json +3 -3
  17. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostic-collection.ts +11 -4
  18. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-diagnostics.ts +77 -6
  19. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-input-admission.ts +149 -0
  20. package/node_modules/@mrclrchtr/supi-lsp/src/client/client-typescript-project.ts +40 -0
  21. package/node_modules/@mrclrchtr/supi-lsp/src/client/client.ts +151 -44
  22. package/node_modules/@mrclrchtr/supi-lsp/src/diagnostics/evidence.ts +2 -2
  23. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-workspace-symbol.ts +157 -23
  24. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager.ts +254 -56
  25. package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-registry.ts +19 -2
  26. package/node_modules/@mrclrchtr/supi-lsp/src/session/runtime-rename.ts +1 -0
  27. package/node_modules/@mrclrchtr/supi-lsp/src/session/workspace-lsp-runtime.ts +5 -1
  28. package/node_modules/@mrclrchtr/supi-tree-sitter/README.md +2 -2
  29. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  30. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/capability/types.ts +3 -1
  31. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/src/query-result.ts +9 -0
  32. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  33. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/child-web-tools.ts +110 -0
  34. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/src/session.ts +11 -0
  35. package/node_modules/@mrclrchtr/supi-tree-sitter/package.json +3 -3
  36. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/tsx/tree-sitter-tsx.wasm +0 -0
  37. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/tsx/tree-sitter-tsx.wasm.json +5 -1
  38. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/typescript/tree-sitter-typescript.wasm +0 -0
  39. package/node_modules/@mrclrchtr/supi-tree-sitter/resources/grammars/typescript/tree-sitter-typescript.wasm.json +5 -1
  40. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/call-sites.ts +40 -25
  41. package/node_modules/@mrclrchtr/supi-tree-sitter/src/tool/callees.ts +2 -0
  42. package/node_modules/@mrclrchtr/supi-tree-sitter/src/worker/call-context.ts +44 -0
  43. package/package.json +6 -5
  44. package/src/analysis/health/server-status.ts +6 -2
  45. package/src/analysis/search/exclusions.ts +47 -0
  46. package/src/analysis/search/paths.ts +32 -9
  47. package/src/analysis/target/anchored-structural.ts +3 -8
  48. package/src/analysis/target/anchored.ts +4 -20
  49. package/src/analysis/target/identity.ts +1 -1
  50. package/src/analysis/target/latex-label-container.ts +6 -6
  51. package/src/analysis/target/latex-section-anchor.ts +6 -6
  52. package/src/analysis/target/resolution.ts +18 -0
  53. package/src/analysis/target/symbol.ts +39 -11
  54. package/src/analysis/target/types.ts +6 -1
  55. package/src/extension.ts +17 -11
  56. package/src/session/graph/collect.ts +1 -10
  57. package/src/session/graph-types.ts +2 -0
  58. package/src/session/graph-workflow.ts +1 -0
  59. package/src/session/inspect/collect.ts +8 -2
  60. package/src/session/inspect/file-point.ts +2 -3
  61. package/src/session/inspect-workflow.ts +1 -1
  62. package/src/session/orientation/collect.ts +54 -16
  63. package/src/session/orientation/context-sections.ts +2 -3
  64. package/src/session/orientation/facts.ts +9 -1
  65. package/src/session/orientation-types.ts +3 -0
  66. package/src/session/orientation-workflow.ts +18 -5
  67. package/src/session/refactor-identity.ts +76 -0
  68. package/src/session/refactor-workflow.ts +11 -14
  69. package/src/session/target-store.ts +3 -18
  70. package/src/session/target-workflow.ts +33 -16
  71. package/src/substrate/lsp/recovery.ts +5 -5
  72. package/src/tool/code_find/render.ts +8 -4
  73. package/src/tool/code_find/result.ts +78 -6
  74. package/src/tool/code_find/spec.ts +4 -3
  75. package/src/tool/code_find/structured.ts +25 -9
  76. package/src/tool/code_graph/details.ts +1 -0
  77. package/src/tool/code_graph/display.ts +1 -1
  78. package/src/tool/code_graph/guidance.ts +1 -1
  79. package/src/tool/code_graph/markdown.ts +11 -6
  80. package/src/tool/code_graph/read-next.ts +38 -9
  81. package/src/tool/code_graph/reference-selection.ts +30 -0
  82. package/src/tool/code_graph/result.ts +25 -118
  83. package/src/tool/code_graph/section.ts +133 -0
  84. package/src/tool/code_graph/spec.ts +3 -3
  85. package/src/tool/code_graph/structured.ts +17 -6
  86. package/src/tool/code_health/display-paths.ts +92 -0
  87. package/src/tool/code_health/file-scope-markdown.ts +3 -2
  88. package/src/tool/code_health/result.ts +4 -2
  89. package/src/tool/code_health/spec.ts +3 -3
  90. package/src/tool/code_health/structured-schema.ts +44 -44
  91. package/src/tool/code_inspect/spec.ts +5 -1
  92. package/src/tool/code_inspect/structured.ts +1 -2
  93. package/src/tool/code_orientation/execute.ts +1 -1
  94. package/src/tool/code_orientation/result.ts +22 -5
  95. package/src/tool/code_orientation/structured-schema.ts +46 -36
  96. package/src/tool/code_orientation/structured-workspace.ts +2 -1
  97. package/src/tool/code_orientation/structured.ts +6 -12
  98. package/src/tool/code_orientation/workspace-format.ts +2 -5
  99. package/src/tool/code_orientation/workspace-sections.ts +3 -2
  100. package/src/tool/code_refactor_apply/result.ts +1 -1
  101. package/src/tool/code_refactor_plan/result.ts +2 -1
  102. package/src/tool/code_refactor_plan/structured.ts +2 -3
  103. package/src/tool/code_resolve/markdown.ts +6 -30
  104. package/src/tool/code_resolve/result.ts +24 -11
  105. package/src/tool/code_resolve/structured.ts +7 -9
  106. package/src/tool/result/refactor.ts +8 -5
  107. package/src/tool/result/structured.ts +8 -5
  108. package/src/tool/result/types.ts +18 -14
  109. package/src/tool/schemas.ts +5 -5
  110. package/src/ui/status-command.ts +37 -1
  111. package/src/ui/status-overlay.ts +70 -51
  112. package/src/ui/status-presentation.ts +108 -0
@@ -0,0 +1,76 @@
1
+ /** Fingerprint-bound edit evidence for refactor planning. */
2
+
3
+ import { createHash } from "node:crypto";
4
+ import { readFileSync } from "node:fs";
5
+ import type { FileEdit, WorkspaceEdit } from "@mrclrchtr/supi-code-runtime/api";
6
+ import { createLogicalLineIndex, type LogicalLineIndex } from "../analysis/refactor/position.ts";
7
+ import { computeFileFingerprint } from "./refactor-plans.ts";
8
+
9
+ type FileFingerprint = { file: string; fingerprint: string };
10
+
11
+ /** Fingerprint each edited file, reusing an earlier source snapshot when provided. */
12
+ export function collectFileFingerprints(
13
+ edits: readonly { file: string }[],
14
+ sourceSnapshot?: FileFingerprint,
15
+ ): FileFingerprint[] {
16
+ const files = [...new Set(edits.map((edit) => edit.file))];
17
+ return files.map((file) => ({
18
+ file,
19
+ fingerprint:
20
+ sourceSnapshot?.file === file ? sourceSnapshot.fingerprint : computeFileFingerprint(file),
21
+ }));
22
+ }
23
+
24
+ /**
25
+ * Drop edits whose replacement exactly equals the text they replace.
26
+ *
27
+ * Text is read only from content whose hash still equals the plan's verified
28
+ * fingerprint, so the comparison uses the snapshot that the plan was validated
29
+ * against. Files left without edits lose their fingerprints and preconditions.
30
+ * Edits whose ranges do not fit the content are kept for normal validation.
31
+ */
32
+ export function dropIdentityEdits(
33
+ edits: WorkspaceEdit,
34
+ fileFingerprints: readonly FileFingerprint[],
35
+ ):
36
+ | { kind: "ok"; edits: WorkspaceEdit; fileFingerprints: FileFingerprint[] }
37
+ | { kind: "unavailable"; reason: string } {
38
+ const contents = new Map<string, { content: string; index: LogicalLineIndex }>();
39
+ for (const { file, fingerprint } of fileFingerprints) {
40
+ let content: string;
41
+ try {
42
+ content = readFileSync(file, "utf-8");
43
+ } catch {
44
+ return { kind: "unavailable", reason: `File ${file} could not be read during planning.` };
45
+ }
46
+ if (createHash("sha256").update(content).digest("hex") !== fingerprint) {
47
+ return {
48
+ kind: "unavailable",
49
+ reason: `File ${file} changed during planning. Request a new plan.`,
50
+ };
51
+ }
52
+ contents.set(file, { content, index: createLogicalLineIndex(content) });
53
+ }
54
+
55
+ const kept = edits.edits.filter((edit) => !isIdentityEdit(edit, contents.get(edit.file)));
56
+ const files = new Set(kept.map((edit) => edit.file));
57
+ const preconditions = edits.documentPreconditions?.filter((item) => files.has(item.file));
58
+ return {
59
+ kind: "ok",
60
+ edits: preconditions ? { edits: kept, documentPreconditions: preconditions } : { edits: kept },
61
+ fileFingerprints: fileFingerprints.filter(({ file }) => files.has(file)),
62
+ };
63
+ }
64
+
65
+ function isIdentityEdit(
66
+ edit: FileEdit,
67
+ source: { content: string; index: LogicalLineIndex } | undefined,
68
+ ): boolean {
69
+ if (!source) return false;
70
+ try {
71
+ const start = source.index.offsetAt(edit.range.start);
72
+ return source.content.slice(start, source.index.offsetAt(edit.range.end)) === edit.newText;
73
+ } catch {
74
+ return false;
75
+ }
76
+ }
@@ -24,6 +24,7 @@ import {
24
24
  parseRefactorApplyWorkflowInput,
25
25
  parseRefactorPlanWorkflowInput,
26
26
  } from "./input/health-refactor.ts";
27
+ import { collectFileFingerprints, dropIdentityEdits } from "./refactor-identity.ts";
27
28
  import {
28
29
  computeFileFingerprint,
29
30
  generatePlanId,
@@ -202,6 +203,14 @@ async function planResolvedRefactor(
202
203
  deps.cwd,
203
204
  );
204
205
  if (snapshotError) return { kind: "unavailable", reason: snapshotError };
206
+ const changed = dropIdentityEdits(result.edits, fileFingerprints);
207
+ if (changed.kind === "unavailable") return changed;
208
+ if (changed.edits.edits.length === 0) {
209
+ return {
210
+ kind: "invalid-input",
211
+ message: `The ${parsed.operation} refactor produces no changes; every planned edit matches the current text.`,
212
+ };
213
+ }
205
214
 
206
215
  const plan: RefactorPlan = {
207
216
  id: generatePlanId(
@@ -216,10 +225,10 @@ async function planResolvedRefactor(
216
225
  targetFile: file,
217
226
  targetLine: target.displayLine,
218
227
  targetCharacter: target.displayCharacter,
219
- edits: result.edits,
228
+ edits: changed.edits,
220
229
  evidenceSource: sectionRename.evidenceSource,
221
230
  authorizedMutationRoots: authority.canonicalRoots,
222
- fileFingerprints,
231
+ fileFingerprints: changed.fileFingerprints,
223
232
  createdAt: Date.now(),
224
233
  };
225
234
  deps.storePlan(plan);
@@ -366,18 +375,6 @@ async function planWithProvider(
366
375
  };
367
376
  }
368
377
 
369
- function collectFileFingerprints(
370
- edits: Array<{ file: string }>,
371
- sourceSnapshot?: { readonly file: string; readonly fingerprint: string },
372
- ): Array<{ file: string; fingerprint: string }> {
373
- const files = [...new Set(edits.map((edit) => edit.file))];
374
- return files.map((file) => ({
375
- file,
376
- fingerprint:
377
- sourceSnapshot?.file === file ? sourceSnapshot.fingerprint : computeFileFingerprint(file),
378
- }));
379
- }
380
-
381
378
  function immutablePlan(plan: RefactorPlan): Readonly<RefactorPlan> {
382
379
  return Object.freeze({
383
380
  ...plan,
@@ -31,9 +31,9 @@ export type TargetProviderProvenance = "semantic" | "structural";
31
31
  /**
32
32
  * A stored resolved target entry with handles and metadata.
33
33
  *
34
- * This is the canonical post-registration target type — all tool layers
35
- * (executors, renderers, details) use it directly. Computed fields like
36
- * relative paths are derived at the rendering boundary.
34
+ * Contains stable target facts only; request-local resolution metadata belongs
35
+ * to the Target workflow outcome. Computed fields like relative paths are
36
+ * derived at the rendering boundary.
37
37
  */
38
38
  export interface TargetStoreEntry {
39
39
  targetId: string;
@@ -60,12 +60,6 @@ export interface TargetStoreEntry {
60
60
  fileFingerprint: string;
61
61
  /** Named symbolic container, or null when no container name was reported. */
62
62
  container: string | null;
63
- /**
64
- * Resolution provenance — present when the target was resolved from
65
- * anchored coordinates. Carries requested/resolved coordinates, whether
66
- * the anchor was snapped, and the provider-backed evidence source.
67
- */
68
- resolution?: import("../types/index.ts").AnchoredResolutionMetadata;
69
63
  }
70
64
 
71
65
  /** Input shape for registering a resolved target. */
@@ -95,12 +89,6 @@ export interface TargetRegistrationInput {
95
89
  anchorKind: AnchorKind;
96
90
  /** Named symbolic container used to disambiguate same-file identity collisions, or null when unreported (ADR 0003). */
97
91
  container: string | null;
98
- /**
99
- * Resolution provenance — present when the target was resolved from
100
- * anchored coordinates. Carries requested/resolved coordinates, whether
101
- * the anchor was snapped, and the provider-backed evidence source.
102
- */
103
- resolution?: import("../types/index.ts").AnchoredResolutionMetadata;
104
92
  /** Reuse one verified fingerprint across a bounded registration batch. */
105
93
  fileFingerprint?: string;
106
94
  }
@@ -261,7 +249,6 @@ export function registerWorkflowTarget(
261
249
  anchorKind: input.anchorKind,
262
250
  fileFingerprint: fingerprint,
263
251
  container: input.container,
264
- resolution: input.resolution,
265
252
  };
266
253
 
267
254
  const existing = store.get(targetId);
@@ -293,7 +280,6 @@ function mergeTargetRefinement(
293
280
  displayCharacter: anchorSource.displayCharacter,
294
281
  kind: displayKind,
295
282
  anchorKind: anchorSource.anchorKind,
296
- resolution: anchorSource.resolution,
297
283
  confidence: strongestEvidenceSource.confidence,
298
284
  provenance: mergeProvenance(existing.provenance, incoming.provenance),
299
285
  };
@@ -305,7 +291,6 @@ function selectAnchorSource(
305
291
  ): TargetStoreEntry {
306
292
  if (existing.anchorKind === "declaration" && incoming.anchorKind === "name") return incoming;
307
293
  if (existing.anchorKind === "name" && incoming.anchorKind === "declaration") return existing;
308
- if (!existing.resolution && incoming.resolution) return incoming;
309
294
  return existing;
310
295
  }
311
296
 
@@ -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
  }
@@ -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)];