@ecopages/react 0.2.1 → 0.3.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 (173) hide show
  1. package/README.md +178 -35
  2. package/package.json +80 -32
  3. package/src/app/client-only.js +10 -0
  4. package/src/app/dynamic.js +9 -0
  5. package/src/app/dynamic.test.browser.d.ts +1 -0
  6. package/src/app/dynamic.test.browser.js +38 -0
  7. package/src/bundling/bootstrap-package-paths.d.ts +5 -0
  8. package/src/bundling/bootstrap-package-paths.js +5 -0
  9. package/src/bundling/bundle.d.ts +78 -0
  10. package/src/bundling/bundle.js +130 -0
  11. package/src/bundling/runtime-alias-map.d.ts +12 -0
  12. package/src/bundling/runtime-alias-map.js +110 -0
  13. package/src/bundling/runtime-bundle.d.ts +70 -0
  14. package/src/bundling/runtime-bundle.js +233 -0
  15. package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +1 -1
  16. package/src/bundling/runtime-interop-plugin.js +32 -0
  17. package/src/bundling/runtime-mode.d.ts +1 -0
  18. package/src/bundling/runtime-mode.js +10 -0
  19. package/src/bundling/runtime-modules.d.ts +21 -0
  20. package/src/bundling/runtime-modules.js +28 -0
  21. package/src/client-graph/ast-transform-eco-page.d.ts +10 -0
  22. package/src/client-graph/ast-transform-eco-page.js +71 -0
  23. package/src/client-graph/ast-transform-import-edits.d.ts +13 -0
  24. package/src/client-graph/ast-transform-import-edits.js +75 -0
  25. package/src/client-graph/ast-transform-walk-imports.d.ts +20 -0
  26. package/src/client-graph/ast-transform-walk-imports.js +105 -0
  27. package/src/client-graph/ast-transform.d.ts +12 -0
  28. package/src/client-graph/ast-transform.js +91 -0
  29. package/src/client-graph/ast-walk.d.ts +10 -0
  30. package/src/client-graph/ast-walk.js +26 -0
  31. package/src/client-graph/boundary-plugin-read-file-inline.d.ts +7 -0
  32. package/src/client-graph/boundary-plugin-read-file-inline.js +43 -0
  33. package/src/client-graph/boundary-plugin-transform.d.ts +16 -0
  34. package/src/client-graph/boundary-plugin-transform.js +31 -0
  35. package/src/client-graph/boundary-plugin.d.ts +23 -0
  36. package/src/client-graph/boundary-plugin.js +177 -0
  37. package/src/client-graph/component-config-traversal.d.ts +36 -0
  38. package/src/client-graph/component-config-traversal.js +77 -0
  39. package/src/{utils → client-graph}/declared-modules.d.ts +1 -1
  40. package/src/client-graph/declared-modules.js +69 -0
  41. package/src/client-graph/module-classification.d.ts +3 -0
  42. package/src/client-graph/module-classification.js +43 -0
  43. package/src/client-graph/reachability-analyzer.d.ts +26 -0
  44. package/src/client-graph/reachability-analyzer.js +55 -0
  45. package/src/client-graph/reachability-client-roots.d.ts +8 -0
  46. package/src/client-graph/reachability-client-roots.js +59 -0
  47. package/src/client-graph/reachability-export-names.d.ts +5 -0
  48. package/src/client-graph/reachability-export-names.js +34 -0
  49. package/src/client-graph/reachability-fallback-roots.d.ts +3 -0
  50. package/src/client-graph/reachability-fallback-roots.js +71 -0
  51. package/src/client-graph/reachability-preload.d.ts +10 -0
  52. package/src/client-graph/reachability-preload.js +30 -0
  53. package/src/client-graph/reachability-top-level-index.d.ts +14 -0
  54. package/src/client-graph/reachability-top-level-index.js +93 -0
  55. package/src/client-graph/reachability-traverse.d.ts +7 -0
  56. package/src/client-graph/reachability-traverse.js +201 -0
  57. package/src/client-graph/specifier-classification.d.ts +74 -0
  58. package/src/client-graph/specifier-classification.js +191 -0
  59. package/src/content/collection-component-cache.d.ts +25 -0
  60. package/src/content/collection-component-cache.js +62 -0
  61. package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +7 -14
  62. package/src/contracts/router-adapter.js +6 -0
  63. package/src/dev-transform/react-dev-transform-contributor.d.ts +17 -0
  64. package/src/dev-transform/react-dev-transform-contributor.js +22 -0
  65. package/src/hmr/hmr-strategy-process.d.ts +34 -0
  66. package/src/hmr/hmr-strategy-process.js +83 -0
  67. package/src/hmr/hmr-strategy.d.ts +67 -0
  68. package/src/hmr/hmr-strategy.js +306 -0
  69. package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +6 -2
  70. package/src/hmr/page-metadata-cache.js +44 -0
  71. package/src/hmr/react-hmr-dev-transform-plugins.d.ts +22 -0
  72. package/src/hmr/react-hmr-dev-transform-plugins.js +19 -0
  73. package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
  74. package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
  75. package/src/hydration/bootstrap-imports.d.ts +25 -0
  76. package/src/hydration/bootstrap-imports.js +33 -0
  77. package/src/hydration/browser/island-hydration.d.ts +82 -0
  78. package/src/hydration/browser/island-hydration.js +251 -0
  79. package/src/hydration/browser/page-hydration-hmr.d.ts +11 -0
  80. package/src/hydration/browser/page-hydration-hmr.js +56 -0
  81. package/src/hydration/browser/page-hydration-module.d.ts +8 -0
  82. package/src/hydration/browser/page-hydration-module.js +17 -0
  83. package/src/hydration/browser/page-hydration.d.ts +54 -0
  84. package/src/hydration/browser/page-hydration.js +177 -0
  85. package/src/hydration/compiled-page-hydration-options.d.ts +20 -0
  86. package/src/hydration/compiled-page-hydration-options.js +1 -0
  87. package/src/hydration/hydration-asset.d.ts +127 -0
  88. package/src/hydration/hydration-asset.js +379 -0
  89. package/src/hydration/hydration-lifecycle.test.browser.d.ts +1 -0
  90. package/src/hydration/hydration-lifecycle.test.browser.js +461 -0
  91. package/src/hydration/hydration-page-entry-source.d.ts +5 -0
  92. package/src/hydration/hydration-page-entry-source.js +87 -0
  93. package/src/hydration/hydration-script-compiler.d.ts +48 -0
  94. package/src/hydration/hydration-script-compiler.js +213 -0
  95. package/src/hydration/page-data-manifest.d.ts +58 -0
  96. package/src/hydration/page-data-manifest.js +97 -0
  97. package/src/hydration/page-data-reader.d.ts +17 -0
  98. package/src/hydration/page-data-reader.js +31 -0
  99. package/src/hydration/page-payload.d.ts +68 -0
  100. package/src/hydration/page-payload.js +106 -0
  101. package/src/hydration/serialize-page-data-script.d.ts +27 -0
  102. package/src/hydration/serialize-page-data-script.js +30 -0
  103. package/src/mdx/mdx-config-dependency.d.ts +37 -0
  104. package/src/mdx/mdx-config-dependency.js +107 -0
  105. package/src/mdx/mdx-loader-plugin.d.ts +8 -0
  106. package/src/mdx/mdx-loader-plugin.js +11 -0
  107. package/src/page/page-module.d.ts +46 -0
  108. package/src/page/page-module.js +74 -0
  109. package/src/plugin/react.constants.d.ts +1 -0
  110. package/src/plugin/react.constants.js +1 -0
  111. package/src/plugin/react.plugin.d.ts +71 -0
  112. package/src/plugin/react.plugin.js +210 -0
  113. package/src/plugin/react.types.d.ts +106 -0
  114. package/src/plugin/react.types.js +1 -0
  115. package/src/render/component-ownership.d.ts +49 -0
  116. package/src/render/component-ownership.js +47 -0
  117. package/src/render/component-ssr.d.ts +59 -0
  118. package/src/render/component-ssr.js +76 -0
  119. package/src/render/eco-embed.d.ts +11 -0
  120. package/src/render/eco-embed.js +9 -0
  121. package/src/render/errors.d.ts +16 -0
  122. package/src/render/errors.js +23 -0
  123. package/src/render/html-boundary.js +59 -0
  124. package/src/render/layout-compose.d.ts +66 -0
  125. package/src/render/layout-compose.js +134 -0
  126. package/src/render/react-renderer.d.ts +114 -0
  127. package/src/render/react-renderer.js +490 -0
  128. package/src/render/react-runtime.d.ts +13 -0
  129. package/src/render/react-runtime.js +26 -0
  130. package/src/render/unified-layout-composition.d.ts +22 -0
  131. package/src/render/unified-layout-composition.js +31 -0
  132. package/src/runtime/use-sync-external-store-with-selector.d.ts +3 -0
  133. package/src/runtime/use-sync-external-store-with-selector.js +54 -0
  134. package/CHANGELOG.md +0 -29
  135. package/src/react-hmr-strategy.d.ts +0 -148
  136. package/src/react-hmr-strategy.js +0 -313
  137. package/src/react-renderer.d.ts +0 -213
  138. package/src/react-renderer.js +0 -654
  139. package/src/react.plugin.d.ts +0 -147
  140. package/src/react.plugin.js +0 -146
  141. package/src/router-adapter.js +0 -0
  142. package/src/services/react-bundle.service.d.ts +0 -47
  143. package/src/services/react-bundle.service.js +0 -93
  144. package/src/services/react-hmr-page-metadata-cache.js +0 -35
  145. package/src/services/react-hydration-asset.service.d.ts +0 -76
  146. package/src/services/react-hydration-asset.service.js +0 -210
  147. package/src/services/react-page-module.service.d.ts +0 -83
  148. package/src/services/react-page-module.service.js +0 -162
  149. package/src/services/react-runtime-bundle.service.d.ts +0 -40
  150. package/src/services/react-runtime-bundle.service.js +0 -130
  151. package/src/utils/client-graph-boundary-plugin.d.ts +0 -43
  152. package/src/utils/client-graph-boundary-plugin.js +0 -494
  153. package/src/utils/client-only.js +0 -19
  154. package/src/utils/declared-modules.js +0 -59
  155. package/src/utils/dynamic.js +0 -12
  156. package/src/utils/hmr-scripts.d.ts +0 -18
  157. package/src/utils/hmr-scripts.js +0 -31
  158. package/src/utils/html-boundary.js +0 -55
  159. package/src/utils/hydration-scripts.d.ts +0 -86
  160. package/src/utils/hydration-scripts.js +0 -285
  161. package/src/utils/reachability-analyzer.d.ts +0 -66
  162. package/src/utils/reachability-analyzer.js +0 -339
  163. package/src/utils/react-dom-runtime-interop-plugin.js +0 -29
  164. package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
  165. package/src/utils/react-mdx-loader-plugin.js +0 -45
  166. package/src/utils/react-runtime-specifier-map.d.ts +0 -6
  167. package/src/utils/react-runtime-specifier-map.js +0 -37
  168. package/src/utils/use-sync-external-store-shim-plugin.d.ts +0 -5
  169. package/src/utils/use-sync-external-store-shim-plugin.js +0 -41
  170. /package/src/{utils → app}/client-only.d.ts +0 -0
  171. /package/src/{utils → app}/dynamic.d.ts +0 -0
  172. /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
  173. /package/src/{utils → render}/html-boundary.d.ts +0 -0
@@ -0,0 +1,177 @@
1
+ /**
2
+ * @module ClientGraphBoundaryPlugin
3
+ *
4
+ * Build plugin securing the Ecopages isomorphic compilation pipeline.
5
+ */
6
+ import { readFileSync } from 'node:fs';
7
+ import path from 'node:path';
8
+ import { parseDeclaredModules, toModuleBaseSpecifier } from './specifier-classification.js';
9
+ import { classifyClientGraphModule } from './module-classification.js';
10
+ import { transformClientGraphModule } from './boundary-plugin-transform.js';
11
+ const SOURCE_FILE_FILTER = /\.(tsx?|jsx?)$/;
12
+ /**
13
+ * Shares transitive export reachability among boundary plugins in one grouped build.
14
+ *
15
+ * @remarks
16
+ * Grouped entries load one shared copy of each helper, so every entry's root analysis
17
+ * must be visible to whichever boundary plugin transforms that helper first.
18
+ */
19
+ const groupedRequestedExports = new WeakMap();
20
+ const buildRequestedExports = new WeakMap();
21
+ const buildContexts = new WeakMap();
22
+ function getRequestedExports(groupedEntrypointFiles) {
23
+ if (!groupedEntrypointFiles) {
24
+ return new Map();
25
+ }
26
+ const existing = groupedRequestedExports.get(groupedEntrypointFiles);
27
+ if (existing) {
28
+ return existing;
29
+ }
30
+ const requestedExports = new Map();
31
+ groupedRequestedExports.set(groupedEntrypointFiles, requestedExports);
32
+ return requestedExports;
33
+ }
34
+ function normalizeClientGraphBoundaryOptions(options) {
35
+ const absWorkingDir = path.resolve(options?.absWorkingDir ?? process.cwd());
36
+ const projectRoot = options?.projectRoot ? path.resolve(absWorkingDir, options.projectRoot) : undefined;
37
+ const entrypointFile = options?.entrypointFile ? path.resolve(absWorkingDir, options.entrypointFile) : undefined;
38
+ const groupedEntrypointFiles = new Set([entrypointFile, ...(options?.groupedEntrypointFiles ?? [])]
39
+ .filter((filePath) => filePath !== undefined)
40
+ .map((filePath) => path.resolve(absWorkingDir, filePath)));
41
+ const declaredModules = [...(options?.declaredModules ?? [])];
42
+ const groupedDeclaredModules = [...(options?.groupedDeclaredModules ?? declaredModules)];
43
+ const alwaysAllowSpecifiers = [...(options?.alwaysAllowSpecifiers ?? [])];
44
+ const cacheKey = JSON.stringify({
45
+ projectRoot,
46
+ absWorkingDir,
47
+ entrypointFile,
48
+ groupedEntrypointFiles: [...groupedEntrypointFiles].sort(),
49
+ groupedDeclaredModules: [...groupedDeclaredModules].sort(),
50
+ declaredModules: [...declaredModules].sort(),
51
+ alwaysAllowSpecifiers: [...alwaysAllowSpecifiers].sort(),
52
+ });
53
+ return {
54
+ absWorkingDir,
55
+ projectRoot,
56
+ entrypointFile,
57
+ groupedEntrypointFiles,
58
+ groupedDeclaredModules,
59
+ declaredModules,
60
+ alwaysAllowSpecifiers,
61
+ cacheKey,
62
+ };
63
+ }
64
+ function loadClientGraphBoundaryModule(args, options, requestedExports, isEntrypoint = options.entrypointFile === path.resolve(options.absWorkingDir, args.path)) {
65
+ const sourcePath = path.resolve(options.absWorkingDir, args.path);
66
+ if (options.entrypointFile &&
67
+ options.groupedEntrypointFiles.has(sourcePath) &&
68
+ sourcePath !== options.entrypointFile) {
69
+ return undefined;
70
+ }
71
+ const sourceDeclarations = options.entrypointFile && options.groupedEntrypointFiles.has(sourcePath)
72
+ ? options.declaredModules
73
+ : options.groupedDeclaredModules;
74
+ const globallyDeclaredSources = parseDeclaredModules(sourceDeclarations);
75
+ for (const alwaysAllow of options.alwaysAllowSpecifiers) {
76
+ globallyDeclaredSources.set(toModuleBaseSpecifier(alwaysAllow), '*');
77
+ }
78
+ const category = classifyClientGraphModule(args.path, options.projectRoot);
79
+ if (category === 'package' || category === 'vendored' || category === 'virtual') {
80
+ return undefined;
81
+ }
82
+ let source;
83
+ try {
84
+ source = readFileSync(args.path, 'utf-8');
85
+ }
86
+ catch {
87
+ return undefined;
88
+ }
89
+ return transformClientGraphModule({
90
+ filePath: args.path,
91
+ source,
92
+ absWorkingDir: options.absWorkingDir,
93
+ category,
94
+ globallyDeclaredSources,
95
+ requestedExports,
96
+ preserveUnreachableSideEffectImports: !isEntrypoint,
97
+ });
98
+ }
99
+ function resolveEntryImports(entrypointFiles, entrypoint) {
100
+ try {
101
+ const source = readFileSync(entrypoint, 'utf-8');
102
+ const wrapper = /^\s*(?:export\s+\*\s+from|import)\s+(['"])([^'"\n]+)\1\s*;?\s*$/.exec(source);
103
+ const specifier = wrapper?.[2];
104
+ if (!specifier)
105
+ return;
106
+ if (path.isAbsolute(specifier)) {
107
+ entrypointFiles.add(path.resolve(specifier));
108
+ }
109
+ else if (specifier.startsWith('.')) {
110
+ entrypointFiles.add(path.resolve(path.dirname(entrypoint), specifier));
111
+ }
112
+ }
113
+ catch { }
114
+ }
115
+ function getBuildContext(entrypoints, options) {
116
+ const existing = buildContexts.get(entrypoints);
117
+ if (existing)
118
+ return existing;
119
+ const entrypointFiles = new Set(Object.values(entrypoints).map((entry) => path.resolve(options.absWorkingDir, entry)));
120
+ for (const entrypoint of entrypointFiles)
121
+ resolveEntryImports(entrypointFiles, entrypoint);
122
+ const context = {
123
+ configs: [],
124
+ entrypointFiles,
125
+ requestedExports: buildRequestedExports.get(entrypoints) ?? new Map(),
126
+ };
127
+ buildRequestedExports.set(entrypoints, context.requestedExports);
128
+ buildContexts.set(entrypoints, context);
129
+ return context;
130
+ }
131
+ function loadBuildClientGraphBoundaryModule(args, context) {
132
+ const sourcePath = path.resolve(context.configs[0]?.absWorkingDir ?? process.cwd(), args.path);
133
+ const rootConfigs = context.configs.filter((config) => config.entrypointFile === sourcePath);
134
+ const reactEntrypointFiles = new Set(context.configs
135
+ .flatMap((config) => [config.entrypointFile, ...config.groupedEntrypointFiles])
136
+ .filter((filePath) => filePath !== undefined));
137
+ if (context.entrypointFiles.has(sourcePath) && !reactEntrypointFiles.has(sourcePath)) {
138
+ return undefined;
139
+ }
140
+ const first = context.configs[0];
141
+ if (!first)
142
+ return undefined;
143
+ const groupedDeclaredModules = [...new Set(context.configs.flatMap((config) => config.groupedDeclaredModules))];
144
+ const declaredModules = [...new Set(rootConfigs.flatMap((config) => config.declaredModules))];
145
+ const options = {
146
+ ...first,
147
+ entrypointFile: rootConfigs.length > 0 ? sourcePath : undefined,
148
+ groupedEntrypointFiles: reactEntrypointFiles,
149
+ declaredModules,
150
+ groupedDeclaredModules,
151
+ alwaysAllowSpecifiers: [...new Set(context.configs.flatMap((config) => config.alwaysAllowSpecifiers))],
152
+ };
153
+ return loadClientGraphBoundaryModule(args, options, context.requestedExports);
154
+ }
155
+ /**
156
+ * Instantiates the client graph boundary build plugin.
157
+ */
158
+ export function createClientGraphBoundaryPlugin(options) {
159
+ const normalizedOptions = normalizeClientGraphBoundaryOptions(options);
160
+ const requestedExports = getRequestedExports(options?.groupedEntrypointFiles);
161
+ return {
162
+ name: 'ecopages-client-graph-boundary',
163
+ cacheKey: normalizedOptions.cacheKey,
164
+ bundleGroupKey: 'react-client-graph-boundary',
165
+ setup(build) {
166
+ if (!build.entrypoints ||
167
+ (!normalizedOptions.entrypointFile && normalizedOptions.groupedEntrypointFiles.size === 0)) {
168
+ const entrypointFiles = new Set(Object.values(build.entrypoints ?? {}).map((entrypoint) => path.resolve(normalizedOptions.absWorkingDir, entrypoint)));
169
+ build.onLoad({ filter: SOURCE_FILE_FILTER }, (args) => loadClientGraphBoundaryModule(args, normalizedOptions, requestedExports, entrypointFiles.has(path.resolve(normalizedOptions.absWorkingDir, args.path))));
170
+ return;
171
+ }
172
+ const context = getBuildContext(build.entrypoints, normalizedOptions);
173
+ context.configs.push(normalizedOptions);
174
+ build.onLoad({ filter: SOURCE_FILE_FILTER }, (args) => loadBuildClientGraphBoundaryModule(args, context));
175
+ },
176
+ };
177
+ }
@@ -0,0 +1,36 @@
1
+ import type { EcoComponent, EcoComponentConfig } from '@ecopages/core';
2
+ /**
3
+ * Walks a component config tree once, including nested layout configs and
4
+ * dependency component configs.
5
+ *
6
+ * The shared React integration code performs several different analyses over the
7
+ * same config graph. Centralizing the traversal keeps cycle handling and graph
8
+ * shape assumptions in one place instead of repeating them in the renderer and
9
+ * services.
10
+ */
11
+ export declare function walkConfigTree(config: EcoComponentConfig | undefined, visitor: (config: EcoComponentConfig) => void, visited?: Set<EcoComponentConfig>): void;
12
+ /**
13
+ * Walks a forest of root component configs using one shared visited set.
14
+ *
15
+ * This is useful when a page contributes multiple config roots, such as a page
16
+ * config plus a resolved layout config, and duplicate nested nodes should still
17
+ * be processed only once.
18
+ */
19
+ export declare function walkConfigForest(configs: Iterable<EcoComponentConfig | undefined>, visitor: (config: EcoComponentConfig) => void): void;
20
+ /**
21
+ * Collects values from a config tree while preserving the shared traversal and
22
+ * cycle protection behavior used across the React integration.
23
+ */
24
+ export declare function collectFromConfigTree<T>(config: EcoComponentConfig | undefined, collector: (config: EcoComponentConfig) => T[]): T[];
25
+ /**
26
+ * Collects values from multiple config roots with one shared visited set.
27
+ */
28
+ export declare function collectFromConfigForest<T>(configs: Iterable<EcoComponentConfig | undefined>, collector: (config: EcoComponentConfig) => T[]): T[];
29
+ /**
30
+ * Returns true when any node in the config tree matches the predicate.
31
+ */
32
+ export declare function someInConfigTree(config: EcoComponentConfig | undefined, predicate: (config: EcoComponentConfig) => boolean): boolean;
33
+ /**
34
+ * Reads config roots from partial components while tolerating undefined config.
35
+ */
36
+ export declare function getComponentConfigs(components: Partial<EcoComponent>[]): Array<EcoComponentConfig | undefined>;
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Walks a component config tree once, including nested layout configs and
3
+ * dependency component configs.
4
+ *
5
+ * The shared React integration code performs several different analyses over the
6
+ * same config graph. Centralizing the traversal keeps cycle handling and graph
7
+ * shape assumptions in one place instead of repeating them in the renderer and
8
+ * services.
9
+ */
10
+ export function walkConfigTree(config, visitor, visited = new Set()) {
11
+ if (!config || visited.has(config)) {
12
+ return;
13
+ }
14
+ visited.add(config);
15
+ visitor(config);
16
+ for (const layout of config.layouts ?? []) {
17
+ if (layout?.config) {
18
+ walkConfigTree(layout.config, visitor, visited);
19
+ }
20
+ }
21
+ for (const component of config.dependencies?.components ?? []) {
22
+ walkConfigTree(component.config, visitor, visited);
23
+ }
24
+ }
25
+ /**
26
+ * Walks a forest of root component configs using one shared visited set.
27
+ *
28
+ * This is useful when a page contributes multiple config roots, such as a page
29
+ * config plus a resolved layout config, and duplicate nested nodes should still
30
+ * be processed only once.
31
+ */
32
+ export function walkConfigForest(configs, visitor) {
33
+ const visited = new Set();
34
+ for (const config of configs) {
35
+ walkConfigTree(config, visitor, visited);
36
+ }
37
+ }
38
+ /**
39
+ * Collects values from a config tree while preserving the shared traversal and
40
+ * cycle protection behavior used across the React integration.
41
+ */
42
+ export function collectFromConfigTree(config, collector) {
43
+ const values = [];
44
+ walkConfigTree(config, (node) => {
45
+ values.push(...collector(node));
46
+ });
47
+ return values;
48
+ }
49
+ /**
50
+ * Collects values from multiple config roots with one shared visited set.
51
+ */
52
+ export function collectFromConfigForest(configs, collector) {
53
+ const values = [];
54
+ walkConfigForest(configs, (node) => {
55
+ values.push(...collector(node));
56
+ });
57
+ return values;
58
+ }
59
+ /**
60
+ * Returns true when any node in the config tree matches the predicate.
61
+ */
62
+ export function someInConfigTree(config, predicate) {
63
+ let matched = false;
64
+ walkConfigTree(config, (node) => {
65
+ if (matched) {
66
+ return;
67
+ }
68
+ matched = predicate(node);
69
+ });
70
+ return matched;
71
+ }
72
+ /**
73
+ * Reads config roots from partial components while tolerating undefined config.
74
+ */
75
+ export function getComponentConfigs(components) {
76
+ return components.map((component) => component.config);
77
+ }
@@ -29,7 +29,7 @@ export declare function normalizeDeclaredModuleSources(modules?: string[]): stri
29
29
  * Recursively walks a component config tree (including layouts and nested
30
30
  * `dependencies.components`) to collect all declared module sources.
31
31
  */
32
- export declare function collectDeclaredModulesInConfig(config: EcoComponentConfig | undefined, visited?: Set<EcoComponentConfig>): string[];
32
+ export declare function collectDeclaredModulesInConfig(config: EcoComponentConfig | undefined): string[];
33
33
  /**
34
34
  * Collects declared module sources from an already imported page module.
35
35
  */
@@ -0,0 +1,69 @@
1
+ /**
2
+ * Shared utilities for collecting declared module sources from component configs.
3
+ * Used by both the production ReactRenderer and the HMR strategy to ensure
4
+ * the client-graph-boundary plugin receives a consistent set of allowed modules.
5
+ *
6
+ * @module
7
+ */
8
+ import { collectFromConfigTree } from './component-config-traversal.js';
9
+ /**
10
+ * Extracts the module source (package name) from a declared module string,
11
+ * stripping any `{namedImport,...}` grammar.
12
+ *
13
+ * @example
14
+ * parseDeclaredModuleSource('@ecopages/image-processor/component/react{EcoImage}')
15
+ * // → '@ecopages/image-processor/component/react'
16
+ */
17
+ export function parseDeclaredModuleSource(value) {
18
+ const source = value.trim();
19
+ if (source.length === 0)
20
+ return undefined;
21
+ const openBraceIndex = source.indexOf('{');
22
+ if (openBraceIndex < 0)
23
+ return source;
24
+ const from = source.slice(0, openBraceIndex).trim();
25
+ return from.length > 0 ? from : undefined;
26
+ }
27
+ /**
28
+ * Normalizes an array of declared module strings into unique source paths.
29
+ */
30
+ export function normalizeDeclaredModuleSources(modules) {
31
+ const seen = new Set();
32
+ for (const declaration of modules ?? []) {
33
+ const from = parseDeclaredModuleSource(declaration);
34
+ if (from) {
35
+ seen.add(from);
36
+ }
37
+ }
38
+ return Array.from(seen);
39
+ }
40
+ /**
41
+ * Recursively walks a component config tree (including layouts and nested
42
+ * `dependencies.components`) to collect all declared module sources.
43
+ */
44
+ export function collectDeclaredModulesInConfig(config) {
45
+ return collectFromConfigTree(config, (node) => normalizeDeclaredModuleSources(node.dependencies?.modules));
46
+ }
47
+ /**
48
+ * Collects declared module sources from an already imported page module.
49
+ */
50
+ export function collectPageDeclaredModulesFromModule(pageModule) {
51
+ const declarations = [
52
+ ...collectDeclaredModulesInConfig(pageModule.default?.config),
53
+ ...collectDeclaredModulesInConfig(pageModule.config),
54
+ ];
55
+ return Array.from(new Set(declarations));
56
+ }
57
+ /**
58
+ * Imports a page entrypoint and collects all transitively declared module sources
59
+ * from its config, layout config, and nested component configs.
60
+ */
61
+ export async function collectPageDeclaredModules(pagePath) {
62
+ try {
63
+ const pageModule = (await import(/* @vite-ignore */ pagePath));
64
+ return collectPageDeclaredModulesFromModule(pageModule);
65
+ }
66
+ catch {
67
+ return [];
68
+ }
69
+ }
@@ -0,0 +1,3 @@
1
+ export type ClientGraphModuleKind = 'app' | 'workspace' | 'package' | 'vendored' | 'virtual';
2
+ export declare function classifyClientGraphModule(filePath: string, projectRoot?: string): ClientGraphModuleKind;
3
+ export declare function isPageOrLayoutEntry(filePath: string): boolean;
@@ -0,0 +1,43 @@
1
+ import path from 'node:path';
2
+ /**
3
+ * Splits a file path into OS-agnostic segments.
4
+ *
5
+ * @remarks
6
+ * Bundlers may pass POSIX or Windows separators; classification must not depend
7
+ * on the host's `path.sep` alone.
8
+ */
9
+ function pathSegments(filePath) {
10
+ return filePath.split(/[\\/]+/).filter(Boolean);
11
+ }
12
+ function hasPathSegment(filePath, segment) {
13
+ return pathSegments(filePath).includes(segment);
14
+ }
15
+ function hasPathSuffix(filePath, segments) {
16
+ const parts = pathSegments(filePath);
17
+ for (let index = 0; index <= parts.length - segments.length; index += 1) {
18
+ if (segments.every((segment, offset) => parts[index + offset] === segment)) {
19
+ return true;
20
+ }
21
+ }
22
+ return false;
23
+ }
24
+ export function classifyClientGraphModule(filePath, projectRoot) {
25
+ if (filePath.startsWith('\0') || filePath.includes('?'))
26
+ return 'virtual';
27
+ if (hasPathSegment(filePath, 'node_modules'))
28
+ return 'package';
29
+ if (hasPathSegment(filePath, '.eco') || hasPathSuffix(filePath, ['assets', 'vendors']))
30
+ return 'vendored';
31
+ if (projectRoot) {
32
+ const resolvedRoot = path.resolve(projectRoot);
33
+ const resolvedFile = path.resolve(filePath);
34
+ if (resolvedFile === resolvedRoot || resolvedFile.startsWith(`${resolvedRoot}${path.sep}`)) {
35
+ return 'app';
36
+ }
37
+ }
38
+ return 'workspace';
39
+ }
40
+ export function isPageOrLayoutEntry(filePath) {
41
+ const segments = pathSegments(filePath);
42
+ return segments.includes('pages') || segments.includes('layouts');
43
+ }
@@ -0,0 +1,26 @@
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
+ import type { ParseResult } from 'oxc-parser';
9
+ export { hasPagePreloadExport } from './reachability-preload.js';
10
+ import type { ExplicitlyRequestedExports } from './reachability-export-names.js';
11
+ /**
12
+ * Represents the computed results of a reachability analysis pass.
13
+ */
14
+ export type ReachabilityResult = {
15
+ reachableImports: Map<string, Set<string> | '*'>;
16
+ reachableDeclarations: Set<unknown>;
17
+ unreachableSideEffectImports: unknown[];
18
+ isFallbackRoots: boolean;
19
+ analyzed: boolean;
20
+ };
21
+ /**
22
+ * Analyzes a module using Oxc AST and extracts a strict reachability graph
23
+ * starting from client roots: `render`, `errorBoundary`, and `loadingFallback` of
24
+ * `eco.page`, `eco.layout`, or `eco.component`, plus a Page's named `preload` export.
25
+ */
26
+ export declare function analyzeReachability(source: string, filename: string, program?: ParseResult['program'], explicitlyRequestedExports?: ExplicitlyRequestedExports): ReachabilityResult;
@@ -0,0 +1,55 @@
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
+ import { parseModuleSource } from '@ecopages/core/build';
9
+ import { finalizeClientRoots } from './reachability-client-roots.js';
10
+ import { resolveFallbackClientRoots } from './reachability-fallback-roots.js';
11
+ export { hasPagePreloadExport } from './reachability-preload.js';
12
+ import { buildTopLevelIndex } from './reachability-top-level-index.js';
13
+ import { runReachabilityTraversal } from './reachability-traverse.js';
14
+ function emptyReachabilityResult(isFallbackRoots) {
15
+ return {
16
+ reachableImports: new Map(),
17
+ reachableDeclarations: new Set(),
18
+ unreachableSideEffectImports: [],
19
+ isFallbackRoots,
20
+ analyzed: false,
21
+ };
22
+ }
23
+ /**
24
+ * Analyzes a module using Oxc AST and extracts a strict reachability graph
25
+ * starting from client roots: `render`, `errorBoundary`, and `loadingFallback` of
26
+ * `eco.page`, `eco.layout`, or `eco.component`, plus a Page's named `preload` export.
27
+ */
28
+ export function analyzeReachability(source, filename, program, explicitlyRequestedExports) {
29
+ let resolvedProgram;
30
+ if (program) {
31
+ resolvedProgram = program;
32
+ }
33
+ else {
34
+ try {
35
+ resolvedProgram = parseModuleSource(filename, source).program;
36
+ }
37
+ catch {
38
+ return emptyReachabilityResult(true);
39
+ }
40
+ }
41
+ const index = buildTopLevelIndex(resolvedProgram);
42
+ const potentialClientRoots = finalizeClientRoots(index.clientRootState);
43
+ const isFallbackRoots = resolveFallbackClientRoots(resolvedProgram, potentialClientRoots, explicitlyRequestedExports);
44
+ const { reachableImports, reachableDeclarations } = runReachabilityTraversal(potentialClientRoots, index.topLevelImports, index.topLevelDeclarations, explicitlyRequestedExports);
45
+ const unreachableSideEffectImports = index.topLevelImports
46
+ .filter((imp) => imp.isSideEffect && !reachableImports.has(imp.specifier))
47
+ .map((imp) => imp.node);
48
+ return {
49
+ reachableImports,
50
+ reachableDeclarations,
51
+ unreachableSideEffectImports,
52
+ isFallbackRoots,
53
+ analyzed: true,
54
+ };
55
+ }
@@ -0,0 +1,8 @@
1
+ export type ClientRootScanState = {
2
+ potentialClientRoots: unknown[];
3
+ pagePreloadRoots: unknown[];
4
+ hasEcoPageRoot: boolean;
5
+ };
6
+ export declare function createClientRootScanState(): ClientRootScanState;
7
+ export declare function checkPotentialClientRoot(node: unknown, state: ClientRootScanState): void;
8
+ export declare function finalizeClientRoots(state: ClientRootScanState): unknown[];
@@ -0,0 +1,59 @@
1
+ export function createClientRootScanState() {
2
+ return {
3
+ potentialClientRoots: [],
4
+ pagePreloadRoots: [],
5
+ hasEcoPageRoot: false,
6
+ };
7
+ }
8
+ function collectEcoPageClientProperties(arg, state) {
9
+ if (!arg || arg.type !== 'ObjectExpression')
10
+ return;
11
+ for (const prop of arg.properties ?? []) {
12
+ if (prop?.type === 'Property' && prop.key?.type === 'Identifier') {
13
+ if (['render', 'errorBoundary', 'loadingFallback', 'clientScripts'].includes(prop.key.name)) {
14
+ state.potentialClientRoots.push(prop.value);
15
+ }
16
+ }
17
+ }
18
+ }
19
+ function inspectEcoMemberCall(node, state) {
20
+ const propName = node.callee.property?.name;
21
+ if (propName === 'page') {
22
+ state.hasEcoPageRoot = true;
23
+ }
24
+ state.potentialClientRoots.push(node.callee);
25
+ collectEcoPageClientProperties(node.arguments?.[0], state);
26
+ }
27
+ /**
28
+ * Inspects a node to determine if it represents an Ecopages client root declaration.
29
+ */
30
+ function isEcoFactoryCall(node) {
31
+ if (node.callee?.type !== 'MemberExpression')
32
+ return false;
33
+ const obj = node.callee.object;
34
+ const prop = node.callee.property;
35
+ return (obj?.type === 'Identifier' &&
36
+ obj.name === 'eco' &&
37
+ prop?.type === 'Identifier' &&
38
+ (prop.name === 'page' || prop.name === 'component' || prop.name === 'layout'));
39
+ }
40
+ export function checkPotentialClientRoot(node, state) {
41
+ if (!node || typeof node !== 'object')
42
+ return;
43
+ const astNode = node;
44
+ if (astNode.type === 'CallExpression' && isEcoFactoryCall(astNode)) {
45
+ inspectEcoMemberCall(astNode, state);
46
+ return;
47
+ }
48
+ if (astNode.type === 'CallExpression' &&
49
+ astNode.callee?.type === 'Identifier' &&
50
+ astNode.callee.name === 'dynamic') {
51
+ state.potentialClientRoots.push(node);
52
+ }
53
+ }
54
+ export function finalizeClientRoots(state) {
55
+ if (state.hasEcoPageRoot) {
56
+ state.potentialClientRoots.push(...state.pagePreloadRoots);
57
+ }
58
+ return state.potentialClientRoots;
59
+ }
@@ -0,0 +1,5 @@
1
+ export type ExplicitlyRequestedExports = Set<string> | '*';
2
+ export declare function isExplicitlyRequestedExport(name: string, explicitlyRequestedExports?: ExplicitlyRequestedExports): boolean;
3
+ export declare function getExportedName(specifier: any): string | undefined;
4
+ export declare function getReexportedImportName(specifier: any): string | undefined;
5
+ export declare function getLocalExportName(specifier: any): string | undefined;
@@ -0,0 +1,34 @@
1
+ export function isExplicitlyRequestedExport(name, explicitlyRequestedExports) {
2
+ if (explicitlyRequestedExports === '*')
3
+ return true;
4
+ return explicitlyRequestedExports?.has(name) ?? false;
5
+ }
6
+ export function getExportedName(specifier) {
7
+ if (specifier?.exported?.type === 'Identifier')
8
+ return specifier.exported.name;
9
+ if (typeof specifier?.exported?.value === 'string')
10
+ return specifier.exported.value;
11
+ if (specifier?.local?.type === 'Identifier')
12
+ return specifier.local.name;
13
+ if (typeof specifier?.local?.value === 'string')
14
+ return specifier.local.value;
15
+ return undefined;
16
+ }
17
+ export function getReexportedImportName(specifier) {
18
+ if (specifier?.local?.type === 'Identifier')
19
+ return specifier.local.name;
20
+ if (typeof specifier?.local?.value === 'string')
21
+ return specifier.local.value;
22
+ if (specifier?.imported?.type === 'Identifier')
23
+ return specifier.imported.name;
24
+ if (typeof specifier?.imported?.value === 'string')
25
+ return specifier.imported.value;
26
+ return getExportedName(specifier);
27
+ }
28
+ export function getLocalExportName(specifier) {
29
+ if (specifier?.local?.type === 'Identifier')
30
+ return specifier.local.name;
31
+ if (typeof specifier?.local?.value === 'string')
32
+ return specifier.local.value;
33
+ return undefined;
34
+ }
@@ -0,0 +1,3 @@
1
+ import type { ParseResult } from 'oxc-parser';
2
+ import { type ExplicitlyRequestedExports } from './reachability-export-names.js';
3
+ export declare function resolveFallbackClientRoots(program: ParseResult['program'], potentialClientRoots: unknown[], explicitlyRequestedExports?: ExplicitlyRequestedExports): boolean;