@ecopages/core 0.2.0-alpha.9 → 0.2.0-beta.1

package/src/build/browser-runtime-manifest.js

@@ -0,0 +1,61 @@
+class BrowserRuntimeManifestConflictError extends Error {
+  specifier;
+  existing;
+  incoming;
+  constructor(specifier, existing, incoming) {
+    super(
+      `Browser runtime asset conflict for ${specifier}: ${existing.owner} maps to ${existing.publicPath}, ${incoming.owner} maps to ${incoming.publicPath}`
+    );
+    this.name = "BrowserRuntimeManifestConflictError";
+    this.specifier = specifier;
+    this.existing = existing;
+    this.incoming = incoming;
+  }
+}
+function normalizeDeclaration(declaration) {
+  return {
+    ...declaration,
+    externals: declaration.externals ?? []
+  };
+}
+function hasCompatibleRuntimeAsset(existing, incoming) {
+  return existing.owner === incoming.owner && existing.importPath === incoming.importPath && existing.publicPath === incoming.publicPath && existing.mode === incoming.mode && arrayEquals(existing.externals, incoming.externals);
+}
+function arrayEquals(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  return left.every((value, index) => value === right[index]);
+}
+function createBrowserRuntimeManifest(declarations = []) {
+  const assets = [];
+  const bySpecifier = /* @__PURE__ */ new Map();
+  for (const declaration of declarations) {
+    const asset = normalizeDeclaration(declaration);
+    const existing = bySpecifier.get(asset.specifier);
+    if (existing) {
+      if (!hasCompatibleRuntimeAsset(existing, asset)) {
+        throw new BrowserRuntimeManifestConflictError(asset.specifier, existing, asset);
+      }
+      continue;
+    }
+    assets.push(asset);
+    bySpecifier.set(asset.specifier, asset);
+  }
+  return {
+    assets,
+    bySpecifier
+  };
+}
+function mergeBrowserRuntimeManifests(...manifests) {
+  return createBrowserRuntimeManifest(manifests.flatMap((manifest) => manifest?.assets ?? []));
+}
+function getBrowserRuntimeSpecifierMap(manifest) {
+  return new Map(manifest.assets.map((asset) => [asset.specifier, asset.publicPath]));
+}
+export {
+  BrowserRuntimeManifestConflictError,
+  createBrowserRuntimeManifest,
+  getBrowserRuntimeSpecifierMap,
+  mergeBrowserRuntimeManifests
+};

package/src/build/browser-runtime-plugin-helpers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared helpers for the browser-runtime plugin.
+ *
+ * @remarks
+ * `createBrowserRuntimePlugin` needs to:
+ *
+ * 1. Escape each specifier for inclusion in a regex filter.
+ * 2. Build a `RegExp` whose alternation matches any of those specifiers.
+ *
+ * These utilities are extracted here so the plugin does not duplicate
+ * the same code path.
+ */
+/**
+ * Escapes a literal specifier for inclusion in a regular expression.
+ *
+ * Only the regex metacharacters are escaped: `. * + ? ^ $ { } ( ) | [ ] \`
+ */
+export declare function escapeRegExp(value: string): string;
+/**
+ * Builds a `RegExp` whose alternation matches any of the keys in
+ * `specifierMap`.
+ *
+ * Returns `null` for an empty map so callers can short-circuit and
+ * avoid registering a no-op `onResolve` / `onLoad` filter.
+ */
+export declare function buildSpecifierFilter(specifierMap: ReadonlyMap<string, string>): RegExp | null;

package/src/build/browser-runtime-plugin-helpers.js

@@ -0,0 +1,14 @@
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildSpecifierFilter(specifierMap) {
+  if (specifierMap.size === 0) {
+    return null;
+  }
+  const alternation = Array.from(specifierMap.keys()).map(escapeRegExp).join("|");
+  return new RegExp(`^(${alternation})$`);
+}
+export {
+  buildSpecifierFilter,
+  escapeRegExp
+};

package/src/build/browser-runtime-plugin.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Unified browser-runtime plugin factory.
+ *
+ * @remarks
+ * Single factory that exposes the union of behaviors for the browser
+ * runtime:
+ *
+ * - `onResolve` for manifest specifiers → mapped public URL, marked external
+ * - `onResolve` for paths starting with `/` whose target is in the manifest's
+ *   public path set → marked external
+ * - `onLoad` for JS/TS files → AST-walking import/export rewrite against the
+ *   manifest specifier set, with a `code.includes(specifier)` fast path
+ *
+ * The plugin object carries the manifest's `specifier → publicPath` map
+ * under `BROWSER_RUNTIME_IMPORT_REWRITE_MAP` so
+ * `collectBrowserRuntimeImportRewriteMap` and the post-build rewriter can
+ * read it without re-walking the manifest.
+ *
+ * This is the single source of truth for browser-runtime plugin behavior.
+ * Per-bundler bridges can treat it as a single plugin.
+ */
+import type { EcoBuildPlugin } from './build-types.js';
+import { type BrowserRuntimeManifest } from './browser-runtime-manifest.js';
+/**
+ * Symbol used to attach the manifest's `specifier → publicPath` map to a
+ * plugin instance. Consumers read it via `getBrowserRuntimeImportRewriteMap`
+ * or `collectBrowserRuntimeImportRewriteMap`.
+ */
+export declare const BROWSER_RUNTIME_IMPORT_REWRITE_MAP: unique symbol;
+/**
+ * Default name used by `createBrowserRuntimePlugin` when the caller
+ * does not provide one.
+ */
+export declare const DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME = "browser-runtime-plugin";
+export type CreateBrowserRuntimePluginOptions = {
+    /** Manifest whose specifier → publicPath entries drive the plugin. */
+    manifest: BrowserRuntimeManifest;
+    /** Stable build plugin name used for deduplication and selective exclusion. */
+    name?: string;
+    /**
+     * Whether alias `onResolve` results should be marked `external`.
+     * Default `true`. Pass `false` to let the bundler try to bundle the
+     * mapped URL.
+     */
+    external?: boolean;
+    /**
+     * Enable source-level AST import/export rewrite via the `onLoad`
+     * hook. Default `true`. Set `false` for alias-only consumers
+     * (e.g. `react`/`react-dom` externals in vendor assets).
+     */
+    rewriteImports?: boolean;
+    /**
+     * Register an `onResolve` for paths starting with `/` whose target
+     * is in the manifest's public path set. Marks them external so the
+     * bundler does not try to resolve them as source modules. Default
+     * `true`.
+     */
+    matchPublicPaths?: boolean;
+};
+/**
+ * Rewrites static ESM import/export specifiers and string-literal dynamic imports
+ * from manifest-owned runtime specifiers to concrete browser public URLs.
+ *
+ * Exposed for the post-build rewriter and for tests.
+ */
+export declare function rewriteBrowserRuntimeImports(code: string, specifierMap: ReadonlyMap<string, string>, filePath?: string): string;
+export declare function getBrowserRuntimeImportRewriteMap(plugin: EcoBuildPlugin): ReadonlyMap<string, string> | undefined;
+export declare function collectBrowserRuntimeImportRewriteMap(plugins: EcoBuildPlugin[] | undefined): ReadonlyMap<string, string>;
+/**
+ * Creates a build plugin that exposes the union of browser-runtime
+ * manifest behaviors (alias resolution, public-path matching, and source
+ * import/export rewrite). See {@link CreateBrowserRuntimePluginOptions}
+ * for per-behavior toggles.
+ *
+ * Returns `null` for an empty manifest so callers can short-circuit
+ * registration without sprinkling `if (plugin)` everywhere.
+ */
+export declare function createBrowserRuntimePlugin(options: CreateBrowserRuntimePluginOptions): EcoBuildPlugin | null;

package/src/build/browser-runtime-plugin.js

@@ -0,0 +1,173 @@
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { cachedParseSync } from "../cache/module-parse-cache.js";
+import { getBrowserRuntimeSpecifierMap } from "./browser-runtime-manifest.js";
+import { buildSpecifierFilter } from "./browser-runtime-plugin-helpers.js";
+const BROWSER_RUNTIME_IMPORT_REWRITE_MAP = /* @__PURE__ */ Symbol.for("ecopages.browserRuntimeImportRewriteMap");
+const DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME = "browser-runtime-plugin";
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object";
+}
+function inferLoaderFromPath(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  switch (extension) {
+    case ".mts":
+    case ".cts":
+    case ".ts":
+      return "ts";
+    case ".tsx":
+      return "tsx";
+    case ".jsx":
+      return "jsx";
+    default:
+      return "js";
+  }
+}
+function queueReplacement(options) {
+  if (!isRecord(options.source) || typeof options.source.value !== "string") {
+    return;
+  }
+  const mappedPath = options.specifierMap.get(options.source.value);
+  if (!mappedPath || typeof options.source.start !== "number" || typeof options.source.end !== "number") {
+    return;
+  }
+  const quote = options.code[options.source.start] === "'" ? "'" : '"';
+  options.edits.push({
+    start: options.source.start,
+    end: options.source.end,
+    replacement: `${quote}${mappedPath}${quote}`
+  });
+}
+function rewriteBrowserRuntimeImports(code, specifierMap, filePath = "browser-runtime-imports.js") {
+  if (specifierMap.size === 0) {
+    return code;
+  }
+  const edits = [];
+  try {
+    const result = cachedParseSync(filePath, code, {
+      sourceType: "module",
+      lang: path.extname(filePath).endsWith("x") ? "tsx" : "ts"
+    });
+    const walk = (node) => {
+      if (!isRecord(node)) {
+        return;
+      }
+      if (node.type === "ImportDeclaration" || node.type === "ExportNamedDeclaration" || node.type === "ExportAllDeclaration") {
+        queueReplacement({ code, source: node.source, specifierMap, edits });
+      }
+      if (node.type === "ImportExpression" && isRecord(node.source)) {
+        if (node.source.type === "StringLiteral" || node.source.type === "Literal") {
+          queueReplacement({ code, source: node.source, specifierMap, edits });
+        }
+      }
+      for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+          for (const child of value) {
+            walk(child);
+          }
+        } else {
+          walk(value);
+        }
+      }
+    };
+    walk(result.program);
+  } catch {
+    return code;
+  }
+  if (edits.length === 0) {
+    return code;
+  }
+  edits.sort((left, right) => right.start - left.start);
+  let rewritten = code;
+  for (const edit of edits) {
+    rewritten = rewritten.slice(0, edit.start) + edit.replacement + rewritten.slice(edit.end);
+  }
+  return rewritten;
+}
+function getBrowserRuntimeImportRewriteMap(plugin) {
+  return plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP];
+}
+function collectBrowserRuntimeImportRewriteMap(plugins) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const plugin of plugins ?? []) {
+    const specifierMap = getBrowserRuntimeImportRewriteMap(plugin);
+    if (!specifierMap) {
+      continue;
+    }
+    for (const [specifier, publicPath] of specifierMap.entries()) {
+      if (!merged.has(specifier)) {
+        merged.set(specifier, publicPath);
+      }
+    }
+  }
+  return merged;
+}
+function createBrowserRuntimePlugin(options) {
+  const { manifest } = options;
+  const specifierMap = getBrowserRuntimeSpecifierMap(manifest);
+  const specifierFilter = buildSpecifierFilter(specifierMap);
+  if (!specifierFilter) {
+    return null;
+  }
+  const external = options.external ?? true;
+  const rewriteImports = options.rewriteImports ?? true;
+  const matchPublicPaths = options.matchPublicPaths ?? true;
+  const publicPathSet = new Set(specifierMap.values());
+  const specifierKeys = Array.from(specifierMap.keys());
+  const plugin = {
+    name: options.name ?? DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME,
+    setup(build) {
+      build.onResolve({ filter: specifierFilter }, (args) => {
+        const mappedPath = specifierMap.get(args.path);
+        if (!mappedPath) {
+          return void 0;
+        }
+        return {
+          path: mappedPath,
+          external
+        };
+      });
+      if (matchPublicPaths) {
+        build.onResolve({ filter: /^\// }, (args) => {
+          if (!publicPathSet.has(args.path)) {
+            return void 0;
+          }
+          return {
+            path: args.path,
+            external: true
+          };
+        });
+      }
+      if (rewriteImports) {
+        build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, (args) => {
+          if (!path.isAbsolute(args.path) || !existsSync(args.path)) {
+            return void 0;
+          }
+          const code = readFileSync(args.path, "utf-8");
+          if (!specifierKeys.some((specifier) => code.includes(specifier))) {
+            return void 0;
+          }
+          const rewritten = rewriteBrowserRuntimeImports(code, specifierMap, args.path);
+          if (rewritten === code) {
+            return void 0;
+          }
+          return {
+            contents: rewritten,
+            loader: inferLoaderFromPath(args.path),
+            resolveDir: path.dirname(args.path)
+          };
+        });
+      }
+    }
+  };
+  plugin[BROWSER_RUNTIME_IMPORT_REWRITE_MAP] = specifierMap;
+  return plugin;
+}
+export {
+  BROWSER_RUNTIME_IMPORT_REWRITE_MAP,
+  DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME,
+  collectBrowserRuntimeImportRewriteMap,
+  createBrowserRuntimePlugin,
+  getBrowserRuntimeImportRewriteMap,
+  rewriteBrowserRuntimeImports
+};