@mrclrchtr/supi-code-intelligence 9.1.1 → 10.0.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 (94) hide show
  1. package/README.md +24 -8
  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/node_modules/@mrclrchtr/supi-code-runtime/package.json +1 -1
  10. package/node_modules/@mrclrchtr/supi-tree-sitter/node_modules/@mrclrchtr/supi-core/package.json +1 -1
  11. package/node_modules/@mrclrchtr/supi-tree-sitter/package.json +3 -3
  12. package/node_modules/ignore/LICENSE-MIT +21 -0
  13. package/node_modules/ignore/README.md +501 -0
  14. package/node_modules/ignore/index.d.ts +81 -0
  15. package/node_modules/ignore/index.js +1566 -0
  16. package/node_modules/ignore/legacy.js +1346 -0
  17. package/node_modules/ignore/package.json +93 -0
  18. package/node_modules/smol-toml/LICENSE +24 -0
  19. package/node_modules/smol-toml/README.md +605 -0
  20. package/node_modules/smol-toml/dist/date.d.ts +41 -0
  21. package/node_modules/smol-toml/dist/date.js +156 -0
  22. package/node_modules/smol-toml/dist/error.d.ts +37 -0
  23. package/node_modules/smol-toml/dist/error.js +67 -0
  24. package/node_modules/smol-toml/dist/extract.js +293 -0
  25. package/node_modules/smol-toml/dist/index.cjs +771 -0
  26. package/node_modules/smol-toml/dist/index.d.ts +44 -0
  27. package/node_modules/smol-toml/dist/index.js +34 -0
  28. package/node_modules/smol-toml/dist/parse.d.ts +73 -0
  29. package/node_modules/smol-toml/dist/parse.js +164 -0
  30. package/node_modules/smol-toml/dist/primitive.js +151 -0
  31. package/node_modules/smol-toml/dist/stringify.d.ts +32 -0
  32. package/node_modules/smol-toml/dist/stringify.js +219 -0
  33. package/node_modules/smol-toml/dist/struct.js +156 -0
  34. package/node_modules/smol-toml/dist/util.d.ts +43 -0
  35. package/node_modules/smol-toml/dist/util.js +57 -0
  36. package/node_modules/smol-toml/package.json +68 -0
  37. package/package.json +9 -5
  38. package/src/analysis/evidence.ts +2 -0
  39. package/src/analysis/target/symbol.ts +19 -8
  40. package/src/analysis/target/types.ts +2 -0
  41. package/src/analysis/workspace/exclusions.ts +35 -0
  42. package/src/analysis/workspace/git.ts +130 -0
  43. package/src/analysis/workspace/go-parser.ts +330 -0
  44. package/src/analysis/workspace/go.ts +154 -0
  45. package/src/analysis/workspace/index.ts +28 -0
  46. package/src/analysis/workspace/inventory.ts +316 -0
  47. package/src/analysis/workspace/membership.ts +223 -0
  48. package/src/analysis/workspace/metadata-types.ts +56 -0
  49. package/src/analysis/workspace/metadata-utils.ts +60 -0
  50. package/src/analysis/workspace/metadata.ts +148 -0
  51. package/src/analysis/workspace/node.ts +214 -0
  52. package/src/analysis/workspace/observe.ts +161 -0
  53. package/src/analysis/workspace/paths.ts +65 -0
  54. package/src/analysis/workspace/python.ts +158 -0
  55. package/src/analysis/workspace/relationships.ts +87 -0
  56. package/src/analysis/workspace/rust.ts +238 -0
  57. package/src/analysis/workspace/safe-path.ts +20 -0
  58. package/src/analysis/workspace/types.ts +245 -0
  59. package/src/app/app.ts +1 -0
  60. package/src/config.ts +4 -4
  61. package/src/extension.ts +16 -49
  62. package/src/overview/budget.ts +23 -0
  63. package/src/overview/collect.ts +22 -0
  64. package/src/session/orientation/workspace-context.ts +166 -0
  65. package/src/session/orientation-types.ts +8 -1
  66. package/src/session/orientation-workflow.ts +16 -3
  67. package/src/session/session.ts +2 -3
  68. package/src/session/target-workflow.ts +2 -0
  69. package/src/tool/code_find/execute.ts +1 -1
  70. package/src/tool/code_find/result.ts +10 -3
  71. package/src/tool/code_graph/result.ts +7 -2
  72. package/src/tool/code_orientation/execute.ts +8 -1
  73. package/src/tool/code_orientation/markdown.ts +58 -8
  74. package/src/tool/code_orientation/result.ts +17 -5
  75. package/src/tool/code_orientation/workspace-format.ts +74 -0
  76. package/src/tool/code_orientation/workspace-instructions.ts +105 -0
  77. package/src/tool/code_orientation/workspace-output.ts +118 -0
  78. package/src/tool/code_orientation/workspace-projects.ts +177 -0
  79. package/src/tool/code_orientation/workspace-sections.ts +217 -0
  80. package/src/tool/code_resolve/execute.ts +1 -1
  81. package/src/tool/code_resolve/markdown.ts +4 -1
  82. package/src/tool/code_resolve/result.ts +14 -2
  83. package/src/tool/register.ts +2 -0
  84. package/src/tool/result/candidate-row.ts +22 -0
  85. package/src/tool/result/display.ts +6 -0
  86. package/src/tool/result/errors.ts +12 -0
  87. package/src/tool/result/types.ts +2 -0
  88. package/src/types/execution.ts +2 -0
  89. package/src/ui/tui/candidate-disclosure.ts +43 -0
  90. package/src/ui/tui/candidate-selection.ts +24 -5
  91. package/src/ui/tui/common.ts +3 -0
  92. package/src/overview/overview-data.ts +0 -154
  93. package/src/overview/overview.ts +0 -91
  94. package/src/overview/types.ts +0 -23
@@ -0,0 +1,245 @@
1
+ /**
2
+ * Shared, presentation-neutral workspace observation types.
3
+ *
4
+ * These facts come from bounded filesystem inventory and explicitly parsed
5
+ * project metadata. They do not describe runtime architecture, source roots,
6
+ * installed dependency resolution, or inferred project roles.
7
+ */
8
+
9
+ /** How the inventory selected files. */
10
+ export type InventorySource = "git" | "filesystem";
11
+
12
+ /** Inventory entries are regular files or symbolic links. Link targets are not followed. */
13
+ export type InventoryEntryKind = "file" | "symlink";
14
+
15
+ /** One workspace-relative inventory path. */
16
+ export interface InventoryEntry {
17
+ /** Root-relative POSIX path. */
18
+ readonly path: string;
19
+ /** Filesystem entry kind observed without following symbolic links. */
20
+ readonly kind: InventoryEntryKind;
21
+ }
22
+
23
+ /** Lower-level reason that stopped inventory traversal. */
24
+ export type InventoryStopReason = "complete" | "entry-limit" | "deadline";
25
+
26
+ /** Declared collection bounds for one observation. */
27
+ export interface CollectionLimits {
28
+ /** Maximum number of inventory entries that collection may retain. */
29
+ readonly maxEntries: number;
30
+ /** Absolute Unix-epoch deadline, or null when the caller set no deadline. */
31
+ readonly deadline: number | null;
32
+ }
33
+
34
+ /** Failure or limitation observed during collection. */
35
+ export interface WorkspaceObservationError {
36
+ /** Collection stage that produced the error. */
37
+ readonly stage: "inventory" | "metadata";
38
+ /** Root-relative path, or null when no single path applies. */
39
+ readonly path: string | null;
40
+ /** Human-readable reason. */
41
+ readonly reason: string;
42
+ }
43
+
44
+ /** Honest completeness state for one observation. */
45
+ export interface WorkspaceCollection {
46
+ /** Complete only when inventory and all eligible metadata were read without limits or errors. */
47
+ readonly status: "complete" | "partial";
48
+ /** Lower-level inventory stop reason. */
49
+ readonly stopReason: InventoryStopReason;
50
+ /** Root-relative explicit directory visited first, or null for ordinary traversal. */
51
+ readonly prioritizedDirectory: string | null;
52
+ /** Bounds applied to this observation. */
53
+ readonly limits: CollectionLimits;
54
+ /** Inventory or metadata errors that affected completeness. */
55
+ readonly errors: readonly WorkspaceObservationError[];
56
+ }
57
+
58
+ /** Explicit inclusion policy captured by one observation. */
59
+ export interface WorkspaceInclusionPolicy {
60
+ /** How the inventory selected files. */
61
+ readonly source: InventorySource;
62
+ /** Caller-supplied Gitignore-style exclusion patterns. */
63
+ readonly exclude: readonly string[];
64
+ /** Whether Git-ignored untracked paths were included for an explicit focus. */
65
+ readonly includeIgnored: boolean;
66
+ /** Symbolic links are returned as entries, never traversed or read through. */
67
+ readonly symlinks: "not-followed";
68
+ /** No directory name is excluded by convention or inferred role. */
69
+ readonly directoryNamesExcluded: false;
70
+ }
71
+
72
+ /** Parsed metadata file kinds supported by the shared observation. */
73
+ export type MetadataDocumentKind =
74
+ | "package-json"
75
+ | "pnpm-workspace"
76
+ | "pyproject"
77
+ | "cargo"
78
+ | "go-mod"
79
+ | "go-work";
80
+
81
+ /** Metadata read outcome retained for provenance. */
82
+ export interface MetadataDocument {
83
+ /** Root-relative document path. */
84
+ readonly path: string;
85
+ readonly kind: MetadataDocumentKind;
86
+ /** Parsed documents can establish declarations; skipped documents are symlinks or non-files. */
87
+ readonly status: "parsed" | "failed" | "skipped";
88
+ /** Failure or skip reason; null for parsed documents. */
89
+ readonly reason: string | null;
90
+ }
91
+
92
+ /** Kind of unsupported, dynamic, inherited, or malformed metadata fact. */
93
+ export type MetadataIssueKind =
94
+ | "malformed"
95
+ | "unreadable"
96
+ | "unsupported"
97
+ | "dynamic"
98
+ | "inherited"
99
+ | "symlink"
100
+ | "unresolved";
101
+
102
+ /** One disclosed metadata limitation with source provenance. */
103
+ export interface MetadataIssue {
104
+ /** Root-relative document path. */
105
+ readonly path: string;
106
+ /** Exact field or directive path, or null for a document-wide issue. */
107
+ readonly field: string | null;
108
+ readonly kind: MetadataIssueKind;
109
+ /** Why the declaration was not interpreted. */
110
+ readonly reason: string;
111
+ }
112
+
113
+ /** Metadata documents and limitations from one observation. */
114
+ export interface WorkspaceMetadataObservation {
115
+ readonly documents: readonly MetadataDocument[];
116
+ readonly issues: readonly MetadataIssue[];
117
+ }
118
+
119
+ /** Native project declaration kinds supported by this collector. */
120
+ export type ProjectKind = "node-package" | "python-project" | "rust-package" | "go-module";
121
+
122
+ /** How one configuration explicitly established project membership. */
123
+ export interface ProjectMembership {
124
+ /** Native workspace declaration family. */
125
+ readonly kind: "node-workspace" | "cargo-workspace" | "go-work";
126
+ /** Root-relative configuration or manifest path that declared membership. */
127
+ readonly manifestPath: string;
128
+ /** Exact declaring field or directive. */
129
+ readonly field: string;
130
+ /** Membership pattern or path exactly as declared. */
131
+ readonly value: string;
132
+ }
133
+
134
+ /** A parsed workspace declaration, including unmatched patterns and exclusions. */
135
+ export interface WorkspaceDeclaration {
136
+ readonly kind: ProjectMembership["kind"];
137
+ readonly manifestPath: string;
138
+ readonly directory: string;
139
+ /** Native field or directive for the membership values. */
140
+ readonly field: string;
141
+ readonly patterns: readonly string[];
142
+ /** Native exclusion field, or null when there is no separate exclusion field. */
143
+ readonly excludeField: string | null;
144
+ readonly excludes: readonly string[];
145
+ }
146
+
147
+ /** One path explicitly declared by project metadata. No field has entrypoint precedence. */
148
+ export interface DeclaredPath {
149
+ /** Exact source field, including nested keys such as `exports["."]`. */
150
+ readonly field: string;
151
+ /** Path text exactly as declared. */
152
+ readonly path: string;
153
+ }
154
+
155
+ /**
156
+ * One dependency-family declaration.
157
+ *
158
+ * `field` keeps separate categories separate. `name` is the declared
159
+ * dependency key or parsed requirement name. `value` is the exact parsed
160
+ * declaration value and may be a string, array, or table.
161
+ */
162
+ export interface DeclaredDependency {
163
+ readonly field: string;
164
+ readonly name: string;
165
+ readonly value: unknown;
166
+ }
167
+
168
+ /** One explicitly declared local project relationship. */
169
+ export interface ProjectRelationship {
170
+ /** Stable source project ID (its root-relative manifest path). */
171
+ readonly from: string;
172
+ /** Stable target project ID (its root-relative manifest path). */
173
+ readonly to: string;
174
+ /** Root-relative manifest that declared the relationship. */
175
+ readonly manifestPath: string;
176
+ /** Exact dependency field that declared the relationship. */
177
+ readonly field: string;
178
+ /** Exact declared dependency value. */
179
+ readonly value: unknown;
180
+ }
181
+
182
+ /** One parsed project declaration with retained native provenance. */
183
+ export interface ProjectDeclaration {
184
+ /** Stable identity: root-relative manifest path. Equal to `manifestPath`. */
185
+ readonly id: string;
186
+ /** Root-relative manifest path. */
187
+ readonly manifestPath: string;
188
+ readonly kind: ProjectKind;
189
+ /** Root-relative project directory; `.` for the observation root. */
190
+ readonly directory: string;
191
+ /** Native identity value, or null when the manifest does not declare a usable value. */
192
+ readonly name: string | null;
193
+ /** Exact field that declared `name`, or null. */
194
+ readonly nameField: string | null;
195
+ /** One-line description when explicitly declared as a string. */
196
+ readonly description: string | null;
197
+ /** Exact field that declared `description`, or null. */
198
+ readonly descriptionField: string | null;
199
+ /** Explicit workspace memberships; this is not inferred from directory adjacency. */
200
+ readonly memberships: readonly ProjectMembership[];
201
+ /** Explicitly declared paths with their source fields. */
202
+ readonly declaredPaths: readonly DeclaredPath[];
203
+ /** Explicit dependency declarations, grouped by their exact source fields. */
204
+ readonly dependencies: readonly DeclaredDependency[];
205
+ }
206
+
207
+ /** Inventory and its source policy. */
208
+ export interface WorkspaceInventory {
209
+ readonly source: InventorySource;
210
+ readonly entries: readonly InventoryEntry[];
211
+ }
212
+
213
+ /** Immutable result of one bounded workspace observation. */
214
+ export interface WorkspaceObservation {
215
+ /** Absolute requested working directory. It is never widened to an ancestor. */
216
+ readonly root: string;
217
+ readonly inventory: WorkspaceInventory;
218
+ readonly inclusion: WorkspaceInclusionPolicy;
219
+ readonly collection: WorkspaceCollection;
220
+ readonly metadata: WorkspaceMetadataObservation;
221
+ readonly projects: readonly ProjectDeclaration[];
222
+ readonly workspaces: readonly WorkspaceDeclaration[];
223
+ /** Declared local relationships between uniquely identified projects. */
224
+ readonly relationships: readonly ProjectRelationship[];
225
+ }
226
+
227
+ /** Bounded collection controls for `observeWorkspace`. */
228
+ export interface ObserveWorkspaceOptions {
229
+ /** Additional Gitignore-style exclusions, matched relative to the requested root. */
230
+ readonly exclude?: readonly string[];
231
+ /**
232
+ * Include Git-ignored untracked paths. Use this for an explicit directory
233
+ * focus whose ignored contents must remain inspectable.
234
+ */
235
+ readonly includeIgnored?: boolean;
236
+ /** Maximum retained inventory entries. Defaults to 10,000. */
237
+ readonly maxEntries?: number;
238
+ /** Explicit in-root directory to collect before spending the inventory budget elsewhere. */
239
+ readonly prioritizeDirectory?: string;
240
+ /**
241
+ * Caller cancellation and absolute deadline. Cancellation throws the abort
242
+ * reason; a reached deadline returns an honest partial observation.
243
+ */
244
+ readonly control?: import("@mrclrchtr/supi-code-runtime/api").CodeRequestControl;
245
+ }
package/src/app/app.ts CHANGED
@@ -115,6 +115,7 @@ export function createCodeIntelligenceApp(pi: ExtensionAPI): CodeIntelligenceApp
115
115
  session.reconstructInstructionState(
116
116
  branch as Parameters<typeof session.reconstructInstructionState>[0],
117
117
  );
118
+ session.restoreOverviewInjection(false);
118
119
  for (const entry of branch as Array<{ type?: string; customType?: string }>) {
119
120
  if (entry.type === "custom_message" && entry.customType === OVERVIEW_CUSTOM_TYPE) {
120
121
  session.restoreOverviewInjection();
package/src/config.ts CHANGED
@@ -18,9 +18,9 @@ const CODE_INTELLIGENCE_SECTION = "code-intelligence";
18
18
  export interface CodeIntelligenceConfig extends Record<string, unknown> {
19
19
  /** Ordered directory-local instruction file names to surface during directory orientation. */
20
20
  instructionFileNames: string[];
21
- /** Inject the hidden first-turn workspace architecture overview when enabled. */
21
+ /** Inject the hidden first-turn workspace overview when enabled. */
22
22
  overviewEnabled: boolean;
23
- /** Gitignore-style paths excluded from automatic LSP and broad AST work. */
23
+ /** Gitignore-style paths excluded from automatic navigation, LSP, and broad AST work. */
24
24
  exclude: string[];
25
25
  }
26
26
 
@@ -84,14 +84,14 @@ export function registerCodeIntelligenceSettings(pi: ExtensionAPI, homeDir?: str
84
84
  kind: "boolean" as const,
85
85
  key: "overviewEnabled",
86
86
  label: "Overview Enabled",
87
- description: "Inject the hidden first-turn workspace architecture overview",
87
+ description: "Inject the hidden first-turn workspace overview",
88
88
  },
89
89
  {
90
90
  kind: "stringList" as const,
91
91
  key: "exclude",
92
92
  label: "Automatic Exclusions",
93
93
  description:
94
- "Gitignore-style patterns for automatic LSP and broad AST work. Edit the project or global config, then reload or restart Pi; exact requests stay available.",
94
+ "Gitignore-style patterns for automatic navigation, LSP, and broad AST work. Reload or restart Pi for runtime scans; exact requests stay available.",
95
95
  },
96
96
  ],
97
97
  ...(homeDir ? { homeDir } : {}),
package/src/extension.ts CHANGED
@@ -1,20 +1,11 @@
1
1
  // Code Intelligence extension entry point — registers the focused code-intelligence tools,
2
2
  // shared provider lifecycle, settings, UI, and the unified /supi-ci-status command.
3
3
 
4
- import type {
5
- BeforeAgentStartEventResult,
6
- ExtensionAPI,
7
- ExtensionContext,
8
- } from "@earendil-works/pi-coding-agent";
9
- import {
10
- recordDebugEvent,
11
- truncateDebugIdentity as truncateIdentity,
12
- } from "@mrclrchtr/supi-core/debug";
13
- import { buildArchitectureModel } from "./analysis/architecture/discovery.ts";
4
+ import type { BeforeAgentStartEventResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
14
5
  import { createCodeIntelligenceApp } from "./app/app.ts";
15
6
  import { registerCodeIntelligenceSettings, resolveOverviewEnabled } from "./config.ts";
16
- import { estimateTokens, OVERVIEW_TOKEN_BUDGET, renderOverview } from "./overview/overview.ts";
17
- import { buildOverviewData } from "./overview/overview-data.ts";
7
+ import { reportWorkspaceBudget } from "./overview/budget.ts";
8
+ import { collectOverview } from "./overview/collect.ts";
18
9
  import type { WorkspaceCodeIntelligenceSession } from "./session/session.ts";
19
10
  import { registerLspSessionLifecycle } from "./substrate/lsp/lifecycle.ts";
20
11
  import { registerWorkspaceRecoveryHandler } from "./substrate/lsp/recovery.ts";
@@ -26,27 +17,6 @@ import { registerCiStatusCommand } from "./ui/status-command.ts";
26
17
 
27
18
  const OVERVIEW_CUSTOM_TYPE = "code-intelligence-overview";
28
19
 
29
- /**
30
- * Warn about an over-budget overview without capping it.
31
- *
32
- * The injected overview is never truncated; the debug record exists in every
33
- * mode, and the visible notification needs a UI.
34
- */
35
- function warnOverviewBudget(ctx: ExtensionContext, estimatedTokens: number): void {
36
- const message = `Code Intelligence overview exceeds soft token budget: ${estimatedTokens} tokens (budget: ${OVERVIEW_TOKEN_BUDGET})`;
37
- recordDebugEvent({
38
- source: "code-intelligence",
39
- level: "warning",
40
- category: "overview",
41
- message,
42
- cwd: truncateIdentity(ctx.cwd),
43
- data: { estimatedTokens, budget: OVERVIEW_TOKEN_BUDGET },
44
- });
45
- if (ctx.hasUI) {
46
- ctx.ui.notify(message, "warning");
47
- }
48
- }
49
-
50
20
  /** Register the full interactive Code Intelligence profile. */
51
21
  export default function codeIntelligenceExtension(
52
22
  pi: ExtensionAPI,
@@ -129,23 +99,20 @@ export default function codeIntelligenceExtension(
129
99
  }
130
100
  if (!session.claimOverviewInjection()) return;
131
101
 
132
- const model = await buildArchitectureModel(ctx.cwd);
133
- if (model.modules.length === 0) return;
134
-
135
- const data = buildOverviewData(model);
136
- if (!data) return;
137
-
138
- const overview = renderOverview(data);
139
- if (!overview) return;
140
-
141
- const estimatedTokens = estimateTokens(overview);
142
- if (estimatedTokens > OVERVIEW_TOKEN_BUDGET) {
143
- warnOverviewBudget(ctx, estimatedTokens);
102
+ try {
103
+ const overview = await collectOverview(ctx.cwd, ctx.isProjectTrusted(), homeDir);
104
+ if (!overview) {
105
+ session.restoreOverviewInjection(false);
106
+ return;
107
+ }
108
+ reportWorkspaceBudget(ctx, overview.warning);
109
+ return {
110
+ message: { customType: OVERVIEW_CUSTOM_TYPE, display: false, content: overview.content },
111
+ };
112
+ } catch (error) {
113
+ session.restoreOverviewInjection(false);
114
+ throw error;
144
115
  }
145
-
146
- return {
147
- message: { customType: OVERVIEW_CUSTOM_TYPE, display: false, content: overview },
148
- };
149
116
  },
150
117
  );
151
118
  }
@@ -0,0 +1,23 @@
1
+ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
2
+ import { recordDebugEvent, truncateDebugIdentity } from "@mrclrchtr/supi-core/debug";
3
+ import type { WorkspaceBudgetWarning } from "../tool/code_orientation/workspace-output.ts";
4
+
5
+ /** Keep soft-limit notices out of model content in every execution mode. */
6
+ export function reportWorkspaceBudget(
7
+ ctx: ExtensionContext,
8
+ warning: WorkspaceBudgetWarning | undefined,
9
+ operationId?: string,
10
+ ): void {
11
+ if (!warning) return;
12
+ const message = `Code Intelligence ${warning.surface} exceeds soft token budget: ${warning.estimatedTokens} estimated tokens (budget: ${warning.threshold})`;
13
+ recordDebugEvent({
14
+ source: "code-intelligence",
15
+ level: "warning",
16
+ category: warning.surface,
17
+ cwd: truncateDebugIdentity(ctx.cwd),
18
+ message,
19
+ operationId,
20
+ data: { estimatedTokens: warning.estimatedTokens, budget: warning.threshold },
21
+ });
22
+ if (ctx.hasUI) ctx.ui.notify(message, "warning");
23
+ }
@@ -0,0 +1,22 @@
1
+ import { statSync } from "node:fs";
2
+ import { loadAutomaticExclusionPatterns } from "@mrclrchtr/supi-core/config";
3
+ import { observeWorkspace } from "../analysis/workspace/observe.ts";
4
+ import { workspaceOrientationData } from "../session/orientation/workspace-context.ts";
5
+ import { prepareWorkspaceOutput } from "../tool/code_orientation/workspace-output.ts";
6
+
7
+ /** Capture a first-turn map without requiring any project metadata or provider. */
8
+ export async function collectOverview(cwd: string, projectTrusted: boolean, homeDir?: string) {
9
+ try {
10
+ if (!statSync(cwd).isDirectory()) return null;
11
+ } catch {
12
+ return null;
13
+ }
14
+ const exclude = loadAutomaticExclusionPatterns(cwd, { projectTrusted, homeDir });
15
+ const observation = await observeWorkspace(cwd, {
16
+ exclude,
17
+ control: { deadline: Date.now() + 10_000 },
18
+ });
19
+ return prepareWorkspaceOutput(
20
+ workspaceOrientationData({ observation, cwd, focus: null, maxResults: 10, overview: true }),
21
+ );
22
+ }
@@ -0,0 +1,166 @@
1
+ import { existsSync, lstatSync, statSync } from "node:fs";
2
+ import * as path from "node:path";
3
+ import { loadAutomaticExclusionPatterns } from "@mrclrchtr/supi-core/config";
4
+ import ignore from "ignore";
5
+ import { isGitIgnoredDirectory } from "../../analysis/workspace/git.ts";
6
+ import { observeWorkspace } from "../../analysis/workspace/observe.ts";
7
+ import { assertUnlinkedPath } from "../../analysis/workspace/safe-path.ts";
8
+ import type { WorkspaceObservation } from "../../analysis/workspace/types.ts";
9
+ import type { OrientationResultData, OrientationWorkflowInput } from "../orientation-types.ts";
10
+ import type { WorkflowControl } from "../workflow-control.ts";
11
+
12
+ /** Captured facts for workspace and directory presentation; no provider or live state. */
13
+ export interface WorkspaceOrientationFacts {
14
+ readonly observation: WorkspaceObservation;
15
+ readonly cwd: string;
16
+ /** Absolute explicit focus, or null for the session working directory. */
17
+ readonly focus: string | null;
18
+ readonly maxResults: number;
19
+ readonly overview?: boolean;
20
+ }
21
+
22
+ /** Select the new navigation path without changing file or symbol-focused workflows. */
23
+ export async function orientWorkspaceContext(
24
+ request: OrientationWorkflowInput,
25
+ options: { cwd: string; homeDir?: string; projectTrusted: boolean },
26
+ control?: WorkflowControl,
27
+ ): Promise<
28
+ | { kind: "completed"; data: OrientationResultData; directory: string | null }
29
+ | { kind: "invalid-input"; message: string }
30
+ | null
31
+ > {
32
+ const selected = directoryFocus(request, options.cwd);
33
+ if (!selected || selected.kind === "invalid-input") return selected;
34
+ let focus = selected.path;
35
+ const exclude = loadAutomaticExclusionPatterns(options.cwd, options);
36
+ if (focus) await assertFocusPath(options.cwd, focus);
37
+ let observation = await initialObservation(options.cwd, focus, exclude, control);
38
+ if (request.focus && "module" in request.focus) {
39
+ const selected = resolveModule(observation, request.focus.module);
40
+ if (selected.kind === "invalid-input") return selected;
41
+ focus = selected.path;
42
+ }
43
+ if (focus) observation = await focusObservation(observation, focus, exclude, control);
44
+ return {
45
+ kind: "completed",
46
+ directory: focus,
47
+ data: workspaceOrientationData({
48
+ observation,
49
+ cwd: options.cwd,
50
+ focus,
51
+ maxResults: request.maxResults ?? 10,
52
+ }),
53
+ };
54
+ }
55
+
56
+ async function initialObservation(
57
+ cwd: string,
58
+ focus: string | null,
59
+ exclude: readonly string[],
60
+ control?: WorkflowControl,
61
+ ): Promise<WorkspaceObservation> {
62
+ const root = focus && !within(cwd, focus) ? focus : cwd;
63
+ const separate = root !== cwd;
64
+ return observeWorkspace(root, {
65
+ exclude: separate ? [] : exclude,
66
+ control,
67
+ prioritizeDirectory: !separate && focus ? focus : undefined,
68
+ includeIgnored: separate && (await isGitIgnoredDirectory(root, control)),
69
+ });
70
+ }
71
+
72
+ async function focusObservation(
73
+ observation: WorkspaceObservation,
74
+ focus: string,
75
+ exclude: readonly string[],
76
+ control?: WorkflowControl,
77
+ ): Promise<WorkspaceObservation> {
78
+ const inside = within(observation.root, focus);
79
+ const relative = path.relative(observation.root, focus).replaceAll(path.sep, "/");
80
+ await assertFocusPath(observation.root, focus);
81
+ const excluded =
82
+ inside &&
83
+ relative !== "" &&
84
+ ignore()
85
+ .add([...exclude])
86
+ .ignores(`${relative}/`);
87
+ const ignored = await isGitIgnoredDirectory(focus, control);
88
+ if (!inside || excluded || (ignored && !observation.inclusion.includeIgnored))
89
+ return observeWorkspace(focus, { includeIgnored: excluded || ignored, control });
90
+ return observation;
91
+ }
92
+
93
+ /** Check new path components from the shared ancestor, including external focuses. */
94
+ async function assertFocusPath(cwd: string, focus: string): Promise<void> {
95
+ let common = path.resolve(cwd);
96
+ while (!within(common, focus)) {
97
+ const parent = path.dirname(common);
98
+ if (parent === common) {
99
+ common = path.parse(focus).root;
100
+ break;
101
+ }
102
+ common = parent;
103
+ }
104
+ await assertUnlinkedPath(common, path.relative(common, focus).replaceAll(path.sep, "/"), true);
105
+ }
106
+
107
+ function directoryFocus(
108
+ request: OrientationWorkflowInput,
109
+ cwd: string,
110
+ ): { kind: "directory"; path: string | null } | { kind: "invalid-input"; message: string } | null {
111
+ if (!request.focus || "module" in request.focus) return { kind: "directory", path: null };
112
+ if ("target" in request.focus) return null;
113
+ const focus = path.resolve(cwd, request.focus.path.replace(/^@/, ""));
114
+ if (!existsSync(focus) || !statSync(focus).isDirectory()) return null;
115
+ if (lstatSync(focus).isSymbolicLink())
116
+ return { kind: "invalid-input", message: "Symbolic-link directory focus is not followed." };
117
+ return { kind: "directory", path: focus };
118
+ }
119
+
120
+ function resolveModule(
121
+ observation: WorkspaceObservation,
122
+ name: string,
123
+ ): { kind: "resolved"; path: string } | { kind: "invalid-input"; message: string } {
124
+ const matches = observation.projects.filter(
125
+ (project) =>
126
+ project.name === name ||
127
+ (project.kind === "node-package" && project.name?.replace(/^@[^/]+\//, "") === name),
128
+ );
129
+ if (matches.length === 1)
130
+ return { kind: "resolved", path: path.resolve(observation.root, matches[0].directory) };
131
+ return {
132
+ kind: "invalid-input",
133
+ message:
134
+ matches.length === 0
135
+ ? `Module focus not found: ${name}.`
136
+ : `Module focus is ambiguous: ${matches.map((project) => `${project.name} (${project.manifestPath})`).join(", ")}.`,
137
+ };
138
+ }
139
+
140
+ /** Create the immutable workflow envelope; result assembly owns display selection. */
141
+ export function workspaceOrientationData(
142
+ workspace: WorkspaceOrientationFacts,
143
+ ): OrientationResultData {
144
+ return {
145
+ title: "Workspace Orientation",
146
+ notes: [],
147
+ sections: [],
148
+ confidence: "unavailable",
149
+ focusTarget: workspace.focus,
150
+ requestedSections: [],
151
+ renderedSections: [],
152
+ omittedCount: 0,
153
+ nextQueries: [],
154
+ readNext: [],
155
+ workspace,
156
+ };
157
+ }
158
+
159
+ /** Test containment without treating a common path prefix as ancestry. */
160
+ export function within(root: string, target: string): boolean {
161
+ const relative = path.relative(root, target);
162
+ return (
163
+ relative === "" ||
164
+ (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))
165
+ );
166
+ }
@@ -58,7 +58,12 @@ export type OrientationItem =
58
58
  readonly language: string | null;
59
59
  readonly lines: readonly string[];
60
60
  }
61
- | { readonly kind: "blank" };
61
+ | { readonly kind: "blank" }
62
+ | {
63
+ readonly kind: "table";
64
+ readonly headers: readonly string[];
65
+ readonly rows: readonly (readonly string[])[];
66
+ };
62
67
 
63
68
  /** Source that established one Orientation section. */
64
69
  export interface OrientationProvenance {
@@ -114,6 +119,8 @@ export interface OrientationResultData {
114
119
  readonly nextQueries: readonly string[];
115
120
  readonly readNext: readonly ReadNextItem[];
116
121
  readonly instructions?: InstructionFilesMetadata;
122
+ /** Captured generic workspace facts; absent for the unchanged file and symbol paths. */
123
+ readonly workspace?: import("./orientation/workspace-context.ts").WorkspaceOrientationFacts;
117
124
  readonly target?: Readonly<TargetStoreEntry>;
118
125
  }
119
126
 
@@ -15,6 +15,7 @@ import { loadCodeIntelligenceConfig } from "../config.ts";
15
15
  import type { CapabilityAdapter } from "./capability-adapter.ts";
16
16
  import { parseOrientationWorkflowInput } from "./input/workflows.ts";
17
17
  import { executeOrientation } from "./orientation/collect.ts";
18
+ import { orientWorkspaceContext } from "./orientation/workspace-context.ts";
18
19
  import type {
19
20
  OrientationFocusInput,
20
21
  OrientationItem,
@@ -31,7 +32,6 @@ export interface OrientationWorkflowDeps extends TargetWorkflowDeps {
31
32
  readonly capability: CapabilityAdapter;
32
33
  readonly nativeInstructionPaths: Set<string>;
33
34
  readonly surfacedInstructionDirs: Set<string>;
34
- readonly markInstructionDirsSurfaced: (directories: string[]) => void;
35
35
  /** Whether the project is trusted — controls instruction-file discovery. */
36
36
  readonly projectTrusted: boolean;
37
37
  /** Global config home for hermetic config reads; undefined uses os.homedir(). */
@@ -47,12 +47,24 @@ export async function runOrientationWorkflow(
47
47
  const parsed = parseOrientationWorkflowInput(input);
48
48
  if (parsed.kind === "invalid-input") return parsed;
49
49
  const request = parsed.value;
50
- throwIfAborted(control);
50
+ control?.signal?.throwIfAborted();
51
51
  reportProgress(control, {
52
52
  intent: "orientation",
53
53
  phase: "model",
54
54
  message: "Building workspace orientation model",
55
55
  });
56
+ const navigation = await orientWorkspaceContext(request, deps, control);
57
+ if (navigation) {
58
+ if (navigation.kind === "invalid-input") return navigation;
59
+ control?.signal?.throwIfAborted();
60
+ return {
61
+ kind: "completed",
62
+ data: navigation.directory
63
+ ? addInstructionFiles(navigation.data, navigation.directory, deps)
64
+ : navigation.data,
65
+ };
66
+ }
67
+ throwIfAborted(control);
56
68
  const model = await buildArchitectureModel(deps.cwd);
57
69
  const provider = deps.capability.getProvider(deps.cwd);
58
70
  const lspRuntime = deps.capability.getLspRuntimeState(deps.cwd);
@@ -135,6 +147,7 @@ async function orientTarget(options: {
135
147
  totalCount: target.totalCount,
136
148
  omittedCount: target.omittedCount,
137
149
  partialReason: target.partialReason,
150
+ partialMessage: target.partialMessage,
138
151
  }
139
152
  : {
140
153
  kind: "disambiguation",
@@ -142,6 +155,7 @@ async function orientTarget(options: {
142
155
  totalCount: target.totalCount,
143
156
  omittedCount: target.omittedCount,
144
157
  partialReason: target.partialReason,
158
+ partialMessage: target.partialMessage,
145
159
  };
146
160
  }
147
161
  if (target.kind !== "resolved") return target;
@@ -226,7 +240,6 @@ function addInstructionFiles(
226
240
  });
227
241
  const collected = collectInstructionFiles(matches);
228
242
  if (!collected) return result;
229
- deps.markInstructionDirsSurfaced(collected.metadata.files.map((file) => file.directory));
230
243
  const items: OrientationItem[] = [];
231
244
  for (const file of collected.files) {
232
245
  items.push(