@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.21

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

@@ -0,0 +1,97 @@
+import type { EcoSourceTransform } from '../plugins/source-transform.js';
+import type { EcoBuildPlugin } from './build-types.js';
+/**
+ * Which backend owns the app's build pipeline.
+ *
+ * - `'rolldown'`: the default. Ecopages runs the build directly through
+ *   its bundler-backed adapter.
+ * - `'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';
+/** A single message emitted by the build backend. */
+export interface BuildLog {
+    message: string;
+}
+/** A single artifact emitted by the build backend. */
+export interface BuildOutput {
+    path: string;
+}
+/** Per-entrypoint dependency metadata surfaced alongside a build. */
+export interface BuildDependencyGraph {
+    entrypoints: Record<string, string[]>;
+}
+/** The full result of one `BuildAdapter.build` call. */
+export interface BuildResult {
+    success: boolean;
+    logs: BuildLog[];
+    outputs: BuildOutput[];
+    dependencyGraph?: BuildDependencyGraph;
+    entryOutputs?: Record<string, string>;
+}
+/**
+ * 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.
+ */
+export interface BuildOptions {
+    entrypoints: string[] | Record<string, string>;
+    outdir?: string;
+    /**
+     * Base directory for `[dir]` placeholders in `naming`. Currently
+     * the bundled adapter derives the base from `root` directly and
+     * ignores this field.
+     *
+     * @deprecated Accepted for call-site compatibility only. Use record-form
+     * `entrypoints` keys to preserve directory structure.
+     */
+    outbase?: string;
+    naming?: string;
+    conditions?: string[];
+    define?: Record<string, string>;
+    minify?: boolean;
+    treeshaking?: boolean;
+    target?: string;
+    format?: string;
+    sourcemap?: string;
+    /** @deprecated Accepted for call-site compatibility only. */
+    splitting?: boolean;
+    root?: string;
+    /** @deprecated Accepted for call-site compatibility only. */
+    bundle?: boolean;
+    externalPackages?: boolean;
+    external?: string[];
+    jsx?: {
+        development?: boolean;
+        factory?: string;
+        fragment?: string;
+        importSource?: string;
+        runtime?: 'classic' | 'automatic';
+        sideEffects?: boolean;
+    };
+    plugins?: EcoBuildPlugin[];
+    sourceTransforms?: EcoSourceTransform[];
+    [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. */
+export interface BuildTranspileOptions {
+    target: string;
+    format: string;
+    sourcemap: string;
+}
+/** Low-level build backend contract. */
+export interface BuildAdapter {
+    readonly ownership?: BuildOwnership;
+    build(options: BuildOptions): Promise<BuildResult>;
+    resolve(importPath: string, rootDir: string): string;
+    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
+}
+/** Runtime-facing facade for issuing builds. */
+export interface BuildExecutor {
+    build(options: BuildOptions): Promise<BuildResult>;
+}

package/src/build/build-input-fingerprint.d.ts

@@ -0,0 +1,28 @@
+import type { IntegrationPlugin } from '../plugins/integration-plugin.js';
+import type { Processor } from '../plugins/processor.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+/**
+ * Optional contributor surface for build-time cache invalidation.
+ *
+ * @remarks
+ * Processors and integrations may override {@link didChange} to report that
+ * their build inputs changed independently of route source files.
+ */
+export interface BuildInputChangeContributor {
+    /**
+     * Returns `true` when this contributor's build inputs changed since the last
+     * persisted incremental build metadata was written.
+     */
+    didChange?(): boolean;
+}
+/** Returns whether a processor or integration signals changed build inputs. */
+export declare function didBuildInputContributorChange(contributor: BuildInputChangeContributor): boolean;
+/** Hashes the app's eco.config.ts file when present. */
+export declare function hashAppConfigFile(appConfig: EcoPagesAppConfig): string;
+/** Fingerprints processor/integration build-input state for cache invalidation. */
+export declare function createBuildInputsFingerprint(appConfig: EcoPagesAppConfig): string;
+/** Returns true when any processor or integration reports changed build inputs. */
+export declare function haveBuildInputsChanged(appConfig: EcoPagesAppConfig): boolean;
+/** Collects every processor and integration that can invalidate incremental builds. */
+export declare function collectBuildInputContributors(appConfig: EcoPagesAppConfig): BuildInputChangeContributor[];
+export type { Processor, IntegrationPlugin };

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

@@ -0,0 +1,31 @@
+import { fileSystem } from "@ecopages/file-system";
+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);
+}
+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";
+}
+function collectBuildInputContributors(appConfig) {
+  return [...Array.from(appConfig.processors?.values() ?? []), ...appConfig.integrations ?? []];
+}
+export {
+  collectBuildInputContributors,
+  createBuildInputsFingerprint,
+  didBuildInputContributorChange,
+  hashAppConfigFile,
+  haveBuildInputsChanged
+};

package/src/build/build-profile-options.d.ts

@@ -0,0 +1,7 @@
+import type { BuildOptions } from './build-adapter.js';
+import type { BuildProfile } from './build-runtime.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+/**
+ * Resolves shared Rolldown options for a build profile.
+ */
+export declare function resolveBuildProfileOptions(profile: BuildProfile, appConfig: EcoPagesAppConfig, overrides?: Partial<BuildOptions>): Partial<BuildOptions>;

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

@@ -0,0 +1,37 @@
+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
+      };
+  }
+}
+export {
+  resolveBuildProfileOptions
+};

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

@@ -0,0 +1,24 @@
+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
+ * All profiles use one-shot Rolldown. Server-entry stays serialized
+ * single-flight; route-module and browser-HMR run in parallel.
+ */
+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/build-runtime.js

@@ -0,0 +1,65 @@
+import { availableParallelism } from "node:os";
+import {
+  getAppBrowserBuildPlugins,
+  getAppBuildAdapter,
+  getAppServerBuildPlugins,
+  withBuildExecutorPlugins
+} 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 serverPlugins = withBuildExecutorPlugins(adapter, () => getAppServerBuildPlugins(appConfig));
+    const browserPlugins = withBuildExecutorPlugins(adapter, () => getAppBrowserBuildPlugins(appConfig));
+    const limit = resolveParallelismLimit();
+    this.serverEntryExecutor = new SerializedBuildExecutor(serverPlugins);
+    this.routeModuleExecutor = new DedupingBuildExecutor(new ParallelBuildExecutor(serverPlugins, limit));
+    this.hmrExecutor = new DedupingBuildExecutor(new ParallelBuildExecutor(browserPlugins, 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;
+    }
+  }
+  async dispose() {
+  }
+}
+function getBuildRuntime(appConfig) {
+  return appConfig.runtime?.buildRuntime;
+}
+function requireBuildRuntime(appConfig) {
+  return getBuildRuntime(appConfig) ?? installBuildRuntime(appConfig);
+}
+function installBuildRuntime(appConfig) {
+  const buildRuntime = new AppBuildRuntime(appConfig);
+  patchAppRuntime(appConfig, { buildRuntime });
+  return buildRuntime;
+}
+async function disposeAppBuildRuntime(appConfig) {
+  await getBuildRuntime(appConfig)?.dispose();
+}
+export {
+  disposeAppBuildRuntime,
+  getBuildRuntime,
+  installBuildRuntime,
+  requireBuildRuntime
+};

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

@@ -0,0 +1,28 @@
+import type { BuildExecutor, BuildOptions, BuildResult } from './build-adapter.js';
+/**
+ * Stable cache key for coalescing concurrent identical build requests.
+ *
+ * @remarks
+ * Reuses the same material as route-module disk cache keys: normalized entrypoints,
+ * outdir, splitting, JSX, and plugin setup fingerprints.
+ */
+export declare function createBuildOptionsDedupeKey(options: BuildOptions): string;
+/**
+ * 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/deduping-build-executor.js

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { createJsxCacheKey, createPluginCacheKey } from "../services/module-loading/route-module-build-manifest.js";
+function createBuildOptionsDedupeKey(options) {
+  return [
+    normalizeEntrypoints(options.entrypoints),
+    options.root ? path.resolve(options.root) : "root:default",
+    options.outdir ? path.resolve(options.outdir) : "outdir:default",
+    options.splitting ?? "splitting: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",
+    createJsxCacheKey(options.jsx),
+    createPluginCacheKey(options.plugins)
+  ].join("::");
+}
+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("|");
+}
+class DedupingBuildExecutor {
+  inner;
+  inFlight = /* @__PURE__ */ new Map();
+  constructor(inner) {
+    this.inner = inner;
+  }
+  build(options) {
+    const key = createBuildOptionsDedupeKey(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;
+  }
+}
+export {
+  DedupingBuildExecutor,
+  createBuildOptionsDedupeKey
+};

package/src/build/jsx-ownership-plugins.d.ts

@@ -0,0 +1,24 @@
+import type { EcoBuildPlugin } from './build-types.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+/**
+ * Foreign JSX override plugins for mixed-integration app builds.
+ *
+ * Each plugin rewrites files for one `(integration, extension)` pair with that
+ * integration's own `@jsxImportSource` so the bundler preserves the owning JSX
+ * runtime for native extension ownership.
+ *
+ * Extensions are sorted longest-first so `.page.react.tsx` wins over `.tsx`.
+ */
+export declare function getJsxOwnershipPlugins(appConfig: EcoPagesAppConfig): EcoBuildPlugin[];
+/**
+ * Host-scoped JSX override plugins for one integration's client bundle graph.
+ *
+ * When a host integration (for example React) bundles foreign `.tsx` files, those
+ * files must compile with the host JSX runtime instead of the project default.
+ * Use this helper for host-owned client bundles. For app-wide transpilation that
+ * should preserve each integration's native JSX runtime, use
+ * {@link getJsxOwnershipPlugins} instead.
+ */
+export declare function getHostScopedJsxOwnershipPlugins(appConfig: EcoPagesAppConfig, hostIntegrationName: string, options?: {
+    name?: string;
+}): EcoBuildPlugin[];

package/src/build/jsx-ownership-plugins.js

@@ -0,0 +1,41 @@
+import { createForeignJsxOverridePlugin } from "../plugins/foreign-jsx-override-plugin.js";
+import { collectJsxExtensions, filterJsxSourceExtensions } from "../plugins/jsx-import-source.utils.js";
+function collectJsxExtensionEntries(appConfig) {
+  return (appConfig.integrations ?? []).filter((integration) => integration.jsxImportSource).flatMap(
+    (integration) => filterJsxSourceExtensions(integration.extensions).map((extension) => ({ integration, extension }))
+  ).sort((left, right) => right.extension.length - left.extension.length);
+}
+function getJsxOwnershipPlugins(appConfig) {
+  const jsxExtensions = collectJsxExtensionEntries(appConfig);
+  return jsxExtensions.map(
+    ({ integration, extension }) => createForeignJsxOverridePlugin({
+      hostJsxImportSource: integration.jsxImportSource,
+      foreignExtensions: [extension],
+      excludeExtensions: jsxExtensions.filter((candidate) => candidate.extension.length > extension.length).filter((candidate) => candidate.extension.endsWith(extension)).map((candidate) => candidate.extension),
+      name: `ecopages-jsx-ownership-${integration.name}-${extension.replace(/[^a-zA-Z0-9]+/g, "-")}`
+    })
+  );
+}
+function getHostScopedJsxOwnershipPlugins(appConfig, hostIntegrationName, options) {
+  const hostIntegration = (appConfig.integrations ?? []).find(
+    (integration) => integration.name === hostIntegrationName
+  );
+  const hostJsxImportSource = hostIntegration?.jsxImportSource;
+  if (!hostJsxImportSource) {
+    return [];
+  }
+  const foreignExtensions = collectJsxExtensions(appConfig.integrations ?? [], {
+    excludeIntegrationName: hostIntegrationName
+  });
+  return [
+    createForeignJsxOverridePlugin({
+      name: options?.name ?? `ecopages-jsx-ownership-host-${hostIntegrationName}`,
+      hostJsxImportSource,
+      foreignExtensions
+    })
+  ];
+}
+export {
+  getHostScopedJsxOwnershipPlugins,
+  getJsxOwnershipPlugins
+};

package/src/build/pages-unified-graph-build.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Unified pages Rolldown graph (Phase A build + Phase C import).
+ *
+ * Enabled by default in production builds. Opt out with
+ * `ECOPAGES_UNIFIED_PAGES_GRAPH=0`. Covers all static page template extensions
+ * registered on the app config.
+ */
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+export declare const PAGES_UNIFIED_GRAPH_CACHE_DIR = ".server-pages-graph";
+export declare const PAGES_UNIFIED_GRAPH_CACHE_FILENAME = ".build-cache.json";
+export interface PagesUnifiedGraphCacheManifest {
+    invalidationVersion: string;
+    buildInputsFingerprint: string;
+    buildKey: string;
+    builtAt: number;
+    outputs: Record<string, string>;
+}
+export declare function isPagesUnifiedGraphEnabled(): boolean;
+/** True when the unified graph should build or serve prebuilt page modules. */
+export declare function shouldBuildPagesUnifiedGraph(): boolean;
+export declare function isPagesUnifiedGraphPage(filePath: string, appConfig: EcoPagesAppConfig): boolean;
+/**
+ * Builds eligible static pages in one Rolldown invocation and seeds route-module disk cache.
+ */
+export declare function ensurePagesUnifiedGraphBuilt(options: {
+    appConfig: EcoPagesAppConfig;
+    entryPaths: readonly string[];
+    outdir: string;
+    force?: boolean;
+}): Promise<PagesUnifiedGraphCacheManifest | undefined>;
+export declare function importPagesUnifiedGraphModule<T>(appConfig: EcoPagesAppConfig, filePath: string): Promise<T | undefined>;