Repository navigation
Expand file tree
/
Copy pathfacade-exports.ts
More file actions
166 lines (161 loc) · 8.48 KB
/
Copy pathfacade-exports.ts
File metadata and controls
166 lines (161 loc) · 8.48 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
// Named-export enumeration for a façade module's own source text — the R11
// structural gate in `package-boundaries.test.ts` uses this to prove a
// façade names its exports explicitly instead of a bare `export *`.
//
// Split out of `package-boundaries.ts` (#1574 review): the boundary rules
// answer "may this file import that one?", while this module answers "what
// does this façade name?" — different questions, so per AGENTS.md they are
// different bounded reads.
//
// This module used to also carry `readFacadeExports`, a ~200-line star-chain
// resolver (`GetExportedNames`/`ResolveExport` re-implemented over relative
// specifiers) that existed only to enumerate what a barrel's `export *`
// hides, feeding a hand-maintained 816-symbol pin table
// (`facade-symbols.ts`, #1574). Every workspace-package façade now names its
// exports explicitly (`export { a, b } from './x.ts'`), so there is nothing
// left for a star-chain walker to resolve — the façade file itself is the
// pin, and `readNamedExports` below is enough to prove it stays that way.
import { parseSync } from 'oxc-parser';
/**
* Every name a façade module exports, value or type-only, sorted — the exact
* "named-export-list" a package-boundaries gate can pin (#1555 review P1,
* "add the reviewer-required exact exported-symbol gate"). Covers both
* re-export forms (`export { a, b } from './x.ts'`,
* `export type { a, b } from './x.ts'`, with or without `as` aliasing — the
* alias is reported, since that is the name a consumer actually imports),
* `export * as ns from './x.ts'` (one real name, `ns`), and direct
* declarations (`export function`/`const`/`class`/`type`/`interface`,
* including `export const a = 1, b = 2`'s multiple declarators). A stray
* export — intentional or not — changes this list, so a test that pins it
* exactly turns "the façade grew a symbol" into a loud failure instead of a
* silent widening only a PR diff review would catch.
*
* AST-based (`oxc-parser`, already a devDependency — `session-state.ts` is
* the existing precedent for using it in this gate), not a regex, for the
* SAME reason `session-state.ts` gives: a regex has to enumerate every
* export FORM by hand, and the one it forgets is exactly the one that slips
* through. That is precisely what happened here (#1555 review, second pass,
* "the gate also ignores export-star declarations, so it can miss future
* widening"): `export * from './x.ts'` re-exports an unbounded, statically
* unknowable set of names — the old regex scanner had no case for it at all,
* so it silently contributed NOTHING to the list instead of failing loudly.
* `parsed.module.staticExports` is oxc's own resolved export-entry table
* (built for exactly this purpose, not re-derived from a manual AST walk),
* and its `exportName.kind` already draws the line this function needs:
* `'None'` is bare `export *` (unenumerable — thrown), `'Default'` is
* `export default …` (also thrown — a facade pinned to an exact named-export
* list must not carry one), and `'Name'` is every enumerable form above,
* `export * as ns` included (oxc reports its one real bound name, `ns`).
*/
export function readNamedExports(source: string): string[] {
const parsed = parseSync('package-boundaries-export-scan.ts', source);
const names = new Set<string>();
for (const staticExport of parsed.module.staticExports) {
for (const entry of staticExport.entries) {
if (entry.exportName.kind === 'None') {
throw new Error(
"readNamedExports cannot enumerate 'export * from …' — it re-exports an unknown set " +
'of names, exactly the widening an exact-export-list gate exists to catch. Name the ' +
're-exported symbols explicitly instead of re-exporting the whole module.',
);
}
if (entry.exportName.kind === 'Default') {
throw new Error(
"readNamedExports cannot enumerate 'export default …' as a named symbol — a facade a " +
'caller pins to an exact named-export list must not carry a default export.',
);
}
if (entry.exportName.name) names.add(entry.exportName.name);
}
}
return [...names].sort();
}
/**
* Every name a module declares or re-exports BY NAME, ignoring any bare
* `export *` it also carries. `readNamedExports` refuses such a module
* outright, which is right for a façade — a star there is unbounded widening —
* but wrong for a SOURCE the exhaustiveness gate is reading: skipping the whole
* file also skips its direct exports, so removing one of those from a façade
* would narrow the surface undetected (#1614 review P2). The starred names are
* not lost: a façade must re-export the starred module directly too, and that
* path is checked on its own.
*/
export function readDirectNamedExports(source: string): string[] {
const parsed = parseSync('facade-source-export-scan.ts', source);
const names = new Set<string>();
for (const staticExport of parsed.module.staticExports) {
for (const entry of staticExport.entries) {
// `None` is the bare star (unenumerable here, covered elsewhere);
// `Default` is never reachable through a star re-export.
if (entry.exportName.kind !== 'Name') continue;
if (entry.exportName.name) names.add(entry.exportName.name);
}
}
return [...names].sort();
}
/**
* Which module each name in `source` is re-exported FROM, for names that come
* from a re-export rather than a local declaration.
*
* A façade's export *names* are only half its boundary: a type re-exported
* from the right module and one re-exported from a package-private module read
* identically in the name list, while only the second leaks. #1649 shipped
* exactly that — a policy outcome re-exported from the parser-side module, so
* its nested `resolution` field handed callers the private AST — and the
* name-list gate stayed green throughout.
*/
export function readReExportSources(source: string): Map<string, string> {
const parsed = parseSync('facade-reexport-source-scan.ts', source);
const sources = new Map<string, string>();
for (const staticExport of parsed.module.staticExports) {
for (const entry of staticExport.entries) {
if (entry.exportName.kind !== 'Name' || !entry.exportName.name) continue;
if (!entry.moduleRequest) continue;
sources.set(entry.exportName.name, entry.moduleRequest.value);
}
}
return sources;
}
/**
* Re-export edges grouped by the module they come FROM: each `export { … } from
* './m.ts'` entry contributes one `{ imported, exported }` pair to `./m.ts`'s
* list — `imported` is the name in the source module (the alias target),
* `exported` the name the façade publishes — and `export * as ns from './m.ts'`
* contributes the binding `namespace:<ns>`, which carries the module's whole
* surface. Bare `export *` throws exactly as in `readNamedExports`.
*
* This is the per-source shape the exhaustiveness gate needs. Keying by export
* NAME — `readReExportSources`, or a flat name set — cannot answer "does the
* façade still carry everything THIS module exports?" when two sources export
* the same name: the survivor's entry hides the dropped one, so narrowing a
* single source passes (#3289 cubic review P2). Edges keep their module, so a
* pair is satisfied only by the module that declares the name.
*/
export function readFacadeReExportEdgesByModule(
source: string,
): Map<string, { imported: string; exported: string }[]> {
const parsed = parseSync('facade-reexport-edge-scan.ts', source);
const edges = new Map<string, { imported: string; exported: string }[]>();
for (const staticExport of parsed.module.staticExports) {
for (const entry of staticExport.entries) {
if (entry.exportName.kind === 'None') {
throw new Error(
"readFacadeReExportEdgesByModule cannot enumerate 'export * from …' — it re-exports " +
'an unknown set of names. Name the re-exported symbols explicitly instead.',
);
}
if (entry.exportName.kind !== 'Name' || !entry.exportName.name) continue;
if (!entry.moduleRequest) continue;
const moduleRequest = entry.moduleRequest.value;
const exported = entry.exportName.name;
const pair =
entry.importName.kind === 'All'
? { imported: `namespace:${exported}`, exported }
: { imported: entry.importName.name ?? exported, exported };
const list = edges.get(moduleRequest);
if (list) list.push(pair);
else edges.set(moduleRequest, [pair]);
}
}
return edges;
}