@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.32

package/src/build/rolldown/rolldown-plugin-bridge.js

@@ -1,214 +1,284 @@
-import path from "node:path";
-import { finalizeLoadResultWithSourceTransforms } from "./rolldown-source-transform-pass.js";
-import { escapeRegExp } from "../browser/browser-runtime-plugin-helpers.js";
-const NAMESPACE_SEPARATOR = ":";
+/**
+ * Bundler plugin bridge.
+ *
+ * @remarks
+ * Translates an array of `EcoBuildPlugin` instances (the runtime-agnostic
+ * plugin contract used by Ecopages processors and integrations) into
+ * the bundler's native `Plugin` array. The bridge exposes the same
+ * three hooks (`onResolve`, `onLoad`, `module`) the `EcoBuildPlugin`
+ * contract uses, but maps them to the bundler's `resolveId`/`load`
+ * hooks.
+ *
+ * The shared `EcoBuildPlugin` contract stays the boundary between
+ * integrations and bundler backends.
+ *
+ * **Namespace handling.**
+ *
+ * The shared `EcoBuildPlugin` contract scopes `onResolve`/`onLoad`
+ * handlers with a `namespace` string. The bundler encodes namespaces
+ * into the module id (no separate field). The bridge prepends
+ * `<namespace>:` to the resolved id when the result includes a
+ * namespace, and matches `onLoad`/`onResolve` filters against that
+ * prefix. The bridge strips the prefix before forwarding the id back
+ * to the callback so plugin code keeps seeing the same `path` shape
+ * it did on the historical contract.
+ *
+ * **Plugin ordering is semantically significant.**
+ *
+ * The bundler's `resolveId` and `load` are "first" hooks: the first
+ * plugin that returns a non-null value wins. Because the bridge
+ * translates each `EcoBuildPlugin` into its own bundler plugin and
+ * preserves the array order, the position of each plugin in the
+ * `plugins` array determines its priority:
+ *
+ * - **Index 0** has the highest priority.
+ * - **Last index** has the lowest priority.
+ *
+ * When adding new integrations or processors, ensure security-critical
+ * plugins (e.g. `ecopages-client-graph-boundary`) are placed **before**
+ * general-purpose loaders in the array so they always get first refusal
+ * on every source file.
+ */
+import path from 'node:path';
+import { finalizeLoadResultWithSourceTransforms } from './rolldown-source-transform-pass.js';
+import { escapeRegExp } from '../browser/browser-runtime-plugin-helpers.js';
+const NAMESPACE_SEPARATOR = ':';
 function joinNamespace(namespace, value) {
-  return namespace ? `${namespace}${NAMESPACE_SEPARATOR}${value}` : value;
+    return namespace ? `${namespace}${NAMESPACE_SEPARATOR}${value}` : value;
 }
 function splitNamespace(id) {
-  const separatorIndex = id.indexOf(NAMESPACE_SEPARATOR);
-  if (separatorIndex <= 0) {
-    return { namespace: void 0, path: id };
-  }
-  return {
-    namespace: id.slice(0, separatorIndex),
-    path: id.slice(separatorIndex + 1)
-  };
+    const separatorIndex = id.indexOf(NAMESPACE_SEPARATOR);
+    if (separatorIndex <= 0) {
+        return { namespace: undefined, path: id };
+    }
+    return {
+        namespace: id.slice(0, separatorIndex),
+        path: id.slice(separatorIndex + 1),
+    };
 }
 function inferRolldownModuleTypeFromPath(filePath) {
-  const extension = path.extname(filePath).toLowerCase();
-  switch (extension) {
-    case ".ts":
-      return "ts";
-    case ".tsx":
-      return "tsx";
-    case ".jsx":
-      return "jsx";
-    case ".json":
-      return "json";
-    case ".css":
-      return "css";
-    default:
-      return "js";
-  }
+    const extension = path.extname(filePath).toLowerCase();
+    switch (extension) {
+        case '.ts':
+            return 'ts';
+        case '.tsx':
+            return 'tsx';
+        case '.jsx':
+            return 'jsx';
+        case '.json':
+            return 'json';
+        case '.css':
+            return 'css';
+        default:
+            return 'js';
+    }
 }
 function normalizeRolldownModuleType(loader) {
-  switch (loader) {
-    case "js":
-    case "jsx":
-    case "ts":
-    case "tsx":
-    case "json":
-    case "css":
-    case "text":
-    case "base64":
-    case "dataurl":
-    case "binary":
-    case "empty":
-      return loader;
-    case "global-css":
-    case "local-css":
-      return "css";
-    case "file":
-    case "copy":
-      return "asset";
-    default:
-      return void 0;
-  }
+    switch (loader) {
+        case 'js':
+        case 'jsx':
+        case 'ts':
+        case 'tsx':
+        case 'json':
+        case 'css':
+        case 'text':
+        case 'base64':
+        case 'dataurl':
+        case 'binary':
+        case 'empty':
+            return loader;
+        case 'global-css':
+        case 'local-css':
+            return 'css';
+        case 'file':
+        case 'copy':
+            return 'asset';
+        default:
+            return undefined;
+    }
 }
 function convertLoadResultToModuleSource(result) {
-  if (result.loader === "object" && result.exports && typeof result.exports === "object") {
-    return Object.entries(result.exports).map(
-      ([key, value]) => key === "default" ? `export default ${JSON.stringify(value)};` : `export const ${key} = ${JSON.stringify(value)};`
-    ).join("\n");
-  }
-  return void 0;
+    if (result.loader === 'object' && result.exports && typeof result.exports === 'object') {
+        return Object.entries(result.exports)
+            .map(([key, value]) => key === 'default'
+            ? `export default ${JSON.stringify(value)};`
+            : `export const ${key} = ${JSON.stringify(value)};`)
+            .join('\n');
+    }
+    return undefined;
 }
 function buildIdFilter(filter, namespace) {
-  if (!namespace) {
-    return filter;
-  }
-  return new RegExp(`^${escapeRegExp(namespace)}${NAMESPACE_SEPARATOR}${filter.source.slice(1)}`);
+    if (!namespace) {
+        return filter;
+    }
+    return new RegExp(`^${escapeRegExp(namespace)}${NAMESPACE_SEPARATOR}${filter.source.slice(1)}`);
 }
 function resolvePluginPath(value, importer, contextRoot) {
-  if (path.isAbsolute(value)) {
+    if (path.isAbsolute(value)) {
+        return value;
+    }
+    if (value.startsWith('.') || value.startsWith('..')) {
+        const baseDir = importer ? path.dirname(importer) : contextRoot;
+        return path.resolve(baseDir, value);
+    }
     return value;
-  }
-  if (value.startsWith(".") || value.startsWith("..")) {
-    const baseDir = importer ? path.dirname(importer) : contextRoot;
-    return path.resolve(baseDir, value);
-  }
-  return value;
 }
 function convertPluginOnLoadResult(args, result) {
-  if (!result || typeof result !== "object") {
-    return void 0;
-  }
-  const candidate = result;
-  const { path: sourcePath } = splitNamespace(args.id);
-  const sourceFromExports = convertLoadResultToModuleSource(candidate);
-  if (sourceFromExports) {
-    const description = {
-      code: sourceFromExports,
-      moduleType: "js"
-    };
-    return description;
-  }
-  if (typeof candidate.contents === "string" || candidate.contents instanceof Uint8Array) {
-    const code = typeof candidate.contents === "string" ? candidate.contents : new TextDecoder().decode(candidate.contents);
-    const description = {
-      code,
-      moduleType: normalizeRolldownModuleType(candidate.loader) ?? inferRolldownModuleTypeFromPath(sourcePath)
-    };
-    return description;
-  }
-  return void 0;
+    if (!result || typeof result !== 'object') {
+        return undefined;
+    }
+    const candidate = result;
+    const { path: sourcePath } = splitNamespace(args.id);
+    const sourceFromExports = convertLoadResultToModuleSource(candidate);
+    if (sourceFromExports) {
+        const description = {
+            code: sourceFromExports,
+            moduleType: 'js',
+        };
+        return description;
+    }
+    if (typeof candidate.contents === 'string' || candidate.contents instanceof Uint8Array) {
+        const code = typeof candidate.contents === 'string' ? candidate.contents : new TextDecoder().decode(candidate.contents);
+        const description = {
+            code,
+            moduleType: (normalizeRolldownModuleType(candidate.loader) ??
+                inferRolldownModuleTypeFromPath(sourcePath)),
+        };
+        return description;
+    }
+    return undefined;
 }
 function convertPluginOnResolveResult(result, importer, contextRoot) {
-  if (!result || typeof result !== "object") {
-    return void 0;
-  }
-  const candidate = result;
-  if (typeof candidate.path !== "string" && typeof candidate.namespace !== "string") {
-    if (typeof candidate.external !== "boolean") {
-      return void 0;
-    }
-  }
-  const partial = { id: "" };
-  if (typeof candidate.path === "string") {
-    partial.id = joinNamespace(candidate.namespace, resolvePluginPath(candidate.path, importer, contextRoot));
-  } else if (typeof candidate.namespace === "string") {
-    partial.id = joinNamespace(candidate.namespace, "");
-  }
-  if (typeof candidate.external === "boolean") {
-    partial.external = candidate.external;
-  }
-  return partial;
+    if (!result || typeof result !== 'object') {
+        return undefined;
+    }
+    const candidate = result;
+    if (typeof candidate.path !== 'string' && typeof candidate.namespace !== 'string') {
+        if (typeof candidate.external !== 'boolean') {
+            return undefined;
+        }
+    }
+    const partial = { id: '' };
+    if (typeof candidate.path === 'string') {
+        partial.id = joinNamespace(candidate.namespace, resolvePluginPath(candidate.path, importer, contextRoot));
+    }
+    else if (typeof candidate.namespace === 'string') {
+        partial.id = joinNamespace(candidate.namespace, '');
+    }
+    if (typeof candidate.external === 'boolean') {
+        partial.external = candidate.external;
+    }
+    return partial;
 }
-function createRolldownPluginBridge(plugins, contextRoot, sourceTransforms = []) {
-  if (plugins.length === 0) {
-    return [];
-  }
-  const moduleCounter = { value: 0 };
-  const resolveRegistrations = [];
-  const loadRegistrations = [];
-  const registerResolve = (filter, callback) => {
-    resolveRegistrations.push({ filter, callback });
-  };
-  const registerLoad = (filter, callback) => {
-    loadRegistrations.push({ filter, callback });
-  };
-  const resolveIdHandler = async (source, importer, _extraOptions) => {
-    for (const { filter, callback } of resolveRegistrations) {
-      if (!filter.test(source)) {
-        continue;
-      }
-      const { namespace, path: sourcePath } = splitNamespace(source);
-      const result = await callback({ path: sourcePath, importer, namespace });
-      const converted = convertPluginOnResolveResult(result, importer, contextRoot);
-      if (converted !== void 0) {
-        return converted;
-      }
-    }
-    return void 0;
-  };
-  const loadHandler = async (id) => {
-    let loadResult;
-    for (const { filter, callback } of loadRegistrations) {
-      if (!filter.test(id)) {
-        continue;
-      }
-      const { namespace: namespace2, path: sourcePath2 } = splitNamespace(id);
-      const result = await callback({ path: sourcePath2, namespace: namespace2 });
-      const converted = convertPluginOnLoadResult({ id }, result);
-      if (converted !== void 0) {
-        loadResult = converted;
-        break;
-      }
-    }
-    const { namespace, path: sourcePath } = splitNamespace(id);
-    return finalizeLoadResultWithSourceTransforms({
-      id,
-      namespace,
-      sourcePath,
-      loadResult,
-      sourceTransforms,
-      contextRoot,
-      inferModuleTypeFromPath: (filePath) => inferRolldownModuleTypeFromPath(filePath)
-    });
-  };
-  const plugin = {
-    name: "ecopages-plugin-bridge",
-    buildStart: async () => {
-      resolveRegistrations.length = 0;
-      loadRegistrations.length = 0;
-      moduleCounter.value = 0;
-      for (const ecoPlugin of plugins) {
-        const bridge = {
-          onResolve: (options, callback) => {
-            registerResolve(buildIdFilter(options.filter, options.namespace), callback);
-          },
-          onLoad: (options, callback) => {
-            registerLoad(buildIdFilter(options.filter, options.namespace), callback);
-          },
-          module: (specifier, callback) => {
-            const namespace = `ecopages-module-${moduleCounter.value}`;
-            moduleCounter.value += 1;
-            const filter = new RegExp(`^${escapeRegExp(specifier)}$`);
-            registerResolve(filter, async () => ({
-              path: joinNamespace(namespace, specifier)
-            }));
-            registerLoad(buildIdFilter(/.*/, namespace), async () => callback());
-          }
-        };
-        await ecoPlugin.setup(bridge);
-      }
-    },
-    resolveId: resolveIdHandler,
-    load: loadHandler
-  };
-  return [plugin];
+/**
+ * Creates a Rolldown `Plugin` array that drives the supplied
+ * `EcoBuildPlugin` instances.
+ *
+ * All eco plugins are merged into a single Rolldown plugin to minimize
+ * Rust→JS FFI overhead. Rolldown calls every hook for every module when
+ * there is no static filter, so N separate plugins would cause N
+ * `resolveId` + N `load` calls per module. Consolidating into one
+ * plugin reduces that to 1 call each, with JavaScript-side filtering
+ * routing to the correct eco plugin callback.
+ *
+ * Plugin ordering is preserved: registrations from earlier eco plugins
+ * are checked before registrations from later ones, matching the
+ * original per-plugin priority semantics.
+ *
+ * @remarks
+ * Rolldown re-fires `buildStart` on each build, so registrations and the
+ * virtual-module counter are cleared before every `setup` pass — otherwise
+ * handlers accumulate when bridge plugins are reused.
+ *
+ * @param plugins - `EcoBuildPlugin` instances registered for this build.
+ * @param contextRoot - Project root used to resolve relative load paths.
+ * @param sourceTransforms - Optional app-owned transforms applied after a matching
+ * `onLoad` handler returns module contents. Browser builds pass
+ * {@link getAppSourceTransforms | app source transforms} here so metadata injection
+ * still runs on output rewritten by boundary/runtime plugins. Virtual modules,
+ * CSS, and asset loads are skipped.
+ */
+export function createRolldownPluginBridge(plugins, contextRoot, sourceTransforms = []) {
+    if (plugins.length === 0) {
+        return [];
+    }
+    const moduleCounter = { value: 0 };
+    const resolveRegistrations = [];
+    const loadRegistrations = [];
+    const registerResolve = (filter, callback) => {
+        resolveRegistrations.push({ filter, callback });
+    };
+    const registerLoad = (filter, callback) => {
+        loadRegistrations.push({ filter, callback });
+    };
+    const resolveIdHandler = async (source, importer, _extraOptions) => {
+        for (const { filter, callback } of resolveRegistrations) {
+            if (!filter.test(source)) {
+                continue;
+            }
+            const { namespace, path: sourcePath } = splitNamespace(source);
+            const result = await callback({ path: sourcePath, importer, namespace });
+            const converted = convertPluginOnResolveResult(result, importer, contextRoot);
+            if (converted !== undefined) {
+                return converted;
+            }
+        }
+        return undefined;
+    };
+    const loadHandler = async (id) => {
+        let loadResult;
+        for (const { filter, callback } of loadRegistrations) {
+            if (!filter.test(id)) {
+                continue;
+            }
+            const { namespace, path: sourcePath } = splitNamespace(id);
+            const result = await callback({ path: sourcePath, namespace });
+            const converted = convertPluginOnLoadResult({ id }, result);
+            if (converted !== undefined) {
+                loadResult = converted;
+                break;
+            }
+        }
+        const { namespace, path: sourcePath } = splitNamespace(id);
+        return finalizeLoadResultWithSourceTransforms({
+            id,
+            namespace,
+            sourcePath,
+            loadResult,
+            sourceTransforms,
+            contextRoot,
+            inferModuleTypeFromPath: (filePath) => inferRolldownModuleTypeFromPath(filePath),
+        });
+    };
+    const plugin = {
+        name: 'ecopages-plugin-bridge',
+        buildStart: async () => {
+            resolveRegistrations.length = 0;
+            loadRegistrations.length = 0;
+            moduleCounter.value = 0;
+            for (const ecoPlugin of plugins) {
+                const bridge = {
+                    onResolve: (options, callback) => {
+                        registerResolve(buildIdFilter(options.filter, options.namespace), callback);
+                    },
+                    onLoad: (options, callback) => {
+                        registerLoad(buildIdFilter(options.filter, options.namespace), callback);
+                    },
+                    module: (specifier, callback) => {
+                        const namespace = `ecopages-module-${moduleCounter.value}`;
+                        moduleCounter.value += 1;
+                        const filter = new RegExp(`^${escapeRegExp(specifier)}$`);
+                        registerResolve(filter, async () => ({
+                            path: joinNamespace(namespace, specifier),
+                        }));
+                        registerLoad(buildIdFilter(/.*/, namespace), async () => callback());
+                    },
+                };
+                await ecoPlugin.setup(bridge);
+            }
+        },
+        resolveId: resolveIdHandler,
+        load: loadHandler,
+    };
+    return [plugin];
 }
-export {
-  createRolldownPluginBridge
-};

package/src/build/rolldown/rolldown-source-transform-pass.js

@@ -1,61 +1,70 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import {
-  applySourceTransforms,
-  normalizeTransformId
-} from "../../plugins/source-transform.js";
-const TRANSFORMABLE_SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mdx"]);
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { applySourceTransforms, normalizeTransformId, } from '../../plugins/source-transform.js';
+/**
+ * Standard source extensions eligible for the browser post-load transform pass.
+ *
+ * @remarks
+ * Compound integration templates (for example `.kita.tsx`) still match because
+ * matching uses the final path suffix. Keep this aligned with integration
+ * template extensions registered in app config.
+ */
+const TRANSFORMABLE_SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mdx']);
 function shouldApplySourceTransforms(namespace, sourcePath) {
-  if (namespace !== void 0) {
-    return false;
-  }
-  const normalizedPath = normalizeTransformId(sourcePath);
-  return TRANSFORMABLE_SOURCE_EXTENSIONS.has(path.extname(normalizedPath).toLowerCase());
+    if (namespace !== undefined) {
+        return false;
+    }
+    const normalizedPath = normalizeTransformId(sourcePath);
+    return TRANSFORMABLE_SOURCE_EXTENSIONS.has(path.extname(normalizedPath).toLowerCase());
 }
 function shouldTransformLoadedModule(moduleType) {
-  return moduleType !== "css" && moduleType !== "asset";
+    return moduleType !== 'css' && moduleType !== 'asset';
 }
 function applyTransformsToLoadedSource(sourceTransforms, id, sourcePath, code) {
-  if (sourceTransforms.length === 0) {
-    return code;
-  }
-  return applySourceTransforms(sourceTransforms, code, sourcePath);
+    if (sourceTransforms.length === 0) {
+        return code;
+    }
+    return applySourceTransforms(sourceTransforms, code, sourcePath);
 }
-async function finalizeLoadResultWithSourceTransforms(options) {
-  const { id, namespace, sourcePath, loadResult, sourceTransforms, contextRoot, inferModuleTypeFromPath } = options;
-  if (!shouldApplySourceTransforms(namespace, sourcePath)) {
-    return loadResult;
-  }
-  if (typeof loadResult === "object" && loadResult !== null && "code" in loadResult && typeof loadResult.code === "string") {
-    if (!shouldTransformLoadedModule(loadResult.moduleType)) {
-      return loadResult;
+/**
+ * Runs app-owned source transforms after first-wins `onLoad` plugins produce
+ * module contents for one Rolldown load request.
+ */
+export async function finalizeLoadResultWithSourceTransforms(options) {
+    const { id, namespace, sourcePath, loadResult, sourceTransforms, contextRoot, inferModuleTypeFromPath } = options;
+    if (!shouldApplySourceTransforms(namespace, sourcePath)) {
+        return loadResult;
+    }
+    if (typeof loadResult === 'object' &&
+        loadResult !== null &&
+        'code' in loadResult &&
+        typeof loadResult.code === 'string') {
+        if (!shouldTransformLoadedModule(loadResult.moduleType)) {
+            return loadResult;
+        }
+        const transformedCode = applyTransformsToLoadedSource(sourceTransforms, id, sourcePath, loadResult.code);
+        if (transformedCode === loadResult.code) {
+            return loadResult;
+        }
+        return {
+            code: transformedCode,
+            moduleType: loadResult.moduleType,
+        };
+    }
+    if (loadResult !== undefined || sourceTransforms.length === 0) {
+        return loadResult;
+    }
+    const normalizedPath = path.isAbsolute(sourcePath) ? sourcePath : path.resolve(contextRoot, sourcePath);
+    if (!fileSystem.exists(normalizedPath)) {
+        return loadResult;
     }
-    const transformedCode2 = applyTransformsToLoadedSource(sourceTransforms, id, sourcePath, loadResult.code);
-    if (transformedCode2 === loadResult.code) {
-      return loadResult;
+    const originalCode = fileSystem.readFileSync(normalizedPath);
+    const transformedCode = applyTransformsToLoadedSource(sourceTransforms, id, sourcePath, originalCode);
+    if (transformedCode === originalCode) {
+        return loadResult;
     }
     return {
-      code: transformedCode2,
-      moduleType: loadResult.moduleType
+        code: transformedCode,
+        moduleType: inferModuleTypeFromPath(normalizedPath),
     };
-  }
-  if (loadResult !== void 0 || sourceTransforms.length === 0) {
-    return loadResult;
-  }
-  const normalizedPath = path.isAbsolute(sourcePath) ? sourcePath : path.resolve(contextRoot, sourcePath);
-  if (!fileSystem.exists(normalizedPath)) {
-    return loadResult;
-  }
-  const originalCode = fileSystem.readFileSync(normalizedPath);
-  const transformedCode = applyTransformsToLoadedSource(sourceTransforms, id, sourcePath, originalCode);
-  if (transformedCode === originalCode) {
-    return loadResult;
-  }
-  return {
-    code: transformedCode,
-    moduleType: inferModuleTypeFromPath(normalizedPath)
-  };
 }
-export {
-  finalizeLoadResultWithSourceTransforms
-};