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

package/src/build/runtime/build-profile-options.js

@@ -0,0 +1,37 @@
+/**
+ * Resolves shared Rolldown options for a build profile.
+ */
+export function resolveBuildProfileOptions(profile, appConfig, overrides = {}) {
+    const root = appConfig.rootDir;
+    switch (profile) {
+        case 'server-entry':
+            return {
+                root,
+                target: 'node',
+                format: 'esm',
+                sourcemap: 'none',
+                minify: false,
+                externalPackages: true,
+                ...overrides,
+            };
+        case 'route-module':
+            return {
+                root,
+                target: 'es2022',
+                format: 'esm',
+                sourcemap: 'none',
+                minify: false,
+                externalPackages: true,
+                ...overrides,
+            };
+        case 'browser-hmr':
+            return {
+                root,
+                target: 'browser',
+                format: 'esm',
+                sourcemap: 'none',
+                minify: false,
+                ...overrides,
+            };
+    }
+}

package/src/build/runtime/build-request-identity.d.ts

@@ -0,0 +1,17 @@
+import type { BuildOptions } from '../contracts/build-contracts.js';
+/**
+ * Canonical identity for one complete {@link BuildOptions} request.
+ *
+ * @remarks
+ * Semantically unordered collections (`external`, `define` keys, array entrypoints)
+ * are sorted. Plugin, `conditions`, and source-transform order is preserved because
+ * Rolldown hook and `conditionNames` precedence depend on it.
+ *
+ * Deprecated / ignored adapter fields (`splitting`, `bundle`, `outbase`) still
+ * participate in the key so requests that differ only on those fields do not
+ * coalesce. Empty `conditions` / `define` / `external` normalize to the same
+ * sentinel as `undefined`.
+ */
+export declare function createBuildRequestIdentity(options: BuildOptions): string;
+/** @deprecated Use {@link createBuildRequestIdentity}. */
+export declare const createBuildOptionsDedupeKey: typeof createBuildRequestIdentity;

package/src/build/runtime/build-request-identity.js

@@ -0,0 +1,79 @@
+import path from 'node:path';
+import { createJsxCacheKey, createPluginCacheKey, createSourceTransformCacheKey } from '../cache/cache-keys.js';
+function normalizeEntrypoints(entrypoints) {
+    if (Array.isArray(entrypoints)) {
+        return entrypoints
+            .map((entrypoint) => path.resolve(entrypoint))
+            .sort()
+            .join('|');
+    }
+    return Object.entries(entrypoints)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => `${key}:${path.resolve(value)}`)
+        .join('|');
+}
+/**
+ * Preserves list order for collections where Rolldown precedence depends on position.
+ */
+function normalizeOrderedStringList(values, label) {
+    if (!values || values.length === 0) {
+        return `${label}:default`;
+    }
+    return `${label}:${values.join(',')}`;
+}
+/**
+ * Sorts unordered sets so equivalent membership produces one identity.
+ */
+function normalizeUnorderedStringList(values, label) {
+    if (!values || values.length === 0) {
+        return `${label}:default`;
+    }
+    return `${label}:${[...values].sort().join(',')}`;
+}
+function normalizeDefine(define) {
+    if (!define || Object.keys(define).length === 0) {
+        return 'define:default';
+    }
+    return `define:${Object.entries(define)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => `${key}=${value}`)
+        .join(',')}`;
+}
+/**
+ * Canonical identity for one complete {@link BuildOptions} request.
+ *
+ * @remarks
+ * Semantically unordered collections (`external`, `define` keys, array entrypoints)
+ * are sorted. Plugin, `conditions`, and source-transform order is preserved because
+ * Rolldown hook and `conditionNames` precedence depend on it.
+ *
+ * Deprecated / ignored adapter fields (`splitting`, `bundle`, `outbase`) still
+ * participate in the key so requests that differ only on those fields do not
+ * coalesce. Empty `conditions` / `define` / `external` normalize to the same
+ * sentinel as `undefined`.
+ */
+export function createBuildRequestIdentity(options) {
+    return [
+        normalizeEntrypoints(options.entrypoints),
+        options.root ? path.resolve(options.root) : 'root:default',
+        options.outdir ? path.resolve(options.outdir) : 'outdir:default',
+        options.outbase ? path.resolve(options.outbase) : 'outbase:default',
+        options.splitting ?? 'splitting:default',
+        options.bundle ?? 'bundle:default',
+        options.externalPackages ?? 'externalPackages:default',
+        options.target ?? 'target:default',
+        options.format ?? 'format:default',
+        options.sourcemap ?? 'sourcemap:default',
+        options.minify ?? 'minify:default',
+        options.treeshaking ?? 'treeshaking:default',
+        options.naming ?? 'naming:default',
+        normalizeOrderedStringList(options.conditions, 'conditions'),
+        normalizeDefine(options.define),
+        normalizeUnorderedStringList(options.external, 'external'),
+        createJsxCacheKey(options.jsx),
+        createPluginCacheKey(options.plugins),
+        createSourceTransformCacheKey(options.sourceTransforms),
+    ].join('::');
+}
+/** @deprecated Use {@link createBuildRequestIdentity}. */
+export const createBuildOptionsDedupeKey = createBuildRequestIdentity;

package/src/build/runtime/build-request-policy.d.ts

@@ -0,0 +1,58 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { EcoBuildPlugin } from '../contracts/build-types.js';
+import type { BuildOptions, BuildTranspileProfile } from '../contracts/build-contracts.js';
+import type { BuildProfile } from './build-runtime.js';
+/**
+ * Resolves app-owned server plugins plus JSX ownership for one config.
+ *
+ * @remarks
+ * Always goes through {@link getAppServerBuildPlugins} so sealed-manifest and
+ * source-transform apps share one plugin list with the alias resolver. Used by
+ * both request assembly and unified-graph cache keys.
+ */
+export declare function resolveServerAppBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+/**
+ * Merges caller plugins with app-owned manifest plugins.
+ *
+ * @remarks
+ * App-manifest plugins cannot be silently replaced by same-name caller plugins.
+ * Unique caller plugins are prepended so first-wins Rolldown hooks (for example
+ * React vendor/alias rewrites) still run before general app loaders. Use
+ * `excludeAppBuildPlugins` on browser requests to omit app-owned plugins.
+ */
+export declare function mergeCallerBuildPlugins(appPlugins: EcoBuildPlugin[], callerPlugins?: EcoBuildPlugin[]): EcoBuildPlugin[];
+export type ServerBuildRequestInput = Partial<BuildOptions> & {
+    entrypoints: BuildOptions['entrypoints'];
+    profile?: Extract<BuildProfile, 'server-entry' | 'route-module'>;
+};
+export type BrowserBuildRequestInput = Partial<BuildOptions> & {
+    entrypoints: BuildOptions['entrypoints'];
+    profile: BuildTranspileProfile;
+    excludeAppBuildPlugins?: string[];
+};
+/**
+ * Assembles a complete server-oriented {@link BuildOptions} before scheduling.
+ *
+ * @remarks
+ * Defaults `profile` to `'route-module'`. Plugins are
+ * {@link resolveServerAppBuildPlugins} plus unique caller contributions via
+ * {@link mergeCallerBuildPlugins}. Source transforms are applied on every
+ * compilation target, so server module loading shares browser attribution.
+ */
+export declare function createServerBuildRequest(appConfig: EcoPagesAppConfig, input: ServerBuildRequestInput): BuildOptions;
+/**
+ * Assembles a complete browser-oriented {@link BuildOptions} before scheduling.
+ *
+ * @remarks
+ * Applies {@link resolveBuildProfileOptions} for `'browser-hmr'` (browser target
+ * defaults), then overlays {@link getAppTranspileOptions} for the given
+ * {@link BuildTranspileProfile}. That profile selects transpile settings only;
+ * the {@link BuildRuntime} executor slot is chosen later by the caller
+ * (typically {@link BrowserBundleService}).
+ *
+ * Always attaches {@link getAppSourceTransforms}. App browser plugins come from
+ * {@link getAppBrowserBuildPlugins} (includes JSX ownership); use
+ * `excludeAppBuildPlugins` to omit app-owned names. Caller plugins cannot
+ * replace app-manifest names ({@link mergeCallerBuildPlugins}).
+ */
+export declare function createBrowserBuildRequest(appConfig: EcoPagesAppConfig, input: BrowserBuildRequestInput): BuildOptions;

package/src/build/runtime/build-request-policy.js

@@ -0,0 +1,84 @@
+import { getAppBrowserBuildPlugins, getAppServerBuildPlugins, getAppTranspileOptions } from '../build-adapter.js';
+import { resolveBuildProfileOptions } from './build-profile-options.js';
+import { getJsxOwnershipPlugins } from '../browser/jsx-ownership-plugins.js';
+import { getAppSourceTransforms } from '../../plugins/source-transform.js';
+/**
+ * Resolves app-owned server plugins plus JSX ownership for one config.
+ *
+ * @remarks
+ * Always goes through {@link getAppServerBuildPlugins} so sealed-manifest and
+ * source-transform apps share one plugin list with the alias resolver. Used by
+ * both request assembly and unified-graph cache keys.
+ */
+export function resolveServerAppBuildPlugins(appConfig) {
+    return [...getAppServerBuildPlugins(appConfig), ...getJsxOwnershipPlugins(appConfig)];
+}
+/**
+ * Merges caller plugins with app-owned manifest plugins.
+ *
+ * @remarks
+ * App-manifest plugins cannot be silently replaced by same-name caller plugins.
+ * Unique caller plugins are prepended so first-wins Rolldown hooks (for example
+ * React vendor/alias rewrites) still run before general app loaders. Use
+ * `excludeAppBuildPlugins` on browser requests to omit app-owned plugins.
+ */
+export function mergeCallerBuildPlugins(appPlugins, callerPlugins) {
+    if (!callerPlugins || callerPlugins.length === 0) {
+        return appPlugins;
+    }
+    const appByName = new Map(appPlugins.map((plugin) => [plugin.name, plugin]));
+    const uniqueCallerPlugins = callerPlugins.filter((plugin) => !appByName.has(plugin.name));
+    return [...uniqueCallerPlugins, ...appPlugins];
+}
+/**
+ * Assembles a complete server-oriented {@link BuildOptions} before scheduling.
+ *
+ * @remarks
+ * Defaults `profile` to `'route-module'`. Plugins are
+ * {@link resolveServerAppBuildPlugins} plus unique caller contributions via
+ * {@link mergeCallerBuildPlugins}. Source transforms are applied on every
+ * compilation target, so server module loading shares browser attribution.
+ */
+export function createServerBuildRequest(appConfig, input) {
+    const profile = input.profile ?? 'route-module';
+    const plugins = mergeCallerBuildPlugins(resolveServerAppBuildPlugins(appConfig), input.plugins);
+    const { plugins: _callerPlugins, profile: _profile, ...overrides } = input;
+    return {
+        ...resolveBuildProfileOptions(profile, appConfig, overrides),
+        ...overrides,
+        entrypoints: input.entrypoints,
+        ...(plugins.length > 0 ? { plugins } : {}),
+        sourceTransforms: getAppSourceTransforms(appConfig),
+    };
+}
+/**
+ * Assembles a complete browser-oriented {@link BuildOptions} before scheduling.
+ *
+ * @remarks
+ * Applies {@link resolveBuildProfileOptions} for `'browser-hmr'` (browser target
+ * defaults), then overlays {@link getAppTranspileOptions} for the given
+ * {@link BuildTranspileProfile}. That profile selects transpile settings only;
+ * the {@link BuildRuntime} executor slot is chosen later by the caller
+ * (typically {@link BrowserBundleService}).
+ *
+ * Always attaches {@link getAppSourceTransforms}. App browser plugins come from
+ * {@link getAppBrowserBuildPlugins} (includes JSX ownership); use
+ * `excludeAppBuildPlugins` to omit app-owned names. Caller plugins cannot
+ * replace app-manifest names ({@link mergeCallerBuildPlugins}).
+ */
+export function createBrowserBuildRequest(appConfig, input) {
+    const { profile, excludeAppBuildPlugins, plugins: callerPlugins, ...overrides } = input;
+    const appBrowserPlugins = getAppBrowserBuildPlugins(appConfig);
+    const filteredAppBrowserPlugins = excludeAppBuildPlugins && excludeAppBuildPlugins.length > 0
+        ? appBrowserPlugins.filter((plugin) => !excludeAppBuildPlugins.includes(plugin.name))
+        : appBrowserPlugins;
+    const plugins = mergeCallerBuildPlugins(filteredAppBrowserPlugins, callerPlugins);
+    return {
+        ...resolveBuildProfileOptions('browser-hmr', appConfig, overrides),
+        ...getAppTranspileOptions(appConfig, profile),
+        ...overrides,
+        entrypoints: input.entrypoints,
+        plugins,
+        sourceTransforms: getAppSourceTransforms(appConfig),
+    };
+}

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

@@ -0,0 +1,28 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import { type BuildExecutor } from '../build-adapter.js';
+export type BuildProfile = 'server-entry' | 'route-module' | 'browser-hmr';
+export interface BuildRuntime {
+    getProfile(profile: BuildProfile): BuildExecutor;
+    dispose(): Promise<void>;
+}
+export declare function getBuildRuntime(appConfig: EcoPagesAppConfig): BuildRuntime | undefined;
+/**
+ * Returns the installed build runtime, installing it when missing.
+ */
+export declare function requireBuildRuntime(appConfig: EcoPagesAppConfig): BuildRuntime;
+/**
+ * Installs profile-based build executors for one app instance.
+ *
+ * @remarks
+ * For Rolldown ownership, server-entry stays serialized single-flight while
+ * route-module and browser-HMR run in parallel one-shot builds. Vite-host
+ * profiles wrap a boundary marker and reject framework-owned build attempts.
+ * Profiles do not inject app plugins — assemble complete
+ * {@link BuildOptions} with {@link createServerBuildRequest} /
+ * {@link createBrowserBuildRequest} (or {@link BrowserBundleService}) first.
+ */
+export declare function installBuildRuntime(appConfig: EcoPagesAppConfig): BuildRuntime;
+/**
+ * No-op retained for server teardown call sites.
+ */
+export declare function disposeAppBuildRuntime(appConfig: EcoPagesAppConfig): Promise<void>;

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

@@ -0,0 +1,75 @@
+import { availableParallelism } from 'node:os';
+import { getAppBuildAdapter } from '../build-adapter.js';
+import { ParallelBuildExecutor } from './parallel-build-executor.js';
+import { DedupingBuildExecutor } from './deduping-build-executor.js';
+import { SerializedBuildExecutor } from './serialized-build-executor.js';
+function resolveParallelismLimit() {
+    return Math.max(1, availableParallelism() - 1);
+}
+function patchAppRuntime(appConfig, patch) {
+    appConfig.runtime = {
+        ...(appConfig.runtime ?? {}),
+        ...patch,
+    };
+}
+class AppBuildRuntime {
+    serverEntryExecutor;
+    routeModuleExecutor;
+    hmrExecutor;
+    constructor(appConfig) {
+        const adapter = getAppBuildAdapter(appConfig);
+        const limit = resolveParallelismLimit();
+        this.serverEntryExecutor = new SerializedBuildExecutor(adapter);
+        this.routeModuleExecutor = new DedupingBuildExecutor(new ParallelBuildExecutor(adapter, limit));
+        this.hmrExecutor = new DedupingBuildExecutor(new ParallelBuildExecutor(adapter, Math.min(3, limit)));
+    }
+    getProfile(profile) {
+        switch (profile) {
+            case 'server-entry':
+                return this.serverEntryExecutor;
+            case 'route-module':
+                return this.routeModuleExecutor;
+            case 'browser-hmr':
+                return this.hmrExecutor;
+        }
+    }
+    /**
+     * No-op for profile teardown.
+     *
+     * @remarks
+     * Rolldown-owned profiles use one-shot builds, and Vite-host profiles only
+     * wrap a boundary marker. Neither owns a long-lived engine to close.
+     */
+    async dispose() { }
+}
+export function getBuildRuntime(appConfig) {
+    return appConfig.runtime?.buildRuntime;
+}
+/**
+ * Returns the installed build runtime, installing it when missing.
+ */
+export function requireBuildRuntime(appConfig) {
+    return getBuildRuntime(appConfig) ?? installBuildRuntime(appConfig);
+}
+/**
+ * Installs profile-based build executors for one app instance.
+ *
+ * @remarks
+ * For Rolldown ownership, server-entry stays serialized single-flight while
+ * route-module and browser-HMR run in parallel one-shot builds. Vite-host
+ * profiles wrap a boundary marker and reject framework-owned build attempts.
+ * Profiles do not inject app plugins — assemble complete
+ * {@link BuildOptions} with {@link createServerBuildRequest} /
+ * {@link createBrowserBuildRequest} (or {@link BrowserBundleService}) first.
+ */
+export function installBuildRuntime(appConfig) {
+    const buildRuntime = new AppBuildRuntime(appConfig);
+    patchAppRuntime(appConfig, { buildRuntime });
+    return buildRuntime;
+}
+/**
+ * No-op retained for server teardown call sites.
+ */
+export async function disposeAppBuildRuntime(appConfig) {
+    await getBuildRuntime(appConfig)?.dispose();
+}

package/src/build/runtime/deduping-build-executor.d.ts

@@ -0,0 +1,21 @@
+import type { BuildExecutor, BuildOptions, BuildResult } from '../build-adapter.js';
+export { createBuildRequestIdentity, createBuildOptionsDedupeKey } from './build-request-identity.js';
+/**
+ * In-flight build coalescing wrapper.
+ *
+ * @remarks
+ * `ParallelBuildExecutor` allows concurrent builds but does not dedupe identical
+ * options. Multiple callers (route import, browser bundles, HMR) can hit the
+ * same Rolldown request before disk or import caches warm. This wrapper shares
+ * one inner `build()` promise per dedupe key until it settles.
+ *
+ * Wrap route-module and browser-hmr profiles only; server-entry stays serialized.
+ */
+export declare class DedupingBuildExecutor implements BuildExecutor {
+    private readonly inner;
+    private readonly inFlight;
+    constructor(inner: BuildExecutor);
+    build(options: BuildOptions): Promise<BuildResult>;
+    unwrap(): BuildExecutor;
+    getInFlightCountForTests(): number;
+}

package/src/build/runtime/deduping-build-executor.js

@@ -0,0 +1,40 @@
+import { createBuildRequestIdentity } from './build-request-identity.js';
+export { createBuildRequestIdentity, createBuildOptionsDedupeKey } from './build-request-identity.js';
+/**
+ * In-flight build coalescing wrapper.
+ *
+ * @remarks
+ * `ParallelBuildExecutor` allows concurrent builds but does not dedupe identical
+ * options. Multiple callers (route import, browser bundles, HMR) can hit the
+ * same Rolldown request before disk or import caches warm. This wrapper shares
+ * one inner `build()` promise per dedupe key until it settles.
+ *
+ * Wrap route-module and browser-hmr profiles only; server-entry stays serialized.
+ */
+export class DedupingBuildExecutor {
+    inner;
+    inFlight = new Map();
+    constructor(inner) {
+        this.inner = inner;
+    }
+    build(options) {
+        const key = createBuildRequestIdentity(options);
+        const existing = this.inFlight.get(key);
+        if (existing) {
+            return existing;
+        }
+        const buildPromise = this.inner.build(options).finally(() => {
+            if (this.inFlight.get(key) === buildPromise) {
+                this.inFlight.delete(key);
+            }
+        });
+        this.inFlight.set(key, buildPromise);
+        return buildPromise;
+    }
+    unwrap() {
+        return this.inner;
+    }
+    getInFlightCountForTests() {
+        return this.inFlight.size;
+    }
+}

package/src/build/{parallel-build-executor.d.ts → runtime/parallel-build-executor.d.ts}

@@ -1,4 +1,4 @@
-import type { BuildExecutor, BuildOptions, BuildResult } from './build-adapter.js';
+import type { BuildExecutor, BuildOptions, BuildResult } from '../build-adapter.js';
 /**
  * Concurrency-limited build executor wrapper.
  *

package/src/build/runtime/parallel-build-executor.js

@@ -0,0 +1,60 @@
+/**
+ * Concurrency-limited build executor wrapper.
+ *
+ * @remarks
+ * Runs up to `limit` builds concurrently. Use for independent route-module
+ * and HMR browser builds where FIFO serialization is unnecessary.
+ */
+export class ParallelBuildExecutor {
+    inner;
+    limit;
+    activeCount = 0;
+    queue = [];
+    constructor(inner, limit) {
+        this.inner = inner;
+        this.limit = Math.max(1, limit);
+    }
+    build(options) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                operation: () => this.inner.build(options),
+                resolve,
+                reject,
+            });
+            this.drainQueue();
+        });
+    }
+    drainQueue() {
+        while (this.activeCount < this.limit && this.queue.length > 0) {
+            const next = this.queue.shift();
+            if (!next) {
+                return;
+            }
+            this.activeCount += 1;
+            void next
+                .operation()
+                .then((result) => {
+                next.resolve(result);
+            })
+                .catch((error) => {
+                next.reject(error);
+            })
+                .finally(() => {
+                this.activeCount -= 1;
+                this.drainQueue();
+            });
+        }
+    }
+    unwrap() {
+        return this.inner;
+    }
+    getConcurrencyLimitForTests() {
+        return this.limit;
+    }
+    getActiveCountForTests() {
+        return this.activeCount;
+    }
+    getQueuedCountForTests() {
+        return this.queue.length;
+    }
+}

package/src/build/{serialized-build-executor.d.ts → runtime/serialized-build-executor.d.ts}

@@ -1,4 +1,4 @@
-import type { BuildExecutor, BuildOptions, BuildResult } from './build-adapter.js';
+import type { BuildExecutor, BuildOptions, BuildResult } from '../build-adapter.js';
 /**
  * FIFO-serialized build executor wrapper.
  *

package/src/build/runtime/serialized-build-executor.js

@@ -0,0 +1,79 @@
+/**
+ * FIFO-serialized build executor wrapper.
+ *
+ * @remarks
+ * Wraps any `BuildExecutor` and ensures that no two builds run
+ * concurrently. The next build waits for the previous one to finish
+ * (success or failure) before starting.
+ *
+ * This is a bundler-agnostic primitive. It is unaware of bundler
+ * lifecycle events and exists purely to enforce one build at a time.
+ * Use it from the dev watch pipeline, the static preview path, or any
+ * caller that issues builds concurrently.
+ */
+/**
+ * FIFO-serialized wrapper around a {@link BuildExecutor}.
+ *
+ * Every `build()` call enqueues onto the wrapper's internal queue. A
+ * build only starts after the previous build's promise has settled.
+ */
+export class SerializedBuildExecutor {
+    inner;
+    tail = Promise.resolve();
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /**
+     * Run a build through the serialized queue. The returned promise
+     * resolves with the inner executor's `BuildResult`. A rejected
+     * inner build does not block the queue — the next caller can
+     * proceed.
+     */
+    build(options) {
+        return this.run(() => this.inner.build(options));
+    }
+    /**
+     * Run an arbitrary async operation through the serialized queue.
+     *
+     * Use this when the work is not a `build()` call against a wrapped
+     * executor (e.g. when composing with a coordinator that needs to
+     * inject recovery around the inner call). The returned promise
+     * resolves with the operation's result. A rejected operation does
+     * not block the queue.
+     */
+    run(operation) {
+        const next = this.tail.catch(() => undefined).then(() => operation());
+        this.tail = next.catch(() => undefined);
+        return next;
+    }
+    /**
+     * Returns the wrapped executor. Tests use this to assert the
+     * delegation chain.
+     */
+    unwrap() {
+        return this.inner;
+    }
+    /**
+     * Reset the queue to an empty state. Tests use this to recover
+     * from a poisoned tail.
+     */
+    resetForTests() {
+        this.tail = Promise.resolve();
+    }
+    /**
+     * Overrides the internal queue tail for fault-recovery tests. The
+     * supplied promise is awaited before the next enqueued operation
+     * starts.
+     */
+    setBuildQueueForTests(queue) {
+        this.tail = queue;
+    }
+    /**
+     * Returns the current internal queue tail for fault-recovery
+     * tests. Tests await this to assert that recovery has cleared a
+     * wedged queue.
+     */
+    getBuildQueueForTests() {
+        return this.tail;
+    }
+}

package/src/cache/index.d.ts

@@ -3,4 +3,5 @@
  *
  * @module @ecopages/core/cache
  */
-export { ModuleParseCache, moduleParseCache, cachedParseSync, type ModuleParseOptions } from './module-parse-cache.js';
+export { ModuleParseCache, moduleParseCache, cachedParseSync, parseModuleSource, parserLanguageForFile, type ModuleParseOptions, type ParserLanguage, } from './module-parse-cache.js';
+export { recordModuleTransformProfile } from './module-transform-profiler.js';

package/src/cache/index.js

@@ -1,6 +1,7 @@
-import { ModuleParseCache, moduleParseCache, cachedParseSync } from "./module-parse-cache.js";
-export {
-  ModuleParseCache,
-  cachedParseSync,
-  moduleParseCache
-};
+/**
+ * Public cache exports for the bundler plugin chain.
+ *
+ * @module @ecopages/core/cache
+ */
+export { ModuleParseCache, moduleParseCache, cachedParseSync, parseModuleSource, parserLanguageForFile, } from './module-parse-cache.js';
+export { recordModuleTransformProfile } from './module-transform-profiler.js';

package/src/cache/module-parse-cache.d.ts

@@ -22,6 +22,11 @@ export type ModuleParseOptions = ParserOptions & {
      */
     lang?: ParserOptions['lang'];
 };
+export type ParserLanguage = 'js' | 'jsx' | 'ts' | 'tsx';
+/** Resolves the Oxc dialect for a source module from its file extension. */
+export declare function parserLanguageForFile(filePath: string): ParserLanguage;
+/** Parses an ECMAScript module with the shared, normalized cache contract. */
+export declare function parseModuleSource(filePath: string, source: string, options?: ModuleParseOptions): ParseResult;
 /**
  * LRU-bounded module parse cache.
  *