ushman-equiv 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/AGENTS.md +81 -0
  2. package/LICENSE.md +21 -0
  3. package/README.md +201 -0
  4. package/bin/ushman-equiv +19 -0
  5. package/dist/analysis-context.d.ts +102 -0
  6. package/dist/analysis-context.d.ts.map +1 -0
  7. package/dist/analysis-context.js +708 -0
  8. package/dist/ast-guards.d.ts +24 -0
  9. package/dist/ast-guards.d.ts.map +1 -0
  10. package/dist/ast-guards.js +83 -0
  11. package/dist/candidate-boot.d.ts +30 -0
  12. package/dist/candidate-boot.d.ts.map +1 -0
  13. package/dist/candidate-boot.js +262 -0
  14. package/dist/canonicalize.d.ts +19 -0
  15. package/dist/canonicalize.d.ts.map +1 -0
  16. package/dist/canonicalize.js +525 -0
  17. package/dist/cli.d.ts +4 -0
  18. package/dist/cli.d.ts.map +1 -0
  19. package/dist/cli.js +312 -0
  20. package/dist/equiv-execution-context.d.ts +25 -0
  21. package/dist/equiv-execution-context.d.ts.map +1 -0
  22. package/dist/equiv-execution-context.js +82 -0
  23. package/dist/index.d.ts +13 -0
  24. package/dist/index.d.ts.map +1 -0
  25. package/dist/index.js +11 -0
  26. package/dist/run.d.ts +8 -0
  27. package/dist/run.d.ts.map +1 -0
  28. package/dist/run.js +129 -0
  29. package/dist/shared.d.ts +9 -0
  30. package/dist/shared.d.ts.map +1 -0
  31. package/dist/shared.js +47 -0
  32. package/dist/tier-i-import-graph.d.ts +7 -0
  33. package/dist/tier-i-import-graph.d.ts.map +1 -0
  34. package/dist/tier-i-import-graph.js +34 -0
  35. package/dist/tier-l-child-runtime.d.ts +2 -0
  36. package/dist/tier-l-child-runtime.d.ts.map +1 -0
  37. package/dist/tier-l-child-runtime.js +62 -0
  38. package/dist/tier-l-module-load.d.ts +6 -0
  39. package/dist/tier-l-module-load.d.ts.map +1 -0
  40. package/dist/tier-l-module-load.js +139 -0
  41. package/dist/tier-l-stub-source.d.ts +11 -0
  42. package/dist/tier-l-stub-source.d.ts.map +1 -0
  43. package/dist/tier-l-stub-source.js +246 -0
  44. package/dist/tier-r-replay.d.ts +6 -0
  45. package/dist/tier-r-replay.d.ts.map +1 -0
  46. package/dist/tier-r-replay.js +382 -0
  47. package/dist/tier-s-symbol-diff.d.ts +19 -0
  48. package/dist/tier-s-symbol-diff.d.ts.map +1 -0
  49. package/dist/tier-s-symbol-diff.js +156 -0
  50. package/dist/types.d.ts +91 -0
  51. package/dist/types.d.ts.map +1 -0
  52. package/dist/types.js +19 -0
  53. package/dist/workspace.d.ts +63 -0
  54. package/dist/workspace.d.ts.map +1 -0
  55. package/dist/workspace.js +459 -0
  56. package/package.json +64 -0
package/AGENTS.md ADDED
@@ -0,0 +1,81 @@
1
+ # AGENTS.md — ushman-equiv
2
+
3
+ Read this before changing code in this package.
4
+
5
+ ## What this package is
6
+
7
+ A pure-Node equivalence gate for ushman cleanup workspaces. It checks whether a candidate still resolves imports, loads in Node with vendor/browser shims, preserves baseline top-level symbols, and reproduces captured fixture outputs.
8
+
9
+ ## What this package is NOT
10
+
11
+ - Not a browser harness. Renderer parity stays in the `ushman` orchestrator.
12
+ - Not a mutator. Equiv reads the workspace and optionally writes `.lab/equiv/result.json`, `.lab/equiv/baseline.json`, or explicit operator-requested baseline output files.
13
+ - Not a substitute for `@ushman/verify`. Verify proves the handoff is structurally sane; Equiv proves the refactor is still equivalent enough to continue.
14
+ - Not an npm-published package in v0. Treat it as local-link only.
15
+
16
+ ## Read order
17
+
18
+ 1. This file.
19
+ 2. `README.md`.
20
+ 3. `src/run.ts` — report orchestration and result writing.
21
+ 4. `src/types.ts` — durable report and option contracts.
22
+ 5. `src/canonicalize.ts` — trace canonicalization contract for tier `R`.
23
+ 6. `src/equiv-execution-context.ts` — shared memoized execution context for boot + analysis reuse.
24
+ 7. `src/analysis-context.ts` — parsed-source cache and shared import/symbol analysis.
25
+ 8. The tier module you are changing.
26
+
27
+ ## Code map
28
+
29
+ | File | Owns |
30
+ |------|------|
31
+ | `src/index.ts` | Public package surface and re-exports |
32
+ | `src/run.ts` | Tier orchestration, verdict aggregation, render/write helpers |
33
+ | `src/types.ts` | `EquivReport`, `EquivCheckResult`, tier option shapes |
34
+ | `src/equiv-execution-context.ts` | Shared boot/import/symbol memoization across tier runs |
35
+ | `src/analysis-context.ts` | AST cache, source-file analysis, filtered import/symbol views |
36
+ | `src/ast-guards.ts` | Narrow AST guard helpers for internal Babel shape handling |
37
+ | `src/workspace.ts` | Workspace resolution, importmap/index parsing, file walking, atomic writes |
38
+ | `src/canonicalize.ts` | Pure-Node canonicalization and hydration helpers used by replay |
39
+ | `src/tier-i-import-graph.ts` | Tier `I` import discovery and resolution |
40
+ | `src/tier-l-module-load.ts` | Tier `L` child-process load smoke and vendor stubbing |
41
+ | `src/tier-l-child-runtime.ts` | Externalized Tier `L` child runtime source |
42
+ | `src/tier-l-stub-source.ts` | Shared Tier `L` stub/browser-shim source generation |
43
+ | `src/tier-s-symbol-diff.ts` | Tier `S` baseline emission and candidate symbol coverage |
44
+ | `src/tier-r-replay.ts` | Tier `R` fixture replay and drift reporting |
45
+ | `src/cli.ts` | `ushman-equiv` CLI |
46
+
47
+ ## Working rules
48
+
49
+ - **No Bun APIs in runtime files.** `src/**/*.ts` that are not tests stay pure Node.
50
+ - **No network.** Equiv must run air-gapped.
51
+ - **Keep writes narrow.** Runtime writes only `.lab/equiv/result.json`, `.lab/equiv/baseline.json`, and explicit operator-requested baseline output files.
52
+ - **Every tier ships with fixture coverage.** Keep `test/fixtures/v4-equiv/` small and descriptive.
53
+ - **Keep the exit-code contract stable.** `0` non-red, `1` red, `2` runtime error.
54
+ - **Shared context first.** Cross-tier reuse belongs in `src/equiv-execution-context.ts` and `src/analysis-context.ts`, not private sentinel fields or tier-to-tier imports.
55
+ - **Workspace boundaries are lexical and realpath-checked.** Do not weaken the symlink escape guard in `src/workspace.ts` without tests for lexical traversal, file escapes, directory escapes, and safe in-workspace symlinks.
56
+ - **Local sister packages are part of the dev contract.** `ushman-lab-types` resolves from a sibling workspace package, not a vendored copy inside this repo.
57
+
58
+ ## Commands
59
+
60
+ ```bash
61
+ bun test
62
+ bun run typecheck
63
+ node dist/cli.js .
64
+ ```
65
+
66
+ ## Validation rules
67
+
68
+ - `bun test` green before handoff.
69
+ - `bun run typecheck` green.
70
+ - `bun run lint` green.
71
+ - New tier behavior implies new fixture-backed tests.
72
+ - Keep `package.json` on `node >= 24` only.
73
+
74
+ ## LLM boundaries
75
+
76
+ This package is intended to run inside LLM handoff environments. That means:
77
+
78
+ - It may read the workspace and report equivalence findings.
79
+ - It may not mutate candidate source files.
80
+ - It must remain pure Node in published runtime code.
81
+ - Tiers `L` and `R` intentionally execute workspace code inside Node. Treat the workspace as trusted operator input.
package/LICENSE.md ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ragaeeb Haq
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,201 @@
1
+ # ushman-equiv
2
+
3
+ > **Pure-Node behavioral and structural equivalence checks for ushman refactors.**
4
+
5
+ Runs four Node-only tiers against a candidate workspace: import-graph resolution, module-load smoke, symbol-preservation diff, and replay against captured fixtures. Designed for the same air-gapped handoff zips and local-link workflows as `@ushman/verify`.
6
+
7
+ When `runEquiv()` executes multiple tiers together, it shares entrypoint discovery, source walking, and AST parsing across tiers so each source file is parsed once per run.
8
+
9
+ ```mermaid
10
+ flowchart LR
11
+ A["runEquiv(opts)"] --> B["EquivExecutionContext"]
12
+ B --> C["Analysis Context"]
13
+ B --> D["Candidate Boot"]
14
+ C --> E["Tier I: import graph"]
15
+ C --> F["Tier S: symbol diff"]
16
+ C --> G["Tier L: module load"]
17
+ C --> H["Tier R: replay"]
18
+ D --> G
19
+ D --> H
20
+ ```
21
+
22
+ ## Status
23
+
24
+ Extracted as a sister package for the cleanup lane.
25
+ **Runtime:** pure Node ≥ 24. **No Bun APIs in published runtime code.** Tests run with Bun.
26
+ **Distribution:** local-link only for now. Do not publish to npm in v0.
27
+
28
+ ## Install
29
+
30
+ ```bash
31
+ cd ~/workspace/ushman-lab-types
32
+ bun link
33
+
34
+ cd ~/workspace/ushman-equiv
35
+ bun link
36
+
37
+ cd ~/workspace/ushman
38
+ bun link ushman-equiv
39
+ ```
40
+
41
+ ## Quick start
42
+
43
+ ```ts
44
+ import { runEquiv } from 'ushman-equiv';
45
+
46
+ const report = await runEquiv({ workspaceRoot: '.' });
47
+ console.log(report.verdict); // 'green' | 'yellow' | 'red'
48
+ ```
49
+
50
+ ```bash
51
+ ushman-equiv . # all tiers
52
+ ushman-equiv ./candidate --tier=R
53
+ ushman-equiv emit-baseline --workspace=.
54
+ ```
55
+
56
+ ## Tiers
57
+
58
+ | Tier | What it checks |
59
+ |------|----------------|
60
+ | `I` | Static import-graph resolution for relative imports and bare specifiers against the workspace importmap |
61
+ | `L` | Child-process module-load smoke with browser-global shims and vendor stubs |
62
+ | `S` | Baseline vs candidate top-level symbol preservation |
63
+ | `R` | Replay of captured fixture calls against refactored exports |
64
+
65
+ ## Public API
66
+
67
+ See [`src/index.ts`](src/index.ts) for the full surface. Top-level:
68
+
69
+ ```ts
70
+ runEquiv(opts: EquivOptions): Promise<EquivReport>;
71
+ renderEquivReport(report: EquivReport): string;
72
+ writeEquivResult(opts: { report: EquivReport; workspaceRoot: string }): Promise<void>;
73
+ emitSymbolBaseline(opts: { workspaceRoot: string; outputPath?: string }): Promise<{ symbolCount: number; outputPath: string }>;
74
+ canonicalize(value: unknown, opts?: { precision?: number; exemptFields?: readonly string[]; maxBytes?: number }): unknown;
75
+ ```
76
+
77
+ `canonicalize()` treats `exemptFields` as dot-notation paths rooted at the replay payload, for example `['events.0.timestamp', 'meta.uuid']`.
78
+
79
+ `emitSymbolBaseline` also accepts `{ bundlePath, outputPath }` for bundle-driven baseline generation when the caller is not operating on a live v4 workspace.
80
+
81
+ Plus per-tier helpers (`checkImportGraph`, `checkModuleLoad`, `checkSymbolDiff`, `checkReplay`) for callers that want one tier.
82
+ `createEquivExecutionContext()` plus the `check*WithContext()` variants are also exported for callers that want to reuse one shared boot/analysis cache across multiple tier calls in the same process.
83
+
84
+ Error behavior:
85
+
86
+ - `runEquiv()` catches unexpected tier crashes and records them as red tier results so the overall report still renders.
87
+ - Standalone tier helpers still throw for invalid input/options and unexpected setup failures. They return an `EquivCheckResult` only after the tier has started running normally.
88
+ - `check*WithContext` exports exist for callers that want to reuse one `EquivExecutionContext` across multiple tier invocations in the same process.
89
+
90
+ ## CLI
91
+
92
+ ```bash
93
+ ushman-equiv <workspace> [--tiers=I,L,S,R | --tier=I] [--filter=<glob>]
94
+ [--entrypoint=<path>] [--baseline=<path>]
95
+ [--fixtures=<dir>] [--modules=<dir>]
96
+ [--src-roots=<comma-list>] [--mode=preview|dev]
97
+ [--write-result] [--json]
98
+ [--max-concurrency=<n>]
99
+
100
+ ushman-equiv emit-baseline [<workspace> | --workspace=<path>] [--out=<path>]
101
+ ushman-equiv --version
102
+ ```
103
+
104
+ Exit codes:
105
+
106
+ - `0`: verdict is `green` or `yellow`
107
+ - `1`: verdict is `red`
108
+ - `2`: equiv runtime / CLI error
109
+
110
+ `--mode=preview` is the authoritative default for tiers `L` and `R`; `--mode=dev` is the faster smoke path.
111
+ `--write-result` writes `<workspace>/.lab/equiv/result.json` atomically.
112
+ `--filter` matches fixture names for tier `R`, symbol names for tier `S`, and relative source-file paths for tier `I`.
113
+ `--baseline` may point at a workspace-relative or absolute baseline file.
114
+ `--max-concurrency` is capped at `64`.
115
+
116
+ Defaults for v4 workspaces:
117
+
118
+ - Tier `S` baseline: `<workspace>/.lab/equiv/baseline.json`
119
+ - Tier `R` fixtures: `<workspace>/.lab/characterize/replay/`
120
+ - Tier `R` fallback modules: `<workspace>/.lab/characterize/modules/`
121
+
122
+ Relevant environment overrides:
123
+
124
+ - `USHMAN_EQUIV_NODE_BINARY`: override the Node binary used for Tier `L` child-process module loading when the parent process is not plain Node.
125
+ - `USHMAN_EQUIV_MODULE_LOAD_TIMEOUT_MS`: cap Tier `L` child-process runtime.
126
+ - `USHMAN_EQUIV_BOOT_TIMEOUT_MS`, `USHMAN_EQUIV_BUILD_TIMEOUT_MS`, `USHMAN_EQUIV_MAX_LOG_BYTES`: tune preview/dev boot behavior.
127
+ - `USHMAN_EQUIV_BOOT_PORT_RETRY_LIMIT`: retry strict-port preview/dev boot when the chosen port loses a race to another local process.
128
+
129
+ Internal execution notes for contributors:
130
+
131
+ - Tier orchestration uses a shared execution context so Tier `L` and Tier `R` reuse the same boot smoke result during `runEquiv()`.
132
+ - Import-graph and symbol analysis are memoized per workspace/entrypoint/source-root set, then filtered per tier request.
133
+ - Tier `L` delivers one shared vendor-stub helper module into the child runtime so large bare-specifier graphs do not duplicate the proxy factory in every generated stub.
134
+ - Candidate boot still uses strict ports for deterministic probing, but it now retries `EADDRINUSE` contention with fresh ports before failing.
135
+
136
+ v3 workspaces are refused with the standard v4 cutover hint:
137
+
138
+ ```text
139
+ This workspace is in v3 layout (legacy stages/, .ushman/, handoff.json at root).
140
+ ushman v4 no longer ships the v3 layout readers or the live migrator.
141
+ `ushman migrate-v3-v4` is retained only as a diagnostic stub.
142
+ All known v3 workspaces were migrated during the v4 cutover.
143
+ If this workspace was not on that migration list, restore shibuk v2.x + ushman v3.x to migrate it first.
144
+ Workspace: <workspace>
145
+ ```
146
+
147
+ This package does not ship the migrator itself. The migration is owned by the main `ushman` CLI.
148
+
149
+ Examples:
150
+
151
+ ```bash
152
+ ushman-equiv ./candidate --tier=R --filter='clamp*'
153
+ ushman-equiv ./candidate --tier=I --filter='src/**/math/*.js'
154
+ ushman-equiv ./candidate --tier=S --filter='/^Game/'
155
+ ```
156
+
157
+ Replay fixture shape:
158
+
159
+ ```json
160
+ {
161
+ "fn": "clamp",
162
+ "module": ".lab/characterize/modules/clamp.mjs",
163
+ "calls": [
164
+ { "args": [-1, 0, 10], "return": 0 },
165
+ { "args": [4, 0, 10], "return": 4 }
166
+ ]
167
+ }
168
+ ```
169
+
170
+ `module` is optional. When present, it is resolved relative to the workspace root. When omitted, Tier `R` falls back to `<workspace>/.lab/characterize/modules/<sanitized-fn>.mjs`.
171
+ `thisArg` and `threw` are also supported in `calls` when characterize captured a bound-method invocation or an expected throw.
172
+
173
+ Workspace-relative path resolution is validated twice:
174
+
175
+ - lexical path containment under the workspace root
176
+ - realpath containment under the workspace's real root, including the nearest existing ancestor for future output paths
177
+
178
+ This rejects symlink escapes while still allowing symlinks that resolve back inside the workspace.
179
+
180
+ Advanced replay knobs:
181
+
182
+ - `fixturesDir`: override the default `.lab/characterize/replay/` directory.
183
+ - `modulesDir`: override the fallback replay-module directory.
184
+ - `maxConcurrency`: cap fixture replay fan-out. The CLI enforces a maximum of `64`.
185
+
186
+ ## Why This Exists Separate From `ushman`
187
+
188
+ `ushman-equiv` runs in the same pure-Node LLM sandbox and operator-side handoff flow as `@ushman/verify`, but it answers a different question. `verify` proves the candidate still parses and references sane files. `equiv` proves the refactor still resolves, loads, preserves required symbols, and reproduces captured outputs.
189
+
190
+ ## Where This Fits In The Family
191
+
192
+ | | |
193
+ |---|---|
194
+ | Runs **after** | `@ushman/verify` preflight |
195
+ | Reuses output from | `@ushman/characterize` replay fixture generation |
196
+ | Runs **before** | operator-side parity / merge acceptance |
197
+ | Does **not** run | browsers, screenshots, or networked validation |
198
+
199
+ ## Safety Boundary
200
+
201
+ Tiers `L` and `R` execute workspace modules inside Node. Run `ushman-equiv` only against operator-controlled workspaces and handoff trees you trust to execute locally.
@@ -0,0 +1,19 @@
1
+ #!/usr/bin/env bash
2
+ # ushman-equiv CLI wrapper. Symlinked from ~/.bun/bin/ushman-equiv after
3
+ # `bun link` so operators can invoke `ushman-equiv <args>` directly.
4
+ # Resolves this script's real location through any symlink chain and hands
5
+ # off to bun, which executes the TypeScript entrypoint.
6
+ set -euo pipefail
7
+
8
+ SELF="$0"
9
+ while [ -L "$SELF" ]; do
10
+ LINK_TARGET="$(readlink "$SELF")"
11
+ case "$LINK_TARGET" in
12
+ /*) SELF="$LINK_TARGET" ;;
13
+ *) SELF="$(dirname "$SELF")/$LINK_TARGET" ;;
14
+ esac
15
+ done
16
+ HERE="$(cd "$(dirname "$SELF")" && pwd)"
17
+ PACKAGE_ROOT="$(cd "$HERE/.." && pwd)"
18
+
19
+ exec "${BUN_BIN:-bun}" run "$PACKAGE_ROOT/src/cli.ts" "$@"
@@ -0,0 +1,102 @@
1
+ import { type File } from '@babel/types';
2
+ import type { EquivFinding, SymbolBaselineDeclaration } from './types.ts';
3
+ import { parseSourceFile } from './workspace.ts';
4
+ export type BareImportUsage = {
5
+ readonly defaultImported: boolean;
6
+ readonly namedImports: ReadonlySet<string>;
7
+ readonly namespaceImported: boolean;
8
+ };
9
+ export type ImportReference = {
10
+ readonly importerPath: string;
11
+ readonly message?: string;
12
+ readonly resolved: boolean;
13
+ readonly resolvedPath?: string;
14
+ readonly specifier: string;
15
+ };
16
+ export type ImportGraphAnalysis = {
17
+ readonly bareUsages: ReadonlyMap<string, BareImportUsage>;
18
+ readonly entrypointPath: string;
19
+ readonly importMap: Readonly<Record<string, string>>;
20
+ readonly imports: readonly ImportReference[];
21
+ readonly parseFindings: readonly EquivFinding[];
22
+ readonly warnings: readonly EquivFinding[];
23
+ };
24
+ export type SymbolIndexEntry = {
25
+ readonly exported: boolean;
26
+ readonly filePath: string;
27
+ readonly kind: SymbolBaselineDeclaration['kind'];
28
+ readonly name: string;
29
+ };
30
+ export type WorkspaceSymbolIndex = {
31
+ readonly byFile: ReadonlyMap<string, readonly SymbolIndexEntry[]>;
32
+ readonly byName: ReadonlyMap<string, readonly SymbolIndexEntry[]>;
33
+ readonly declarations: ReadonlyMap<string, SymbolBaselineDeclaration['kind']>;
34
+ readonly errors: readonly EquivFinding[];
35
+ readonly exportFiles: ReadonlyMap<string, string>;
36
+ readonly warnings: readonly EquivFinding[];
37
+ };
38
+ export type CandidateSymbolCollection = {
39
+ readonly errors: readonly EquivFinding[];
40
+ readonly exportFiles: ReadonlyMap<string, string>;
41
+ readonly index: WorkspaceSymbolIndex;
42
+ readonly symbolNames: readonly string[];
43
+ readonly symbols: readonly SymbolBaselineDeclaration[];
44
+ readonly warnings: readonly EquivFinding[];
45
+ };
46
+ /**
47
+ * Inputs that shape the filtered symbol projection exposed to tiers.
48
+ * `filter` applies after the shared workspace-wide symbol index is built.
49
+ */
50
+ export type CandidateSymbolAnalysisOptions = {
51
+ readonly entrypoint?: string;
52
+ readonly filter?: string;
53
+ readonly srcRoots?: readonly string[];
54
+ readonly workspaceRoot: string;
55
+ };
56
+ type ParsedSourceFile = Awaited<ReturnType<typeof parseSourceFile>>;
57
+ /**
58
+ * Inputs that define the reusable analysis scope for a single workspace.
59
+ * Callers that want cache hits should pass semantically equivalent paths.
60
+ */
61
+ export type AnalysisContextSeed = {
62
+ readonly entrypoint?: string;
63
+ readonly srcRoots?: readonly string[];
64
+ readonly workspaceRoot: string;
65
+ };
66
+ type TopLevelDeclarationScan = {
67
+ readonly declarations: ReadonlyMap<string, SymbolBaselineDeclaration['kind']>;
68
+ readonly exportedNames: ReadonlySet<string>;
69
+ };
70
+ type AnalysisTestHooks = {
71
+ readonly onParseSourceFile?: (filePath: string) => void;
72
+ };
73
+ export declare const withAnalysisContextTestHooks: <T>({ hooks, run, }: {
74
+ readonly hooks: AnalysisTestHooks;
75
+ readonly run: () => Promise<T>;
76
+ }) => Promise<T>;
77
+ export type SharedAnalysisContext = {
78
+ readonly entrypointPath: string;
79
+ readonly importMap: Readonly<Record<string, string>>;
80
+ readonly missingRoots: readonly string[];
81
+ readonly sourceFiles: readonly string[];
82
+ readonly workspaceRoot: string;
83
+ readonly getImportGraphAnalysis: (filter: string | undefined) => Promise<ImportGraphAnalysis>;
84
+ readonly getParsedSourceFile: (filePath: string) => Promise<ParsedSourceFile>;
85
+ readonly getSymbolIndex: () => Promise<WorkspaceSymbolIndex>;
86
+ };
87
+ export declare const scanTopLevelDeclarations: (ast: File) => TopLevelDeclarationScan;
88
+ /**
89
+ * Builds the shared per-workspace analysis context used by tier orchestration.
90
+ * The context owns entrypoint discovery, source walking, parse dedupe,
91
+ * import-graph filtering, and symbol-index reuse for a single workspace root.
92
+ */
93
+ export declare const createAnalysisContext: (options: AnalysisContextSeed) => Promise<SharedAnalysisContext>;
94
+ /**
95
+ * Projects a filtered symbol view from the cached workspace symbol index.
96
+ */
97
+ export declare const selectCandidateSymbols: ({ filter, index, }: {
98
+ readonly filter?: string;
99
+ readonly index: WorkspaceSymbolIndex;
100
+ }) => CandidateSymbolCollection;
101
+ export {};
102
+ //# sourceMappingURL=analysis-context.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"analysis-context.d.ts","sourceRoot":"","sources":["../src/analysis-context.ts"],"names":[],"mappings":"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"}