@ecopages/react 0.2.0-beta.8 → 0.2.0-rc.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.
- package/README.md +179 -7
- package/package.json +54 -29
- package/src/app/client-only.js +15 -0
- package/src/app/dynamic.js +9 -0
- package/src/app/dynamic.test.browser.js +31 -0
- package/src/bundling/bootstrap-package-paths.d.ts +5 -0
- package/src/bundling/bootstrap-package-paths.js +5 -0
- package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +23 -8
- package/src/bundling/bundle.js +120 -0
- package/src/bundling/discover-layout-runtime-modules.d.ts +32 -0
- package/src/bundling/discover-layout-runtime-modules.js +185 -0
- package/src/bundling/runtime-alias-map.d.ts +13 -0
- package/src/bundling/runtime-alias-map.js +113 -0
- package/src/{services/react-runtime-bundle.service.d.ts → bundling/runtime-bundle.d.ts} +25 -4
- package/src/bundling/runtime-bundle.js +258 -0
- package/src/bundling/runtime-interop-plugin.js +34 -0
- package/src/bundling/runtime-mode.d.ts +9 -0
- package/src/bundling/runtime-mode.js +11 -0
- package/src/bundling/runtime-modules.d.ts +29 -0
- package/src/bundling/runtime-modules.js +49 -0
- package/src/client-graph/ast-transform.d.ts +18 -0
- package/src/client-graph/ast-transform.js +426 -0
- package/src/{utils/client-graph-boundary-cache.d.ts → client-graph/boundary-cache.d.ts} +23 -13
- package/src/client-graph/boundary-cache.js +182 -0
- package/src/{utils/client-graph-boundary-plugin.d.ts → client-graph/boundary-plugin.d.ts} +4 -13
- package/src/client-graph/boundary-plugin.js +149 -0
- package/src/client-graph/component-config-traversal.js +77 -0
- package/src/client-graph/declared-modules.js +69 -0
- package/src/client-graph/module-classification.d.ts +3 -0
- package/src/client-graph/module-classification.js +43 -0
- package/src/{utils → client-graph}/reachability-analyzer.d.ts +4 -12
- package/src/client-graph/reachability-analyzer.js +515 -0
- package/src/client-graph/specifier-classification.d.ts +75 -0
- package/src/client-graph/specifier-classification.js +214 -0
- package/src/contracts/router-adapter.js +6 -0
- package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
- package/src/dev-transform/react-dev-transform-contributor.js +22 -0
- package/src/hmr/hmr-scripts.js +44 -0
- package/src/hmr/hmr-strategy.d.ts +74 -0
- package/src/hmr/hmr-strategy.js +351 -0
- package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
- package/src/hmr/page-metadata-cache.js +44 -0
- package/src/hmr/react-hmr-dev-transform-plugins.d.ts +23 -0
- package/src/hmr/react-hmr-dev-transform-plugins.js +20 -0
- package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
- package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
- package/src/hydration/bootstrap-imports.d.ts +25 -0
- package/src/hydration/bootstrap-imports.js +33 -0
- package/src/hydration/hydration-asset.d.ts +84 -0
- package/src/hydration/hydration-asset.js +227 -0
- package/src/hydration/hydration-scripts.d.ts +104 -0
- package/src/hydration/hydration-scripts.js +483 -0
- package/src/hydration/hydration-scripts.test.browser.js +199 -0
- package/src/hydration/page-data-manifest.d.ts +58 -0
- package/src/hydration/page-data-manifest.js +97 -0
- package/src/hydration/page-data-reader.d.ts +31 -0
- package/src/hydration/page-data-reader.js +77 -0
- package/src/hydration/page-payload.d.ts +67 -0
- package/src/hydration/page-payload.js +106 -0
- package/src/hydration/serialize-page-data-script.d.ts +27 -0
- package/src/hydration/serialize-page-data-script.js +30 -0
- package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +6 -6
- package/src/mdx/mdx-config-dependency.js +110 -0
- package/src/mdx/mdx-loader-plugin.d.ts +2 -0
- package/src/mdx/mdx-loader-plugin.js +8 -0
- package/src/page/page-module.d.ts +46 -0
- package/src/page/page-module.js +74 -0
- package/src/plugin/react.constants.js +1 -0
- package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +9 -3
- package/src/plugin/react.plugin.js +241 -0
- package/src/plugin/react.types.d.ts +156 -0
- package/src/plugin/react.types.js +1 -0
- package/src/render/component-ownership.d.ts +49 -0
- package/src/render/component-ownership.js +46 -0
- package/src/render/component-ssr.d.ts +113 -0
- package/src/render/component-ssr.js +180 -0
- package/src/render/eco-embed.js +9 -0
- package/src/render/errors.d.ts +16 -0
- package/src/render/errors.js +23 -0
- package/src/render/html-boundary.js +59 -0
- package/src/render/layout-compose.d.ts +66 -0
- package/src/render/layout-compose.js +134 -0
- package/src/render/react-renderer.d.ts +138 -0
- package/src/render/react-renderer.js +448 -0
- package/src/render/react-runtime.d.ts +13 -0
- package/src/render/react-runtime.js +26 -0
- package/src/render/unified-layout-composition.d.ts +53 -0
- package/src/render/unified-layout-composition.js +78 -0
- package/src/runtime/use-sync-external-store-with-selector.js +52 -54
- package/src/eco-embed.js +0 -11
- package/src/react-hmr-strategy.d.ts +0 -230
- package/src/react-hmr-strategy.js +0 -657
- package/src/react-renderer.d.ts +0 -233
- package/src/react-renderer.js +0 -622
- package/src/react.constants.js +0 -4
- package/src/react.plugin.js +0 -209
- package/src/react.types.d.ts +0 -88
- package/src/react.types.js +0 -0
- package/src/router-adapter.js +0 -0
- package/src/services/pages-index.d.ts +0 -64
- package/src/services/pages-index.js +0 -73
- package/src/services/react-bundle.service.js +0 -86
- package/src/services/react-hmr-page-metadata-cache.js +0 -35
- package/src/services/react-hydration-asset.service.d.ts +0 -84
- package/src/services/react-hydration-asset.service.js +0 -217
- package/src/services/react-mdx-config-dependency.service.js +0 -122
- package/src/services/react-page-module.service.d.ts +0 -88
- package/src/services/react-page-module.service.js +0 -166
- package/src/services/react-page-payload.service.d.ts +0 -46
- package/src/services/react-page-payload.service.js +0 -67
- package/src/services/react-runtime-bundle.service.js +0 -192
- package/src/utils/client-graph-boundary-cache.js +0 -116
- package/src/utils/client-graph-boundary-plugin.js +0 -552
- package/src/utils/client-only.js +0 -19
- package/src/utils/component-config-traversal.js +0 -54
- package/src/utils/declared-modules.js +0 -47
- package/src/utils/dynamic.js +0 -12
- package/src/utils/dynamic.test.browser.js +0 -33
- package/src/utils/hmr-scripts.js +0 -31
- package/src/utils/html-boundary.js +0 -55
- package/src/utils/hydration-scripts.d.ts +0 -92
- package/src/utils/hydration-scripts.js +0 -358
- package/src/utils/hydration-scripts.test.browser.js +0 -198
- package/src/utils/reachability-analyzer.js +0 -339
- package/src/utils/react-dom-runtime-interop-plugin.js +0 -38
- package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
- package/src/utils/react-mdx-loader-plugin.js +0 -45
- package/src/utils/react-runtime-alias-map.d.ts +0 -8
- package/src/utils/react-runtime-alias-map.js +0 -90
- /package/src/{utils → app}/client-only.d.ts +0 -0
- /package/src/{utils → app}/dynamic.d.ts +0 -0
- /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
- /package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +0 -0
- /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
- /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
- /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
- /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
- /package/src/{utils → hmr}/hmr-scripts.d.ts +0 -0
- /package/src/{utils → hydration}/hydration-scripts.test.browser.d.ts +0 -0
- /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
- /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
- /package/src/{utils → render}/html-boundary.d.ts +0 -0
|
@@ -0,0 +1,515 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module ReachabilityAnalyzer
|
|
3
|
+
*
|
|
4
|
+
* This module is responsible for performing static analysis on Ecopages client components
|
|
5
|
+
* using the Oxc AST parser. It computes a strict "reachability graph" of all JavaScript/TypeScript
|
|
6
|
+
* dependencies (imports, variables, functions, and classes) that begin from explicit client roots.
|
|
7
|
+
*
|
|
8
|
+
* In Ecopages, "client roots" are defined as the `render`, `errorBoundary`, or `loadingFallback`
|
|
9
|
+
* properties passed into `eco.page()`, `eco.layout()`, or `eco.component()`. By tracing the execution path from
|
|
10
|
+
* these roots, the analyzer determines exactly which modules and bindings are actually needed
|
|
11
|
+
* by the browser to hydrate the page, and which imports are unused on the client (and thus can be pruned).
|
|
12
|
+
*/
|
|
13
|
+
import { parseModuleSource } from '@ecopages/core/cache';
|
|
14
|
+
/**
|
|
15
|
+
* Analyzes a module using Oxc AST and extracts a strict reachability graph
|
|
16
|
+
* starting from client roots (`render`, `errorBoundary`, `loadingFallback` of `eco.page`, `eco.layout`, or `eco.component`).
|
|
17
|
+
*
|
|
18
|
+
* @param source - Raw source string of the module.
|
|
19
|
+
* @param filename - Absolute or relative path to the module file.
|
|
20
|
+
* @param program - Optional pre-parsed Oxc program AST. When supplied, the
|
|
21
|
+
* internal `parseSync` call is skipped entirely (avoids double-parsing).
|
|
22
|
+
* @param explicitlyRequestedExports - Optional named export filter propagated
|
|
23
|
+
* from a downstream importer when this module is only partially reachable.
|
|
24
|
+
*/
|
|
25
|
+
export function analyzeReachability(source, filename, program, explicitlyRequestedExports) {
|
|
26
|
+
/**
|
|
27
|
+
* AST Resolution
|
|
28
|
+
*
|
|
29
|
+
* If the caller already has a parsed AST (e.g. from a prior `parseSync` call in the same
|
|
30
|
+
* pipeline), we reuse it directly to avoid double-parsing the same source text.
|
|
31
|
+
* Otherwise we parse here and return early with an empty "unanalyzed" result on failure.
|
|
32
|
+
*/
|
|
33
|
+
let resolvedProgram;
|
|
34
|
+
if (program) {
|
|
35
|
+
resolvedProgram = program;
|
|
36
|
+
}
|
|
37
|
+
else {
|
|
38
|
+
let result;
|
|
39
|
+
try {
|
|
40
|
+
result = parseModuleSource(filename, source);
|
|
41
|
+
}
|
|
42
|
+
catch {
|
|
43
|
+
return {
|
|
44
|
+
reachableImports: new Map(),
|
|
45
|
+
reachableDeclarations: new Set(),
|
|
46
|
+
unreachableSideEffectImports: [],
|
|
47
|
+
isFallbackRoots: true,
|
|
48
|
+
analyzed: false,
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
resolvedProgram = result.program;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Top-level statement scan
|
|
55
|
+
*
|
|
56
|
+
* Make a single pass over the top-level AST body to build two indexes:
|
|
57
|
+
*
|
|
58
|
+
* - `topLevelImports`: every `import` declaration found in this module, keyed by specifier.
|
|
59
|
+
* Each entry carries a `bindings` map from local alias → imported name so that later
|
|
60
|
+
* identifier lookups can resolve `import { readFile as rf } from 'node:fs'` correctly.
|
|
61
|
+
*
|
|
62
|
+
* - `topLevelDeclarations`: every locally declared variable, function, or class so that
|
|
63
|
+
* the BFS traversal can follow identifier references into their definition nodes.
|
|
64
|
+
*
|
|
65
|
+
* As declarations are catalogued, `checkPotentialClientRoot()` is called to detect whether
|
|
66
|
+
* any of them are `eco.page(…)` or `eco.component(…)` calls — the seed nodes for the graph.
|
|
67
|
+
*/
|
|
68
|
+
const topLevelImports = [];
|
|
69
|
+
const topLevelDeclarations = new Map();
|
|
70
|
+
const potentialClientRoots = [];
|
|
71
|
+
for (const statement of resolvedProgram.body) {
|
|
72
|
+
if (statement.type === 'ImportDeclaration') {
|
|
73
|
+
if (statement.importKind === 'type') {
|
|
74
|
+
continue;
|
|
75
|
+
}
|
|
76
|
+
const specifier = statement.source.value;
|
|
77
|
+
const bindings = new Map();
|
|
78
|
+
if (!statement.specifiers || statement.specifiers.length === 0) {
|
|
79
|
+
topLevelImports.push({ node: statement, specifier, bindings, isSideEffect: true });
|
|
80
|
+
}
|
|
81
|
+
else {
|
|
82
|
+
for (const spec of statement.specifiers) {
|
|
83
|
+
if (spec.type === 'ImportDefaultSpecifier') {
|
|
84
|
+
bindings.set(spec.local.name, 'default');
|
|
85
|
+
}
|
|
86
|
+
else if (spec.type === 'ImportNamespaceSpecifier') {
|
|
87
|
+
bindings.set(spec.local.name, '*');
|
|
88
|
+
}
|
|
89
|
+
else if (spec.type === 'ImportSpecifier') {
|
|
90
|
+
const importedName = spec.imported.type === 'Identifier' ? spec.imported.name : spec.imported.value;
|
|
91
|
+
bindings.set(spec.local.name, importedName);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
topLevelImports.push({ node: statement, specifier, bindings, isSideEffect: false });
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
else if (statement.type === 'VariableDeclaration') {
|
|
98
|
+
for (const decl of statement.declarations) {
|
|
99
|
+
if (decl.id.type === 'Identifier') {
|
|
100
|
+
topLevelDeclarations.set(decl.id.name, statement);
|
|
101
|
+
checkPotentialClientRoot(decl.init);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
else if (statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration') {
|
|
106
|
+
if (statement.id && statement.id.type === 'Identifier') {
|
|
107
|
+
topLevelDeclarations.set(statement.id.name, statement);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
else if (statement.type === 'ExportNamedDeclaration') {
|
|
111
|
+
if (statement.declaration) {
|
|
112
|
+
const decl = statement.declaration;
|
|
113
|
+
if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
|
|
114
|
+
if (decl.id && decl.id.type === 'Identifier') {
|
|
115
|
+
topLevelDeclarations.set(decl.id.name, statement);
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
else if (decl.type === 'VariableDeclaration') {
|
|
119
|
+
for (const v of decl.declarations) {
|
|
120
|
+
if (v.id.type === 'Identifier') {
|
|
121
|
+
topLevelDeclarations.set(v.id.name, statement);
|
|
122
|
+
checkPotentialClientRoot(v.init);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
else if (statement.type === 'ExportDefaultDeclaration') {
|
|
129
|
+
checkPotentialClientRoot(statement.declaration);
|
|
130
|
+
}
|
|
131
|
+
else if (statement.type === 'ExpressionStatement') {
|
|
132
|
+
checkPotentialClientRoot(statement.expression);
|
|
133
|
+
}
|
|
134
|
+
else if (statement.type === 'ExportAllDeclaration' && statement.source) {
|
|
135
|
+
/**
|
|
136
|
+
* `export * from '...'` unconditionally re-exports every binding from the
|
|
137
|
+
* source module. Because the re-exported bindings do not create local
|
|
138
|
+
* identifiers in this file, the BFS traverser would never encounter them
|
|
139
|
+
* naturally. We therefore always seed these nodes into `potentialClientRoots`
|
|
140
|
+
* so that `traverse` can mark the source specifier as fully reachable ('*').
|
|
141
|
+
*/
|
|
142
|
+
potentialClientRoots.push(statement);
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Inspects a node to determine if it represents an Ecopages client root declaration.
|
|
147
|
+
*
|
|
148
|
+
* @param node - The AST node to inspect.
|
|
149
|
+
*/
|
|
150
|
+
function checkPotentialClientRoot(node) {
|
|
151
|
+
if (!node || typeof node !== 'object')
|
|
152
|
+
return;
|
|
153
|
+
if (node.type === 'CallExpression' &&
|
|
154
|
+
node.callee.type === 'MemberExpression') {
|
|
155
|
+
const obj = node.callee.object;
|
|
156
|
+
const prop = node.callee.property;
|
|
157
|
+
if (obj.type === 'Identifier' &&
|
|
158
|
+
obj.name === 'eco' &&
|
|
159
|
+
prop.type === 'Identifier' &&
|
|
160
|
+
(prop.name === 'page' ||
|
|
161
|
+
prop.name === 'component' ||
|
|
162
|
+
prop.name === 'layout')) {
|
|
163
|
+
potentialClientRoots.push(node.callee);
|
|
164
|
+
const arg = node.arguments[0];
|
|
165
|
+
if (arg && arg.type === 'ObjectExpression') {
|
|
166
|
+
for (const prop of arg.properties) {
|
|
167
|
+
if (prop.type === 'Property' &&
|
|
168
|
+
prop.key.type === 'Identifier') {
|
|
169
|
+
if ([
|
|
170
|
+
'render',
|
|
171
|
+
'errorBoundary',
|
|
172
|
+
'loadingFallback',
|
|
173
|
+
'clientScripts',
|
|
174
|
+
'dependencies',
|
|
175
|
+
].includes(prop.key.name)) {
|
|
176
|
+
potentialClientRoots.push(prop.value);
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
else if (node.type === 'CallExpression' &&
|
|
184
|
+
node.callee.type === 'Identifier' &&
|
|
185
|
+
node.callee.name === 'dynamic') {
|
|
186
|
+
potentialClientRoots.push(node);
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Resolves the externally visible export name from an export specifier.
|
|
191
|
+
*
|
|
192
|
+
* @param specifier - Oxc export specifier node.
|
|
193
|
+
* @returns The exported binding name when available.
|
|
194
|
+
*/
|
|
195
|
+
function getExportedName(specifier) {
|
|
196
|
+
if (specifier?.exported?.type === 'Identifier')
|
|
197
|
+
return specifier.exported.name;
|
|
198
|
+
if (typeof specifier?.exported?.value === 'string')
|
|
199
|
+
return specifier.exported.value;
|
|
200
|
+
if (specifier?.local?.type === 'Identifier')
|
|
201
|
+
return specifier.local.name;
|
|
202
|
+
if (typeof specifier?.local?.value === 'string')
|
|
203
|
+
return specifier.local.value;
|
|
204
|
+
return undefined;
|
|
205
|
+
}
|
|
206
|
+
/**
|
|
207
|
+
* Resolves the imported binding name represented by a re-export specifier.
|
|
208
|
+
*
|
|
209
|
+
* @param specifier - Oxc export specifier node.
|
|
210
|
+
* @returns The source-module binding name that should be marked reachable.
|
|
211
|
+
*/
|
|
212
|
+
function getReexportedImportName(specifier) {
|
|
213
|
+
if (specifier?.local?.type === 'Identifier')
|
|
214
|
+
return specifier.local.name;
|
|
215
|
+
if (typeof specifier?.local?.value === 'string')
|
|
216
|
+
return specifier.local.value;
|
|
217
|
+
if (specifier?.imported?.type === 'Identifier')
|
|
218
|
+
return specifier.imported.name;
|
|
219
|
+
if (typeof specifier?.imported?.value === 'string')
|
|
220
|
+
return specifier.imported.value;
|
|
221
|
+
return getExportedName(specifier);
|
|
222
|
+
}
|
|
223
|
+
/**
|
|
224
|
+
* Resolves the local identifier used by a local export list entry.
|
|
225
|
+
*
|
|
226
|
+
* @param specifier - Oxc export specifier node.
|
|
227
|
+
* @returns The local symbol name referenced by the export list.
|
|
228
|
+
*/
|
|
229
|
+
function getLocalExportName(specifier) {
|
|
230
|
+
if (specifier?.local?.type === 'Identifier')
|
|
231
|
+
return specifier.local.name;
|
|
232
|
+
if (typeof specifier?.local?.value === 'string')
|
|
233
|
+
return specifier.local.value;
|
|
234
|
+
return undefined;
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* Checks whether a named export is part of the explicitly requested subset.
|
|
238
|
+
*
|
|
239
|
+
* @param name - Export name to test.
|
|
240
|
+
* @returns True when the export should seed or continue traversal.
|
|
241
|
+
*/
|
|
242
|
+
function isExplicitlyRequestedExport(name) {
|
|
243
|
+
if (explicitlyRequestedExports === '*')
|
|
244
|
+
return true;
|
|
245
|
+
return explicitlyRequestedExports?.has(name) ?? false;
|
|
246
|
+
}
|
|
247
|
+
/**
|
|
248
|
+
* Client root resolution (fallback mode)
|
|
249
|
+
*
|
|
250
|
+
* If *no* `eco.page`/`eco.component` call was found in the file, we fall back to treating
|
|
251
|
+
* every exported declaration as a potential client root. This covers utility modules that
|
|
252
|
+
* don't use Ecopages conventions (plain React components, shared helpers, etc.)
|
|
253
|
+
*
|
|
254
|
+
* In fallback mode the analysis is intentionally permissive — the `isFallbackRoots` flag
|
|
255
|
+
* propagates to callers so they know not to hard-fail on reachable forbidden imports
|
|
256
|
+
* (since we cannot be 100% certain about the execution boundary).
|
|
257
|
+
*/
|
|
258
|
+
let isFallbackRoots = false;
|
|
259
|
+
if (potentialClientRoots.length === 0) {
|
|
260
|
+
if (explicitlyRequestedExports) {
|
|
261
|
+
for (const node of resolvedProgram.body) {
|
|
262
|
+
if (node.type === 'ExportNamedDeclaration') {
|
|
263
|
+
const exportNode = node;
|
|
264
|
+
if (exportNode.source && exportNode.specifiers?.length) {
|
|
265
|
+
const hasRequestedReexport = exportNode.specifiers.some((specifier) => {
|
|
266
|
+
const exportedName = getExportedName(specifier);
|
|
267
|
+
return exportedName ? isExplicitlyRequestedExport(exportedName) : false;
|
|
268
|
+
});
|
|
269
|
+
if (hasRequestedReexport) {
|
|
270
|
+
potentialClientRoots.push(node);
|
|
271
|
+
}
|
|
272
|
+
continue;
|
|
273
|
+
}
|
|
274
|
+
if (exportNode.declaration?.type === 'FunctionDeclaration' ||
|
|
275
|
+
exportNode.declaration?.type === 'ClassDeclaration') {
|
|
276
|
+
const declarationName = exportNode.declaration.id?.name;
|
|
277
|
+
if (declarationName && isExplicitlyRequestedExport(declarationName)) {
|
|
278
|
+
potentialClientRoots.push(node);
|
|
279
|
+
}
|
|
280
|
+
continue;
|
|
281
|
+
}
|
|
282
|
+
if (exportNode.declaration?.type === 'VariableDeclaration') {
|
|
283
|
+
const hasRequestedDeclaration = exportNode.declaration.declarations.some((declaration) => declaration.id?.type === 'Identifier' &&
|
|
284
|
+
isExplicitlyRequestedExport(declaration.id.name));
|
|
285
|
+
if (hasRequestedDeclaration) {
|
|
286
|
+
potentialClientRoots.push(node);
|
|
287
|
+
}
|
|
288
|
+
continue;
|
|
289
|
+
}
|
|
290
|
+
if (exportNode.specifiers?.length) {
|
|
291
|
+
const hasRequestedSpecifier = exportNode.specifiers.some((specifier) => {
|
|
292
|
+
const exportedName = getExportedName(specifier);
|
|
293
|
+
return exportedName ? isExplicitlyRequestedExport(exportedName) : false;
|
|
294
|
+
});
|
|
295
|
+
if (hasRequestedSpecifier) {
|
|
296
|
+
potentialClientRoots.push(node);
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
else if (node.type === 'ExportDefaultDeclaration') {
|
|
301
|
+
if (isExplicitlyRequestedExport('default')) {
|
|
302
|
+
potentialClientRoots.push(node);
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
else if (node.type === 'ExportAllDeclaration') {
|
|
306
|
+
if (explicitlyRequestedExports === '*') {
|
|
307
|
+
potentialClientRoots.push(node);
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
else {
|
|
313
|
+
isFallbackRoots = true;
|
|
314
|
+
for (const node of resolvedProgram.body) {
|
|
315
|
+
if (node.type === 'ExportNamedDeclaration' ||
|
|
316
|
+
node.type === 'ExportDefaultDeclaration' ||
|
|
317
|
+
node.type === 'ExportAllDeclaration') {
|
|
318
|
+
potentialClientRoots.push(node);
|
|
319
|
+
}
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
/**
|
|
324
|
+
* BFS reachability traversal
|
|
325
|
+
*
|
|
326
|
+
* Starting from the seed nodes collected above, we perform a breadth-first walk of the AST.
|
|
327
|
+
* Every identifier encountered is checked against `topLevelDeclarations` (to enqueue further
|
|
328
|
+
* nodes) and `topLevelImports` (to mark the referenced binding as reachable).
|
|
329
|
+
*
|
|
330
|
+
* `visitedNodes` guards against infinite cycles in recursive or mutually-recursive declarations.
|
|
331
|
+
*/
|
|
332
|
+
const reachableImports = new Map();
|
|
333
|
+
const reachableDeclarations = new Set();
|
|
334
|
+
const queue = [...potentialClientRoots];
|
|
335
|
+
const visitedNodes = new Set();
|
|
336
|
+
/**
|
|
337
|
+
* Registers an imported binding as reachable in the client graph.
|
|
338
|
+
*
|
|
339
|
+
* @param specifier - The module specifier from which the binding is imported.
|
|
340
|
+
* @param importedName - The specific named export being imported, or '*' for namespace imports.
|
|
341
|
+
*/
|
|
342
|
+
function markImportReachable(specifier, importedName) {
|
|
343
|
+
let current = reachableImports.get(specifier);
|
|
344
|
+
if (current === '*')
|
|
345
|
+
return;
|
|
346
|
+
if (importedName === '*') {
|
|
347
|
+
reachableImports.set(specifier, '*');
|
|
348
|
+
}
|
|
349
|
+
else {
|
|
350
|
+
if (!current) {
|
|
351
|
+
current = new Set();
|
|
352
|
+
reachableImports.set(specifier, current);
|
|
353
|
+
}
|
|
354
|
+
current.add(importedName);
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
/**
|
|
358
|
+
* Traces an identifier to its origin declaration, enqueuing it for deep traversal if it resolves
|
|
359
|
+
* to a local module-level declaration, or marking it as a reachable import if it originates from another module.
|
|
360
|
+
*
|
|
361
|
+
* @param name - The identifier name to check.
|
|
362
|
+
*/
|
|
363
|
+
function checkIdentifier(name) {
|
|
364
|
+
if (topLevelDeclarations.has(name)) {
|
|
365
|
+
const declNode = topLevelDeclarations.get(name);
|
|
366
|
+
if (!reachableDeclarations.has(declNode)) {
|
|
367
|
+
reachableDeclarations.add(declNode);
|
|
368
|
+
queue.push(declNode);
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
for (const imp of topLevelImports) {
|
|
372
|
+
if (imp.bindings.has(name)) {
|
|
373
|
+
markImportReachable(imp.specifier, imp.bindings.get(name));
|
|
374
|
+
}
|
|
375
|
+
}
|
|
376
|
+
}
|
|
377
|
+
/**
|
|
378
|
+
* Recursively walks down an AST node to discover referenced variables and function calls,
|
|
379
|
+
* building out the reachability graph.
|
|
380
|
+
*
|
|
381
|
+
* @param node - The Oxc AST node to traverse. Typed as `any` because Oxc lacks a unified iterable node type.
|
|
382
|
+
* @param localScope - A set of identifiers that shadow module-level declarations within the current lexical scope.
|
|
383
|
+
*/
|
|
384
|
+
function traverse(node, localScope) {
|
|
385
|
+
if (!node || typeof node !== 'object')
|
|
386
|
+
return;
|
|
387
|
+
if (visitedNodes.has(node))
|
|
388
|
+
return;
|
|
389
|
+
visitedNodes.add(node);
|
|
390
|
+
if (Array.isArray(node)) {
|
|
391
|
+
for (const child of node)
|
|
392
|
+
traverse(child, localScope);
|
|
393
|
+
return;
|
|
394
|
+
}
|
|
395
|
+
const currentScope = localScope;
|
|
396
|
+
/**
|
|
397
|
+
* `export * from '...'` nodes are seeded into the BFS queue by the top-level scan.
|
|
398
|
+
* When the traverser reaches one here we immediately mark the entire source module
|
|
399
|
+
* as reachable ('*'), then stop — there are no local identifiers to follow.
|
|
400
|
+
*/
|
|
401
|
+
if (node.type === 'ExportAllDeclaration' && typeof node.source?.value === 'string') {
|
|
402
|
+
markImportReachable(node.source.value, '*');
|
|
403
|
+
return;
|
|
404
|
+
}
|
|
405
|
+
if (node.type === 'ExportNamedDeclaration' && typeof node.source?.value === 'string') {
|
|
406
|
+
for (const specifier of node.specifiers ?? []) {
|
|
407
|
+
const importedName = getReexportedImportName(specifier);
|
|
408
|
+
if (importedName) {
|
|
409
|
+
markImportReachable(node.source.value, importedName);
|
|
410
|
+
}
|
|
411
|
+
}
|
|
412
|
+
return;
|
|
413
|
+
}
|
|
414
|
+
if (node.type === 'ExportNamedDeclaration' &&
|
|
415
|
+
!node.source &&
|
|
416
|
+
explicitlyRequestedExports &&
|
|
417
|
+
node.specifiers?.length) {
|
|
418
|
+
for (const specifier of node.specifiers) {
|
|
419
|
+
const exportedName = getExportedName(specifier);
|
|
420
|
+
if (!exportedName || !isExplicitlyRequestedExport(exportedName)) {
|
|
421
|
+
continue;
|
|
422
|
+
}
|
|
423
|
+
const localName = getLocalExportName(specifier);
|
|
424
|
+
if (localName && !currentScope.has(localName)) {
|
|
425
|
+
checkIdentifier(localName);
|
|
426
|
+
}
|
|
427
|
+
}
|
|
428
|
+
return;
|
|
429
|
+
}
|
|
430
|
+
if (node.type === 'Identifier' || (node.type === 'JSXIdentifier' && /^[A-Z]/.test(node.name))) {
|
|
431
|
+
if (!currentScope.has(node.name)) {
|
|
432
|
+
checkIdentifier(node.name);
|
|
433
|
+
}
|
|
434
|
+
}
|
|
435
|
+
else if (node.type === 'MemberExpression') {
|
|
436
|
+
traverse(node.object, currentScope);
|
|
437
|
+
if (node.computed) {
|
|
438
|
+
traverse(node.property, currentScope);
|
|
439
|
+
}
|
|
440
|
+
return;
|
|
441
|
+
}
|
|
442
|
+
else if (node.type === 'Property') {
|
|
443
|
+
if (node.computed)
|
|
444
|
+
traverse(node.key, currentScope);
|
|
445
|
+
traverse(node.value, currentScope);
|
|
446
|
+
return;
|
|
447
|
+
}
|
|
448
|
+
else if (node.type === 'JSXOpeningElement' || node.type === 'JSXClosingElement') {
|
|
449
|
+
traverse(node.name, currentScope);
|
|
450
|
+
if (node.attributes) {
|
|
451
|
+
for (const attr of node.attributes)
|
|
452
|
+
traverse(attr, currentScope);
|
|
453
|
+
}
|
|
454
|
+
return;
|
|
455
|
+
}
|
|
456
|
+
else if (node.type === 'JSXIdentifier') {
|
|
457
|
+
if (/^[A-Z]/.test(node.name) && !currentScope.has(node.name)) {
|
|
458
|
+
checkIdentifier(node.name);
|
|
459
|
+
}
|
|
460
|
+
}
|
|
461
|
+
else if (node.type === 'JSXMemberExpression') {
|
|
462
|
+
traverse(node.object, currentScope);
|
|
463
|
+
return;
|
|
464
|
+
}
|
|
465
|
+
else if (node.type === 'CallExpression' &&
|
|
466
|
+
node.callee.type === 'Identifier' &&
|
|
467
|
+
node.callee.name === 'dynamic') {
|
|
468
|
+
const arg = node.arguments[0];
|
|
469
|
+
if (arg && (arg.type === 'ArrowFunctionExpression' || arg.type === 'FunctionExpression')) {
|
|
470
|
+
const body = arg.body;
|
|
471
|
+
if (body.type === 'ImportExpression' && body.source.type === 'Literal') {
|
|
472
|
+
markImportReachable(body.source.value, '*');
|
|
473
|
+
}
|
|
474
|
+
}
|
|
475
|
+
}
|
|
476
|
+
else if (node.type === 'ImportExpression' && node.source.type === 'Literal') {
|
|
477
|
+
markImportReachable(node.source.value, '*');
|
|
478
|
+
}
|
|
479
|
+
if (node.type === 'ArrowFunctionExpression' ||
|
|
480
|
+
node.type === 'FunctionExpression' ||
|
|
481
|
+
node.type === 'FunctionDeclaration') {
|
|
482
|
+
const newScope = new Set(currentScope);
|
|
483
|
+
if (node.id && node.id.type === 'Identifier')
|
|
484
|
+
newScope.add(node.id.name);
|
|
485
|
+
if (node.params && node.params.items) {
|
|
486
|
+
for (const p of node.params.items) {
|
|
487
|
+
if (p.pattern && p.pattern.type === 'Identifier') {
|
|
488
|
+
newScope.add(p.pattern.name);
|
|
489
|
+
}
|
|
490
|
+
}
|
|
491
|
+
}
|
|
492
|
+
traverse(node.body, newScope);
|
|
493
|
+
return;
|
|
494
|
+
}
|
|
495
|
+
for (const key in node) {
|
|
496
|
+
if (key !== 'type' && key !== 'start' && key !== 'end') {
|
|
497
|
+
traverse(node[key], currentScope);
|
|
498
|
+
}
|
|
499
|
+
}
|
|
500
|
+
}
|
|
501
|
+
while (queue.length > 0) {
|
|
502
|
+
const root = queue.shift();
|
|
503
|
+
traverse(root, new Set());
|
|
504
|
+
}
|
|
505
|
+
const unreachableSideEffectImports = topLevelImports
|
|
506
|
+
.filter((imp) => imp.isSideEffect && !reachableImports.has(imp.specifier))
|
|
507
|
+
.map((imp) => imp.node);
|
|
508
|
+
return {
|
|
509
|
+
reachableImports,
|
|
510
|
+
reachableDeclarations,
|
|
511
|
+
unreachableSideEffectImports,
|
|
512
|
+
isFallbackRoots,
|
|
513
|
+
analyzed: true,
|
|
514
|
+
};
|
|
515
|
+
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Specifier classification and requested-export registry helpers for the client graph boundary.
|
|
3
|
+
*/
|
|
4
|
+
import type { RequestedExportRules } from './boundary-cache.js';
|
|
5
|
+
export declare function isBareSpecifier(specifier: string): boolean;
|
|
6
|
+
export declare function isProjectAliasSpecifier(specifier: string, projectRoot?: string): boolean;
|
|
7
|
+
/**
|
|
8
|
+
* Determines whether a specifier should be treated as server-only.
|
|
9
|
+
*
|
|
10
|
+
* This covers Node built-ins as well as local module conventions such as
|
|
11
|
+
* `.server.ts` and extensionless imports that resolve to `.server.*` files.
|
|
12
|
+
*
|
|
13
|
+
* @param specifier - Raw import specifier from the module source.
|
|
14
|
+
* @returns True when the import must never become client-reachable.
|
|
15
|
+
*/
|
|
16
|
+
export declare function isServerOnlySpecifier(specifier: string): boolean;
|
|
17
|
+
/**
|
|
18
|
+
* Strips down a deep path module specifier to its foundational root package name.
|
|
19
|
+
*
|
|
20
|
+
* When checking against the "allowed modules" whitelist, a component might import something deeply
|
|
21
|
+
* nested like `lodash/fp/map` or `@myorg/ui/button`. However, the user configuration only whitelists
|
|
22
|
+
* the root `lodash` or `@myorg/ui` package. This normalizer ensures we are comparing apples to apples
|
|
23
|
+
* by extracting the base package scope before checking the authorization list.
|
|
24
|
+
*
|
|
25
|
+
* @example
|
|
26
|
+
* toModuleBaseSpecifier('@scope/package/deep/file') -> '@scope/package'
|
|
27
|
+
* toModuleBaseSpecifier('lodash/cloneDeep') -> 'lodash'
|
|
28
|
+
* toModuleBaseSpecifier('node:fs') -> 'node:fs'
|
|
29
|
+
*
|
|
30
|
+
* @param specifier - The raw import specifier from the code.
|
|
31
|
+
* @returns The root package name, preserving scoped npm organizations.
|
|
32
|
+
*/
|
|
33
|
+
export declare function toModuleBaseSpecifier(specifier: string): string;
|
|
34
|
+
/**
|
|
35
|
+
* Parses the grammar syntax of declared modules.
|
|
36
|
+
* Handles patterns like `@pkg/name` and `@pkg/name{namedImport,anotherImport}`
|
|
37
|
+
* returning a map of base packages to their explicitly allowed specifiers.
|
|
38
|
+
*
|
|
39
|
+
* @param moduleDeclarations - A list of module declaration strings.
|
|
40
|
+
* @returns A structured map of allowed packages and their named exports.
|
|
41
|
+
*/
|
|
42
|
+
export declare function parseDeclaredModules(moduleDeclarations: readonly string[] | undefined): Map<string, Set<string> | '*'>;
|
|
43
|
+
/**
|
|
44
|
+
* Merges two declared module maps, combining their allowable specific scopes.
|
|
45
|
+
*
|
|
46
|
+
* @param a - First map of declared modules.
|
|
47
|
+
* @param b - Second map of declared modules to merge into the first.
|
|
48
|
+
* @returns A unified map of both declarations.
|
|
49
|
+
*/
|
|
50
|
+
export declare function mergeDeclaredModulesMap(a: Map<string, Set<string> | '*'>, b: Map<string, Set<string> | '*'>): Map<string, Set<string> | '*'>;
|
|
51
|
+
export declare function normalizeRequestedExportsKey(pathname: string): string;
|
|
52
|
+
/**
|
|
53
|
+
* Resolves a local import specifier into a requested-export registry key.
|
|
54
|
+
*
|
|
55
|
+
* Bare package specifiers and project aliases are intentionally ignored because
|
|
56
|
+
* requested-export propagation is only used for cross-file local reachability.
|
|
57
|
+
*
|
|
58
|
+
* @param importer - Absolute path of the importing module.
|
|
59
|
+
* @param specifier - Raw import or re-export specifier.
|
|
60
|
+
* @returns Registry key for a local dependency, or `undefined` when not applicable.
|
|
61
|
+
*/
|
|
62
|
+
export declare function resolveRequestedExportsKey(importer: string, specifier: string): string | undefined;
|
|
63
|
+
/**
|
|
64
|
+
* Merges newly discovered requested-export rules into the local propagation registry.
|
|
65
|
+
*
|
|
66
|
+
* Once a module is promoted to `'*'`, it stays fully reachable for the remainder
|
|
67
|
+
* of the transform pass.
|
|
68
|
+
*
|
|
69
|
+
* @param registry - Cross-module requested-export registry.
|
|
70
|
+
* @param moduleKey - Normalized local module key.
|
|
71
|
+
* @param rules - Newly observed reachable export rules for the module.
|
|
72
|
+
*/
|
|
73
|
+
export declare function mergeRequestedExportRules(registry: Map<string, RequestedExportRules>, moduleKey: string, rules: Set<string> | '*'): void;
|
|
74
|
+
export declare function snapshotRegistry(registry: Map<string, RequestedExportRules>): Map<string, RequestedExportRules>;
|
|
75
|
+
export declare function diffRequestedExportRules(before: RequestedExportRules | undefined, after: RequestedExportRules): RequestedExportRules | undefined;
|