@mrclrchtr/supi-code-intelligence 9.1.0 → 9.1.2

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 (36) hide show
  1. package/README.md +4 -2
  2. package/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  3. package/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  4. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  5. package/node_modules/@mrclrchtr/supi-lsp/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  6. package/node_modules/@mrclrchtr/supi-lsp/package.json +3 -3
  7. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-workspace-symbol.ts +29 -0
  8. package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager.ts +25 -22
  9. package/node_modules/@mrclrchtr/supi-tree-sitter/README.md +3 -1
  10. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  11. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  12. package/node_modules/@mrclrchtr/supi-tree-sitter/package.json +3 -3
  13. package/node_modules/@mrclrchtr/supi-tree-sitter/src/session/structural-worker-json.ts +23 -0
  14. package/node_modules/@mrclrchtr/supi-tree-sitter/src/session/structural-worker-node.ts +29 -0
  15. package/node_modules/@mrclrchtr/supi-tree-sitter/src/session/structural-worker-process.ts +21 -5
  16. package/node_modules/@mrclrchtr/supi-tree-sitter/src/worker/process-host.mjs +20 -3
  17. package/package.json +5 -5
  18. package/src/analysis/evidence.ts +2 -0
  19. package/src/analysis/target/symbol.ts +19 -8
  20. package/src/analysis/target/types.ts +2 -0
  21. package/src/session/orientation-workflow.ts +2 -0
  22. package/src/session/target-workflow.ts +2 -0
  23. package/src/tool/code_find/execute.ts +1 -1
  24. package/src/tool/code_find/result.ts +10 -3
  25. package/src/tool/code_graph/result.ts +7 -2
  26. package/src/tool/code_orientation/result.ts +6 -3
  27. package/src/tool/code_resolve/execute.ts +1 -1
  28. package/src/tool/code_resolve/markdown.ts +4 -1
  29. package/src/tool/code_resolve/result.ts +14 -2
  30. package/src/tool/result/candidate-row.ts +22 -0
  31. package/src/tool/result/display.ts +6 -0
  32. package/src/tool/result/errors.ts +12 -0
  33. package/src/tool/result/types.ts +2 -0
  34. package/src/ui/tui/candidate-disclosure.ts +43 -0
  35. package/src/ui/tui/candidate-selection.ts +24 -5
  36. package/src/ui/tui/common.ts +3 -0
package/README.md CHANGED
@@ -26,6 +26,8 @@ For local development, run `pi install ./packages/supi-code-intelligence` from t
26
26
 
27
27
  This package is included in the SuPi release installer. SuPi remains pre-release. The package bundles its LSP and Tree-sitter runtime dependencies, but not language-server binaries.
28
28
 
29
+ Under Bun, including compiled applications such as Pi-Bolt, structural analysis also requires a Node.js executable named `node` on `PATH`. The parser runs in a protected Node child process, not in Bun. If Node.js is unavailable, structural analysis reports an installation error; LSP startup remains separate.
30
+
29
31
  ## What it adds
30
32
 
31
33
  - **Language Server Protocol (LSP) tools** for types, definitions, references, implementations, diagnostics, workspace symbols, and semantic refactoring.
@@ -74,7 +76,7 @@ code_health({ scope: "packages/api/src/index.ts", refresh: true })
74
76
 
75
77
  Important tool rules:
76
78
 
77
- - **Resolve:** new target handles require semantic readiness. A comment or whitespace point is not a symbol; use `code_inspect` there. Handles are session-local and become stale when file contents change. Resolve the symbol again rather than reuse a stale handle.
79
+ - **Resolve:** new target handles require semantic readiness. A comment or whitespace point is not a symbol; use `code_inspect` there. Handles are session-local and become stale when file contents change. Resolve the symbol again rather than reuse a stale handle. Symbol queries put case-sensitive exact-name matches first, before the display cap. Provider order stays unchanged within exact-name and other matches. An incomplete provider result never selects a target automatically.
78
80
  - **Graph:** relations are `references` (default), `callees`, and `implements`. Use `["all"]` for all three. Callee depth is `direct` by default; `deep` includes nested scopes, not transitive calls. Callees match source shape, not symbol identity. Counts include each distinct call site; repeated expressions share one agent-output row with all shown line/column coordinates. Each relation reports its counts and limits once. Provider-limited results have unknown totals; invalid locations are disclosed separately. Callee previews shorten receiver argument lists from syntax without changing grouping by the full expression. Matching previews get local expression numbers so distinct source expressions remain clear. Unavailable references retain the provider reason, including an exhausted enrollment retry. Unavailable callees retain the provider reason and a source-inspection next step. Ambiguous targets ask for candidate selection, not input correction. Candidate limits retain exact totals, or unknown totals when the provider returns partial data. Agent output and both transcript views disclose omissions. Only shown candidates receive target handles. The human transcript shows the resolved target and per-relation evidence types and status. The expanded view groups up to 20 sites per relation by file, without a duplicate Markdown body. If this display limit hides returned sites, the transcript links to a temporary file with all returned evidence. This file does not include evidence beyond `maxResults`, and its path does not add text to an otherwise complete agent result. Merged read ranges use neutral guidance.
79
81
  - **Find:** AST mode requires `kind`: `definition`, `import`, `export`, `call`, `type`, `interface`, `class`, `method`, or `enum`. Semantic mode does not accept `kind`. A supplied `scope` is a non-empty array.
80
82
  - **Health:** `include` accepts `diagnostics` and `servers` (both by default); `level` is `summary` (default) or `detailed`. Server inventory and route counts remain workspace-wide, even with a diagnostic scope. A diagnostic snapshot does not prove that the whole workspace is clean. Tsconfig and jsconfig coverage applies only to TypeScript and JavaScript-family files; other-language files have no `Tsconfig` label.
@@ -85,7 +87,7 @@ Important tool rules:
85
87
 
86
88
  All Code Intelligence tools show PI execution failures with the tool name and the available reason. Structured failure text takes priority; a failure without details uses PI's plain error text. The transcript removes terminal controls and keeps up to 4096 characters. Collapsed output keeps two wrapped rows; expanded output keeps 20. A notice discloses further display limits. These limits do not change agent output or saved results.
87
89
 
88
- Candidate selection for Graph, Resolve, and Orientation uses one structured transcript view. The collapsed view shows `Choose a target` and one count summary. The expanded view shows one candidate section and selection guidance; it does not repeat raw Markdown when candidate rows are available. Older results use structured evidence when available. When candidate rows are unavailable, or structured reason or guidance is missing, the renderer uses a bounded raw detail view with up to 4096 source characters and 40 wrapped body rows. It shows a truncation notice and keeps any existing full-output link.
90
+ Candidate selection for Graph, Resolve, and Orientation uses one structured transcript view. The collapsed view shows `Choose a target` and one count summary. Incomplete symbol-query results retain the provider reason and distinguish collected candidates from display omissions in agent output and both transcript views. The transcript removes terminal controls from this disclosure and limits it to 4096 source characters and 3 collapsed or 10 expanded body rows, plus a notice when text is hidden. These display limits do not change agent output or saved details. The expanded view shows one candidate section and selection guidance; it does not repeat raw Markdown when candidate rows are available. Older results use structured evidence when available. When candidate rows are unavailable, or structured reason or guidance is missing, the renderer uses a bounded raw detail view with up to 4096 source characters and 40 wrapped body rows. It shows a truncation notice and keeps any existing full-output link.
89
91
 
90
92
  ### Refactor checks
91
93
 
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-code-runtime",
3
- "version": "9.1.0",
3
+ "version": "9.1.2",
4
4
  "description": "Shared workspace context and capability contracts for code intelligence",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-core",
3
- "version": "9.1.0",
3
+ "version": "9.1.2",
4
4
  "description": "Shared settings, configuration, reporting, and session infrastructure",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-code-runtime",
3
- "version": "9.1.0",
3
+ "version": "9.1.2",
4
4
  "description": "Shared workspace context and capability contracts for code intelligence",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-core",
3
- "version": "9.1.0",
3
+ "version": "9.1.2",
4
4
  "description": "Shared settings, configuration, reporting, and session infrastructure",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-lsp",
3
- "version": "9.1.0",
3
+ "version": "9.1.2",
4
4
  "description": "Language Server Protocol runtime for SuPi code intelligence",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -37,8 +37,8 @@
37
37
  "vscode-jsonrpc": "^9.0.0",
38
38
  "vscode-languageserver-protocol": "^3.18.0",
39
39
  "vscode-languageserver-types": "^3.18.0",
40
- "@mrclrchtr/supi-code-runtime": "9.1.0",
41
- "@mrclrchtr/supi-core": "9.1.0"
40
+ "@mrclrchtr/supi-code-runtime": "9.1.2",
41
+ "@mrclrchtr/supi-core": "9.1.2"
42
42
  },
43
43
  "bundledDependencies": [
44
44
  "@mrclrchtr/supi-code-runtime",
@@ -1,3 +1,4 @@
1
+ import { statSync } from "node:fs";
1
2
  import * as path from "node:path";
2
3
  import {
3
4
  type CodeQueryResult,
@@ -6,6 +7,7 @@ import {
6
7
  partialCodeQuery,
7
8
  unavailableCodeQuery,
8
9
  } from "@mrclrchtr/supi-code-runtime/api";
10
+ import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
9
11
  import type { LspClient } from "../client/client.ts";
10
12
  import type {
11
13
  DocumentSymbol,
@@ -34,6 +36,8 @@ export interface WorkspaceSymbolWarmOptions {
34
36
  maxMarkerDepth?: number;
35
37
  /** Runtime-owned automatic path policy. */
36
38
  policy?: AutomaticLspPathPolicy;
39
+ /** Absolute request scopes. Search only their intersection with the route root. */
40
+ scopes?: readonly string[];
37
41
  }
38
42
 
39
43
  export function getWorkspaceSymbolWarmPosition(
@@ -144,6 +148,31 @@ export function findWorkspaceSymbolWarmTargets(
144
148
  const policy = options.policy ?? createDefaultAutomaticLspPathPolicy(resolvedRoot);
145
149
  if (allowed.size === 0) return [];
146
150
 
151
+ if (options.scopes?.length) {
152
+ const targets = options.scopes.flatMap((scope) => {
153
+ const searchRoot = isWithinOrEqual(resolvedRoot, scope)
154
+ ? scope
155
+ : isWithinOrEqual(scope, resolvedRoot)
156
+ ? resolvedRoot
157
+ : null;
158
+ return searchRoot
159
+ ? findWorkspaceSymbolWarmTargets(searchRoot, rootMarkers, fileTypes, {
160
+ ...options,
161
+ policy,
162
+ scopes: undefined,
163
+ })
164
+ : [];
165
+ });
166
+ return [...new Map(targets.map((target) => [target.file, target])).values()];
167
+ }
168
+
169
+ if (statSync(resolvedRoot, { throwIfNoEntry: false })?.isFile()) {
170
+ return allowed.has(path.extname(resolvedRoot).slice(1).toLowerCase()) &&
171
+ policy.isEligible(resolvedRoot, "file")
172
+ ? [{ projectRoot: path.dirname(resolvedRoot), file: resolvedRoot }]
173
+ : [];
174
+ }
175
+
147
176
  const markerRoots = collectMarkerRoots(resolvedRoot, rootMarkers, maxMarkerDepth, policy);
148
177
  const targets = markerRoots
149
178
  .map((entry) => {
@@ -334,8 +334,8 @@ export class LspManager {
334
334
  private invalidationEpoch = 0;
335
335
  /** Invalidation generation in which each route last received a recovery restart. */
336
336
  private recoveryRestartEpochs = new Map<string, number>();
337
- /** Project roots already warmed for workspace-symbol queries. */
338
- private warmedWorkspaceSymbolProjects = new Set<string>();
337
+ /** Files already probed for workspace-symbol warm-up. */
338
+ private warmedWorkspaceSymbolFiles = new Set<string>();
339
339
  /** Project roots whose semantic state was warmed with a readiness probe. */
340
340
  private warmedSemanticProjects = new Set<string>();
341
341
  /** In-flight warm-up probes keyed by project key so concurrent callers share one probe. */
@@ -527,7 +527,7 @@ export class LspManager {
527
527
  root,
528
528
  failureMessage: "The LSP client is not running.",
529
529
  });
530
- this.clearWarmedWorkspaceSymbolProjects(existing.name, existing.root);
530
+ this.clearWarmedWorkspaceSymbolFiles(existing.name, existing.root);
531
531
  this.clearWarmedSemanticProjects(existing.name, existing.root);
532
532
  this.clearPendingWarmProbes(existing.name, existing.root);
533
533
  if (!retryFailedStart) return null;
@@ -1246,7 +1246,7 @@ export class LspManager {
1246
1246
  ): LspClient {
1247
1247
  const key = route.key;
1248
1248
  if (this.clients.get(key) === recovery.failedClient) this.clients.delete(key);
1249
- this.clearWarmedWorkspaceSymbolProjects(route.serverName, route.root);
1249
+ this.clearWarmedWorkspaceSymbolFiles(route.serverName, route.root);
1250
1250
  this.clearWarmedSemanticProjects(route.serverName, route.root);
1251
1251
  this.clearPendingWarmProbes(route.serverName, route.root);
1252
1252
 
@@ -1402,7 +1402,7 @@ export class LspManager {
1402
1402
 
1403
1403
  // Spawn new client
1404
1404
  const client = this.createClient(serverName, serverConfig, root, key);
1405
- this.clearWarmedWorkspaceSymbolProjects(serverName, root);
1405
+ this.clearWarmedWorkspaceSymbolFiles(serverName, root);
1406
1406
  this.clearWarmedSemanticProjects(serverName, root);
1407
1407
  this.clearPendingWarmProbes(serverName, root);
1408
1408
  this.clients.set(key, client);
@@ -1532,7 +1532,7 @@ export class LspManager {
1532
1532
  if (this.clients.get(key) !== client) return { files, restarted: false };
1533
1533
  this.clients.delete(key);
1534
1534
  this.unavailable.delete(key);
1535
- this.clearWarmedWorkspaceSymbolProjects(client.name, client.root);
1535
+ this.clearWarmedWorkspaceSymbolFiles(client.name, client.root);
1536
1536
  this.clearWarmedSemanticProjects(client.name, client.root);
1537
1537
  this.clearPendingWarmProbes(client.name, client.root);
1538
1538
 
@@ -2307,7 +2307,7 @@ export class LspManager {
2307
2307
  this.recoveryRestartEpochs.clear();
2308
2308
  this.unavailable.clear();
2309
2309
  this.knownRoots.clear();
2310
- this.warmedWorkspaceSymbolProjects.clear();
2310
+ this.warmedWorkspaceSymbolFiles.clear();
2311
2311
  this.warmedSemanticProjects.clear();
2312
2312
  this.pendingWarmProbes.clear();
2313
2313
  this.pendingRestarts.clear();
@@ -2671,6 +2671,7 @@ export class LspManager {
2671
2671
  findWarmTargets: (root, rootMarkers, fileTypes) =>
2672
2672
  findWorkspaceSymbolWarmTargets(root, rootMarkers, fileTypes, {
2673
2673
  policy: this.automaticPathPolicy,
2674
+ scopes: resolvedScopes,
2674
2675
  }),
2675
2676
  getWarmPosition: getWorkspaceSymbolWarmPosition,
2676
2677
  collect,
@@ -2696,22 +2697,21 @@ export class LspManager {
2696
2697
  collection: WorkspaceSymbolCollection,
2697
2698
  scopes: readonly string[] | undefined,
2698
2699
  ): WorkspaceSymbolCollection {
2699
- const excludedExamples: string[] = [];
2700
+ const excludedExamples = new Set(collection.excludedExamples ?? []);
2700
2701
  let excludedCount = 0;
2701
2702
  const results = collection.results.filter((result) => {
2702
2703
  const file = uriToFile(result.location.uri);
2703
2704
  if (this.isWorkspaceSymbolResultAllowed(file, scopes)) return true;
2704
2705
  excludedCount++;
2705
- if (excludedExamples.length < 5) {
2706
- excludedExamples.push(displayRelativeFilePath(file, this.cwd));
2707
- }
2706
+ const example = displayRelativeFilePath(file, this.cwd);
2707
+ if (excludedExamples.size < 5) excludedExamples.add(example);
2708
2708
  return false;
2709
2709
  });
2710
2710
  return {
2711
2711
  ...collection,
2712
2712
  results,
2713
2713
  excludedCount: (collection.excludedCount ?? 0) + excludedCount,
2714
- excludedExamples: [...(collection.excludedExamples ?? []), ...excludedExamples].slice(0, 5),
2714
+ excludedExamples: [...excludedExamples].slice(0, 5),
2715
2715
  };
2716
2716
  }
2717
2717
 
@@ -2803,6 +2803,7 @@ export class LspManager {
2803
2803
  }): Promise<{ warmedAny: boolean; collection: WorkspaceSymbolCollection | null }> {
2804
2804
  const { findWarmTargets, getWarmPosition, collect, routeMatches, query, control } = options;
2805
2805
  let warmedAny = false;
2806
+ let latestCollection: WorkspaceSymbolCollection | null = null;
2806
2807
 
2807
2808
  for (const client of Array.from(this.clients.values())) {
2808
2809
  if (routeMatches && !routeMatches(client)) continue;
@@ -2819,8 +2820,9 @@ export class LspManager {
2819
2820
  ).slice(0, 24);
2820
2821
 
2821
2822
  for (const target of warmTargets) {
2822
- const projectKey = this.workspaceSymbolProjectKey(client.name, target.projectRoot);
2823
- if (this.warmedWorkspaceSymbolProjects.has(projectKey)) continue;
2823
+ // A file probe does not load every program under the route root.
2824
+ const fileKey = `${client.name}:${path.resolve(target.file)}`;
2825
+ if (this.warmedWorkspaceSymbolFiles.has(fileKey)) continue;
2824
2826
 
2825
2827
  const openedClient = await this.ensureFileOpen(target.file);
2826
2828
  if (!openedClient) continue;
@@ -2834,18 +2836,19 @@ export class LspManager {
2834
2836
  control,
2835
2837
  );
2836
2838
  if (available) {
2837
- this.warmedWorkspaceSymbolProjects.add(projectKey);
2839
+ this.warmedWorkspaceSymbolFiles.add(fileKey);
2838
2840
  warmedAny = true;
2839
2841
  }
2840
2842
 
2841
- const collected = await collect(this.clients.values(), query);
2842
- if (collected.hasSupport && collected.results.length > 0) {
2843
- return { warmedAny, collection: collected };
2843
+ latestCollection = await collect(this.clients.values(), query);
2844
+ if (latestCollection.hasSupport && latestCollection.results.length > 0) {
2845
+ return { warmedAny, collection: latestCollection };
2844
2846
  }
2845
2847
  }
2846
2848
  }
2847
2849
 
2848
- return { warmedAny, collection: null };
2850
+ // A completed-empty retry replaces an earlier failure too.
2851
+ return { warmedAny, collection: latestCollection };
2849
2852
  }
2850
2853
 
2851
2854
  private async warmSemanticProject(
@@ -2936,11 +2939,11 @@ export class LspManager {
2936
2939
  return `${serverName}:${path.resolve(projectRoot)}`;
2937
2940
  }
2938
2941
 
2939
- private clearWarmedWorkspaceSymbolProjects(serverName: string, root: string): void {
2942
+ private clearWarmedWorkspaceSymbolFiles(serverName: string, root: string): void {
2940
2943
  const prefix = `${serverName}:${path.resolve(root)}`;
2941
- for (const key of Array.from(this.warmedWorkspaceSymbolProjects)) {
2944
+ for (const key of Array.from(this.warmedWorkspaceSymbolFiles)) {
2942
2945
  if (key === prefix || key.startsWith(`${prefix}${path.sep}`)) {
2943
- this.warmedWorkspaceSymbolProjects.delete(key);
2946
+ this.warmedWorkspaceSymbolFiles.delete(key);
2944
2947
  }
2945
2948
  }
2946
2949
  }
@@ -19,6 +19,8 @@ to access structural code-understanding workflows in pi.
19
19
  npm install @mrclrchtr/supi-tree-sitter
20
20
  ```
21
21
 
22
+ Structural analysis always runs in a Node.js child process. Under Bun, including compiled applications such as Pi-Bolt, install Node.js and make the `node` executable available on `PATH`. SuPi validates that executable before it starts the process host. If Node.js is unavailable, structural analysis reports an installation error. There is no Bun Worker or main-thread parser fallback.
23
+
22
24
  ![Tree-sitter outline in action](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-tree-sitter.png)
23
25
 
24
26
  ## What you get
@@ -107,7 +109,7 @@ The benchmark reports cold and repeated outline results. It also reports cold an
107
109
 
108
110
  The Structural Worker reads files asynchronously. It identifies fresh parsed files by canonical path, grammar, and SHA-256 content hash. Cached trees use true least-recently-used eviction with limits of 128 files and 32 MiB of retained UTF-8 source bytes. Compiled queries use the same policy with limits of 128 queries and 512 KiB of retained UTF-8 query text. Source and query byte counts are memory-related proxies because `web-tree-sitter` does not report WASM resource sizes. Cached canonical trees stay private in the Worker.
109
111
 
110
- The Structural Worker runs in a dedicated Node child process. The process uses `--liftoff-only` so V8 avoids the optimizing WebAssembly compiler that uses unsafe amounts of memory for large grammars. This applies to every grammar in the Worker. Pi's main process does not receive this flag, and a V8 failure in the Worker process cannot crash Pi.
112
+ The Structural Worker runs in a dedicated Node child process. The process uses `--liftoff-only` so V8 avoids the optimizing WebAssembly compiler that uses unsafe amounts of memory for large grammars. This applies to every grammar in the Worker. Pi's main process does not receive this flag, and a V8 failure in the Worker process cannot crash Pi. A Node parent uses its current executable and advanced IPC. A Bun parent selects Node explicitly and uses JSON IPC with bounded base64 result chunks; the private Worker-thread protocol stays unchanged.
111
113
 
112
114
  All structural service operations accept optional `CodeRequestControl`. The parent converts cancellation to one shared atomic flag and forwards absolute deadlines. When present, it forwards only the opaque Debug Operation ID through the Worker protocol so parse and query timing events keep direct request ownership. Direct library calls have no ID. The process host creates a shared atomic flag for its Worker thread because Node IPC cannot share the parent flag. Worker read phases observe a local abort signal. Parser and query progress callbacks observe the flag and deadline. If cooperative interruption does not settle in the fixed 250 ms grace period, the parent terminates the Worker process. Valid queued work keeps FIFO order on one fresh Worker with cold caches. There is no main-thread parser fallback.
113
115
 
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-code-runtime",
3
- "version": "9.1.0",
3
+ "version": "9.1.2",
4
4
  "description": "Shared workspace context and capability contracts for code intelligence",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-core",
3
- "version": "9.1.0",
3
+ "version": "9.1.2",
4
4
  "description": "Shared settings, configuration, reporting, and session infrastructure",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-tree-sitter",
3
- "version": "9.1.0",
3
+ "version": "9.1.2",
4
4
  "description": "Structural AST analysis for SuPi code intelligence",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -36,8 +36,8 @@
36
36
  "dependencies": {
37
37
  "jiti": "^2.7.0",
38
38
  "web-tree-sitter": "^0.27.0",
39
- "@mrclrchtr/supi-core": "9.1.0",
40
- "@mrclrchtr/supi-code-runtime": "9.1.0"
39
+ "@mrclrchtr/supi-code-runtime": "9.1.2",
40
+ "@mrclrchtr/supi-core": "9.1.2"
41
41
  },
42
42
  "bundledDependencies": [
43
43
  "@mrclrchtr/supi-code-runtime",
@@ -0,0 +1,23 @@
1
+ import { assertStructuralProtocolMessageSize } from "./structural-worker-message-size.ts";
2
+ import { STRUCTURAL_WORKER_LIMITS } from "./structural-worker-protocol.ts";
3
+
4
+ /** Restore bounded binary chunks before the private Worker protocol validates them. */
5
+ export function decodeStructuralWorkerJsonMessage(message: unknown): unknown {
6
+ assertStructuralProtocolMessageSize(message);
7
+ if (!message || typeof message !== "object" || !("kind" in message) || message.kind !== "chunk") {
8
+ return message;
9
+ }
10
+ const payload = "payload" in message ? message.payload : undefined;
11
+ const maxLength = Math.ceil(STRUCTURAL_WORKER_LIMITS.targetChunkBytes / 3) * 4;
12
+ if (typeof payload !== "string" || payload.length > maxLength) {
13
+ throw new Error("Invalid Structural Worker JSON chunk payload");
14
+ }
15
+ const bytes = Buffer.from(payload, "base64");
16
+ if (
17
+ bytes.byteLength > STRUCTURAL_WORKER_LIMITS.targetChunkBytes ||
18
+ bytes.toString("base64") !== payload
19
+ ) {
20
+ throw new Error("Invalid Structural Worker JSON chunk payload");
21
+ }
22
+ return { ...message, payload: bytes };
23
+ }
@@ -0,0 +1,29 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import { isAbsolute } from "node:path";
3
+
4
+ /** Select a real Node executable without re-entering a compiled Bun application. */
5
+ export function resolveStructuralWorkerNode(): string {
6
+ if (!process.versions.bun) return process.execPath;
7
+
8
+ const probe = spawnSync(
9
+ "node",
10
+ [
11
+ "--liftoff-only",
12
+ "--eval",
13
+ "if (!process.versions.bun) process.stdout.write(process.execPath)",
14
+ ],
15
+ {
16
+ encoding: "utf8",
17
+ env: { ...process.env, NODE_OPTIONS: "" },
18
+ timeout: 2_000,
19
+ maxBuffer: 4_096,
20
+ windowsHide: true,
21
+ },
22
+ );
23
+ if (probe.status !== 0 || !probe.stdout || !isAbsolute(probe.stdout)) {
24
+ throw new Error(
25
+ "Structural analysis under Bun requires Node.js on PATH. Install Node.js and restart Pi.",
26
+ );
27
+ }
28
+ return probe.stdout;
29
+ }
@@ -1,6 +1,8 @@
1
1
  import { type ChildProcess, fork } from "node:child_process";
2
2
  import { EventEmitter } from "node:events";
3
3
  import { fileURLToPath } from "node:url";
4
+ import { decodeStructuralWorkerJsonMessage } from "./structural-worker-json.ts";
5
+ import { resolveStructuralWorkerNode } from "./structural-worker-node.ts";
4
6
  import type {
5
7
  ParentToStructuralWorkerMessage,
6
8
  StructuralWorkerToParentMessage,
@@ -23,23 +25,28 @@ export function createStructuralWorkerProcess(options: {
23
25
  readonly generation: number;
24
26
  }): StructuralWorkerLike {
25
27
  const hostPath = fileURLToPath(new URL("../worker/process-host.mjs", import.meta.url));
28
+ const jsonIpc = Boolean(process.versions.bun);
29
+ const args = [options.cwd, String(options.generation), ...(jsonIpc ? ["json"] : [])];
26
30
  // A child process accepts the V8 flag that a Worker thread rejects.
27
- const child = fork(hostPath, [options.cwd, String(options.generation)], {
31
+ const child = fork(hostPath, args, {
32
+ execPath: resolveStructuralWorkerNode(),
28
33
  execArgv: ["--liftoff-only"],
29
34
  env: { ...process.env, NODE_OPTIONS: "" },
30
- serialization: "advanced",
35
+ serialization: jsonIpc ? "json" : "advanced",
31
36
  stdio: ["ignore", "ignore", "inherit", "ipc"],
32
37
  windowsHide: true,
33
38
  });
34
- return new StructuralWorkerProcess(child);
39
+ return new StructuralWorkerProcess(child, jsonIpc);
35
40
  }
36
41
 
37
42
  class StructuralWorkerProcess implements StructuralWorkerLike {
38
43
  readonly #events = new EventEmitter();
39
44
  readonly #child: ChildProcess;
45
+ readonly #jsonIpc: boolean;
40
46
 
41
- constructor(child: ChildProcess) {
47
+ constructor(child: ChildProcess, jsonIpc: boolean) {
42
48
  this.#child = child;
49
+ this.#jsonIpc = jsonIpc;
43
50
  child.on("message", (value: unknown) => this.#receive(value));
44
51
  child.on("error", (error) => this.#events.emit("error", error));
45
52
  child.on("exit", (code) => this.#events.emit("exit", code ?? 1));
@@ -96,7 +103,16 @@ class StructuralWorkerProcess implements StructuralWorkerLike {
96
103
  this.#events.emit("error", new Error(value.message.message));
97
104
  return;
98
105
  }
99
- this.#events.emit("message", value.message);
106
+ let message: unknown = value.message;
107
+ if (this.#jsonIpc) {
108
+ try {
109
+ message = decodeStructuralWorkerJsonMessage(message);
110
+ } catch (error) {
111
+ this.#events.emit("error", error instanceof Error ? error : new Error(String(error)));
112
+ return;
113
+ }
114
+ }
115
+ this.#events.emit("message", message);
100
116
  }
101
117
  }
102
118
 
@@ -1,8 +1,13 @@
1
1
  import { Worker } from "node:worker_threads";
2
2
 
3
- const [cwd, generationValue] = process.argv.slice(2);
3
+ const [cwd, generationValue, serialization = "advanced"] = process.argv.slice(2);
4
4
  const generation = Number(generationValue);
5
- if (!cwd || !Number.isSafeInteger(generation) || generation < 1) {
5
+ if (
6
+ !cwd ||
7
+ !Number.isSafeInteger(generation) ||
8
+ generation < 1 ||
9
+ !["advanced", "json"].includes(serialization)
10
+ ) {
6
11
  throw new Error("Structural Worker process received invalid startup data");
7
12
  }
8
13
 
@@ -76,7 +81,19 @@ function isParentChannel(value) {
76
81
  }
77
82
 
78
83
  function send(message, callback) {
79
- if (process.connected && process.send) process.send(message, callback);
84
+ if (!process.connected || !process.send) return;
85
+ // Bun and Node use different binary IPC formats. Keep the thread protocol unchanged.
86
+ const forwarded =
87
+ serialization === "json" && message.message.kind === "chunk"
88
+ ? {
89
+ ...message,
90
+ message: {
91
+ ...message.message,
92
+ payload: Buffer.from(message.message.payload).toString("base64"),
93
+ },
94
+ }
95
+ : message;
96
+ process.send(forwarded, callback);
80
97
  }
81
98
 
82
99
  function disconnect() {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-code-intelligence",
3
- "version": "9.1.0",
3
+ "version": "9.1.2",
4
4
  "description": "LSP and AST navigation, search, diagnostics, and refactoring",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -35,10 +35,10 @@
35
35
  ],
36
36
  "dependencies": {
37
37
  "yaml": "^2.9.0",
38
- "@mrclrchtr/supi-code-runtime": "9.1.0",
39
- "@mrclrchtr/supi-lsp": "9.1.0",
40
- "@mrclrchtr/supi-core": "9.1.0",
41
- "@mrclrchtr/supi-tree-sitter": "9.1.0"
38
+ "@mrclrchtr/supi-lsp": "9.1.2",
39
+ "@mrclrchtr/supi-code-runtime": "9.1.2",
40
+ "@mrclrchtr/supi-core": "9.1.2",
41
+ "@mrclrchtr/supi-tree-sitter": "9.1.2"
42
42
  },
43
43
  "bundledDependencies": [
44
44
  "@mrclrchtr/supi-code-runtime",
@@ -27,6 +27,8 @@ export interface EvidenceListMetadata {
27
27
  /** Known collected atoms hidden by presentation; null when not tracked. */
28
28
  omittedCount: number | null;
29
29
  partialReason: EvidencePartialReason | null;
30
+ /** Provider explanation for incomplete collection, when available. */
31
+ partialMessage?: string;
30
32
  /** Unusable semantic-provider locations excluded from valid evidence totals. */
31
33
  invalidLocationCount?: number;
32
34
  }
@@ -133,9 +133,9 @@ export async function resolveSymbolTarget(
133
133
  }
134
134
  if (result.data.length === 0) return emptySymbolOutcome(symbol, result, options?.path);
135
135
 
136
- const scoped = result.data.filter((candidate) =>
137
- scopePath ? isWithinOrEqual(scopePath, candidate.file) : true,
138
- );
136
+ const scoped = result.data
137
+ .filter((candidate) => (scopePath ? isWithinOrEqual(scopePath, candidate.file) : true))
138
+ .sort((a, b) => Number(b.name === symbol) - Number(a.name === symbol));
139
139
  const eligible = options?.exportedOnly
140
140
  ? scoped.filter((candidate) => !NON_EXPORTED_KINDS.has(candidate.kind))
141
141
  : scoped;
@@ -187,9 +187,18 @@ function normalizeProviderKind(kind: string): string {
187
187
  }
188
188
 
189
189
  async function resolveCandidates(
190
- options: CandidateOutcomeBase & Pick<TargetCandidateCompleteness, "totalCount" | "partialReason">,
190
+ options: CandidateOutcomeBase & Omit<TargetCandidateCompleteness, "omittedCount">,
191
191
  ): Promise<TargetOutcome> {
192
- const { candidates, semantic, cwd, maxResults, control, totalCount, partialReason } = options;
192
+ const {
193
+ candidates,
194
+ semantic,
195
+ cwd,
196
+ maxResults,
197
+ control,
198
+ totalCount,
199
+ partialReason,
200
+ partialMessage,
201
+ } = options;
193
202
  const ranged = candidates.filter(
194
203
  (candidate) =>
195
204
  candidate.declarationAnchor.line > 0 || candidate.declarationAnchor.character > 0,
@@ -205,6 +214,7 @@ async function resolveCandidates(
205
214
  maxResults,
206
215
  totalCount,
207
216
  partialReason,
217
+ partialMessage,
208
218
  control,
209
219
  });
210
220
  }
@@ -241,14 +251,14 @@ interface CandidateOutcomeBase {
241
251
  function candidateCompleteness(
242
252
  result: Exclude<CodeQueryResult<CodeSymbol[]>, { kind: "unavailable" }>,
243
253
  totalCount: number,
244
- ): Pick<TargetCandidateCompleteness, "totalCount" | "partialReason"> {
254
+ ): Omit<TargetCandidateCompleteness, "omittedCount"> {
245
255
  return result.kind === "partial"
246
- ? { totalCount: null, partialReason: "provider-limited" }
256
+ ? { totalCount: null, partialReason: "provider-limited", partialMessage: result.reason }
247
257
  : { totalCount, partialReason: null };
248
258
  }
249
259
 
250
260
  type CandidateOutcomeOptions = CandidateOutcomeBase &
251
- Pick<TargetCandidateCompleteness, "totalCount" | "partialReason"> &
261
+ Omit<TargetCandidateCompleteness, "omittedCount"> &
252
262
  (
253
263
  | { kind: "disambiguation"; requestedKind?: never }
254
264
  | { kind: "kind-mismatch"; requestedKind: TargetSymbolKind }
@@ -290,6 +300,7 @@ async function buildCandidateOutcome(
290
300
  totalCount: options.totalCount,
291
301
  omittedCount: Math.max(0, options.candidates.length - cap),
292
302
  partialReason: options.partialReason,
303
+ partialMessage: options.partialMessage,
293
304
  };
294
305
  return options.kind === "kind-mismatch"
295
306
  ? {
@@ -144,6 +144,8 @@ export interface TargetCandidateCompleteness {
144
144
  omittedCount: number;
145
145
  /** Why the provider cannot establish an exact candidate total. */
146
146
  partialReason: "provider-limited" | null;
147
+ /** Provider explanation for incomplete discovery, when available. */
148
+ partialMessage?: string;
147
149
  }
148
150
 
149
151
  /**
@@ -135,6 +135,7 @@ async function orientTarget(options: {
135
135
  totalCount: target.totalCount,
136
136
  omittedCount: target.omittedCount,
137
137
  partialReason: target.partialReason,
138
+ partialMessage: target.partialMessage,
138
139
  }
139
140
  : {
140
141
  kind: "disambiguation",
@@ -142,6 +143,7 @@ async function orientTarget(options: {
142
143
  totalCount: target.totalCount,
143
144
  omittedCount: target.omittedCount,
144
145
  partialReason: target.partialReason,
146
+ partialMessage: target.partialMessage,
145
147
  };
146
148
  }
147
149
  if (target.kind !== "resolved") return target;
@@ -320,6 +320,7 @@ function toWorkflowOutcome(
320
320
  totalCount: outcome.totalCount,
321
321
  omittedCount: outcome.omittedCount,
322
322
  partialReason: outcome.partialReason,
323
+ partialMessage: outcome.partialMessage,
323
324
  }
324
325
  : {
325
326
  kind: "disambiguation",
@@ -327,6 +328,7 @@ function toWorkflowOutcome(
327
328
  totalCount: outcome.totalCount,
328
329
  omittedCount: outcome.omittedCount,
329
330
  partialReason: outcome.partialReason,
331
+ partialMessage: outcome.partialMessage,
330
332
  };
331
333
  }
332
334
 
@@ -19,5 +19,5 @@ export async function executeFindTool(
19
19
  ctx: CodeIntelToolExecCtx,
20
20
  ): Promise<CodeIntelResult> {
21
21
  const outcome = await ctx.session.find(params as FindWorkflowInput, toWorkflowControl(ctx));
22
- return finishFindResult(outcome, params.scope);
22
+ return finishFindResult(outcome, params.scope, params.mode);
23
23
  }
@@ -4,7 +4,7 @@ import {
4
4
  createPartialEvidenceList,
5
5
  type EvidenceListMetadata,
6
6
  } from "../../analysis/evidence.ts";
7
- import type { FindWorkflowOutcome } from "../../session/find-types.ts";
7
+ import type { FindMode, FindWorkflowOutcome } from "../../session/find-types.ts";
8
8
  import {
9
9
  assembledNextQueries,
10
10
  assembleToolResult,
@@ -155,7 +155,7 @@ function findProvenance(
155
155
  }
156
156
 
157
157
  import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
158
- import { searchErrorResult } from "../result/errors.ts";
158
+ import { scopedSymbolFailureMessage, searchErrorResult } from "../result/errors.ts";
159
159
  import { renderFindResult } from "./render.ts";
160
160
 
161
161
  type FindOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["find"]>>;
@@ -164,8 +164,15 @@ type FindOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["find"]>>;
164
164
  export function finishFindResult(
165
165
  outcome: FindOutcome,
166
166
  scope: readonly string[] | undefined,
167
+ mode?: FindMode,
167
168
  ): CodeIntelResult {
168
- if (outcome.kind === "unavailable") throw new Error(outcome.reason);
169
+ if (outcome.kind === "unavailable") {
170
+ const reason =
171
+ mode === "semantic" && scope?.length
172
+ ? scopedSymbolFailureMessage(outcome.reason)
173
+ : outcome.reason;
174
+ throw new Error(reason);
175
+ }
169
176
  if (outcome.kind === "invalid-input") {
170
177
  return searchErrorResult(`**Error:** ${outcome.message}`, {
171
178
  scope: Array.isArray(scope) ? scope.join(", ") : null,
@@ -19,7 +19,7 @@ import {
19
19
  type ResultProvenance,
20
20
  type ToolResultAssembly,
21
21
  } from "../result/assembly.ts";
22
- import { formatCandidateRow } from "../result/candidate-row.ts";
22
+ import { formatCandidateRow, formatPartialCandidateDisclosure } from "../result/candidate-row.ts";
23
23
  import { createToolDisplaySection } from "../result/display.ts";
24
24
  import type { ToolDisplaySection } from "../result/types.ts";
25
25
  import type { GraphDetails, GraphFileGroup, GraphSectionDetails } from "./details.ts";
@@ -280,7 +280,10 @@ function finishGraphCandidates(
280
280
  );
281
281
  }
282
282
  const evidence = graphCandidateEvidence(outcome);
283
- lines.push("", formatGraphEvidence(evidence, "candidates"));
283
+ lines.push(
284
+ "",
285
+ formatPartialCandidateDisclosure(evidence) ?? formatGraphEvidence(evidence, "candidates"),
286
+ );
284
287
  if (outcome.kind === "kind-mismatch") {
285
288
  lines.push(
286
289
  "",
@@ -295,6 +298,7 @@ function finishGraphCandidates(
295
298
  totalCount: evidence.totalCount,
296
299
  omittedCount: evidence.omittedCount,
297
300
  partialReason: evidence.partialReason,
301
+ partialMessage: evidence.partialMessage,
298
302
  format: (candidate) => formatCandidateRow(candidate, "handle-first"),
299
303
  }),
300
304
  ];
@@ -323,6 +327,7 @@ function graphCandidateEvidence(
323
327
  shownCount: outcome.candidates.length,
324
328
  omittedCount: outcome.omittedCount,
325
329
  partialReason: outcome.partialReason,
330
+ partialMessage: outcome.partialMessage,
326
331
  };
327
332
  }
328
333
 
@@ -18,7 +18,7 @@ import {
18
18
  type ResultSection,
19
19
  type ToolResultAssembly,
20
20
  } from "../result/assembly.ts";
21
- import { formatCandidateRow } from "../result/candidate-row.ts";
21
+ import { formatCandidateRow, formatPartialCandidateDisclosure } from "../result/candidate-row.ts";
22
22
  import { createToolDisplaySection } from "../result/display.ts";
23
23
  import type {
24
24
  ContextDetails,
@@ -61,6 +61,7 @@ export function orientationCandidateDisplaySections(
61
61
  totalCount: evidence.totalCount,
62
62
  omittedCount: evidence.omittedCount,
63
63
  partialReason: evidence.partialReason,
64
+ partialMessage: evidence.partialMessage,
64
65
  format: (candidate) => formatCandidateRow(candidate, "rank-first"),
65
66
  }),
66
67
  ];
@@ -207,7 +208,7 @@ export function finishOrientationResult(outcome: OrientationOutcome): CodeIntelR
207
208
  });
208
209
  }
209
210
  if (outcome.kind === "disambiguation" || outcome.kind === "kind-mismatch") {
210
- const candidates = outcome.candidates ?? [];
211
+ const candidates = outcome.candidates;
211
212
  const lines = [
212
213
  outcome.kind === "kind-mismatch"
213
214
  ? `# No Orientation target matched provider kind \`${outcome.requestedKind}\``
@@ -225,8 +226,10 @@ export function finishOrientationResult(outcome: OrientationOutcome): CodeIntelR
225
226
  shownCount: candidates.length,
226
227
  omittedCount: outcome.omittedCount,
227
228
  partialReason: outcome.partialReason,
229
+ partialMessage: outcome.partialMessage,
228
230
  };
229
- const disclosure = renderEvidenceListMetadataDisclosure(evidence);
231
+ const disclosure =
232
+ formatPartialCandidateDisclosure(evidence) ?? renderEvidenceListMetadataDisclosure(evidence);
230
233
  if (disclosure) lines.push("", disclosure);
231
234
  const nextQueries =
232
235
  outcome.kind === "kind-mismatch"
@@ -15,5 +15,5 @@ export async function executeResolveTool(
15
15
  ctx: CodeIntelToolExecCtx,
16
16
  ): Promise<CodeIntelResult> {
17
17
  const outcome = await ctx.session.resolve(params, toWorkflowControl(ctx));
18
- return finishResolveResult(outcome, ctx.cwd);
18
+ return finishResolveResult(outcome, ctx.cwd, params.target);
19
19
  }
@@ -3,6 +3,7 @@
3
3
  import { relative } from "node:path";
4
4
  import { renderEvidenceListMetadataDisclosure } from "../../analysis/evidence.ts";
5
5
  import type { TargetStoreEntry } from "../../session/target-store.ts";
6
+ import { formatPartialCandidateDisclosure } from "../result/candidate-row.ts";
6
7
  import type { ResolveDetails } from "../result/types.ts";
7
8
  import type { ResolveResultAssembly } from "./result.ts";
8
9
 
@@ -155,6 +156,8 @@ function appendCandidates(lines: string[], details: ResolveDetails): void {
155
156
 
156
157
  function appendDisclosure(lines: string[], details: ResolveDetails): void {
157
158
  const evidence = details.evidenceLists?.[0];
158
- const disclosure = evidence ? renderEvidenceListMetadataDisclosure(evidence) : null;
159
+ const disclosure = evidence
160
+ ? (formatPartialCandidateDisclosure(evidence) ?? renderEvidenceListMetadataDisclosure(evidence))
161
+ : null;
159
162
  if (disclosure) lines.push("", disclosure);
160
163
  }
@@ -2,6 +2,7 @@ import { relative } from "node:path";
2
2
  import type { ConfidenceMode } from "@mrclrchtr/supi-code-runtime/api";
3
3
  import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
4
4
  import { createEvidenceList } from "../../analysis/evidence.ts";
5
+ import type { ResolveTargetInput } from "../../session/target-input.ts";
5
6
  import type { TargetStoreEntry } from "../../session/target-store.ts";
6
7
  import type { TargetWorkflowOutcome } from "../../session/target-workflow.ts";
7
8
  import {
@@ -12,6 +13,7 @@ import {
12
13
  } from "../result/assembly.ts";
13
14
  import { formatCandidateRow } from "../result/candidate-row.ts";
14
15
  import { createToolDisplaySection } from "../result/display.ts";
16
+ import { scopedSymbolFailureMessage } from "../result/errors.ts";
15
17
  import type { ResolveDetails, ToolDisplaySection } from "../result/types.ts";
16
18
 
17
19
  /** Presentation-neutral assembled code_resolve result. */
@@ -160,6 +162,7 @@ function projectCandidateOutcome(
160
162
  shownCount: outcome.candidates.length,
161
163
  omittedCount: outcome.omittedCount,
162
164
  partialReason: outcome.partialReason,
165
+ partialMessage: outcome.partialMessage,
163
166
  };
164
167
  const collectedCount = evidence.shownCount + (evidence.omittedCount ?? 0);
165
168
  const mismatch = outcome.kind === "kind-mismatch";
@@ -265,6 +268,7 @@ function resolveDisplaySections(details: ResolveDetails): ToolDisplaySection[] {
265
268
  totalCount: evidence.totalCount,
266
269
  omittedCount: evidence.omittedCount,
267
270
  partialReason: evidence.partialReason,
271
+ partialMessage: evidence.partialMessage,
268
272
  format: (candidate) => formatCandidateRow(candidate, "rank-first"),
269
273
  }),
270
274
  ];
@@ -298,9 +302,17 @@ import { renderResolveResult } from "./markdown.ts";
298
302
  type ResolveOutcome = Awaited<ReturnType<CodeIntelToolExecCtx["session"]["resolve"]>>;
299
303
 
300
304
  /** Assemble the final model-visible code_resolve result for one workflow outcome. */
301
- export function finishResolveResult(outcome: ResolveOutcome, cwd: string): CodeIntelResult {
305
+ export function finishResolveResult(
306
+ outcome: ResolveOutcome,
307
+ cwd: string,
308
+ target?: ResolveTargetInput,
309
+ ): CodeIntelResult {
302
310
  if (outcome.kind === "unavailable") {
303
- throw new Error(outcome.reason);
311
+ const reason =
312
+ target && "symbol" in target && target.symbol.scope
313
+ ? scopedSymbolFailureMessage(outcome.reason)
314
+ : outcome.reason;
315
+ throw new Error(reason);
304
316
  }
305
317
 
306
318
  const assembly = assembleResolveResult(outcome, cwd);
@@ -1,3 +1,5 @@
1
+ import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
2
+
1
3
  /** Candidate fields used by the three target-selection row formats. */
2
4
  export interface CandidateRowData {
3
5
  readonly targetId: string;
@@ -25,3 +27,23 @@ export function formatCandidateRow(
25
27
  const rank = candidate.rank && candidate.rank > 0 ? candidate.rank : fallbackRank;
26
28
  return `${rank}. ${candidate.name} (${kind}) — ${candidate.file}:${candidate.line}:${candidate.character} [${candidate.targetId}]`;
27
29
  }
30
+
31
+ /** Separate display omissions from incomplete provider collection in candidate output. */
32
+ export function formatPartialCandidateDisclosure(
33
+ evidence: Pick<
34
+ EvidenceListMetadata,
35
+ "shownCount" | "totalCount" | "omittedCount" | "partialMessage"
36
+ >,
37
+ ): string | null {
38
+ if (evidence.totalCount !== null || !evidence.partialMessage) return null;
39
+ const { shownCount, omittedCount, partialMessage } = evidence;
40
+ const collectedCount = shownCount + (omittedCount ?? 0);
41
+ const noun = collectedCount === 1 ? "candidate" : "candidates";
42
+ const count =
43
+ omittedCount === null
44
+ ? `${shownCount} collected ${noun}.`
45
+ : omittedCount === 0
46
+ ? `all ${shownCount} collected ${noun}.`
47
+ : `${shownCount} of ${collectedCount} collected ${noun}; ${omittedCount} omitted.`;
48
+ return `Showing ${count}\nSearch completeness is unknown: ${partialMessage}`;
49
+ }
@@ -15,6 +15,8 @@ export interface ToolDisplaySectionInput<T> {
15
15
  totalCount?: number | null;
16
16
  omittedCount?: number | null;
17
17
  partialReason?: string | null;
18
+ /** Provider explanation for incomplete collection, when available. */
19
+ partialMessage?: string;
18
20
  maxItems?: number;
19
21
  }
20
22
 
@@ -42,6 +44,7 @@ export function createToolDisplaySection<T>(input: ToolDisplaySectionInput<T>):
42
44
  totalCount,
43
45
  omittedCount,
44
46
  partialReason: input.partialReason ?? null,
47
+ ...(input.partialMessage === undefined ? {} : { partialMessage: input.partialMessage }),
45
48
  };
46
49
  }
47
50
 
@@ -89,6 +92,9 @@ export function readToolDisplaySections(value: unknown): ToolDisplaySection[] {
89
92
  totalCount: record.totalCount,
90
93
  omittedCount: record.omittedCount,
91
94
  partialReason: record.partialReason,
95
+ ...(typeof record.partialMessage === "string"
96
+ ? { partialMessage: record.partialMessage }
97
+ : {}),
92
98
  },
93
99
  ];
94
100
  });
@@ -3,6 +3,18 @@ import type { EvidenceListMetadata } from "../../analysis/evidence.ts";
3
3
  import type { CodeIntelResult, ToolDisplaySection } from "../../types/index.ts";
4
4
  import { assembledNextQueries, assembleToolResult } from "./assembly.ts";
5
5
 
6
+ /** Keep the failure reason and suggest same-session recovery for a scoped symbol query. */
7
+ export function scopedSymbolFailureMessage(reason: string): string {
8
+ return [
9
+ reason,
10
+ "",
11
+ "Next steps:",
12
+ "- If a source file in this scope is known, use `code_resolve` with `target.file`. This can start a missing LSP route and return declaration handles.",
13
+ "- If the file is unknown, use `bash` to locate a source file in the requested scope first.",
14
+ "- Use a returned handle directly, or retry the scoped symbol query. Opening one file does not confirm that the full workspace index is ready.",
15
+ ].join("\n");
16
+ }
17
+
6
18
  /** Full failure or candidate-selection result for search-family tools. */
7
19
  export function searchErrorResult(
8
20
  content: string,
@@ -41,6 +41,8 @@ export interface ToolDisplaySection {
41
41
  totalCount: number | null;
42
42
  omittedCount: number | null;
43
43
  partialReason: string | null;
44
+ /** Provider explanation for incomplete collection, when available. */
45
+ partialMessage?: string;
44
46
  }
45
47
 
46
48
  // ── Anchored coordinate resolution metadata ───────────────────────────
@@ -0,0 +1,43 @@
1
+ import { stripVTControlCharacters } from "node:util";
2
+ import type { Theme } from "@earendil-works/pi-coding-agent";
3
+ import { type Component, Text } from "@earendil-works/pi-tui";
4
+
5
+ const MAX_DISCLOSURE_CHARACTERS = 4096;
6
+ const MAX_COLLAPSED_ROWS = 3;
7
+ const MAX_EXPANDED_ROWS = 10;
8
+
9
+ /** Limit candidate disclosure text without changing the full saved provider reason. */
10
+ export class BoundedCandidateDisclosure implements Component {
11
+ private readonly text: string;
12
+ private readonly sourceLimited: boolean;
13
+
14
+ constructor(
15
+ text: string,
16
+ private readonly expanded: boolean,
17
+ private readonly theme: Theme,
18
+ ) {
19
+ const plain = stripVTControlCharacters(text)
20
+ .replace(/\r\n?/g, "\n")
21
+ .replace(/\t/g, " ")
22
+ .replace(/[\p{Cc}\p{Bidi_Control}]/gu, (character) => (character === "\n" ? character : ""));
23
+ this.text = plain.slice(0, MAX_DISCLOSURE_CHARACTERS);
24
+ this.sourceLimited = plain.length > MAX_DISCLOSURE_CHARACTERS;
25
+ }
26
+
27
+ render(width: number): string[] {
28
+ const safeWidth = Math.max(1, width);
29
+ const rows = new Text(this.theme.fg("muted", this.text), 0, 0).render(safeWidth);
30
+ const maxRows = this.expanded ? MAX_EXPANDED_ROWS : MAX_COLLAPSED_ROWS;
31
+ if (!this.sourceLimited && rows.length <= maxRows) return rows;
32
+ const notice = this.expanded
33
+ ? "Provider reason limited for display."
34
+ : "Provider reason limited; expand for more.";
35
+ return [
36
+ ...rows.slice(0, maxRows),
37
+ ...new Text(this.theme.fg("dim", notice), 0, 0).render(safeWidth),
38
+ ];
39
+ }
40
+
41
+ /** Text and theme formatting are rebuilt for each render. */
42
+ invalidate(): void {}
43
+ }
@@ -1,13 +1,17 @@
1
1
  /** Shared human transcript renderer for target-candidate selections. */
2
2
  import type { Theme } from "@earendil-works/pi-coding-agent";
3
3
  import { type Component, Container, Spacer, Text } from "@earendil-works/pi-tui";
4
- import { formatCandidateRow } from "../../tool/result/candidate-row.ts";
4
+ import {
5
+ formatCandidateRow,
6
+ formatPartialCandidateDisclosure,
7
+ } from "../../tool/result/candidate-row.ts";
5
8
  import {
6
9
  MAX_TUI_DISPLAY_ITEMS,
7
10
  readToolDisplaySections,
8
11
  truncateDisplayText,
9
12
  } from "../../tool/result/display.ts";
10
13
  import type { ToolDisplaySection } from "../../tool/result/types.ts";
14
+ import { BoundedCandidateDisclosure } from "./candidate-disclosure.ts";
11
15
  import { createLegacyCandidateBody, readLegacyCandidateText } from "./candidate-legacy-body.ts";
12
16
  import {
13
17
  type EvidenceEntry,
@@ -144,6 +148,7 @@ function displayEvidence(display: ToolDisplaySection, key: CandidateSelectionKey
144
148
  ? unknownOmittedCount(display.omittedCount, Math.max(0, display.shownCount - shownCount))
145
149
  : Math.max(0, display.totalCount - shownCount),
146
150
  partialReason: display.partialReason,
151
+ partialMessage: display.partialMessage,
147
152
  };
148
153
  }
149
154
 
@@ -273,8 +278,15 @@ class CandidateSelectionComponent implements Component {
273
278
  invalidate(): void {}
274
279
 
275
280
  private renderCollapsed(container: Container, width: number): string[] {
276
- const summary = this.selection.evidence ? formatEvidenceEntry(this.selection.evidence) : null;
277
- if (summary) container.addChild(new Text(this.theme.fg("muted", summary), 0, 0));
281
+ const disclosure = this.selection.evidence
282
+ ? formatPartialCandidateDisclosure(this.selection.evidence)
283
+ : null;
284
+ if (disclosure) {
285
+ container.addChild(new BoundedCandidateDisclosure(disclosure, false, this.theme));
286
+ } else if (this.selection.evidence) {
287
+ const summary = formatEvidenceEntry(this.selection.evidence);
288
+ container.addChild(new Text(this.theme.fg("muted", summary), 0, 0));
289
+ }
278
290
  this.appendTruncation(container);
279
291
  return this.renderContainer(container, width);
280
292
  }
@@ -304,10 +316,17 @@ class CandidateSelectionComponent implements Component {
304
316
  private appendStructuredSelection(container: Container): void {
305
317
  container.addChild(new Spacer(1));
306
318
  const title = this.selection.display?.title ?? "Candidates";
307
- const bounds = this.selection.evidence ? formatSectionBounds(this.selection.evidence) : "";
319
+ const disclosure = this.selection.evidence
320
+ ? formatPartialCandidateDisclosure(this.selection.evidence)
321
+ : null;
322
+ const bounds =
323
+ !disclosure && this.selection.evidence ? formatSectionBounds(this.selection.evidence) : "";
308
324
  container.addChild(
309
325
  new Text(this.theme.fg("dim", `${title}${bounds ? ` (${bounds})` : ""}`), 0, 0),
310
326
  );
327
+ if (disclosure) {
328
+ container.addChild(new BoundedCandidateDisclosure(disclosure, true, this.theme));
329
+ }
311
330
  for (const row of this.selection.rows) {
312
331
  container.addChild(new Text(this.theme.fg("muted", row), 0, 0));
313
332
  }
@@ -344,7 +363,7 @@ function formatSectionBounds(entry: EvidenceEntry): string {
344
363
 
345
364
  function unknownOmittedCount(base: number | null, additional: number): number | null {
346
365
  const omitted = (base ?? 0) + additional;
347
- return omitted > 0 ? omitted : null;
366
+ return base !== null || omitted > 0 ? omitted : null;
348
367
  }
349
368
 
350
369
  function asRecord(value: unknown): Record<string, unknown> | null {
@@ -79,6 +79,8 @@ export interface EvidenceEntry {
79
79
  totalCount: number | null;
80
80
  omittedCount: number | null;
81
81
  partialReason: string | null;
82
+ /** Provider explanation for incomplete collection, when available. */
83
+ partialMessage?: string;
82
84
  invalidLocationCount?: number;
83
85
  }
84
86
 
@@ -116,6 +118,7 @@ function readEvidenceEntry(value: unknown): EvidenceEntry | null {
116
118
  totalCount,
117
119
  omittedCount,
118
120
  partialReason,
121
+ ...(typeof record.partialMessage === "string" ? { partialMessage: record.partialMessage } : {}),
119
122
  ...(invalidLocationCount === undefined ? {} : { invalidLocationCount }),
120
123
  };
121
124
  }