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

package/src/plugins/processor.js

@@ -1,160 +1,170 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { DEFAULT_ECOPAGES_WORK_DIR } from "../config/constants.js";
-import { GENERATED_BASE_PATHS } from "../config/constants.js";
-import { deepMerge } from "../utils/deep-merge.js";
-const PROCESSOR_ERRORS = {
-  CACHE_DIRECTORY_NOT_SET: "Cache directory not set in context"
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { DEFAULT_ECOPAGES_WORK_DIR } from '../config/constants.js';
+import { GENERATED_BASE_PATHS } from '../config/constants.js';
+import { deepMerge } from '../utils/deep-merge.js';
+export const PROCESSOR_ERRORS = {
+    CACHE_DIRECTORY_NOT_SET: 'Cache directory not set in context',
 };
-function mergeProcessorOptions(defaults, overrides) {
-  return deepMerge(defaults, overrides);
+export function mergeProcessorOptions(defaults, overrides) {
+    return deepMerge(defaults, overrides);
 }
-function resolveGeneratedPath(type, options) {
-  const { root, module, subPath } = options;
-  const parts = [root, GENERATED_BASE_PATHS[type], module, subPath].filter(Boolean);
-  return path.join(...parts);
+export function resolveGeneratedPath(type, options) {
+    const { root, module, subPath } = options;
+    const parts = [root, GENERATED_BASE_PATHS[type], module, subPath].filter(Boolean);
+    return path.join(...parts);
 }
-class Processor {
-  name;
-  context;
-  options;
-  watchConfig;
-  capabilities = [];
-  runtimeCapability;
-  constructor(config) {
-    this.name = config.name;
-    this.options = config.options;
-    this.watchConfig = config.watch;
-    this.capabilities = config.capabilities ?? [];
-    this.runtimeCapability = config.runtimeCapability;
-  }
-  setContext(appConfig) {
-    const workDir = appConfig.absolutePaths.workDir ?? path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
-    const cachePath = resolveGeneratedPath("cache", {
-      root: workDir,
-      module: this.name
-    });
-    fileSystem.ensureDir(cachePath);
-    this.context = {
-      config: appConfig,
-      rootDir: appConfig.rootDir,
-      srcDir: appConfig.absolutePaths.srcDir,
-      distDir: appConfig.absolutePaths.distDir,
-      cache: cachePath
-    };
-  }
-  /**
-   * Prepares build-facing processor contributions before config finalization.
-   *
-   * @remarks
-   * Override this when a processor must compute runtime/build plugins or other
-   * manifest-owned state before startup. Runtime-only work such as cache
-   * warming or watcher registration should stay in `setup()`.
-   */
-  async prepareBuildContributions() {
-  }
-  /**
-   * Reports whether this processor's build inputs changed since the last
-   * incremental static build.
-   *
-   * @remarks
-   * No shipped processor overrides this today. Integrations and processors can
-   * opt in when they own build inputs that should invalidate incremental static
-   * exports without a full rebuild.
-   */
-  didChange() {
-    return false;
-  }
-  /**
-   * Releases runtime resources owned by the processor.
-   *
-   * @remarks
-   * Core does not call this hook today. Override only when a processor owns
-   * watchers, compiler handles, or other resources that outlive individual
-   * requests.
-   */
-  async teardown() {
-  }
-  getCachePath(key) {
-    return `${this.context?.cache}/${key}`;
-  }
-  async readCache(key) {
-    const cachePath = this.getCachePath(key);
-    try {
-      const data = await fileSystem.readFile(cachePath);
-      return JSON.parse(data);
-    } catch {
-      return null;
+/**
+ * Base class for content and asset processors that contribute build plugins.
+ *
+ * @remarks
+ * Processors declare plugins through two getters that map to
+ * {@link AppBuildManifest} buckets (names differ from integrations):
+ *
+ * - `plugins` → `runtimePlugins` (server **and** browser builds)
+ * - `buildPlugins` → `browserBundlePlugins` (browser bundles only)
+ *
+ * Virtual modules that must resolve during route-module transpile belong in
+ * `plugins`. Browser-only bundler hooks belong in `buildPlugins`.
+ */
+export class Processor {
+    name;
+    context;
+    options;
+    watchConfig;
+    capabilities = [];
+    runtimeCapability;
+    constructor(config) {
+        this.name = config.name;
+        this.options = config.options;
+        this.watchConfig = config.watch;
+        this.capabilities = config.capabilities ?? [];
+        this.runtimeCapability = config.runtimeCapability;
     }
-  }
-  async writeCache(key, data) {
-    if (!this.context?.cache) {
-      throw new Error(PROCESSOR_ERRORS.CACHE_DIRECTORY_NOT_SET);
+    setContext(appConfig) {
+        const workDir = appConfig.absolutePaths.workDir ??
+            path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
+        const cachePath = resolveGeneratedPath('cache', {
+            root: workDir,
+            module: this.name,
+        });
+        fileSystem.ensureDir(cachePath);
+        this.context = {
+            config: appConfig,
+            rootDir: appConfig.rootDir,
+            srcDir: appConfig.absolutePaths.srcDir,
+            distDir: appConfig.absolutePaths.distDir,
+            cache: cachePath,
+        };
     }
-    const cachePath = this.getCachePath(key);
-    fileSystem.write(cachePath, JSON.stringify(data, null, 2));
-  }
-  getWatchConfig() {
-    return this.watchConfig;
-  }
-  getName() {
-    return this.name;
-  }
-  getAssetCapabilities() {
-    return this.capabilities;
-  }
-  matchesFileFilter(_filepath) {
-    return true;
-  }
-  canProcessAsset(kind, filepath) {
-    const capabilities = this.getAssetCapabilities();
-    if (capabilities.length === 0) {
-      return false;
+    /**
+     * Prepares build-facing processor contributions before config finalization.
+     *
+     * @remarks
+     * Override this when a processor must compute runtime/build plugins or other
+     * manifest-owned state before startup. Runtime-only work such as cache
+     * warming or watcher registration should stay in `setup()`.
+     */
+    async prepareBuildContributions() { }
+    /**
+     * Reports whether this processor's build inputs changed since the last
+     * incremental static build.
+     *
+     * @remarks
+     * No shipped processor overrides this today. Integrations and processors can
+     * opt in when they own build inputs that should invalidate incremental static
+     * exports without a full rebuild.
+     */
+    didChange() {
+        return false;
     }
-    const matchingKind = capabilities.filter((capability) => capability.kind === kind);
-    if (matchingKind.length === 0) {
-      return false;
+    /**
+     * Releases runtime resources owned by the processor.
+     *
+     * @remarks
+     * Core does not call this hook today. Override only when a processor owns
+     * watchers, compiler handles, or other resources that outlive individual
+     * requests.
+     */
+    async teardown() { }
+    getCachePath(key) {
+        return `${this.context?.cache}/${key}`;
     }
-    if (!filepath) {
-      return true;
+    async readCache(key) {
+        const cachePath = this.getCachePath(key);
+        try {
+            const data = await fileSystem.readFile(cachePath);
+            return JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
     }
-    return matchingKind.some((capability) => this.matchesCapabilityExtensions(filepath, capability.extensions));
-  }
-  matchesCapabilityExtensions(filepath, extensions) {
-    if (!extensions || extensions.length === 0) {
-      return true;
+    async writeCache(key, data) {
+        if (!this.context?.cache) {
+            throw new Error(PROCESSOR_ERRORS.CACHE_DIRECTORY_NOT_SET);
+        }
+        const cachePath = this.getCachePath(key);
+        fileSystem.write(cachePath, JSON.stringify(data, null, 2));
     }
-    const normalizedExt = path.extname(filepath).toLowerCase();
-    return extensions.some((rawPattern) => {
-      const pattern = this.normalizeExtensionPattern(rawPattern);
-      if (!pattern) {
-        return false;
-      }
-      if (pattern === "*") {
+    getWatchConfig() {
+        return this.watchConfig;
+    }
+    getName() {
+        return this.name;
+    }
+    getAssetCapabilities() {
+        return this.capabilities;
+    }
+    matchesFileFilter(_filepath) {
         return true;
-      }
-      const groupedMatch = pattern.match(/^\*\.\{(.+)\}$/);
-      if (groupedMatch) {
-        const groupItems = groupedMatch[1].split(",").map((item) => this.normalizeExtensionPattern(item)).filter(Boolean);
-        return groupItems.some((item) => normalizedExt === item || normalizedExt === `.${item}`);
-      }
-      if (pattern.startsWith("*")) {
-        const suffix = pattern.slice(1);
-        return normalizedExt.endsWith(suffix);
-      }
-      if (pattern.startsWith(".")) {
-        return normalizedExt === pattern;
-      }
-      return normalizedExt === `.${pattern}`;
-    });
-  }
-  normalizeExtensionPattern(rawPattern) {
-    return rawPattern.trim().toLowerCase();
-  }
+    }
+    canProcessAsset(kind, filepath) {
+        const capabilities = this.getAssetCapabilities();
+        if (capabilities.length === 0) {
+            return false;
+        }
+        const matchingKind = capabilities.filter((capability) => capability.kind === kind);
+        if (matchingKind.length === 0) {
+            return false;
+        }
+        if (!filepath) {
+            return true;
+        }
+        return matchingKind.some((capability) => this.matchesCapabilityExtensions(filepath, capability.extensions));
+    }
+    matchesCapabilityExtensions(filepath, extensions) {
+        if (!extensions || extensions.length === 0) {
+            return true;
+        }
+        const normalizedExt = path.extname(filepath).toLowerCase();
+        return extensions.some((rawPattern) => {
+            const pattern = this.normalizeExtensionPattern(rawPattern);
+            if (!pattern) {
+                return false;
+            }
+            if (pattern === '*') {
+                return true;
+            }
+            const groupedMatch = pattern.match(/^\*\.\{(.+)\}$/);
+            if (groupedMatch) {
+                const groupItems = groupedMatch[1]
+                    .split(',')
+                    .map((item) => this.normalizeExtensionPattern(item))
+                    .filter(Boolean);
+                return groupItems.some((item) => normalizedExt === item || normalizedExt === `.${item}`);
+            }
+            if (pattern.startsWith('*')) {
+                const suffix = pattern.slice(1);
+                return normalizedExt.endsWith(suffix);
+            }
+            if (pattern.startsWith('.')) {
+                return normalizedExt === pattern;
+            }
+            return normalizedExt === `.${pattern}`;
+        });
+    }
+    normalizeExtensionPattern(rawPattern) {
+        return rawPattern.trim().toLowerCase();
+    }
 }
-export {
-  PROCESSOR_ERRORS,
-  Processor,
-  mergeProcessorOptions,
-  resolveGeneratedPath
-};

package/src/plugins/runtime-capability.js

@@ -0,0 +1 @@
+export {};

package/src/plugins/source-transform.js

@@ -1,93 +1,123 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-function normalizeTransformId(id) {
-  const queryIndex = id.indexOf("?");
-  const hashIndex = id.indexOf("#");
-  const endIndex = [queryIndex, hashIndex].filter((index) => index >= 0).sort((left, right) => left - right)[0];
-  return endIndex === void 0 ? id : id.slice(0, endIndex);
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+/**
+ * Normalizes bundler module ids so one transform can serve Ecopages loaders,
+ * Vite, and future bundler adapters.
+ */
+export function normalizeTransformId(id) {
+    const queryIndex = id.indexOf('?');
+    const hashIndex = id.indexOf('#');
+    const endIndex = [queryIndex, hashIndex].filter((index) => index >= 0).sort((left, right) => left - right)[0];
+    return endIndex === undefined ? id : id.slice(0, endIndex);
 }
-function applySourceTransform(transform, code, id) {
-  const normalizedId = normalizeTransformId(id);
-  if (!transform.filter.test(normalizedId)) {
-    return void 0;
-  }
-  return transform.transform(code, normalizedId);
+/**
+ * Applies one source transform if the normalized id matches its filter.
+ */
+export function applySourceTransform(transform, code, id) {
+    const normalizedId = normalizeTransformId(id);
+    if (!transform.filter.test(normalizedId)) {
+        return undefined;
+    }
+    return transform.transform(code, normalizedId);
 }
 const SOURCE_TRANSFORM_ENFORCE_ORDER = {
-  pre: 0,
-  default: 1,
-  post: 2
+    pre: 0,
+    default: 1,
+    post: 2,
 };
 function getSourceTransformEnforceOrder(transform) {
-  return SOURCE_TRANSFORM_ENFORCE_ORDER[transform.enforce ?? "default"];
-}
-function applySourceTransforms(transforms, code, id) {
-  let current = code;
-  for (const transform of [...transforms].sort(
-    (left, right) => getSourceTransformEnforceOrder(left) - getSourceTransformEnforceOrder(right)
-  )) {
-    const result = applySourceTransform(transform, current, id);
-    if (!result) {
-      continue;
-    }
-    current = typeof result === "string" ? result : result.code;
-  }
-  return current;
-}
-function inferLoaderFromPath(filePath) {
-  const extension = path.extname(filePath).toLowerCase();
-  switch (extension) {
-    case ".ts":
-      return "ts";
-    case ".tsx":
-      return "tsx";
-    case ".jsx":
-      return "jsx";
-    default:
-      return "js";
-  }
+    return SOURCE_TRANSFORM_ENFORCE_ORDER[transform.enforce ?? 'default'];
 }
-function createEcoBuildPluginFromSourceTransform(transform) {
-  return {
-    name: transform.name,
-    setup(build) {
-      build.onLoad({ filter: transform.filter }, (args) => {
-        const filePath = normalizeTransformId(args.path);
-        const code = fileSystem.readFileSync(filePath);
-        const result = applySourceTransform(transform, code, filePath);
+/**
+ * Applies app-owned source transforms in deterministic `pre` → default → `post` order.
+ *
+ * @remarks
+ * Used by the Rolldown plugin bridge after `onLoad` plugins produce final module
+ * contents. Transforms that do not match `filter` are skipped; matching transforms
+ * are chained left-to-right on the current source string.
+ *
+ * @param transforms - App-owned transforms, usually from {@link getAppSourceTransforms}.
+ * @param code - Current module source.
+ * @param id - Module id forwarded to each transform after query/hash normalization.
+ * @returns The transformed source, or the original `code` when no transform matches.
+ */
+export function applySourceTransforms(transforms, code, id) {
+    let current = code;
+    for (const transform of [...transforms].sort((left, right) => getSourceTransformEnforceOrder(left) - getSourceTransformEnforceOrder(right))) {
+        const result = applySourceTransform(transform, current, id);
         if (!result) {
-          return void 0;
+            continue;
         }
-        return {
-          contents: typeof result === "string" ? result : result.code,
-          loader: inferLoaderFromPath(filePath),
-          resolveDir: path.dirname(filePath)
-        };
-      });
+        current = typeof result === 'string' ? result : result.code;
     }
-  };
+    return current;
 }
-function createVitePluginFromSourceTransform(transform) {
-  return {
-    name: transform.name,
-    enforce: transform.enforce,
-    transform(code, id) {
-      return applySourceTransform(transform, code, id);
+function inferLoaderFromPath(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    switch (extension) {
+        case '.ts':
+            return 'ts';
+        case '.tsx':
+            return 'tsx';
+        case '.jsx':
+            return 'jsx';
+        default:
+            return 'js';
     }
-  };
 }
-function getAppSourceTransforms(appConfig) {
-  return appConfig.sourceTransforms ? Array.from(appConfig.sourceTransforms.values()) : [];
+/**
+ * Adapts a source transform into the existing Ecopages build-plugin contract.
+ *
+ * @remarks
+ * Server-oriented builds and loader registration still use this adapter.
+ * Browser/HMR builds should register the transform in `appConfig.sourceTransforms`
+ * instead so the Rolldown bridge can run it after competing `onLoad` plugins.
+ */
+export function createEcoBuildPluginFromSourceTransform(transform) {
+    return {
+        name: transform.name,
+        setup(build) {
+            build.onLoad({ filter: transform.filter }, (args) => {
+                const filePath = normalizeTransformId(args.path);
+                const code = fileSystem.readFileSync(filePath);
+                const result = applySourceTransform(transform, code, filePath);
+                if (!result) {
+                    return undefined;
+                }
+                return {
+                    contents: typeof result === 'string' ? result : result.code,
+                    loader: inferLoaderFromPath(filePath),
+                    resolveDir: path.dirname(filePath),
+                };
+            });
+        },
+    };
 }
-function createVitePluginsFromAppSourceTransforms(appConfig) {
-  return getAppSourceTransforms(appConfig).map((transform) => createVitePluginFromSourceTransform(transform));
+/**
+ * Adapts a source transform into a Vite-compatible plugin object.
+ *
+ * @remarks
+ * This intentionally returns a plain object shape so core does not need a hard
+ * dependency on `vite` just to author transform primitives.
+ */
+export function createVitePluginFromSourceTransform(transform) {
+    return {
+        name: transform.name,
+        enforce: transform.enforce,
+        transform(code, id) {
+            return applySourceTransform(transform, code, id);
+        },
+    };
+}
+/**
+ * Returns the app-owned source transforms in stable registration order.
+ */
+export function getAppSourceTransforms(appConfig) {
+    return appConfig.sourceTransforms ? Array.from(appConfig.sourceTransforms.values()) : [];
+}
+/**
+ * Adapts the app-owned source transforms into Vite-compatible plugin objects.
+ */
+export function createVitePluginsFromAppSourceTransforms(appConfig) {
+    return getAppSourceTransforms(appConfig).map((transform) => createVitePluginFromSourceTransform(transform));
 }
-export {
-  applySourceTransform,
-  applySourceTransforms,
-  createEcoBuildPluginFromSourceTransform,
-  createVitePluginFromSourceTransform,
-  createVitePluginsFromAppSourceTransforms,
-  getAppSourceTransforms,
-  normalizeTransformId
-};

package/src/plugins/tsconfig-import-resolver.d.ts

@@ -8,6 +8,23 @@ export declare function matchesTsconfigPathPrefix(specifier: string, prefixes: r
  * a relative path, absolute path, node built-in, tsconfig alias, or `#` import map.
  */
 export declare function isBarePackageImportSpecifier(specifier: string, projectRoot?: string): boolean;
+/**
+ * Resolves a bare npm package entry for browser vendor prebundles.
+ *
+ * @remarks
+ * Prefer package `"browser"` / `"exports.browser"` over Node `"import"` entries.
+ * `createRequire().resolve()` is wrong here — it selects the server facade for
+ * dual packages such as `@ecopages/core`.
+ */
+export declare function resolveBarePackageBrowserEntry(projectRoot: string, specifier: string): string | undefined;
+/**
+ * Resolves a relative import against the filesystem without requiring tsconfig.
+ *
+ * @remarks
+ * Used when oxc-resolver has no tsconfig (minimal fixtures / apps without paths)
+ * and as a fallback when the resolver cannot locate a relative specifier.
+ */
+export declare function resolveRelativeModulePath(fromFile: string, specifier: string): string | undefined;
 /**
  * Resolves a relative or tsconfig path alias import (via oxc-resolver).
  */