@ecopages/core 0.2.0-alpha.9 → 0.2.1-beta.0

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

@@ -1,157 +1,450 @@
+/**
+ * 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.buildExecutor`. It is intentionally narrower than
+ *   `BuildAdapter` so callers that only need to issue builds do not depend
+ *   on `resolve` / `getTranspileOptions`.
+ * - App-owned helpers (`getAppBuildAdapter`, `getAppBuildExecutor`, and
+ *   the `set*` counterparts) — the supported way for runtime code to read
+ *   and mutate the active adapter per `EcoPagesAppConfig`.
+ */
 import type { EcoBuildPlugin } from './build-types.js';
 import { type AppBuildManifest } from './build-manifest.js';
-import type { EcoPagesAppConfig } from '../internal-types.js';
-import type { IHmrManager } from '../public-types.js';
-export { EsbuildBuildAdapter } from './esbuild-build-adapter.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { IHmrManager } from '../types/public-types.js';
+/**
+ * Which backend owns the app's build pipeline.
+ *
+ * - `'rolldown'`: the default. Ecopages runs the build directly through
+ *   its bundler-backed adapter.
+ * - `'rolldown-dev'`: uses Rolldown's DevEngine for cached incremental
+ *   rebuilds. Ideal for HMR and watch mode where the same entrypoints
+ *   are rebuilt repeatedly.
+ * - `'vite-host'`: a host runtime owns the build. {@link ViteHostBuildAdapter}
+ *   is exposed as a boundary marker; any direct call into it throws.
+ */
+export type BuildOwnership = 'vite-host' | 'rolldown' | 'rolldown-dev';
+/**
+ * A single message emitted by the build backend.
+ *
+ * @remarks
+ * Today this only carries `message`. Severity and structured fields
+ * belong in a future schema bump; the current shape mirrors the
+ * bundler's log output 1:1.
+ */
 export interface BuildLog {
     message: string;
 }
+/**
+ * A single artifact emitted by the build backend.
+ *
+ * @remarks
+ * `path` is the absolute on-disk path of the emitted file. For
+ * filename templates that include a content-hash token, the bundler
+ * returns the concrete resolved path (not the template), so callers
+ * can read the file directly.
+ */
 export interface BuildOutput {
     path: string;
 }
 /**
- * Dependency graph metadata produced by a build backend.
+ * Per-entrypoint dependency metadata surfaced alongside a build.
  *
  * @remarks
- * This structure is runtime-neutral at the type level, but current population
- * is Node/esbuild-only. Bun-backed builds may omit this metadata.
+ * Populated from the bundler's per-chunk module list and exposed as a
+ * normalized absolute-path map. Consumers (HMR invalidation, the build
+ * manifest) read this without needing to know which adapter produced
+ * it. The shape is preserved across adapters so historical callers
+ * continue to compile.
  */
 export interface BuildDependencyGraph {
     /**
-     * Normalized absolute entrypoint path mapped to all normalized absolute
-     * source inputs that contributed to that entrypoint output.
+     * Normalized absolute entrypoint path mapped to every normalized
+     * absolute source input that contributed to that entrypoint's
+     * output, including the entrypoint itself.
      */
     entrypoints: Record<string, string[]>;
 }
+/**
+ * The full result of one `BuildAdapter.build` call.
+ *
+ * @remarks
+ * `success === false` means the build failed and `outputs` will be
+ * empty. Inspect `logs` for the error message; the original `Error` is
+ * already normalized into `BuildLog` shape.
+ */
 export interface BuildResult {
     success: boolean;
     logs: BuildLog[];
     outputs: BuildOutput[];
     /**
-     * Optional build dependency metadata for selective invalidation.
-     *
-     * @remarks
-     * This is currently filled by the Node/esbuild adapter. Other runtimes should
-     * treat missing graph data as a valid state and fall back deterministically.
+     * Per-entrypoint dependency metadata, when the backend produced it.
+     * Some backends (notably the Vite-host boundary marker) leave this
+     * undefined; callers must treat that as a valid state and fall
+     * back deterministically.
      */
     dependencyGraph?: BuildDependencyGraph;
 }
+/**
+ * Options accepted by every `BuildAdapter.build` call.
+ *
+ * @remarks
+ * Fields that the adapter can forward are honored; fields that cannot
+ * (currently `splitting`, `bundle`, and `outbase`) are accepted so
+ * call-sites compile, but the adapter ignores them. See each field's
+ * docstring for the current behavior.
+ */
 export interface BuildOptions {
-    entrypoints: string[];
+    /**
+     * Absolute or context-root-relative source files that begin the build graph.
+     *
+     * Use a record (key → source path) when the caller needs to control chunk
+     * names. Keys become the `[name]` token in `naming`, which lets the caller
+     * embed path information that the bundler would otherwise strip.
+     */
+    entrypoints: string[] | Record<string, string>;
+    /** Output directory. Defaults to `dist/assets` when omitted. */
     outdir?: string;
+    /**
+     * Base directory for `[dir]` placeholders in `naming`. Currently
+     * the bundled adapter derives the base from `root` directly and
+     * ignores this field.
+     */
     outbase?: string;
+    /**
+     * Filename pattern for entrypoints. The bundled adapter honors
+     * `[name]`, `[hash]`, and `[ext]`. The `[dir]` token is stripped
+     * before forwarding to the bundler (rolldown does not implement it);
+     * callers that need directory structure preserved should use the
+     * record form of `entrypoints` so each key becomes its own chunk.
+     * When omitted, the bundler's default applies.
+     */
     naming?: string;
+    /**
+     * Package export conditions to honor during resolution
+     * (e.g. `['import', 'browser', 'default']`).
+     */
     conditions?: string[];
+    /**
+     * Global identifier replacements. Honored by the bundled adapter.
+     */
     define?: Record<string, string>;
+    /** Run the bundler's minifier. Off by default. */
     minify?: boolean;
+    /** Enable the bundler's tree-shaker. Defaults to `true`. */
     treeshaking?: boolean;
+    /**
+     * Output target family. Accepted values: `'browser'`, `'node'`,
+     * anything else falls through to a platform-neutral setup.
+     */
     target?: string;
+    /** Output module format. Accepted: `'esm'`, `'cjs'`, `'iife'`. */
     format?: string;
+    /**
+     * Source map mode. Accepted: `'none'`, `'inline'`, `'external'`,
+     * `'linked'`. Anything else maps to the bundler's default (linked).
+     */
     sourcemap?: string;
+    /**
+     * Historical code-splitting flag. Currently a no-op on the bundled
+     * adapter: the bundler splits by default and this flag is not
+     * forwarded. See the per-chunk naming convention in the adapter for
+     * the available control.
+     */
     splitting?: boolean;
+    /** Project root used to resolve relative paths and the tsconfig lookup. */
     root?: string;
+    /**
+     * Historical bundle flag. Currently a no-op on the bundled adapter:
+     * the bundler always bundles. Accepted so call-sites compile.
+     */
     bundle?: boolean;
+    /**
+     * Treat `node_modules` packages as external. Honored by the bundled
+     * adapter.
+     */
     externalPackages?: boolean;
+    /** Explicit list of module specifiers to leave as external imports. */
     external?: string[];
+    /**
+     * JSX runtime configuration. Mirrors the bundler's `jsx` option shape.
+     */
+    jsx?: {
+        development?: boolean;
+        factory?: string;
+        fragment?: string;
+        importSource?: string;
+        runtime?: 'classic' | 'automatic';
+        sideEffects?: boolean;
+    };
+    /**
+     * Runtime-agnostic `EcoBuildPlugin[]` to attach to this build. The
+     * bundled adapter translates the array via the rolldown plugin
+     * bridge.
+     */
     plugins?: EcoBuildPlugin[];
+    /**
+     * Escape hatch for backends that need to forward unknown options
+     * to their underlying driver. Consumers should prefer the typed
+     * fields above.
+     */
     [key: string]: unknown;
 }
+/** Stable profile identifiers for `BuildAdapter.getTranspileOptions`. */
 export type BuildTranspileProfile = 'browser-script' | 'hmr-runtime' | 'hmr-entrypoint';
+/**
+ * Resolved transpile settings for a given profile.
+ *
+ * @remarks
+ * The three fields map 1:1 to the trio the HMR and browser-script
+ * code paths look at: target platform, output format, and source-map
+ * mode. Today the bundled adapter returns identical defaults for all
+ * three profiles; the type is kept open so per-profile tuning can
+ * land without breaking callers.
+ */
 export interface BuildTranspileOptions {
     target: string;
     format: string;
     sourcemap: string;
 }
+/**
+ * Low-level build backend contract.
+ *
+ * @remarks
+ * One instance is owned by each `EcoPagesAppConfig` (see
+ * {@link getAppBuildAdapter}). Two implementations exist: the bundled
+ * adapter does the work; {@link ViteHostBuildAdapter} is a host-owned
+ * boundary marker that throws on direct use.
+ */
 export interface BuildAdapter {
+    /** Which backend owns this adapter. Used for routing decisions in app helpers. */
+    readonly ownership?: BuildOwnership;
     /**
-     * Executes one concrete backend build.
+     * Run one build.
      *
      * @remarks
-     * `BuildAdapter` is the low-level backend contract. The default adapter is
-     * `EsbuildBuildAdapter`, but alternate adapters may satisfy the same shape.
+     * Implementations are expected to be safe to call from any caller.
+     * Concurrent calls are not guaranteed to be serialized by the
+     * adapter itself; the dev-watch pipeline wraps the adapter in
+     * {@link SerializedBuildExecutor} when it needs FIFO ordering.
+     *
+     * Returns a `BuildResult` with `success: false` on failure; the
+     * thrown-error variant (`buildOrThrow`) is reserved for callers
+     * that need the original `Error` object.
      */
     build(options: BuildOptions): Promise<BuildResult>;
+    /**
+     * Resolve a module specifier against the project's `rootDir`.
+     *
+     * @remarks
+     * Used by the source-loading services when they need to know the
+     * absolute path of a specifier without performing a full build.
+     */
     resolve(importPath: string, rootDir: string): string;
+    /**
+     * Resolve transpile settings for a known profile.
+     *
+     * @remarks
+     * Today the bundled adapter returns identical defaults for all
+     * profiles. The profile argument is kept so per-profile tuning
+     * can land without breaking callers.
+     */
     getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
 }
 /**
- * Runtime-owned facade for issuing builds.
+ * Runtime-facing facade for issuing builds.
  *
  * @remarks
- * This is intentionally narrower than `BuildAdapter`. A build executor answers
- * only the question "how should this app execute a build right now?".
+ * Strictly narrower than {@link BuildAdapter}: it only exposes `build`.
+ * This is the shape stored on `appConfig.runtime.buildExecutor` and
+ * passed across the dev-watch and server-module-loading seams, so
+ * callers cannot accidentally depend on `resolve` or
+ * `getTranspileOptions`.
  *
- * In production and non-watch flows the executor is usually the adapter itself,
- * which today means `EsbuildBuildAdapter`. In development watch flows the
- * executor is typically `DevBuildCoordinator`, which wraps the shared esbuild
- * adapter to serialize callers and recover from known worker faults.
+ * In production and non-watch flows the executor is the adapter
+ * itself. In development watch flows the executor is a
+ * {@link SerializedBuildExecutor} wrapping the adapter so dev-watch
+ * pipelines are FIFO-serialized.
  */
 export interface BuildExecutor {
     build(options: BuildOptions): Promise<BuildResult>;
 }
-export declare function createBuildAdapter(): BuildAdapter;
 /**
- * @deprecated Use EsbuildBuildAdapter instead. Bun native build is missing some dependency graph features.
+ * Wraps a {@link BuildExecutor} so each call to `build` receives the
+ * union of the caller's `options.plugins` and the plugins sourced
+ * from `getPlugins()`.
+ *
+ * @remarks
+ * The single point of plugin injection in the runtime path: the
+ * `ConfigBuilder` stores a raw adapter on
+ * `appConfig.runtime.buildAdapter` and the
+ * `installAppRuntimeBuildExecutor` step wraps that adapter with this
+ * helper. Callers that issue builds against
+ * `appConfig.runtime.buildExecutor` get the merged plugin set without
+ * further ceremony.
  */
-export declare class BunBuildAdapter implements BuildAdapter {
-    build(options: BuildOptions): Promise<BuildResult>;
-    resolve(importPath: string, rootDir: string): string;
-    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+export declare function withBuildExecutorPlugins(executor: BuildExecutor, getPlugins: () => EcoBuildPlugin[]): BuildExecutor;
+/**
+ * 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 declare class ViteHostBuildAdapter implements BuildAdapter {
+    readonly ownership: "vite-host";
+    build(_options: BuildOptions): Promise<BuildResult>;
+    resolve(_importPath: string, _rootDir: string): string;
+    getTranspileOptions(_profile: BuildTranspileProfile): BuildTranspileOptions;
 }
+/**
+ * Constructs a {@link ViteHostBuildAdapter}. Use only in code paths
+ * that explicitly opt into the host-owned boundary.
+ */
+export declare function createViteHostBuildAdapter(): BuildAdapter;
+/**
+ * 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 declare function createBuildAdapter(options?: {
+    ownership?: BuildOwnership;
+}): BuildAdapter;
+/** The shared default-bundler backend instance. Use {@link getAppBuildAdapter} in app-aware code. */
+export declare const defaultRolldownBuildAdapter: BuildAdapter;
+/** The shared Vite-host boundary instance. Use {@link getAppBuildAdapter} in app-aware code. */
+export declare const defaultViteHostBuildAdapter: BuildAdapter;
+/**
+ * Global default build adapter.
+ *
+ * @remarks
+ * Resolves to the bundled default-bundler adapter. New app-aware
+ * code should prefer {@link getAppBuildAdapter}.
+ */
 export declare const defaultBuildAdapter: BuildAdapter;
+/**
+ * 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 declare function getDefaultBuildAdapter(ownership?: BuildOwnership): BuildAdapter;
+/**
+ * Reads the {@link BuildOwnership} declared on a {@link BuildAdapter}.
+ *
+ * @param buildAdapter - When `undefined`, defaults to `'rolldown'`.
+ */
+export declare function getBuildAdapterOwnership(buildAdapter: BuildAdapter | undefined): BuildOwnership;
+/**
+ * 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 declare function getAppBuildOwnership(appConfig: EcoPagesAppConfig): BuildOwnership;
+/**
+ * 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 declare function setAppBuildOwnership(appConfig: EcoPagesAppConfig, buildOwnership: BuildOwnership): void;
 /**
  * Returns the adapter owned by an app/runtime instance.
  *
  * @remarks
- * The config builder installs a dedicated adapter per app. The shared default
- * adapter remains only as a compatibility fallback for older tests and helpers
- * that do not yet thread app runtime state explicitly.
+ * Falls back through `appConfig.runtime.buildAdapter` →
+ * {@link getDefaultBuildAdapter} on the resolved ownership. Throws
+ * never; a missing adapter resolves to the global default.
  */
 export declare function getAppBuildAdapter(appConfig: EcoPagesAppConfig): BuildAdapter;
 /**
- * Installs the adapter that should serve future builds for one app instance.
+ * 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 declare function setAppBuildAdapter(appConfig: EcoPagesAppConfig, buildAdapter: BuildAdapter): void;
 /**
  * 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 declare function getAppBuildManifest(appConfig: EcoPagesAppConfig): AppBuildManifest;
-/**
- * Installs the build manifest that should be visible to one app instance.
- */
+/** Installs the build manifest that should be visible to one app instance. */
 export declare function setAppBuildManifest(appConfig: EcoPagesAppConfig, buildManifest: AppBuildManifest): void;
 /**
- * Rebuilds an app-owned manifest from config-owned loaders plus explicit
- * runtime/browser contribution input.
+ * Builds a fresh app manifest from the config's loaders plus optional
+ * caller-supplied runtime/browser contributions.
  *
  * @remarks
- * This keeps loader ownership with config finalization while still letting a
- * caller supply the non-loader plugin buckets that were discovered elsewhere.
+ * 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 declare function createConfiguredAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): AppBuildManifest;
 /**
- * Replaces the app-owned manifest using config-owned loaders and explicit
- * contribution input.
+ * Replaces the app-owned manifest using config-owned loaders and the
+ * caller-supplied contribution input.
  */
 export declare function updateAppBuildManifest(appConfig: EcoPagesAppConfig, input?: Partial<AppBuildManifest>): void;
 /**
- * Collects the build-facing processor and integration contributions that should
- * be sealed into the app manifest during config finalization.
+ * Collects the build-facing processor and integration contributions
+ * that should be sealed into the app manifest during config
+ * finalization.
  *
  * @remarks
- * This runs `prepareBuildContributions()` only. Runtime-only side effects such
- * as HMR registration, cache prewarming, and runtime-origin wiring belong to
- * the startup path and must not be triggered here.
+ * Runs `prepareBuildContributions()` on every processor and
+ * integration. Runtime-only side effects (HMR registration, cache
+ * prewarming, runtime-origin wiring) belong to the startup path and
+ * must not be triggered here; use {@link setupAppRuntimePlugins} for
+ * those.
+ *
+ * @returns The new manifest's runtime / browser / browser-runtime-manifest
+ * contribution buckets. Caller seals them into a manifest via
+ * {@link updateAppBuildManifest}.
  */
-export declare function collectConfiguredAppBuildManifestContributions(appConfig: EcoPagesAppConfig): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins'>>;
+export declare function collectConfiguredAppBuildManifestContributions(appConfig: EcoPagesAppConfig): Promise<Pick<AppBuildManifest, 'runtimePlugins' | 'browserBundlePlugins' | 'browserRuntimeManifest'>>;
 /**
- * Runs runtime-only processor and integration setup against an already sealed
- * app manifest.
+ * Runs runtime-only processor and integration setup against an already
+ * sealed app manifest.
  *
  * @remarks
- * Startup paths call this after config build has finalized manifest
- * contributions. The manifest is reused as-is; this helper only performs the
- * runtime side effects that still need live startup context.
+ * Startup paths call this after `ConfigBuilder.build` has finalized
+ * the manifest. The manifest is reused as-is; this helper only performs
+ * the runtime side effects that need live startup context (cache
+ * prewarming, runtime-origin wiring, HMR manager attachment).
+ *
+ * Loaders, processors, and integrations are visited in that order;
+ * each one's plugins are forwarded to the optional `onRuntimePlugin`
+ * callback so callers can attach to every plugin discovered.
  */
 export declare function setupAppRuntimePlugins(options: {
     appConfig: EcoPagesAppConfig;
@@ -159,28 +452,56 @@ export declare function setupAppRuntimePlugins(options: {
     hmrManager?: IHmrManager;
     onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
 }): Promise<void>;
+/**
+ * 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 declare function getAppServerBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+/**
+ * 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.
+ */
 export declare function getAppBrowserBuildPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
 /**
  * Returns the executor owned by an app/runtime instance.
  *
  * @remarks
- * The config builder seeds this with the shared default adapter. Runtime
- * adapters may replace it with a coordinator that still delegates to the same
- * backend while adding development policy.
+ * Falls back to {@link getAppBuildAdapter} when no executor is set
+ * on the runtime yet. The dev-watch pipeline replaces this value with
+ * a {@link SerializedBuildExecutor} via
+ * {@link installAppRuntimeBuildExecutor}.
  */
 export declare function getAppBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor;
-/**
- * Installs the executor that should serve future builds for one app instance.
- */
+/** Installs the executor that should serve future builds for one app instance. */
 export declare function setAppBuildExecutor(appConfig: EcoPagesAppConfig, buildExecutor: BuildExecutor): void;
 /**
  * Runs a build through the active pipeline.
  *
  * @remarks
- * Callers can pass an explicit executor when builds should be routed through an
- * app-owned development coordinator. Without one, the shared default adapter is
- * used directly.
+ * `executor` defaults to the default-bundler adapter for non-app-aware
+ * callsites. App-aware code should pass
+ * `getAppBuildExecutor(appConfig)` (or read it directly) to honor the
+ * per-app pipeline.
  */
 export declare function build(options: BuildOptions, executor?: BuildExecutor): Promise<BuildResult>;
+/**
+ * Default transpile-options helper for callsites without app runtime
+ * context.
+ *
+ * @remarks
+ * New app-aware code should prefer {@link getAppTranspileOptions}.
+ */
 export declare function getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+/**
+ * Resolves transpile options for one app/runtime instance by asking
+ * the app's adapter.
+ */
+export declare function getAppTranspileOptions(appConfig: EcoPagesAppConfig, profile: BuildTranspileProfile): BuildTranspileOptions;