@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.6

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

@@ -1,74 +0,0 @@
-import type { EcoBuildPlugin } from './build-types.js';
-export { EsbuildBuildAdapter } from './esbuild-build-adapter.js';
-export interface BuildLog {
-    message: string;
-}
-export interface BuildOutput {
-    path: string;
-}
-/**
- * Dependency graph metadata produced by a build backend.
- *
- * @remarks
- * This structure is runtime-neutral at the type level, but current population
- * is Node/esbuild-only. Bun-backed builds may omit this metadata.
- */
-export interface BuildDependencyGraph {
-    /**
-     * Normalized absolute entrypoint path mapped to all normalized absolute
-     * source inputs that contributed to that entrypoint output.
-     */
-    entrypoints: Record<string, string[]>;
-}
-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.
-     */
-    dependencyGraph?: BuildDependencyGraph;
-}
-export interface BuildOptions {
-    entrypoints: string[];
-    outdir?: string;
-    naming?: string;
-    minify?: boolean;
-    treeshaking?: boolean;
-    target?: string;
-    format?: string;
-    sourcemap?: string;
-    splitting?: boolean;
-    root?: string;
-    bundle?: boolean;
-    externalPackages?: boolean;
-    external?: string[];
-    plugins?: EcoBuildPlugin[];
-    [key: string]: unknown;
-}
-export type BuildTranspileProfile = 'browser-script' | 'hmr-runtime' | 'hmr-entrypoint';
-export interface BuildTranspileOptions {
-    target: string;
-    format: string;
-    sourcemap: string;
-}
-export interface BuildAdapter {
-    build(options: BuildOptions): Promise<BuildResult>;
-    resolve(importPath: string, rootDir: string): string;
-    registerPlugin(plugin: EcoBuildPlugin): void;
-    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
-}
-/**
- * @deprecated Use EsbuildBuildAdapter instead. Bun native build is missing some dependency graph features.
- */
-export declare class BunBuildAdapter implements BuildAdapter {
-    build(options: BuildOptions): Promise<BuildResult>;
-    resolve(importPath: string, rootDir: string): string;
-    registerPlugin(plugin: EcoBuildPlugin): void;
-    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
-}
-export declare const defaultBuildAdapter: BuildAdapter;

package/src/build/build-adapter.js

@@ -1,54 +0,0 @@
-import { EsbuildBuildAdapter } from "./esbuild-build-adapter.js";
-import { getRequiredBunRuntime } from "../utils/runtime.js";
-import { EsbuildBuildAdapter as EsbuildBuildAdapter2 } from "./esbuild-build-adapter.js";
-function transpileProfileToOptions(profile) {
-  switch (profile) {
-    case "browser-script":
-      return {
-        target: "browser",
-        format: "esm",
-        sourcemap: "none"
-      };
-    case "hmr-runtime":
-      return {
-        target: "browser",
-        format: "esm",
-        sourcemap: "none"
-      };
-    case "hmr-entrypoint":
-      return {
-        target: "browser",
-        format: "esm",
-        sourcemap: "none"
-      };
-  }
-}
-class BunBuildAdapter {
-  async build(options) {
-    const bun = getRequiredBunRuntime();
-    const result = await bun.build({
-      ...options,
-      plugins: options.plugins
-    });
-    return {
-      success: result.success,
-      logs: result.logs.map((log) => ({ message: log.message })),
-      outputs: result.outputs.map((output) => ({ path: output.path }))
-    };
-  }
-  resolve(importPath, rootDir) {
-    return getRequiredBunRuntime().resolveSync(importPath, rootDir);
-  }
-  registerPlugin(plugin) {
-    getRequiredBunRuntime().plugin(plugin);
-  }
-  getTranspileOptions(profile) {
-    return transpileProfileToOptions(profile);
-  }
-}
-const defaultBuildAdapter = new EsbuildBuildAdapter();
-export {
-  BunBuildAdapter,
-  EsbuildBuildAdapter2 as EsbuildBuildAdapter,
-  defaultBuildAdapter
-};

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

@@ -1,57 +0,0 @@
-/**
- * Arguments passed to a build plugin `onResolve` callback.
- */
-export type EcoBuildOnResolveArgs = {
-    path: string;
-    importer?: string;
-    namespace?: string;
-};
-/**
- * Result returned by a build plugin `onResolve` callback.
- */
-export type EcoBuildOnResolveResult = {
-    path?: string;
-    namespace?: string;
-    external?: boolean;
-};
-/**
- * Arguments passed to a build plugin `onLoad` callback.
- */
-export type EcoBuildOnLoadArgs = {
-    path: string;
-    namespace?: string;
-};
-/**
- * Loader kinds supported across Bun/esbuild bridge points.
- */
-export type EcoBuildLoader = 'base64' | 'binary' | 'copy' | 'css' | 'dataurl' | 'empty' | 'file' | 'global-css' | 'js' | 'json' | 'jsx' | 'local-css' | 'object' | 'text' | 'ts' | 'tsx';
-/**
- * Result returned by a build plugin `onLoad` callback.
- */
-export type EcoBuildOnLoadResult = {
-    contents?: string | Uint8Array;
-    loader?: EcoBuildLoader;
-    exports?: Record<string, unknown>;
-    resolveDir?: string;
-};
-/**
- * Shared plugin builder contract used by Ecopages across Bun and esbuild.
- */
-export interface EcoBuildPluginBuilder {
-    onResolve(options: {
-        filter: RegExp;
-        namespace?: string;
-    }, callback: (args: EcoBuildOnResolveArgs) => EcoBuildOnResolveResult | undefined | Promise<EcoBuildOnResolveResult | undefined>): void;
-    onLoad(options: {
-        filter: RegExp;
-        namespace?: string;
-    }, callback: (args: EcoBuildOnLoadArgs) => EcoBuildOnLoadResult | undefined | Promise<EcoBuildOnLoadResult | undefined>): void;
-    module(specifier: string, callback: () => EcoBuildOnLoadResult | Promise<EcoBuildOnLoadResult>): void;
-}
-/**
- * Runtime-agnostic build plugin contract consumed by Ecopages processors/loaders.
- */
-export type EcoBuildPlugin = {
-    name: string;
-    setup: (build: EcoBuildPluginBuilder) => void | Promise<void>;
-};

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

@@ -1,69 +0,0 @@
-import type { EcoBuildPlugin } from './build-types.js';
-import type { BuildAdapter, BuildOptions, BuildResult, BuildTranspileOptions, BuildTranspileProfile } from './build-adapter.js';
-/**
- * Node build adapter backed by esbuild.
- *
- * This adapter keeps Ecopages build plugin compatibility (`onResolve`, `onLoad`,
- * and `module`) while delegating bundling and TypeScript/decorator transforms to esbuild.
- */
-export declare class EsbuildBuildAdapter implements BuildAdapter {
-    private registeredPlugins;
-    private escapeRegExp;
-    private getPluginsForBuild;
-    private normalizeEsbuildLoader;
-    private inferEsbuildLoaderFromPath;
-    private convertLoadResultToModuleSource;
-    private convertPluginOnLoadResult;
-    private resolvePluginPath;
-    /**
-     * Creates an esbuild plugin bridge compatible with the existing Ecopages
-     * plugin API shape.
-     *
-     * **Plugin ordering is semantically significant.**
-     *
-     * Esbuild applies `onResolve` and `onLoad` hooks in the order they are
-     * registered: the first handler whose filter matches wins for `onResolve`,
-     * and the first handler that returns a non-`undefined` result wins for
-     * `onLoad`. Because we call `plugin.setup(bridge)` sequentially here, the
-     * position of each plugin in the `plugins` array determines its priority:
-     *
-     * - **Index 0** has the highest priority (its hooks run first).
-     * - **Last index** has the lowest priority (its hooks only run if no earlier
-     *   plugin claimed the path).
-     *
-     * When adding new integrations or processors, ensure security-critical plugins
-     * (e.g. `ecopages-client-graph-boundary`) are placed **before** general-purpose
-     * loaders in the array so they always get first refusal on every source file.
-     *
-     * There is currently no priority system or validation — correct ordering is
-     * the caller's responsibility.
-     */
-    private createEcoPluginBridge;
-    private loadEsbuildModule;
-    private mapEsbuildSourcemap;
-    private mapEsbuildFormat;
-    private hasTemplateTokens;
-    private toEntryNamePattern;
-    private normalizeMetafilePath;
-    private extractDependencyGraph;
-    /**
-     * Normalizes esbuild errors into Ecopages `BuildLog` entries.
-     */
-    private toBuildLogs;
-    /**
-     * Bundles entrypoints using esbuild for Node runtime builds.
-     */
-    build(options: BuildOptions): Promise<BuildResult>;
-    /**
-     * Resolves module specifiers from a project root.
-     */
-    resolve(importPath: string, rootDir: string): string;
-    /**
-     * Registers a build plugin once by plugin name.
-     */
-    registerPlugin(plugin: EcoBuildPlugin): void;
-    /**
-     * Returns transpile defaults for a known transpile profile.
-     */
-    getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions;
-}

package/src/build/esbuild-build-adapter.js

@@ -1,390 +0,0 @@
-import path from "node:path";
-import { createRequire } from "node:module";
-import { fileSystem } from "@ecopages/file-system";
-function transpileProfileToOptions(profile) {
-  switch (profile) {
-    case "browser-script":
-      return {
-        target: "browser",
-        format: "esm",
-        sourcemap: "none"
-      };
-    case "hmr-runtime":
-      return {
-        target: "browser",
-        format: "esm",
-        sourcemap: "none"
-      };
-    case "hmr-entrypoint":
-      return {
-        target: "browser",
-        format: "esm",
-        sourcemap: "none"
-      };
-  }
-}
-class EsbuildBuildAdapter {
-  registeredPlugins = [];
-  escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  }
-  getPluginsForBuild(additionalPlugins) {
-    const merged = [...additionalPlugins ?? [], ...this.registeredPlugins];
-    const byName = /* @__PURE__ */ new Map();
-    for (const plugin of merged) {
-      if (!byName.has(plugin.name)) {
-        byName.set(plugin.name, plugin);
-      }
-    }
-    return Array.from(byName.values());
-  }
-  normalizeEsbuildLoader(loader) {
-    switch (loader) {
-      case "base64":
-      case "binary":
-      case "copy":
-      case "css":
-      case "dataurl":
-      case "empty":
-      case "file":
-      case "global-css":
-      case "js":
-      case "json":
-      case "jsx":
-      case "local-css":
-      case "text":
-      case "ts":
-      case "tsx":
-        return loader;
-      default:
-        return void 0;
-    }
-  }
-  inferEsbuildLoaderFromPath(filePath) {
-    const extension = path.extname(filePath).toLowerCase();
-    switch (extension) {
-      case ".ts":
-        return "ts";
-      case ".tsx":
-        return "tsx";
-      case ".jsx":
-        return "jsx";
-      case ".json":
-        return "json";
-      case ".css":
-        return "css";
-      default:
-        return "js";
-    }
-  }
-  convertLoadResultToModuleSource(result) {
-    if (!result || typeof result !== "object") {
-      return void 0;
-    }
-    const candidate = result;
-    if (typeof candidate.contents === "string") {
-      return candidate.contents;
-    }
-    if (candidate.loader === "object" && candidate.exports && typeof candidate.exports === "object") {
-      const entries = Object.entries(candidate.exports).map(
-        ([key, value]) => key === "default" ? `export default ${JSON.stringify(value)};` : `export const ${key} = ${JSON.stringify(value)};`
-      ).join("\n");
-      return entries;
-    }
-    return void 0;
-  }
-  convertPluginOnLoadResult(args, result) {
-    if (!result || typeof result !== "object") {
-      return void 0;
-    }
-    const candidate = result;
-    const sourceFromExports = candidate.loader === "object" && candidate.exports && typeof candidate.exports === "object" ? this.convertLoadResultToModuleSource(candidate) : void 0;
-    if (sourceFromExports) {
-      return {
-        contents: sourceFromExports,
-        loader: "js",
-        resolveDir: path.dirname(args.path)
-      };
-    }
-    if (typeof candidate.contents === "string" || candidate.contents instanceof Uint8Array) {
-      return {
-        contents: candidate.contents,
-        loader: this.normalizeEsbuildLoader(candidate.loader) ?? this.inferEsbuildLoaderFromPath(args.path),
-        resolveDir: typeof candidate.resolveDir === "string" ? candidate.resolveDir : path.dirname(args.path)
-      };
-    }
-    return void 0;
-  }
-  resolvePluginPath(value, args, contextRoot) {
-    if (path.isAbsolute(value)) {
-      return value;
-    }
-    if (value.startsWith(".") || value.startsWith("..")) {
-      const baseDir = args.importer ? path.dirname(args.importer) : contextRoot;
-      return path.resolve(baseDir, value);
-    }
-    return value;
-  }
-  /**
-   * Creates an esbuild plugin bridge compatible with the existing Ecopages
-   * plugin API shape.
-   *
-   * **Plugin ordering is semantically significant.**
-   *
-   * Esbuild applies `onResolve` and `onLoad` hooks in the order they are
-   * registered: the first handler whose filter matches wins for `onResolve`,
-   * and the first handler that returns a non-`undefined` result wins for
-   * `onLoad`. Because we call `plugin.setup(bridge)` sequentially here, the
-   * position of each plugin in the `plugins` array determines its priority:
-   *
-   * - **Index 0** has the highest priority (its hooks run first).
-   * - **Last index** has the lowest priority (its hooks only run if no earlier
-   *   plugin claimed the path).
-   *
-   * When adding new integrations or processors, ensure security-critical plugins
-   * (e.g. `ecopages-client-graph-boundary`) are placed **before** general-purpose
-   * loaders in the array so they always get first refusal on every source file.
-   *
-   * There is currently no priority system or validation — correct ordering is
-   * the caller's responsibility.
-   */
-  createEcoPluginBridge(plugins, contextRoot) {
-    return {
-      name: "ecopages-plugin-bridge",
-      setup: async (build) => {
-        let moduleCounter = 0;
-        const bridge = {
-          onResolve: (options, callback) => {
-            build.onResolve(options, async (args) => {
-              const result = await callback({
-                path: args.path,
-                importer: args.importer,
-                namespace: args.namespace
-              });
-              if (!result || typeof result !== "object") {
-                return void 0;
-              }
-              const candidate = result;
-              const resolveResult = {};
-              if (typeof candidate.path === "string") {
-                resolveResult.path = this.resolvePluginPath(candidate.path, args, contextRoot);
-              }
-              if (typeof candidate.namespace === "string") {
-                resolveResult.namespace = candidate.namespace;
-              }
-              if (typeof candidate.external === "boolean") {
-                resolveResult.external = candidate.external;
-              }
-              return Object.keys(resolveResult).length > 0 ? resolveResult : void 0;
-            });
-          },
-          onLoad: (options, callback) => {
-            build.onLoad(options, async (args) => {
-              const result = await callback({
-                path: args.path,
-                namespace: args.namespace
-              });
-              return this.convertPluginOnLoadResult(args, result);
-            });
-          },
-          module: (specifier, callback) => {
-            const namespace = `ecopages-module-${moduleCounter}`;
-            moduleCounter += 1;
-            const filter = new RegExp(`^${this.escapeRegExp(specifier)}$`);
-            build.onResolve({ filter }, () => ({
-              path: specifier,
-              namespace
-            }));
-            build.onLoad({ filter, namespace }, async (args) => {
-              const result = await callback();
-              return this.convertPluginOnLoadResult(args, result);
-            });
-          }
-        };
-        for (const plugin of plugins) {
-          await plugin.setup(bridge);
-        }
-      }
-    };
-  }
-  async loadEsbuildModule() {
-    const esbuildModule = await import("esbuild");
-    if (typeof esbuildModule.build !== "function") {
-      throw new Error("esbuild is not available. Install esbuild to use Node bundling.");
-    }
-    return esbuildModule;
-  }
-  mapEsbuildSourcemap(value) {
-    switch (value) {
-      case "none":
-        return false;
-      case "inline":
-        return "inline";
-      case "both":
-        return "both";
-      case "external":
-        return "external";
-      default:
-        return "linked";
-    }
-  }
-  mapEsbuildFormat(value) {
-    switch (value) {
-      case "cjs":
-        return "cjs";
-      case "iife":
-        return "iife";
-      default:
-        return "esm";
-    }
-  }
-  hasTemplateTokens(value) {
-    return typeof value === "string" && /\[[^\]]+\]/.test(value);
-  }
-  toEntryNamePattern(value) {
-    if (!value) {
-      return "[name]";
-    }
-    const pattern = value.replaceAll(/\.?\[ext\]/g, "");
-    return pattern.length > 0 ? pattern : "[name]";
-  }
-  normalizeMetafilePath(value, contextRoot) {
-    if (path.isAbsolute(value)) {
-      return path.normalize(value);
-    }
-    return path.normalize(path.resolve(contextRoot, value));
-  }
-  extractDependencyGraph(metafile, contextRoot) {
-    const entrypoints = /* @__PURE__ */ new Map();
-    for (const outputMeta of Object.values(metafile.outputs)) {
-      if (!outputMeta.entryPoint) {
-        continue;
-      }
-      const entrypointPath = this.normalizeMetafilePath(outputMeta.entryPoint, contextRoot);
-      const dependencies = entrypoints.get(entrypointPath) ?? /* @__PURE__ */ new Set();
-      dependencies.add(entrypointPath);
-      for (const inputPath of Object.keys(outputMeta.inputs ?? {})) {
-        dependencies.add(this.normalizeMetafilePath(inputPath, contextRoot));
-      }
-      entrypoints.set(entrypointPath, dependencies);
-    }
-    return {
-      entrypoints: Object.fromEntries(
-        Array.from(entrypoints.entries(), ([entrypointPath, dependencies]) => [
-          entrypointPath,
-          Array.from(dependencies)
-        ])
-      )
-    };
-  }
-  /**
-   * Normalizes esbuild errors into Ecopages `BuildLog` entries.
-   */
-  toBuildLogs(error) {
-    if (error && typeof error === "object") {
-      const candidate = error;
-      if (Array.isArray(candidate.errors) && candidate.errors.length > 0) {
-        return candidate.errors.map((entry) => {
-          const locationPrefix = entry.location?.file ? `${entry.location.file}:${entry.location.line ?? 0}:${entry.location.column ?? 0} ` : "";
-          return {
-            message: `${locationPrefix}${entry.text ?? "Unknown esbuild error"}`
-          };
-        });
-      }
-      if (typeof candidate.message === "string") {
-        return [{ message: candidate.message }];
-      }
-    }
-    return [{ message: "Unknown esbuild error" }];
-  }
-  /**
-   * Bundles entrypoints using esbuild for Node runtime builds.
-   */
-  async build(options) {
-    const esbuild = await this.loadEsbuildModule();
-    const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
-    const outdir = path.resolve(options.outdir ?? ".eco/assets");
-    const tsconfigPath = path.join(contextRoot, "tsconfig.json");
-    const tsconfigExists = fileSystem.exists(tsconfigPath);
-    const plugins = this.getPluginsForBuild(options.plugins);
-    const esbuildPlugins = [
-      ...plugins.length > 0 ? [this.createEcoPluginBridge(plugins, contextRoot)] : []
-    ];
-    const transpileTarget = "es2022";
-    const usesTemplatedNaming = this.hasTemplateTokens(options.naming);
-    const outfile = options.naming && !usesTemplatedNaming ? path.join(outdir, options.naming) : void 0;
-    if (outfile) {
-      fileSystem.ensureDir(path.dirname(outfile));
-    }
-    const outputOptions = outfile ? { outfile } : {
-      outdir,
-      entryNames: usesTemplatedNaming ? this.toEntryNamePattern(options.naming) : "[name]",
-      chunkNames: "[name]-[hash]",
-      assetNames: "[name]-[hash]"
-    };
-    try {
-      const result = await esbuild.build({
-        absWorkingDir: contextRoot,
-        entryPoints: options.entrypoints,
-        bundle: options.bundle ?? true,
-        ...outputOptions,
-        format: this.mapEsbuildFormat(options.format),
-        platform: options.target === "browser" ? "browser" : "node",
-        sourcemap: this.mapEsbuildSourcemap(options.sourcemap),
-        splitting: outfile ? false : !!options.splitting,
-        minify: !!options.minify,
-        ...typeof options.treeshaking === "boolean" ? { treeShaking: options.treeshaking } : {},
-        external: options.external,
-        ...options.target !== "browser" && options.externalPackages !== false ? { packages: "external" } : {},
-        target: transpileTarget,
-        metafile: true,
-        write: true,
-        plugins: esbuildPlugins,
-        jsx: "automatic",
-        tsconfig: tsconfigExists ? tsconfigPath : void 0,
-        logLevel: "silent"
-      });
-      const outputs = Object.keys(result.metafile.outputs).map((outputPath) => ({
-        path: path.isAbsolute(outputPath) ? outputPath : path.join(contextRoot, outputPath)
-      }));
-      const logs = result.warnings.map((warning) => ({ message: warning.text }));
-      const dependencyGraph = this.extractDependencyGraph(result.metafile, contextRoot);
-      return {
-        success: true,
-        logs,
-        outputs,
-        dependencyGraph
-      };
-    } catch (error) {
-      return {
-        success: false,
-        logs: this.toBuildLogs(error),
-        outputs: []
-      };
-    }
-  }
-  /**
-   * Resolves module specifiers from a project root.
-   */
-  resolve(importPath, rootDir) {
-    const localRequire = createRequire(path.join(rootDir, "package.json"));
-    return localRequire.resolve(importPath);
-  }
-  /**
-   * Registers a build plugin once by plugin name.
-   */
-  registerPlugin(plugin) {
-    if (!this.registeredPlugins.find((registered) => registered.name === plugin.name)) {
-      this.registeredPlugins.push(plugin);
-    }
-  }
-  /**
-   * Returns transpile defaults for a known transpile profile.
-   */
-  getTranspileOptions(profile) {
-    return transpileProfileToOptions(profile);
-  }
-}
-export {
-  EsbuildBuildAdapter
-};