@ecopages/react 0.9.0 → 0.10.1

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 (41) hide show
  1. package/README.md +12 -22
  2. package/package.json +4 -4
  3. package/src/bundling/bundle.js +16 -9
  4. package/src/client-graph/ast-transform-eco-page.d.ts +14 -1
  5. package/src/client-graph/ast-transform-eco-page.js +60 -13
  6. package/src/client-graph/ast-transform-stripped-imports.js +1 -1
  7. package/src/client-graph/ast-transform-walk-imports.js +1 -1
  8. package/src/client-graph/boundary-plugin.d.ts +19 -0
  9. package/src/client-graph/boundary-plugin.js +51 -12
  10. package/src/client-graph/foreign-boundary-rewrite.d.ts +18 -3
  11. package/src/client-graph/foreign-boundary-rewrite.js +196 -45
  12. package/src/client-graph/foreign-jsx-reach.d.ts +21 -2
  13. package/src/client-graph/foreign-jsx-reach.js +25 -9
  14. package/src/client-graph/foreign-module.d.ts +45 -0
  15. package/src/client-graph/foreign-module.js +132 -0
  16. package/src/client-graph/reachability-client-roots.js +28 -0
  17. package/src/hmr/hmr-strategy.d.ts +3 -0
  18. package/src/hmr/hmr-strategy.js +7 -0
  19. package/src/hydration/browser/foreign-boundary.d.ts +12 -0
  20. package/src/hydration/browser/foreign-boundary.js +19 -0
  21. package/src/hydration/browser/page-hydration-hmr.d.ts +1 -0
  22. package/src/hydration/browser/page-hydration-hmr.js +1 -1
  23. package/src/hydration/browser/page-hydration.d.ts +2 -1
  24. package/src/hydration/browser/page-hydration.js +3 -2
  25. package/src/hydration/hydration-page-entry-source.js +3 -3
  26. package/src/hydration/page-data-manifest.d.ts +22 -1
  27. package/src/hydration/page-data-manifest.js +38 -3
  28. package/src/hydration/page-data-reader.d.ts +2 -1
  29. package/src/hydration/page-data-reader.js +4 -2
  30. package/src/hydration/page-payload.d.ts +6 -15
  31. package/src/hydration/page-payload.js +5 -42
  32. package/src/hydration/serialize-page-data-script.d.ts +4 -4
  33. package/src/hydration/serialize-page-data-script.js +6 -6
  34. package/src/plugin/react.plugin.js +2 -0
  35. package/src/render/component-ownership.d.ts +1 -6
  36. package/src/render/component-ownership.js +0 -3
  37. package/src/render/component-ssr.d.ts +0 -1
  38. package/src/render/component-ssr.js +0 -7
  39. package/src/render/layout-compose.d.ts +16 -8
  40. package/src/render/layout-compose.js +13 -36
  41. package/src/render/react-renderer.js +24 -37
@@ -2,9 +2,11 @@
2
2
  * Source rewrite that gives a React module the boundary of every Eco Component another Integration owns.
3
3
  */
4
4
  import { fileSystem } from '@ecopages/file-system';
5
- import { parseModuleSource, resolveProjectModulePath } from '@ecopages/core/build';
5
+ import { parseModuleSource } from '@ecopages/core/build';
6
6
  import { FOREIGN_BOUNDARY_PACKAGE } from '../bundling/bootstrap-package-paths.js';
7
7
  import { collectLexicalDeclarations, walkScopedReferences } from './scope-walk.js';
8
+ import { resolveLocalModulePath } from './foreign-jsx-reach.js';
9
+ import { exportSpecifierName, FOREIGN_STUB_SCHEME, toForeignStubSpecifier, } from './foreign-module.js';
8
10
  const HELPER_BINDING = '__ecoForeignBoundary';
9
11
  const NAMESPACE_HELPER_BINDING = '__ecoForeignBoundaryNamespace';
10
12
  /** The module variant a React graph imports of a module that another graph also uses and that imports a foreign Component. */
@@ -24,8 +26,7 @@ const SOURCE_FILE = /\.(?:[cm]?[jt]sx?)$/;
24
26
  * an export, so a barrel that re-exports a foreign Component counts as foreign for that name.
25
27
  *
26
28
  * @remarks
27
- * The barrel itself is never rewritten: it may be shared with an entry that needs the Component, and each React
28
- * import site decides for its own bindings. A file without a re-export is not parsed.
29
+ * A file without a re-export is not parsed.
29
30
  */
30
31
  class ForeignExports {
31
32
  options;
@@ -33,12 +34,16 @@ class ForeignExports {
33
34
  constructor(options) {
34
35
  this.options = options;
35
36
  }
37
+ get projectRoot() {
38
+ return this.options.projectRoot;
39
+ }
36
40
  /**
37
41
  * @remarks
38
- * `preserveBarrel` makes {@link resolveProjectModulePath} return the real path, so it is not resolved again.
42
+ * An absolute path counts too: the MDX loader's attribution imports the Components of plain modules by
43
+ * absolute path before this rewrite runs.
39
44
  */
40
45
  resolve(importer, specifier) {
41
- return resolveProjectModulePath(this.options.projectRoot, importer, specifier, { preserveBarrel: true });
46
+ return resolveLocalModulePath(this.options.projectRoot, importer, specifier);
42
47
  }
43
48
  getReexports(filePath) {
44
49
  let nodes = this.reexports.get(filePath);
@@ -91,7 +96,7 @@ class ForeignExports {
91
96
  const target = this.resolve(filePath, node.source.value);
92
97
  if (!target)
93
98
  continue;
94
- if (node.type === 'ImportDeclaration' && this.valueImportOf(node, target)) {
99
+ if (node.type === 'ImportDeclaration' ? this.valueImportOf(node, target) : this.staticModule(target)) {
95
100
  result = true;
96
101
  break;
97
102
  }
@@ -218,6 +223,23 @@ class ForeignExports {
218
223
  (name === undefined || moduleName(specifier.exported) === name) &&
219
224
  this.isForeign(target, moduleName(specifier.local), seen));
220
225
  }
226
+ /** The exports of `filePath` when it is a foreign file with static Components, whose stub React can load. */
227
+ staticModule(filePath) {
228
+ if (!this.options.foreignModuleOf || !this.options.isForeignFile(filePath))
229
+ return undefined;
230
+ const module = this.options.foreignModuleOf(filePath);
231
+ return module && module.identities.size > 0 ? module : undefined;
232
+ }
233
+ /**
234
+ * {@link staticModule} for a rewrite that uses it: the file is reported to `watchFile`, since a change to its
235
+ * exports changes the rewrite.
236
+ */
237
+ stubbedModule(filePath) {
238
+ const module = this.staticModule(filePath);
239
+ if (module)
240
+ this.options.watchFile?.(filePath);
241
+ return module;
242
+ }
221
243
  /** Whether the export `name` of `filePath` is declared by a foreign file; `undefined` asks about any export. */
222
244
  isForeign(filePath, name, seen = new Set()) {
223
245
  if (this.options.isForeignFile(filePath))
@@ -241,71 +263,197 @@ function importSourceOf(node, target, foreignExports) {
241
263
  ? `${specifier}?${VARIANT_QUERY}`
242
264
  : specifier;
243
265
  }
244
- /** The helper that wraps the export `imported` of `target`, or `undefined` when it is not foreign. */
266
+ /**
267
+ * The helper that wraps the export `imported` of `target`, or `undefined` when it is not foreign.
268
+ *
269
+ * @remarks
270
+ * A static Component a barrel re-exports from a stub module is already a boundary; wrapping it again returns it
271
+ * unchanged, since a boundary carries no identity.
272
+ */
245
273
  function boundaryHelperOf(foreignExports, target, imported) {
246
274
  if (foreignExports.isForeign(target, imported))
247
275
  return HELPER_BINDING;
248
276
  return foreignExports.isForeignNamespace(target, imported) ? NAMESPACE_HELPER_BINDING : undefined;
249
277
  }
278
+ /** Adds one named or default specifier of a rewritten import: wrapped when it needs the boundary, kept otherwise. */
279
+ function rewriteNamedSpecifier(specifier, target, foreignExports, uid, valueReads, rewrite) {
280
+ const local = specifier.local.name;
281
+ const imported = specifier.type === 'ImportDefaultSpecifier' ? 'default' : moduleName(specifier.imported);
282
+ const wrapper = valueReads.has(local) ? boundaryHelperOf(foreignExports, target, imported) : undefined;
283
+ if (!wrapper) {
284
+ rewrite.imports.push(`${JSON.stringify(imported)} as ${local}`);
285
+ return;
286
+ }
287
+ rewrite.foreign = true;
288
+ const temporary = `__eco_foreign_${uid()}`;
289
+ rewrite.imports.push(`${JSON.stringify(imported)} as ${temporary}`);
290
+ rewrite.bindings.push(`const ${local} = ${wrapper}(${temporary});`);
291
+ }
292
+ /** Adds a namespace specifier of a rewritten import: wrapped in the proxy when read, kept otherwise. */
293
+ function rewriteNamespaceSpecifier(local, target, from, foreignExports, uid, valueReads, rewrite) {
294
+ if (!valueReads.has(local) || !foreignExports.isForeign(target, undefined)) {
295
+ rewrite.extra.push(`import * as ${local} from ${from};`);
296
+ return;
297
+ }
298
+ rewrite.foreign = true;
299
+ const temporary = `__eco_foreign_${uid()}`;
300
+ rewrite.extra.push(`import * as ${temporary} from ${from};`);
301
+ rewrite.bindings.push(`const ${local} = ${NAMESPACE_HELPER_BINDING}(${temporary});`);
302
+ }
303
+ /** Whether a module's namespace is all static Components, so the stub module can stand for it whole. */
304
+ function isAllStatic(module) {
305
+ return module.values.size === 0 && !module.star;
306
+ }
307
+ /**
308
+ * Rewrites an import of a foreign file with static Components: those come from its stub module, every other value
309
+ * from the file behind the runtime boundary.
310
+ *
311
+ * @remarks
312
+ * A binding that is not a static Component and that the module never reads as a value is dropped with its type
313
+ * specifiers, so an import of Components alone never loads the file. A namespace import takes the stub when the
314
+ * file exports only static Components, and the file with the namespace proxy otherwise.
315
+ */
316
+ function rewriteForeignFileImport(node, module, stubFrom, uid, valueReads) {
317
+ const realFrom = JSON.stringify(node.source.value);
318
+ const stubbed = [];
319
+ const real = [];
320
+ const lines = [];
321
+ const bindings = [];
322
+ for (const specifier of node.specifiers) {
323
+ if (specifier.importKind === 'type')
324
+ continue;
325
+ const local = specifier.local.name;
326
+ if (specifier.type === 'ImportNamespaceSpecifier') {
327
+ if (isAllStatic(module)) {
328
+ lines.push(`import * as ${local} from ${stubFrom};`);
329
+ }
330
+ else if (valueReads.has(local)) {
331
+ const temporary = `__eco_foreign_${uid()}`;
332
+ lines.push(`import * as ${temporary} from ${realFrom};`);
333
+ bindings.push(`const ${local} = ${NAMESPACE_HELPER_BINDING}(${temporary});`);
334
+ }
335
+ continue;
336
+ }
337
+ const imported = specifier.type === 'ImportDefaultSpecifier' ? 'default' : moduleName(specifier.imported);
338
+ if (module.identities.has(imported)) {
339
+ stubbed.push(`${JSON.stringify(imported)} as ${local}`);
340
+ }
341
+ else if (valueReads.has(local)) {
342
+ const temporary = `__eco_foreign_${uid()}`;
343
+ real.push(`${JSON.stringify(imported)} as ${temporary}`);
344
+ bindings.push(`const ${local} = ${HELPER_BINDING}(${temporary});`);
345
+ }
346
+ }
347
+ if (stubbed.length > 0)
348
+ lines.unshift(`import { ${stubbed.join(', ')} } from ${stubFrom};`);
349
+ if (real.length > 0)
350
+ lines.push(`import { ${real.join(', ')} } from ${realFrom};`);
351
+ return [...lines, ...bindings].join(' ');
352
+ }
250
353
  /**
251
354
  * Rewrites an import declaration so each binding that resolves to a foreign Component goes through the boundary.
252
355
  *
253
356
  * @remarks
254
- * The declaration keeps its line: the replacement holds no newline, so positions after it stay valid. Only a
255
- * binding the module reads as a value is wrapped; a type or an unused binding keeps its plain import, so the
256
- * bundler drops it as it would without the rewrite.
357
+ * The declaration keeps its line: the replacement holds no newline, so positions after it stay valid. An import of
358
+ * a foreign file with static Components takes them from its stub module (see {@link rewriteForeignFileImport}).
359
+ * Otherwise only a binding the module reads as a value, and that is not a static Component a barrel already
360
+ * re-exports as a boundary, is wrapped; a type or an unused binding keeps its plain import, so the bundler drops
361
+ * it as it would without the rewrite.
257
362
  */
258
363
  function rewriteImport(node, source, filePath, foreignExports, uid, valueReads) {
259
364
  if (node.importKind === 'type' || !node.specifiers?.length)
260
365
  return undefined;
261
- const target = foreignExports.resolve(filePath, node.source.value);
366
+ const specifier = node.source.value;
367
+ const target = foreignExports.resolve(filePath, specifier);
262
368
  if (!target)
263
369
  return undefined;
370
+ const module = specifier.includes('?') ? undefined : foreignExports.stubbedModule(target);
371
+ if (module) {
372
+ const stubFrom = JSON.stringify(toForeignStubSpecifier(foreignExports.projectRoot, target));
373
+ return rewriteForeignFileImport(node, module, stubFrom, uid, valueReads);
374
+ }
264
375
  const from = JSON.stringify(importSourceOf(node, target, foreignExports));
265
- const imports = [];
266
- const extra = [];
267
- const bindings = [];
268
- let foreign = false;
376
+ const rewrite = { imports: [], extra: [], bindings: [], foreign: false };
269
377
  for (const specifier of node.specifiers) {
270
378
  if (specifier.importKind === 'type') {
271
- imports.push(source.slice(specifier.start, specifier.end));
272
- continue;
379
+ rewrite.imports.push(source.slice(specifier.start, specifier.end));
273
380
  }
274
- const local = specifier.local.name;
275
- if (specifier.type === 'ImportNamespaceSpecifier') {
276
- if (!valueReads.has(local) || !foreignExports.isForeign(target, undefined)) {
277
- extra.push(`import * as ${local} from ${from};`);
278
- continue;
279
- }
280
- foreign = true;
281
- const temporary = `__eco_foreign_${uid()}`;
282
- extra.push(`import * as ${temporary} from ${from};`);
283
- bindings.push(`const ${local} = ${NAMESPACE_HELPER_BINDING}(${temporary});`);
284
- continue;
381
+ else if (specifier.type === 'ImportNamespaceSpecifier') {
382
+ rewriteNamespaceSpecifier(specifier.local.name, target, from, foreignExports, uid, valueReads, rewrite);
285
383
  }
286
- const imported = specifier.type === 'ImportDefaultSpecifier' ? 'default' : moduleName(specifier.imported);
287
- const wrapper = valueReads.has(local) ? boundaryHelperOf(foreignExports, target, imported) : undefined;
288
- if (!wrapper) {
289
- imports.push(`${JSON.stringify(imported)} as ${local}`);
290
- continue;
384
+ else {
385
+ rewriteNamedSpecifier(specifier, target, foreignExports, uid, valueReads, rewrite);
291
386
  }
292
- foreign = true;
293
- const temporary = `__eco_foreign_${uid()}`;
294
- imports.push(`${JSON.stringify(imported)} as ${temporary}`);
295
- bindings.push(`const ${local} = ${wrapper}(${temporary});`);
296
387
  }
297
- if (!foreign)
388
+ if (!rewrite.foreign)
298
389
  return undefined;
299
- const named = imports.length > 0 ? `import { ${imports.join(', ')} } from ${from};` : '';
300
- return [named, ...extra, ...bindings].filter(Boolean).join(' ');
390
+ const named = rewrite.imports.length > 0 ? `import { ${rewrite.imports.join(', ')} } from ${from};` : '';
391
+ return [named, ...rewrite.extra, ...rewrite.bindings].filter(Boolean).join(' ');
301
392
  }
302
- /** The edit one top-level node needs: wrapped bindings, or the variant id for a shared module that reaches a foreign Component. */
393
+ /** {@link rewriteReexport} for `export * from` and `export * as ns from`. */
394
+ function rewriteStarReexport(node, module, stubFrom, realFrom) {
395
+ if (node.exported) {
396
+ return isAllStatic(module)
397
+ ? `export * as ${exportSpecifierName(moduleName(node.exported))} from ${stubFrom};`
398
+ : undefined;
399
+ }
400
+ const components = [...module.identities.keys()].filter((name) => name !== 'default');
401
+ if (components.length === 0)
402
+ return undefined;
403
+ const values = [...module.values].filter((name) => name !== 'default');
404
+ return [
405
+ `export { ${components.map(exportSpecifierName).join(', ')} } from ${stubFrom};`,
406
+ ...(values.length > 0 ? [`export { ${values.map(exportSpecifierName).join(', ')} } from ${realFrom};`] : []),
407
+ ...(module.star ? [`export * from ${realFrom};`] : []),
408
+ ].join(' ');
409
+ }
410
+ /**
411
+ * Rewrites a re-export of a foreign file with static Components, so a barrel never loads the file for them: the
412
+ * Components come from its stub module, every other value from the file.
413
+ *
414
+ * @remarks
415
+ * `export * from` re-exports the stub's Components by name, plus the file's other value names, and the file's own
416
+ * `export *` when it has one, whose names are unknown here: an explicit name wins over a star-exported one, so the
417
+ * file's star does not clash with the stub. `default` is never part of `export *`. `export * as ns from` takes the
418
+ * stub only when the file exports static Components alone. Type-only names are dropped, since the build erases
419
+ * them. A re-export of no static Component, or of a specifier with a query, is left as written.
420
+ */
421
+ function rewriteReexport(node, filePath, foreignExports) {
422
+ const specifier = node.source.value;
423
+ const target = specifier.includes('?') ? undefined : foreignExports.resolve(filePath, specifier);
424
+ const module = target ? foreignExports.stubbedModule(target) : undefined;
425
+ if (!target || !module)
426
+ return undefined;
427
+ const stubFrom = JSON.stringify(toForeignStubSpecifier(foreignExports.projectRoot, target));
428
+ const realFrom = JSON.stringify(specifier);
429
+ if (node.type === 'ExportAllDeclaration')
430
+ return rewriteStarReexport(node, module, stubFrom, realFrom);
431
+ const stubbed = [];
432
+ const real = [];
433
+ for (const exported of node.specifiers) {
434
+ if (exported.exportKind === 'type')
435
+ continue;
436
+ const local = moduleName(exported.local);
437
+ const text = `${exportSpecifierName(local)} as ${exportSpecifierName(moduleName(exported.exported))}`;
438
+ (module.identities.has(local) ? stubbed : real).push(text);
439
+ }
440
+ if (stubbed.length === 0)
441
+ return undefined;
442
+ return [
443
+ `export { ${stubbed.join(', ')} } from ${stubFrom};`,
444
+ ...(real.length > 0 ? [`export { ${real.join(', ')} } from ${realFrom};`] : []),
445
+ ].join(' ');
446
+ }
447
+ /**
448
+ * The edit one top-level node needs: a rewritten import or re-export, or the variant id for a shared module that
449
+ * reaches a foreign Component.
450
+ */
303
451
  function planEdit(node, code, filePath, foreignExports, uid, valueReads) {
304
452
  if (!node.source || (node.importKind ?? node.exportKind) === 'type')
305
453
  return undefined;
306
454
  const replacement = node.type === 'ImportDeclaration'
307
455
  ? rewriteImport(node, code, filePath, foreignExports, uid, valueReads)
308
- : undefined;
456
+ : rewriteReexport(node, filePath, foreignExports);
309
457
  if (replacement !== undefined)
310
458
  return { start: node.start, end: node.end, replacement };
311
459
  const specifier = node.source.value;
@@ -326,13 +474,16 @@ function planEdit(node, code, filePath, foreignExports, uid, valueReads) {
326
474
  *
327
475
  * @remarks
328
476
  * A module without such an import is not touched: the caller gets `undefined`, so a React-only module compiles
329
- * to the same output as before and ships no boundary code. A module already rewritten is returned as `undefined`
330
- * too, since a build can hold more than one instance of the plugin. A namespace import is wrapped in a proxy.
331
- * Dynamic `import()` of a foreign module is left as it is.
477
+ * to the same output as before and ships no boundary code. A module already rewritten, one that imports the
478
+ * boundary package or a stub module, is returned as `undefined` too, since a build can hold more than one
479
+ * instance of the plugin and a second pass would duplicate re-exports. Dynamic `import()` of a foreign module is
480
+ * left as it is.
332
481
  */
333
482
  export function rewriteForeignImports(code, filePath, options) {
334
483
  if (!/\bimport\b|\bexport\b/.test(code) || code.includes(FOREIGN_BOUNDARY_PACKAGE))
335
484
  return undefined;
485
+ if (code.includes(FOREIGN_STUB_SCHEME))
486
+ return undefined;
336
487
  const lang = /\.(?:mdx?)$/.test(filePath) ? 'jsx' : undefined;
337
488
  const { program } = parseModuleSource(filePath, code, lang ? { lang } : {});
338
489
  let counter = 0;
@@ -5,6 +5,16 @@ export type ForeignJsxReachOptions = {
5
5
  /** Every other entry file of the build. */
6
6
  otherEntryFiles: Iterable<string>;
7
7
  isForeignFile: (filePath: string) => boolean;
8
+ /**
9
+ * The source of a module as React's graph compiles it, or `undefined` to keep it; applied on the walks from
10
+ * React entry files only.
11
+ *
12
+ * @remarks
13
+ * React's rewrite points an import of a foreign file's static Components at the file's stub module, which this
14
+ * walk does not follow, so a walk that read the original source would count that file and its imports as reached
15
+ * by React.
16
+ */
17
+ reactModuleSource?: (filePath: string, source: string) => string | undefined;
8
18
  };
9
19
  export type ForeignJsxReach = {
10
20
  /** Foreign files a React entry file reaches. */
@@ -14,12 +24,21 @@ export type ForeignJsxReach = {
14
24
  };
15
25
  /** `filePath` with symbolic links resolved, so paths from the build and from the scan compare equal. */
16
26
  export declare function toRealPath(filePath: string): string;
27
+ /**
28
+ * Resolves a specifier to a local file: a relative or tsconfig path import of the app's own files, or an absolute
29
+ * file path that exists.
30
+ *
31
+ * @remarks
32
+ * Core's grouped content-script entries import each script by its absolute path, so without the absolute case a
33
+ * script reached only through such an entry would be absent from the scan.
34
+ */
35
+ export declare function resolveLocalModulePath(projectRoot: string, fromFile: string, specifier: string): string | undefined;
17
36
  /**
18
37
  * Finds which foreign JSX files React entry files reach and which other entries reach, from static imports.
19
38
  *
20
39
  * @remarks
21
- * It runs before any module loads, so the answer does not depend on load order. Only relative and tsconfig path
22
- * imports of the app's own files are followed; packages are never scanned. A walk from another entry stops at a
40
+ * It runs before any module loads, so the answer does not depend on load order. Only relative, tsconfig path
41
+ * and absolute path imports of the app's own files are followed; packages are never scanned. A walk from another entry stops at a
23
42
  * React entry file, since React's bootstrap entries import their Page or island module.
24
43
  */
25
44
  export declare function scanForeignJsxReach(options: ForeignJsxReachOptions): ForeignJsxReach;
@@ -2,6 +2,7 @@ import { path } from '@ecopages/file-system/path';
2
2
  import { fileSystem } from '@ecopages/file-system';
3
3
  import { parseModuleSource, resolveProjectModulePath } from '@ecopages/core/build';
4
4
  import { compileSync } from '@mdx-js/mdx';
5
+ import { FOREIGN_STUB_SCHEME } from './foreign-module.js';
5
6
  const MDX_SOURCE = /\.mdx?$/;
6
7
  const SCANNED_SOURCE = /\.(?:[cm]?[jt]sx?|mdx?)$/;
7
8
  /** `filePath` with symbolic links resolved, so paths from the build and from the scan compare equal. */
@@ -21,7 +22,7 @@ export function toRealPath(filePath) {
21
22
  * The parser does not read MDX, so an MDX file is compiled first and its output parsed. A file that does not read,
22
23
  * compile or parse has no specifiers.
23
24
  */
24
- function readImportSpecifiers(filePath) {
25
+ function readImportSpecifiers(filePath, moduleSource) {
25
26
  try {
26
27
  let source = fileSystem.readFileSync(filePath);
27
28
  let parsePath = filePath;
@@ -29,6 +30,7 @@ function readImportSpecifiers(filePath) {
29
30
  source = String(compileSync(source, { format: filePath.endsWith('.md') ? 'md' : 'mdx' }));
30
31
  parsePath = `${filePath}.jsx`;
31
32
  }
33
+ source = moduleSource?.(filePath, source) ?? source;
32
34
  const { module } = parseModuleSource(parsePath, source);
33
35
  return [
34
36
  ...module.staticImports.map((entry) => entry.moduleRequest.value),
@@ -48,11 +50,25 @@ function literalSpecifier(source, span) {
48
50
  return undefined;
49
51
  return text.slice(1, -1);
50
52
  }
53
+ /**
54
+ * Resolves a specifier to a local file: a relative or tsconfig path import of the app's own files, or an absolute
55
+ * file path that exists.
56
+ *
57
+ * @remarks
58
+ * Core's grouped content-script entries import each script by its absolute path, so without the absolute case a
59
+ * script reached only through such an entry would be absent from the scan.
60
+ */
61
+ export function resolveLocalModulePath(projectRoot, fromFile, specifier) {
62
+ const filePath = specifier.replace(/[?#].*$/, '');
63
+ if (path.isAbsolute(filePath))
64
+ return fileSystem.exists(filePath) ? filePath : undefined;
65
+ return resolveProjectModulePath(projectRoot, fromFile, specifier, { preserveBarrel: true });
66
+ }
51
67
  /**
52
68
  * Walks the static imports of the app's own source files from `roots`, never into a file in `stopAt`, and
53
69
  * returns each foreign file it reaches with the root that reached it first.
54
70
  */
55
- function collectForeignFiles(roots, stopAt, options) {
71
+ function collectForeignFiles(roots, stopAt, options, moduleSource) {
56
72
  const foreign = new Map();
57
73
  const visited = new Set();
58
74
  const pending = [...roots].map((root) => [root, root]);
@@ -61,10 +77,10 @@ function collectForeignFiles(roots, stopAt, options) {
61
77
  if (visited.has(filePath))
62
78
  continue;
63
79
  visited.add(filePath);
64
- for (const specifier of readImportSpecifiers(filePath)) {
65
- const resolved = resolveProjectModulePath(options.projectRoot, filePath, specifier, {
66
- preserveBarrel: true,
67
- });
80
+ for (const specifier of readImportSpecifiers(filePath, moduleSource)) {
81
+ if (specifier.startsWith(FOREIGN_STUB_SCHEME))
82
+ continue;
83
+ const resolved = resolveLocalModulePath(options.projectRoot, filePath, specifier);
68
84
  if (!resolved || resolved.split('/').includes('node_modules'))
69
85
  continue;
70
86
  const target = toRealPath(resolved);
@@ -82,13 +98,13 @@ function collectForeignFiles(roots, stopAt, options) {
82
98
  * Finds which foreign JSX files React entry files reach and which other entries reach, from static imports.
83
99
  *
84
100
  * @remarks
85
- * It runs before any module loads, so the answer does not depend on load order. Only relative and tsconfig path
86
- * imports of the app's own files are followed; packages are never scanned. A walk from another entry stops at a
101
+ * It runs before any module loads, so the answer does not depend on load order. Only relative, tsconfig path
102
+ * and absolute path imports of the app's own files are followed; packages are never scanned. A walk from another entry stops at a
87
103
  * React entry file, since React's bootstrap entries import their Page or island module.
88
104
  */
89
105
  export function scanForeignJsxReach(options) {
90
106
  return {
91
- react: new Set(collectForeignFiles(options.reactEntryFiles, new Set(), options).keys()),
107
+ react: new Set(collectForeignFiles(options.reactEntryFiles, new Set(), options, options.reactModuleSource).keys()),
92
108
  others: collectForeignFiles(options.otherEntryFiles, options.reactEntryFiles, options),
93
109
  };
94
110
  }
@@ -0,0 +1,45 @@
1
+ import type { ComponentIdentity } from '@ecopages/core';
2
+ /** What React's browser graph needs to know about the exports of a module another Integration owns. */
3
+ export type ForeignModule = {
4
+ /** Exports that are statically an `eco.*()` call, by name: React gets each from the stub module. */
5
+ identities: ReadonlyMap<string, ComponentIdentity>;
6
+ /** Every other value export: React gets it from the module itself, behind the runtime boundary. */
7
+ values: ReadonlySet<string>;
8
+ /** Whether the module also has an `export * from`, whose names are not known without following it. */
9
+ star: boolean;
10
+ };
11
+ /** The specifier scheme of a stub module; the rest of the specifier is the foreign file, relative to the app root. */
12
+ export declare const FOREIGN_STUB_SCHEME = "ecopages-react-foreign-stub:";
13
+ /**
14
+ * The module id a stub specifier resolves to: the specifier behind `\0`, a virtual id no other plugin loads or
15
+ * transforms, and that names no path of the machine that built it.
16
+ */
17
+ export declare const FOREIGN_STUB_ID_PREFIX = "\0ecopages-react-foreign-stub:";
18
+ /** A name as an export or import specifier writes it: bare when it is an identifier, quoted otherwise. */
19
+ export declare function exportSpecifierName(name: string): string;
20
+ /** The specifier React's graph imports the stub module of the foreign file `filePath` with. */
21
+ export declare function toForeignStubSpecifier(projectRoot: string, filePath: string): string;
22
+ /** The foreign file a stub specifier names. */
23
+ export declare function fromForeignStubSpecifier(projectRoot: string, specifier: string): string;
24
+ /**
25
+ * Returns the source of the stub module of a foreign file: one boundary per static Component export, built from
26
+ * its identity, and no import of the file or of anything it imports.
27
+ *
28
+ * @remarks
29
+ * Each boundary comes from `foreignBoundaryReference`, which keeps one boundary type per identity, so a stub that a
30
+ * development transform inlines into several modules still gives React one Component type.
31
+ */
32
+ export declare function createForeignStubSource(module: ForeignModule, boundaryPackage: string): string;
33
+ /**
34
+ * Returns the lookup of a foreign file's exports for React's browser graph.
35
+ *
36
+ * @remarks
37
+ * `rootDir` must be the app root core attributes identities against, so the ids match the ones the server
38
+ * renders. A file is read on each lookup and parsed again only when its source changed, so a development edit is
39
+ * seen without a separate invalidation. A file no Integration owns, or that does not read or parse, has no entry.
40
+ * A destructured export makes the module count as having unknown names, like `export *`.
41
+ */
42
+ export declare function createForeignModuleReader(options: {
43
+ rootDir: string;
44
+ integrationOf: (filePath: string) => string | undefined;
45
+ }): (filePath: string) => ForeignModule | undefined;
@@ -0,0 +1,132 @@
1
+ import { parseModuleSource, readExportedComponentIdentities, toRootRelativePath } from '@ecopages/core/build';
2
+ import { fileSystem } from '@ecopages/file-system';
3
+ import { path } from '@ecopages/file-system/path';
4
+ /** The specifier scheme of a stub module; the rest of the specifier is the foreign file, relative to the app root. */
5
+ export const FOREIGN_STUB_SCHEME = 'ecopages-react-foreign-stub:';
6
+ /**
7
+ * The module id a stub specifier resolves to: the specifier behind `\0`, a virtual id no other plugin loads or
8
+ * transforms, and that names no path of the machine that built it.
9
+ */
10
+ export const FOREIGN_STUB_ID_PREFIX = `\0${FOREIGN_STUB_SCHEME}`;
11
+ /** A name as an export or import specifier writes it: bare when it is an identifier, quoted otherwise. */
12
+ export function exportSpecifierName(name) {
13
+ return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
14
+ }
15
+ /** The specifier React's graph imports the stub module of the foreign file `filePath` with. */
16
+ export function toForeignStubSpecifier(projectRoot, filePath) {
17
+ return `${FOREIGN_STUB_SCHEME}${toRootRelativePath(projectRoot, filePath)}`;
18
+ }
19
+ /** The foreign file a stub specifier names. */
20
+ export function fromForeignStubSpecifier(projectRoot, specifier) {
21
+ return path.resolve(projectRoot, specifier.slice(FOREIGN_STUB_SCHEME.length));
22
+ }
23
+ /**
24
+ * Returns the source of the stub module of a foreign file: one boundary per static Component export, built from
25
+ * its identity, and no import of the file or of anything it imports.
26
+ *
27
+ * @remarks
28
+ * Each boundary comes from `foreignBoundaryReference`, which keeps one boundary type per identity, so a stub that a
29
+ * development transform inlines into several modules still gives React one Component type.
30
+ */
31
+ export function createForeignStubSource(module, boundaryPackage) {
32
+ const lines = [`import { foreignBoundaryReference } from ${JSON.stringify(boundaryPackage)};`];
33
+ const exported = [];
34
+ let index = 0;
35
+ for (const [name, identity] of module.identities) {
36
+ const local = `__eco_stub_${index++}`;
37
+ lines.push(`const ${local} = /* @__PURE__ */ foreignBoundaryReference(${JSON.stringify(identity)});`);
38
+ exported.push(`${local} as ${exportSpecifierName(name)}`);
39
+ }
40
+ lines.push(`export { ${exported.join(', ')} };`);
41
+ return `${lines.join('\n')}\n`;
42
+ }
43
+ /** Declarations the build erases, so they are no value export; an `enum` stays a value. */
44
+ const TYPE_DECLARATIONS = new Set(['TSInterfaceDeclaration', 'TSTypeAliasDeclaration', 'TSModuleDeclaration']);
45
+ function exportName(node) {
46
+ return node.type === 'Identifier' ? node.name : String(node.value);
47
+ }
48
+ /** Adds the names one `export` declaration or specifier list declares; `true` when a name cannot be read. */
49
+ function addNamedExports(node, names) {
50
+ let unknown = false;
51
+ const declaration = node.declaration;
52
+ if (declaration?.type === 'VariableDeclaration') {
53
+ for (const declarator of declaration.declarations) {
54
+ if (declarator.id.type === 'Identifier')
55
+ names.add(declarator.id.name);
56
+ else
57
+ unknown = true;
58
+ }
59
+ }
60
+ else if (declaration?.id?.type === 'Identifier' &&
61
+ !declaration.declare &&
62
+ !TYPE_DECLARATIONS.has(declaration.type)) {
63
+ names.add(declaration.id.name);
64
+ }
65
+ for (const specifier of node.specifiers ?? []) {
66
+ if (specifier.exportKind !== 'type')
67
+ names.add(exportName(specifier.exported));
68
+ }
69
+ return unknown;
70
+ }
71
+ /** The value export names a module declares itself or through `export ... from`, and whether it has an `export *`. */
72
+ function readValueExports(filePath, source) {
73
+ const names = new Set();
74
+ let star = false;
75
+ const { program } = parseModuleSource(filePath, source);
76
+ for (const node of program.body) {
77
+ if (node.type === 'ExportDefaultDeclaration') {
78
+ names.add('default');
79
+ }
80
+ else if (node.type === 'ExportNamedDeclaration' && node.exportKind !== 'type') {
81
+ star = addNamedExports(node, names) || star;
82
+ }
83
+ else if (node.type === 'ExportAllDeclaration' && node.exportKind !== 'type') {
84
+ if (node.exported)
85
+ names.add(exportName(node.exported));
86
+ else
87
+ star = true;
88
+ }
89
+ }
90
+ return { names, star };
91
+ }
92
+ /**
93
+ * Returns the lookup of a foreign file's exports for React's browser graph.
94
+ *
95
+ * @remarks
96
+ * `rootDir` must be the app root core attributes identities against, so the ids match the ones the server
97
+ * renders. A file is read on each lookup and parsed again only when its source changed, so a development edit is
98
+ * seen without a separate invalidation. A file no Integration owns, or that does not read or parse, has no entry.
99
+ * A destructured export makes the module count as having unknown names, like `export *`.
100
+ */
101
+ export function createForeignModuleReader(options) {
102
+ const cache = new Map();
103
+ return (filePath) => {
104
+ const integration = options.integrationOf(filePath);
105
+ if (!integration)
106
+ return undefined;
107
+ let source;
108
+ try {
109
+ source = fileSystem.readFileSync(filePath);
110
+ }
111
+ catch {
112
+ return undefined;
113
+ }
114
+ const cached = cache.get(filePath);
115
+ if (cached?.source === source)
116
+ return cached.module;
117
+ let module;
118
+ try {
119
+ const identities = readExportedComponentIdentities(source, filePath, {
120
+ integration,
121
+ projectRoot: options.rootDir,
122
+ });
123
+ const { names, star } = readValueExports(filePath, source);
124
+ module = { identities, values: new Set([...names].filter((name) => !identities.has(name))), star };
125
+ }
126
+ catch {
127
+ module = undefined;
128
+ }
129
+ cache.set(filePath, { source, module });
130
+ return module;
131
+ };
132
+ }