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

package/src/build/build-adapter.js

@@ -1,142 +1,279 @@
-import {
-} from "./contracts/build-contracts.js";
-import {
-  createAppBuildManifest,
-  getBrowserBuildPlugins,
-  getServerBuildPlugins
-} from "./contracts/build-manifest.js";
-import { getAppSourceTransforms } from "../plugins/source-transform.js";
-import { createAliasResolverPlugin } from "../plugins/alias-resolver-plugin.js";
-import { getJsxOwnershipPlugins } from "./browser/jsx-ownership-plugins.js";
-import { createRolldownBuildAdapter } from "./rolldown/rolldown-build-adapter.js";
+/**
+ * Build pipeline contracts and app-owned adapter wiring.
+ *
+ * @remarks
+ * The build layer exposes three concentric shapes:
+ *
+ * - `BuildAdapter` — the low-level backend contract. Two implementations
+ *   exist: a bundler-backed adapter (the real backend) and
+ *   {@link ViteHostBuildAdapter} (a host-owned boundary marker that throws
+ *   on direct use, for host runtimes that own their own build pipeline).
+ * - `BuildExecutor` — the runtime-facing facade stored on
+ *   `appConfig.runtime.buildRuntime` via profile-based accessors.
+ * - App-owned helpers (`getAppBuildAdapter` and the `set*` counterparts) —
+ *   the supported way for runtime code to read and mutate the active adapter
+ *   per `EcoPagesAppConfig`. Profile executors live on
+ *   `appConfig.runtime.buildRuntime`.
+ */
+import {} from './contracts/build-contracts.js';
+import { createAppBuildManifest, getBrowserBuildPlugins, getServerBuildPlugins, } from './contracts/build-manifest.js';
+import { getAppSourceTransforms } from '../plugins/source-transform.js';
+import { createAliasResolverPlugin } from '../plugins/alias-resolver-plugin.js';
+import { getJsxOwnershipPlugins } from './browser/jsx-ownership-plugins.js';
+import { createRolldownBuildAdapter } from './rolldown/rolldown-build-adapter.js';
+/**
+ * @remarks
+ * All runtime-bag setters funnel through here so `appConfig.runtime` is patched
+ * in one place instead of repeating the spread-merge at every call site.
+ */
 function patchAppRuntime(appConfig, patch) {
-  appConfig.runtime = {
-    ...appConfig.runtime ?? {},
-    ...patch
-  };
+    appConfig.runtime = {
+        ...(appConfig.runtime ?? {}),
+        ...patch,
+    };
 }
 function createHostOwnedBuildError(methodName) {
-  return new Error(
-    `Vite-hosted builds are owned by the host runtime. Core cannot ${methodName} through the host-owned compatibility adapter.`
-  );
-}
-class ViteHostBuildAdapter {
-  ownership = "vite-host";
-  async build(_options) {
-    throw createHostOwnedBuildError("build");
-  }
-  resolve(_importPath, _rootDir) {
-    throw createHostOwnedBuildError("resolve imports");
-  }
-  getTranspileOptions(_profile) {
-    throw createHostOwnedBuildError("derive transpile options");
-  }
-}
-function createViteHostBuildAdapter() {
-  return new ViteHostBuildAdapter();
-}
-function createBuildAdapter(options) {
-  switch (options?.ownership ?? "rolldown") {
-    case "vite-host":
-      return createViteHostBuildAdapter();
-    case "rolldown":
-    default:
-      return createRolldownBuildAdapter();
-  }
-}
-const defaultRolldownBuildAdapter = createBuildAdapter({ ownership: "rolldown" });
-const defaultViteHostBuildAdapter = createBuildAdapter({ ownership: "vite-host" });
-const defaultBuildAdapter = defaultRolldownBuildAdapter;
-function getDefaultBuildAdapter(ownership = "rolldown") {
-  return ownership === "vite-host" ? defaultViteHostBuildAdapter : defaultRolldownBuildAdapter;
-}
-function getBuildAdapterOwnership(buildAdapter) {
-  return buildAdapter?.ownership ?? "rolldown";
-}
-function getAppBuildOwnership(appConfig) {
-  return appConfig.runtime?.buildOwnership ?? getBuildAdapterOwnership(appConfig.runtime?.buildAdapter);
-}
-function setAppBuildOwnership(appConfig, buildOwnership) {
-  patchAppRuntime(appConfig, { buildOwnership });
-}
-function getAppBuildAdapter(appConfig) {
-  return appConfig.runtime?.buildAdapter ?? getDefaultBuildAdapter(getAppBuildOwnership(appConfig));
-}
-function setAppBuildAdapter(appConfig, buildAdapter) {
-  patchAppRuntime(appConfig, {
-    buildOwnership: getBuildAdapterOwnership(buildAdapter),
-    buildAdapter
-  });
-}
-function getAppBuildManifest(appConfig) {
-  return appConfig.runtime?.buildManifest ?? createAppBuildManifest({
-    loaderPlugins: Array.from(appConfig.loaders?.values() ?? [])
-  });
-}
-function setAppBuildManifest(appConfig, buildManifest) {
-  patchAppRuntime(appConfig, { buildManifest });
-}
-function createConfiguredAppBuildManifest(appConfig, input) {
-  return createAppBuildManifest({
-    loaderPlugins: input?.loaderPlugins ?? Array.from(appConfig.loaders.values()),
-    runtimePlugins: input?.runtimePlugins,
-    browserBundlePlugins: input?.browserBundlePlugins,
-    browserRuntimeManifest: input?.browserRuntimeManifest
-  });
-}
-function updateAppBuildManifest(appConfig, input) {
-  setAppBuildManifest(appConfig, createConfiguredAppBuildManifest(appConfig, input));
-}
-import {
-  collectConfiguredAppBuildManifestContributions,
-  ensureIntegrationRuntimeReady,
-  setupAppRuntimePlugins
-} from "./app-build-manifest-runtime.js";
-function getAppServerBuildPlugins(appConfig) {
-  const projectDir = appConfig.absolutePaths?.projectDir;
-  const aliasPlugin = projectDir ? [createAliasResolverPlugin(projectDir)] : [];
-  return [...aliasPlugin, ...getServerBuildPlugins(getAppBuildManifest(appConfig))];
-}
-function getAppBrowserBuildPlugins(appConfig) {
-  const manifest = getAppBuildManifest(appConfig);
-  const sourceTransformNames = new Set(getAppSourceTransforms(appConfig).map((transform) => transform.name));
-  const browserPlugins = getBrowserBuildPlugins(manifest).filter((plugin) => !sourceTransformNames.has(plugin.name));
-  const projectDir = appConfig.absolutePaths?.projectDir;
-  const aliasPlugin = projectDir ? [createAliasResolverPlugin(projectDir)] : [];
-  return [...aliasPlugin, ...browserPlugins, ...getJsxOwnershipPlugins(appConfig)];
-}
-function build(options, executor = defaultRolldownBuildAdapter) {
-  return executor.build(options);
-}
-function getTranspileOptions(profile) {
-  return defaultRolldownBuildAdapter.getTranspileOptions(profile);
-}
-function getAppTranspileOptions(appConfig, profile) {
-  return getAppBuildAdapter(appConfig).getTranspileOptions(profile);
-}
-export {
-  ViteHostBuildAdapter,
-  build,
-  collectConfiguredAppBuildManifestContributions,
-  createBuildAdapter,
-  createConfiguredAppBuildManifest,
-  createViteHostBuildAdapter,
-  defaultBuildAdapter,
-  defaultRolldownBuildAdapter,
-  defaultViteHostBuildAdapter,
-  ensureIntegrationRuntimeReady,
-  getAppBrowserBuildPlugins,
-  getAppBuildAdapter,
-  getAppBuildManifest,
-  getAppBuildOwnership,
-  getAppServerBuildPlugins,
-  getAppTranspileOptions,
-  getBuildAdapterOwnership,
-  getDefaultBuildAdapter,
-  getTranspileOptions,
-  setAppBuildAdapter,
-  setAppBuildManifest,
-  setAppBuildOwnership,
-  setupAppRuntimePlugins,
-  updateAppBuildManifest
-};
+    return new Error(`Vite-hosted builds are owned by the host runtime. Core cannot ${methodName} through the host-owned compatibility adapter.`);
+}
+/**
+ * Boundary-marker adapter for Vite-host ownership.
+ *
+ * @remarks
+ * This is not a real backend. It exists so `appConfig.runtime.buildAdapter`
+ * can carry the `'vite-host'` ownership without falling back to a
+ * framework-owned bundler path. Every method throws a
+ * {@link createHostOwnedBuildError} so misrouted calls fail loudly
+ * with a clear message instead of silently executing under a
+ * different backend.
+ *
+ * The class stays in the public surface for host runtimes that own
+ * their build pipeline (e.g. Nitro) and for app code that wants to
+ * opt into host-owned ownership before its host wires up the build.
+ */
+export class ViteHostBuildAdapter {
+    ownership = 'vite-host';
+    async build(_options) {
+        throw createHostOwnedBuildError('build');
+    }
+    resolve(_importPath, _rootDir) {
+        throw createHostOwnedBuildError('resolve imports');
+    }
+    getTranspileOptions(_profile) {
+        throw createHostOwnedBuildError('derive transpile options');
+    }
+}
+/**
+ * Constructs a {@link ViteHostBuildAdapter}. Use only in code paths
+ * that explicitly opt into the host-owned boundary.
+ */
+export function createViteHostBuildAdapter() {
+    return new ViteHostBuildAdapter();
+}
+/**
+ * Constructs a build adapter for the given ownership.
+ *
+ * @param options - When `options.ownership` is omitted, the default is
+ * `'rolldown'`. The Vite-host path is opt-in.
+ */
+export function createBuildAdapter(options) {
+    switch (options?.ownership ?? 'rolldown') {
+        case 'vite-host':
+            return createViteHostBuildAdapter();
+        case 'rolldown':
+        default:
+            return createRolldownBuildAdapter();
+    }
+}
+/** The shared default-bundler backend instance. Use {@link getAppBuildAdapter} in app-aware code. */
+export const defaultRolldownBuildAdapter = createBuildAdapter({ ownership: 'rolldown' });
+/** The shared Vite-host boundary instance. Use {@link getAppBuildAdapter} in app-aware code. */
+export const defaultViteHostBuildAdapter = createBuildAdapter({ ownership: 'vite-host' });
+/**
+ * Global default build adapter.
+ *
+ * @remarks
+ * Resolves to the bundled default-bundler adapter. New app-aware
+ * code should prefer {@link getAppBuildAdapter}.
+ */
+export const defaultBuildAdapter = defaultRolldownBuildAdapter;
+/**
+ * Resolves the default build adapter for an ownership value.
+ *
+ * @param ownership - Defaults to `'rolldown'`. Returns the
+ * {@link ViteHostBuildAdapter} only when the caller explicitly asks
+ * for `'vite-host'`.
+ */
+export function getDefaultBuildAdapter(ownership = 'rolldown') {
+    return ownership === 'vite-host' ? defaultViteHostBuildAdapter : defaultRolldownBuildAdapter;
+}
+/**
+ * Reads the {@link BuildOwnership} declared on a {@link BuildAdapter}.
+ *
+ * @param buildAdapter - When `undefined`, defaults to `'rolldown'`.
+ */
+export function getBuildAdapterOwnership(buildAdapter) {
+    return buildAdapter?.ownership ?? 'rolldown';
+}
+/**
+ * Resolves the build ownership of an app config.
+ *
+ * @remarks
+ * Resolution order: `appConfig.runtime.buildOwnership` (explicit), then
+ * the ownership declared on `appConfig.runtime.buildAdapter`, then the
+ * default `'rolldown'`.
+ */
+export function getAppBuildOwnership(appConfig) {
+    return appConfig.runtime?.buildOwnership ?? getBuildAdapterOwnership(appConfig.runtime?.buildAdapter);
+}
+/**
+ * Sets the explicit build ownership on an app config.
+ *
+ * @remarks
+ * The `ConfigBuilder` uses this when the caller calls
+ * `setBuildOwnership`. App code that needs a different ownership
+ * should call this directly with a new value; passing the same
+ * value is a no-op.
+ */
+export function setAppBuildOwnership(appConfig, buildOwnership) {
+    patchAppRuntime(appConfig, { buildOwnership });
+}
+/**
+ * Returns the adapter owned by an app/runtime instance.
+ *
+ * @remarks
+ * Falls back through `appConfig.runtime.buildAdapter` →
+ * {@link getDefaultBuildAdapter} on the resolved ownership. Throws
+ * never; a missing adapter resolves to the global default.
+ */
+export function getAppBuildAdapter(appConfig) {
+    return appConfig.runtime?.buildAdapter ?? getDefaultBuildAdapter(getAppBuildOwnership(appConfig));
+}
+/**
+ * Installs the adapter that should serve future builds for one app
+ * instance, and aligns the ownership field to the new adapter's
+ * declared ownership.
+ */
+export function setAppBuildAdapter(appConfig, buildAdapter) {
+    patchAppRuntime(appConfig, {
+        buildOwnership: getBuildAdapterOwnership(buildAdapter),
+        buildAdapter,
+    });
+}
+/**
+ * Returns the build manifest owned by an app/runtime instance.
+ *
+ * @remarks
+ * Falls back to a fresh manifest seeded from the config's loaders when
+ * the app config has no manifest yet. This is the supported way to
+ * read the manifest across the source-loading and asset-processing
+ * services.
+ */
+export function getAppBuildManifest(appConfig) {
+    return (appConfig.runtime?.buildManifest ??
+        createAppBuildManifest({
+            loaderPlugins: Array.from(appConfig.loaders?.values() ?? []),
+        }));
+}
+/** Installs the build manifest that should be visible to one app instance.
+ *
+ * @remarks
+ * Production apps are sealed via {@link updateAppBuildManifest} during
+ * {@link ConfigBuilder.build}. Call `setAppBuildManifest` directly only in tests or
+ * when replacing the entire manifest object; partial updates should use
+ * {@link updateAppBuildManifest}.
+ */
+export function setAppBuildManifest(appConfig, buildManifest) {
+    patchAppRuntime(appConfig, { buildManifest });
+}
+/**
+ * Builds a fresh app manifest from the config's loaders plus optional
+ * caller-supplied runtime/browser contributions.
+ *
+ * @remarks
+ * Loader plugins are always taken from the config; runtime and
+ * browser-bundle plugins are passed through from the caller when
+ * supplied, otherwise left empty for later population by
+ * {@link collectConfiguredAppBuildManifestContributions}.
+ */
+export function createConfiguredAppBuildManifest(appConfig, input) {
+    return createAppBuildManifest({
+        loaderPlugins: input?.loaderPlugins ?? Array.from(appConfig.loaders.values()),
+        runtimePlugins: input?.runtimePlugins,
+        browserBundlePlugins: input?.browserBundlePlugins,
+        browserRuntimeManifest: input?.browserRuntimeManifest,
+    });
+}
+/**
+ * Replaces the app-owned manifest using config-owned loaders and the
+ * caller-supplied contribution input.
+ *
+ * @remarks
+ * Primary production entry: `ConfigBuilder.build()` passes the return value of
+ * {@link collectConfiguredAppBuildManifestContributions} here to seal
+ * `appConfig.runtime.buildManifest` before startup.
+ */
+export function updateAppBuildManifest(appConfig, input) {
+    setAppBuildManifest(appConfig, createConfiguredAppBuildManifest(appConfig, input));
+}
+export { collectConfiguredAppBuildManifestContributions, ensureIntegrationRuntimeReady, setupAppRuntimePlugins, } from './app-build-manifest-runtime.js';
+/**
+ * Returns the server-bundle plugin list for one app/runtime instance.
+ *
+ * @remarks
+ * Reads from the app's sealed build manifest; the manifest itself is
+ * the source of truth for which plugins participate in the server
+ * bundle.
+ */
+export function getAppServerBuildPlugins(appConfig) {
+    const projectDir = appConfig.absolutePaths?.projectDir;
+    const aliasPlugin = projectDir ? [createAliasResolverPlugin(projectDir)] : [];
+    return [...aliasPlugin, ...getServerBuildPlugins(getAppBuildManifest(appConfig))];
+}
+/**
+ * Returns the browser-bundle plugin list for one app/runtime instance.
+ *
+ * @remarks
+ * Reads from the app's sealed build manifest. The browser-bundle
+ * manifest is the source of truth for which plugins participate in the
+ * browser bundle.
+ *
+ * Plugins whose `name` matches a registered {@link EcoSourceTransform} are
+ * excluded here because browser builds run those transforms via the Rolldown
+ * bridge post-load pass instead of as competing `onLoad` handlers.
+ */
+export function getAppBrowserBuildPlugins(appConfig) {
+    const manifest = getAppBuildManifest(appConfig);
+    const sourceTransformNames = new Set(getAppSourceTransforms(appConfig).map((transform) => transform.name));
+    const browserPlugins = getBrowserBuildPlugins(manifest).filter((plugin) => !sourceTransformNames.has(plugin.name));
+    const projectDir = appConfig.absolutePaths?.projectDir;
+    const aliasPlugin = projectDir ? [createAliasResolverPlugin(projectDir)] : [];
+    return [...aliasPlugin, ...browserPlugins, ...getJsxOwnershipPlugins(appConfig)];
+}
+/**
+ * Runs a build through the active pipeline.
+ *
+ * @remarks
+ * `executor` defaults to the default-bundler adapter for non-app-aware
+ * callsites. App-aware code should pass a profile executor from
+ * {@link requireBuildRuntime} to honor the per-app pipeline.
+ */
+export function build(options, executor = defaultRolldownBuildAdapter) {
+    return executor.build(options);
+}
+/**
+ * Default transpile-options helper for callsites without app runtime
+ * context.
+ *
+ * @remarks
+ * New app-aware code should prefer {@link getAppTranspileOptions}.
+ */
+export function getTranspileOptions(profile) {
+    return defaultRolldownBuildAdapter.getTranspileOptions(profile);
+}
+/**
+ * Resolves transpile options for one app/runtime instance by asking
+ * the app's adapter.
+ */
+export function getAppTranspileOptions(appConfig, profile) {
+    return getAppBuildAdapter(appConfig).getTranspileOptions(profile);
+}

package/src/build/cache/build-input-fingerprint.js

@@ -1,31 +1,33 @@
-import { fileSystem } from "@ecopages/file-system";
-function didBuildInputContributorChange(contributor) {
-  return contributor.didChange?.() === true;
+import { fileSystem } from '@ecopages/file-system';
+/** Returns whether a processor or integration signals changed build inputs. */
+export function didBuildInputContributorChange(contributor) {
+    return contributor.didChange?.() === true;
 }
-function hashAppConfigFile(appConfig) {
-  const configPath = appConfig.absolutePaths?.config;
-  if (!configPath || !fileSystem.exists(configPath)) {
-    return "missing";
-  }
-  return fileSystem.hash(configPath);
+/** Hashes the app's eco.config.ts file when present. */
+export function hashAppConfigFile(appConfig) {
+    const configPath = appConfig.absolutePaths?.config;
+    if (!configPath || !fileSystem.exists(configPath)) {
+        return 'missing';
+    }
+    return fileSystem.hash(configPath);
 }
-function createBuildInputsFingerprint(appConfig) {
-  const changedContributors = [
-    ...Array.from(appConfig.processors?.values() ?? []).filter((processor) => didBuildInputContributorChange(processor)).map((processor) => `processor:${processor.getName()}`),
-    ...(appConfig.integrations ?? []).filter((integration) => didBuildInputContributorChange(integration)).map((integration) => `integration:${integration.name}`)
-  ];
-  return changedContributors.length > 0 ? changedContributors.sort().join("|") : "stable";
+/** Fingerprints processor/integration build-input state for cache invalidation. */
+export function createBuildInputsFingerprint(appConfig) {
+    const changedContributors = [
+        ...Array.from(appConfig.processors?.values() ?? [])
+            .filter((processor) => didBuildInputContributorChange(processor))
+            .map((processor) => `processor:${processor.getName()}`),
+        ...(appConfig.integrations ?? [])
+            .filter((integration) => didBuildInputContributorChange(integration))
+            .map((integration) => `integration:${integration.name}`),
+    ];
+    return changedContributors.length > 0 ? changedContributors.sort().join('|') : 'stable';
 }
-function haveBuildInputsChanged(appConfig) {
-  return createBuildInputsFingerprint(appConfig) !== "stable";
+/** Returns true when any processor or integration reports changed build inputs. */
+export function haveBuildInputsChanged(appConfig) {
+    return createBuildInputsFingerprint(appConfig) !== 'stable';
 }
-function collectBuildInputContributors(appConfig) {
-  return [...Array.from(appConfig.processors?.values() ?? []), ...appConfig.integrations ?? []];
+/** Collects every processor and integration that can invalidate incremental builds. */
+export function collectBuildInputContributors(appConfig) {
+    return [...Array.from(appConfig.processors?.values() ?? []), ...(appConfig.integrations ?? [])];
 }
-export {
-  collectBuildInputContributors,
-  createBuildInputsFingerprint,
-  didBuildInputContributorChange,
-  hashAppConfigFile,
-  haveBuildInputsChanged
-};

package/src/build/cache/cache-constants.js

@@ -1,6 +1,4 @@
-const ROUTE_MODULE_BUILD_CACHE_FILENAME = ".build-cache.json";
-const SERVER_ENTRY_BUILD_CACHE_FILENAME = ROUTE_MODULE_BUILD_CACHE_FILENAME;
-export {
-  ROUTE_MODULE_BUILD_CACHE_FILENAME,
-  SERVER_ENTRY_BUILD_CACHE_FILENAME
-};
+/** Filename written beside persisted production build artifacts that store incremental metadata. */
+export const ROUTE_MODULE_BUILD_CACHE_FILENAME = '.build-cache.json';
+/** @deprecated Use {@link ROUTE_MODULE_BUILD_CACHE_FILENAME}; server-entry caches share the same filename. */
+export const SERVER_ENTRY_BUILD_CACHE_FILENAME = ROUTE_MODULE_BUILD_CACHE_FILENAME;

package/src/build/cache/cache-keys.js

@@ -1,63 +1,71 @@
-import { readFileSync } from "node:fs";
+import { readFileSync } from 'node:fs';
 let cachedCorePackageVersion;
-function getCorePackageVersion() {
-  if (cachedCorePackageVersion) {
+/**
+ * Returns the installed `@ecopages/core` package version for cache invalidation.
+ */
+export function getCorePackageVersion() {
+    if (cachedCorePackageVersion) {
+        return cachedCorePackageVersion;
+    }
+    const packageJsonPath = new URL('../../../package.json', import.meta.url);
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    cachedCorePackageVersion = packageJson.version ?? '0.0.0';
     return cachedCorePackageVersion;
-  }
-  const packageJsonPath = new URL("../../../package.json", import.meta.url);
-  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
-  cachedCorePackageVersion = packageJson.version ?? "0.0.0";
-  return cachedCorePackageVersion;
 }
-function createJsxCacheKey(jsx) {
-  if (!jsx) {
-    return "jsx:default";
-  }
-  return JSON.stringify({
-    development: jsx.development ?? false,
-    factory: jsx.factory ?? null,
-    fragment: jsx.fragment ?? null,
-    importSource: jsx.importSource ?? null,
-    runtime: jsx.runtime ?? null,
-    sideEffects: jsx.sideEffects ?? null
-  });
+/** Stable fingerprint for JSX options used in build and disk cache keys. */
+export function createJsxCacheKey(jsx) {
+    if (!jsx) {
+        return 'jsx:default';
+    }
+    return JSON.stringify({
+        development: jsx.development ?? false,
+        factory: jsx.factory ?? null,
+        fragment: jsx.fragment ?? null,
+        importSource: jsx.importSource ?? null,
+        runtime: jsx.runtime ?? null,
+        sideEffects: jsx.sideEffects ?? null,
+    });
 }
-function createPluginCacheKey(plugins) {
-  if (!plugins || plugins.length === 0) {
-    return "plugins:default";
-  }
-  return `plugins:${plugins.map((plugin) => `${plugin.name}:${hashFunctionIdentity(plugin.setup)}`).join(",")}`;
+/** Stable fingerprint for ordered build plugins. */
+export function createPluginCacheKey(plugins) {
+    if (!plugins || plugins.length === 0) {
+        return 'plugins:default';
+    }
+    return `plugins:${plugins.map((plugin) => `${plugin.name}:${hashFunctionIdentity(plugin.setup)}`).join(',')}`;
 }
-function createSourceTransformCacheKey(sourceTransforms) {
-  if (!sourceTransforms || sourceTransforms.length === 0) {
-    return "sourceTransforms:default";
-  }
-  return `sourceTransforms:${sourceTransforms.map((transform) => {
-    const filterSource = transform.filter.source;
-    const filterFlags = transform.filter.flags;
-    return [
-      transform.name,
-      transform.enforce ?? "default",
-      filterSource,
-      filterFlags,
-      hashFunctionIdentity(transform.transform)
-    ].join(":");
-  }).join(",")}`;
+/** Stable fingerprint for ordered source transforms. */
+export function createSourceTransformCacheKey(sourceTransforms) {
+    if (!sourceTransforms || sourceTransforms.length === 0) {
+        return 'sourceTransforms:default';
+    }
+    return `sourceTransforms:${sourceTransforms
+        .map((transform) => {
+        const filterSource = transform.filter.source;
+        const filterFlags = transform.filter.flags;
+        return [
+            transform.name,
+            transform.enforce ?? 'default',
+            filterSource,
+            filterFlags,
+            hashFunctionIdentity(transform.transform),
+        ].join(':');
+    })
+        .join(',')}`;
 }
-function hashFunctionIdentity(fn) {
-  let hash = 0;
-  const source = fn.toString();
-  for (let index = 0; index < source.length; index += 1) {
-    hash = hash * 31 + source.charCodeAt(index) | 0;
-  }
-  return (hash >>> 0).toString(36);
+/**
+ * Stable fingerprint of a function body for cache and request identity keys.
+ *
+ * @remarks
+ * Hashes `fn.toString()`. Suitable for in-process and persisted keys that must
+ * agree within one install; not stable across minifiers or renames.
+ */
+export function hashFunctionIdentity(fn) {
+    let hash = 0;
+    const source = fn.toString();
+    for (let index = 0; index < source.length; index += 1) {
+        hash = (hash * 31 + source.charCodeAt(index)) | 0;
+    }
+    return (hash >>> 0).toString(36);
 }
-const hashPluginSetup = hashFunctionIdentity;
-export {
-  createJsxCacheKey,
-  createPluginCacheKey,
-  createSourceTransformCacheKey,
-  getCorePackageVersion,
-  hashFunctionIdentity,
-  hashPluginSetup
-};
+/** @deprecated Use {@link hashFunctionIdentity}. */
+export const hashPluginSetup = hashFunctionIdentity;