@ecopages/core 0.2.0-beta.8 → 0.2.0-rc.0

package/src/plugins/processor.js

@@ -1,148 +1,179 @@
-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;
-  dependencies = [];
-  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.
-   */
-  didChange() {
-    return false;
-  }
-  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;
-  }
-  getDependencies() {
-    return this.dependencies;
-  }
-  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() { }
+    /**
+     * Declares watch-mode SSR prewarm pathnames and readiness for core.
+     *
+     * @remarks
+     * Processors return paths and readiness only; core owns parallel rendering and page cache population.
+     */
+    collectDevPrewarmPlan() {
+        return Promise.resolve({ pathnames: [], readiness: 'background' });
     }
-    const matchingKind = capabilities.filter((capability) => capability.kind === kind);
-    if (matchingKind.length === 0) {
-      return false;
+    /**
+     * 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;
     }
-    if (!filepath) {
-      return true;
+    /**
+     * 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}`;
     }
-    return matchingKind.some((capability) => this.matchesCapabilityExtensions(filepath, capability.extensions));
-  }
-  matchesCapabilityExtensions(filepath, extensions) {
-    if (!extensions || extensions.length === 0) {
-      return true;
+    async readCache(key) {
+        const cachePath = this.getCachePath(key);
+        try {
+            const data = await fileSystem.readFile(cachePath);
+            return JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
     }
-    const normalizedExt = path.extname(filepath).toLowerCase();
-    return extensions.some((rawPattern) => {
-      const pattern = this.normalizeExtensionPattern(rawPattern);
-      if (!pattern) {
-        return false;
-      }
-      if (pattern === "*") {
+    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));
+    }
+    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
-};

package/src/plugins/runtime-capability.js

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

package/src/plugins/source-transform.d.ts

@@ -1,12 +1,24 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
 export interface EcoSourceTransformResult {
     code: string;
     map?: unknown;
 }
+/**
+ * Bundler-neutral source transform registered on {@link EcoPagesAppConfig.sourceTransforms}.
+ *
+ * @remarks
+ * Prefer this shape over a competing {@link EcoBuildPlugin} `onLoad` handler when
+ * the transform only rewrites module source. Browser/HMR builds run source
+ * transforms after first-wins `onLoad` plugins, so metadata injection and similar
+ * passes still run on rewritten output from boundary/runtime plugins.
+ */
 export interface EcoSourceTransform {
+    /** Stable transform name. Also used to dedupe loader plugins in browser builds. */
     name: string;
+    /** File-path filter tested against {@link normalizeTransformId | normalized ids}. */
     filter: RegExp;
+    /** Runs before default transforms, or after them when set to `post`. */
     enforce?: 'pre' | 'post';
     transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
 }
@@ -24,8 +36,27 @@ export declare function normalizeTransformId(id: string): string;
  * Applies one source transform if the normalized id matches its filter.
  */
 export declare function applySourceTransform(transform: EcoSourceTransform, code: string, id: string): EcoSourceTransformResult | string | undefined;
+/**
+ * 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 declare function applySourceTransforms(transforms: readonly EcoSourceTransform[], code: string, id: string): string;
 /**
  * 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 declare function createEcoBuildPluginFromSourceTransform(transform: EcoSourceTransform): EcoBuildPlugin;
 /**

package/src/plugins/source-transform.js

@@ -1,71 +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);
 }
-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";
-  }
+const SOURCE_TRANSFORM_ENFORCE_ORDER = {
+    pre: 0,
+    default: 1,
+    post: 2,
+};
+function getSourceTransformEnforceOrder(transform) {
+    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 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,
-  createEcoBuildPluginFromSourceTransform,
-  createVitePluginFromSourceTransform,
-  createVitePluginsFromAppSourceTransforms,
-  getAppSourceTransforms,
-  normalizeTransformId
-};

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

@@ -0,0 +1,37 @@
+/**
+ * Loads `compilerOptions.paths` keys from tsconfig, following `extends` recursively.
+ */
+export declare function loadTsconfigPathPrefixes(projectRoot: string): string[];
+export declare function matchesTsconfigPathPrefix(specifier: string, prefixes: readonly string[]): boolean;
+/**
+ * Returns true when `specifier` looks like a bare npm package import rather than
+ * 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
+ * Framework-owned dual packages such as `@ecopages/core` keep browser-first
+ * `mainFields` and `conditionNames` so vendor prebundles pick the browser facade.
+ * Third-party packages prefer ESM (`module` / `import`) and omit the `browser`
+ * export condition so legacy UMD `exports.browser` entries cannot win during
+ * Rolldown bundling.
+ */
+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).
+ */
+export declare function resolveProjectModulePath(projectRoot: string, fromFile: string, specifier: string): string | undefined;
+/**
+ * Resolves a TS path alias import using the app's tsconfig `paths` (via oxc-resolver).
+ */
+export declare function resolveProjectImportPath(projectRoot: string, fromFile: string, specifier: string): string | undefined;