@ecopages/core 0.2.0-alpha.52 → 0.2.0-alpha.54

package/src/plugins/eco-component-meta-plugin.d.ts

@@ -1,108 +0,0 @@
-/**
- * Bun plugin that auto-injects `__eco` metadata into EcoComponent config objects.
- *
- * This plugin uses AST parsing (via oxc-parser) to reliably inject the `__eco` property
- * into EcoComponent config objects at import time. The injected metadata contains:
- * - `dir`: The directory path of the component file (used for dependency resolution)
- * - `integration`: The integration type (e.g., 'react', 'kitajs', 'ghtml', 'lit')
- *
- * The plugin intercepts file loading for all configured integration extensions and
- * transforms component configs before they are executed.
- *
- * @example
- * ```typescript
- * // Before transformation:
- * export default eco.page({
- *   render: () => '<div>Hello</div>',
- * });
- *
- * // After transformation:
- * export default eco.page({
- *   __eco: { id: "<hash>", file: "/path/to/pages/index.tsx", integration: "react" },
- *   render: () => '<div>Hello</div>',
- * });
- * ```
- *
- * @module eco-component-meta-plugin
- */
-import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { EcoPagesAppConfig } from '../types/internal-types.js';
-import { type EcoSourceTransform, type EcoViteCompatiblePlugin } from './source-transform.js';
-/**
- * Options for creating the eco-component-meta-plugin.
- */
-export interface EcoComponentDirPluginOptions {
-    /** The EcoPages application configuration containing integration settings */
-    config: EcoPagesAppConfig;
-}
-/**
- * Creates the bundler-neutral metadata transform used by Ecopages loaders and
- * Vite-compatible adapters.
- */
-export declare function createEcoComponentMetaTransform(options: EcoComponentDirPluginOptions): EcoSourceTransform;
-/**
- * Creates a build plugin that auto-injects `__eco` metadata into EcoComponent config objects.
- *
- * This plugin intercepts file loading for all integration-compatible files and:
- * 1. Strips any query string from the file path (for dev mode cache-busting)
- * 2. Reads the file contents
- * 3. Parses the AST using oxc-parser to find injection points
- * 4. Injects `__eco: { id: "...", file: "...", integration: "..." }` into config objects
- * 5. Returns the transformed content with the appropriate loader
- *
- * Supported patterns:
- * - `eco.page({ ... })` - Page component declarations
- * - `eco.component({ ... })` - Reusable component declarations
- * - `eco.html({ ... })` - HTML shell declarations
- * - `eco.layout({ ... })` - Layout declarations
- * - `Component.config = { ... }` - Config assignment pattern
- * - `config: { ... }` - Config property in object literals
- * - `export const config = { ... }` - Exported config declarations
- *
- * @param options - Plugin options containing the EcoPages config
- * @returns A build plugin instance ready for registration
- *
- * @example
- * ```typescript
- * import { createEcoComponentMetaPlugin } from '@ecopages/core';
- *
- * const plugin = createEcoComponentMetaPlugin({ config: appConfig });
- * appConfig.loaders.set(plugin.name, plugin);
- * ```
- */
-export declare function createEcoComponentMetaPlugin(options: EcoComponentDirPluginOptions): EcoBuildPlugin;
-/**
- * Creates a Vite-compatible metadata injection plugin from the shared
- * Ecopages source-transform primitive.
- */
-export declare function createEcoComponentMetaVitePlugin(options: EcoComponentDirPluginOptions): EcoViteCompatiblePlugin;
-/**
- * Injects `__eco` metadata into EcoComponent config objects in file content.
- *
- * Uses oxc-parser for robust AST-based code analysis, which handles edge cases
- * that regex-based approaches would miss (e.g., complex generics, nested objects,
- * comments, string literals containing similar patterns).
- *
- * The injection is performed by:
- * 1. Parsing the source code into an AST
- * 2. Walking the AST to find all config object patterns
- * 3. Collecting insertion points (sorted in reverse order to preserve positions)
- * 4. Inserting the `__eco` property at each point
- *
- * @param contents - The source code content to transform
- * @param filePath - Absolute path to the file (used to derive the directory)
- * @param integration - The integration identifier for this file type
- * @returns Transformed source code with `__eco` injected, or original if no patterns found
- *
- * @example
- * ```typescript
- * const result = injectEcoMeta(
- *   'export default eco.page({ render: () => "<div>Hi</div>" });',
- *   '/app/src/pages/index.tsx',
- *   'react'
- * );
- * // Result: 'export default eco.page({ __eco: { id: "<hash>", file: "/app/src/pages/index.tsx", integration: "react" }, render: () => "<div>Hi</div>" });'
- * ```
- */
-export declare function injectEcoMeta(contents: string, filePath: string, integration: string): string;
-export default createEcoComponentMetaPlugin;

package/src/plugins/eco-component-meta-plugin.js

@@ -1,175 +0,0 @@
-import { parseSync } from "oxc-parser";
-import { rapidhash } from "../utils/hash.js";
-import {
-  createEcoBuildPluginFromSourceTransform,
-  createVitePluginFromSourceTransform
-} from "./source-transform.js";
-const REGEX_SPECIAL_CHARS = /[.*+?^${}()|[\]\\]/g;
-const VALID_LOADER_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx"]);
-function hasValidLoaderExtension(ext) {
-  for (const validExt of VALID_LOADER_EXTENSIONS) {
-    if (ext.endsWith(validExt)) {
-      return true;
-    }
-  }
-  return false;
-}
-function buildExtensionToIntegrationMap(integrations) {
-  const mapping = [];
-  for (const integration of integrations) {
-    for (const ext of integration.extensions) {
-      mapping.push([
-        ext,
-        {
-          name: integration.name,
-          jsxImportSource: integration.jsxImportSource
-        }
-      ]);
-    }
-  }
-  mapping.sort((a, b) => b[0].length - a[0].length);
-  return mapping;
-}
-function detectIntegration(filePath, extensionToIntegration) {
-  for (const [ext, integration] of extensionToIntegration) {
-    if (filePath.endsWith(ext)) {
-      return integration;
-    }
-  }
-  return { name: "ghtml" };
-}
-function prependJsxImportSource(code, jsxImportSource) {
-  if (!jsxImportSource || code.includes("@jsxImportSource")) {
-    return code;
-  }
-  return `/** @jsxImportSource ${jsxImportSource} */
-${code}`;
-}
-function createExtensionPattern(extensions) {
-  if (extensions.length === 0) {
-    throw new Error("[eco-component-meta-plugin] No extensions configured. At least one integration is required.");
-  }
-  const uniqueExtensions = [...new Set(extensions)];
-  const escaped = uniqueExtensions.map((ext) => ext.replace(REGEX_SPECIAL_CHARS, "\\$&"));
-  return new RegExp(`(${escaped.join("|")})(\\?.*)?$`);
-}
-function createEcoComponentMetaTransform(options) {
-  const allExtensions = options.config.integrations.flatMap((integration) => integration.extensions).filter(hasValidLoaderExtension);
-  if (allExtensions.length === 0) {
-    throw new Error("[eco-component-meta-plugin] No extensions configured. At least one integration is required.");
-  }
-  const extensionPattern = createExtensionPattern(allExtensions);
-  const extensionToIntegration = buildExtensionToIntegrationMap(options.config.integrations);
-  return {
-    name: "eco-component-meta-plugin",
-    enforce: "pre",
-    filter: extensionPattern,
-    transform(code, id) {
-      const integration = detectIntegration(id, extensionToIntegration);
-      return {
-        code: prependJsxImportSource(injectEcoMeta(code, id, integration.name), integration.jsxImportSource)
-      };
-    }
-  };
-}
-function createEcoComponentMetaPlugin(options) {
-  return createEcoBuildPluginFromSourceTransform(createEcoComponentMetaTransform(options));
-}
-function createEcoComponentMetaVitePlugin(options) {
-  return createVitePluginFromSourceTransform(createEcoComponentMetaTransform(options));
-}
-function findInjectionPoints(node, insertions, injection, isInsideEcoComponent = false) {
-  if (!node || typeof node !== "object") return;
-  const n = node;
-  if (n.type === "CallExpression") {
-    const callee = n.callee;
-    if (callee?.type === "MemberExpression" || callee?.type === "StaticMemberExpression") {
-      const obj = callee.object;
-      const prop = callee.property;
-      if (obj?.type === "Identifier" && obj?.name === "eco" && (prop?.name === "page" || prop?.name === "component" || prop?.name === "html" || prop?.name === "layout")) {
-        const args = n.arguments;
-        const firstArg = args?.[0];
-        if (firstArg?.type === "ObjectExpression") {
-          const start = firstArg.start;
-          if (typeof start === "number") {
-            insertions.push({ position: start + 1, text: injection });
-          }
-        }
-      }
-    }
-  }
-  if (n.type === "AssignmentExpression") {
-    const left = n.left;
-    const right = n.right;
-    if (left?.type === "MemberExpression" || left?.type === "StaticMemberExpression") {
-      const prop = left.property;
-      if (prop?.name === "config" && right?.type === "ObjectExpression") {
-        const start = right.start;
-        if (typeof start === "number") {
-          insertions.push({ position: start + 1, text: injection });
-        }
-      }
-    }
-  }
-  if (n.type === "ObjectProperty" || n.type === "Property") {
-    const key = n.key;
-    const value = n.value;
-    if ((key?.type === "Identifier" || key?.type === "IdentifierName") && key?.name === "config" && value?.type === "ObjectExpression" && isInsideEcoComponent) {
-      const start = value.start;
-      if (typeof start === "number") {
-        insertions.push({ position: start + 1, text: injection });
-      }
-    }
-  }
-  let childIsInsideEcoComponent = isInsideEcoComponent;
-  if (n.type === "VariableDeclarator") {
-    const id = n.id;
-    const typeAnnotation = id?.typeAnnotation;
-    if (typeAnnotation) {
-      const typeStr = JSON.stringify(typeAnnotation);
-      if (typeStr.includes("EcoComponent")) {
-        childIsInsideEcoComponent = true;
-      }
-    }
-  }
-  for (const key in n) {
-    if (key === "start" || key === "end" || key === "type") continue;
-    const value = n[key];
-    if (Array.isArray(value)) {
-      for (const child of value) {
-        findInjectionPoints(child, insertions, injection, childIsInsideEcoComponent);
-      }
-    } else if (typeof value === "object" && value !== null) {
-      findInjectionPoints(value, insertions, injection, childIsInsideEcoComponent);
-    }
-  }
-}
-function injectEcoMeta(contents, filePath, integration) {
-  const result = parseSync(filePath, contents);
-  if (result.errors.length > 0) {
-    console.warn(`[eco-component-meta-plugin] Parse errors in ${filePath}:`, result.errors);
-    return contents;
-  }
-  const ast = result.program;
-  const id = rapidhash(filePath).toString(36);
-  const injection = ` __eco: { id: "${id}", file: "${filePath}", integration: "${integration}" },`;
-  const insertions = [];
-  findInjectionPoints(ast, insertions, injection);
-  if (insertions.length === 0) {
-    return contents;
-  }
-  insertions.sort((a, b) => b.position - a.position);
-  let transformed = contents;
-  for (const { position, text } of insertions) {
-    transformed = transformed.slice(0, position) + text + transformed.slice(position);
-  }
-  return transformed;
-}
-var eco_component_meta_plugin_default = createEcoComponentMetaPlugin;
-export {
-  createEcoComponentMetaPlugin,
-  createEcoComponentMetaTransform,
-  createEcoComponentMetaVitePlugin,
-  eco_component_meta_plugin_default as default,
-  injectEcoMeta
-};

package/src/plugins/foreign-jsx-override-plugin.d.ts

@@ -1,33 +0,0 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
-/**
- * Options for the shared foreign-JSX override build plugin.
- */
-export interface ForeignJsxOverrideOptions {
-    /** JSX runtime that should own the transformed foreign files. */
-    hostJsxImportSource: string;
-    /** Extensions claimed by other JSX integrations that may appear in the host graph. */
-    foreignExtensions: string[];
-    /** More specific owned suffixes that must not be claimed by this override. */
-    excludeExtensions?: string[];
-    /** Optional plugin name override for debug output. */
-    name?: string;
-}
-/**
- * Build plugin that prepends a `@jsxImportSource` pragma to foreign integration
- * files bundled into a host integration's client graph.
- *
- * When a host integration (e.g. React) bundles a component file that belongs to
- * another JSX integration (e.g. `.kita.tsx`), that file inherits the project
- * `tsconfig` JSX runtime which produces the wrong output (HTML strings instead
- * of framework elements). This plugin rewrites the source to explicitly target
- * the host's JSX factory so esbuild compiles every JSX expression into the
- * correct element creation calls.
- *
- * The plugin is intentionally framework-agnostic: any integration that does
- * client-side bundling can use it by passing its own `jsxImportSource` and the
- * set of foreign extensions collected from the app config.
- *
- * When no JSX-bearing foreign extensions are present, the returned plugin is a
- * no-op so integrations can register it unconditionally.
- */
-export declare function createForeignJsxOverridePlugin(options: ForeignJsxOverrideOptions): EcoBuildPlugin;

package/src/plugins/foreign-jsx-override-plugin.js

@@ -1,41 +0,0 @@
-import { readFileSync } from "node:fs";
-import path from "node:path";
-function createForeignJsxOverridePlugin(options) {
-  const extensions = options.foreignExtensions.filter((ext) => ext.endsWith(".tsx") || ext.endsWith(".jsx"));
-  const excludedExtensions = (options.excludeExtensions ?? []).filter(
-    (ext) => ext.endsWith(".tsx") || ext.endsWith(".jsx")
-  );
-  if (extensions.length === 0) {
-    return {
-      name: options.name ?? "foreign-jsx-override",
-      setup() {
-      }
-    };
-  }
-  const pragma = `/** @jsxImportSource ${options.hostJsxImportSource} */
-`;
-  const filter = new RegExp(`(${extensions.map((e) => e.replace(".", "\\.")).join("|")})$`);
-  return {
-    name: options.name ?? "foreign-jsx-override",
-    setup(build) {
-      build.onLoad({ filter }, (args) => {
-        if (excludedExtensions.some((extension) => args.path.endsWith(extension))) {
-          return void 0;
-        }
-        const source = readFileSync(args.path, "utf-8");
-        const loader = args.path.endsWith(".jsx") ? "jsx" : "tsx";
-        if (source.includes("@jsxImportSource")) {
-          return void 0;
-        }
-        return {
-          contents: pragma + source,
-          loader,
-          resolveDir: path.dirname(args.path)
-        };
-      });
-    }
-  };
-}
-export {
-  createForeignJsxOverridePlugin
-};

package/src/plugins/integration-plugin.d.ts

@@ -1,230 +0,0 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
-import { type BrowserRuntimeManifest } from '../build/browser-runtime-manifest.js';
-import type { EcoPagesAppConfig, IHmrManager } from '../types/internal-types.js';
-import type { HmrStrategy } from '../hmr/hmr-strategy.js';
-import type { EcoPagesElement } from '../types/public-types.js';
-import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.js';
-import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.js';
-import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
-import type { RuntimeCapabilityDeclaration } from './runtime-capability.js';
-export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.js';
-export type { EcoBuildLoader, EcoBuildOnLoadArgs, EcoBuildOnLoadResult, EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin, EcoBuildPluginBuilder, } from '../build/build-types.js';
-export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../types/public-types.js';
-export type { HtmlDocumentContribution, HtmlDocumentContributionContext, } from '../route-renderer/orchestration/integration-renderer.js';
-/**
- * Type-erased integration plugin stored in app-level registries.
- *
- * Ecopages keeps one heterogeneous integration list, while each plugin and
- * renderer still owns its framework-specific render payload type internally.
- */
-export type AnyIntegrationPlugin = IntegrationPlugin<unknown>;
-export declare const INTEGRATION_PLUGIN_ERRORS: {
-    readonly NOT_INITIALIZED_WITH_APP_CONFIG: "Plugin not initialized with app config";
-    readonly NOT_INITIALIZED_WITH_ASSET_SERVICE: "Plugin not initialized with asset dependency service";
-};
-export declare function mergeIntegrationOptions<TDefaults, TOverrides>(defaults: TDefaults, overrides: TOverrides): TDefaults & TOverrides;
-export declare function assertIntegrationInvariant(condition: boolean, message?: string): asserts condition;
-/**
- * Base configuration shared by all integration plugins.
- *
- * @remarks
- * Integrations declare their file ownership, optional runtime requirements, and
- * any global assets or build-time contributions here. Runtime-only side effects
- * belong in `setup()` rather than the constructor.
- */
-export interface IntegrationPluginConfig {
-    /**
-     * The name of the integration plugin.
-     */
-    name: string;
-    /**
-     * The extensions that this plugin supports (e.g., ['.kita.js', '.kita.tsx']).
-     */
-    extensions: string[];
-    /**
-     * The dependencies that this plugin requires on a global level.
-     * These dependencies will be resolved during the setup process and injected into the global scope of the application.
-     * They are not specific to any particular page or component.
-     */
-    integrationDependencies?: AssetDefinition[];
-    /**
-     * The strategy to use for static building.
-     * - 'render': Execute component function directly (faster, efficient).
-     * - 'fetch': Start server and fetch URL (slower, needed for some SSR like Lit).
-     * @default 'render'
-     */
-    staticBuildStep?: 'render' | 'fetch';
-    /**
-     * Declares runtime-specific requirements that must be satisfied before the
-     * app can start with this integration enabled.
-     */
-    runtimeCapability?: RuntimeCapabilityDeclaration;
-    /**
-     * JSX import source owned by this integration.
-     *
-     * @remarks
-     * This is primarily used by mixed-JSX flows where host-owned browser bundles
-     * need to preserve the correct JSX runtime for files claimed by the
-     * integration.
-     */
-    jsxImportSource?: string;
-}
-type RendererClass<C> = new (options: {
-    appConfig: EcoPagesAppConfig;
-    assetProcessingService: AssetProcessingService;
-    resolvedIntegrationDependencies: ProcessedAsset[];
-    rendererModules?: unknown;
-    runtimeOrigin: string;
-}) => IntegrationRenderer<C>;
-/**
- * Base class for framework integrations.
- *
- * @remarks
- * An integration owns three main concerns:
- * - which file extensions it claims
- * - which renderer class turns those files into HTML
- * - which build-time or runtime contributions must be registered for that framework
- *
- * Core owns lifecycle ordering. Integrations declare contributions through the
- * hooks on this class, while `ConfigBuilder.build()` and app startup decide when
- * those hooks run. For page-browser and document shaping, integrations should
- * prefer the contribution contracts re-exported from this module:
- * `PageBrowserGraphContribution` / `PageBrowserGraphContributionContext` and
- * `HtmlDocumentContribution` / `HtmlDocumentContributionContext`.
- */
-export declare abstract class IntegrationPlugin<C = EcoPagesElement> {
-    readonly name: string;
-    readonly extensions: string[];
-    abstract renderer: RendererClass<C>;
-    readonly staticBuildStep: 'render' | 'fetch';
-    readonly runtimeCapability?: RuntimeCapabilityDeclaration;
-    readonly jsxImportSource?: string;
-    protected integrationDependencies: AssetDefinition[];
-    protected resolvedIntegrationDependencies: ProcessedAsset[];
-    protected options?: Record<string, unknown>;
-    protected appConfig?: EcoPagesAppConfig;
-    protected assetProcessingService?: AssetProcessingService;
-    protected hmrManager?: IHmrManager;
-    runtimeOrigin: string;
-    get plugins(): EcoBuildPlugin[];
-    /**
-     * Returns build plugins that should only apply to browser-oriented bundles.
-     *
-     * @remarks
-     * Browser-only transforms such as runtime import aliasing belong here so they
-     * do not affect server bundles or static-page module generation.
-     */
-    get browserBuildPlugins(): EcoBuildPlugin[];
-    /**
-     * Returns shared browser runtime asset declarations owned by this integration.
-     *
-     * @remarks
-     * Core seals these declarations into the app build manifest so app-owned browser
-     * bundle paths can rewrite manifest-owned imports even when a specific build
-     * request does not install an integration-local runtime rewrite plugin.
-     */
-    get browserRuntimeManifest(): BrowserRuntimeManifest;
-    /**
-     * Creates the integration with static declaration-only configuration.
-     *
-     * @remarks
-     * Constructors are expected to stay side-effect free. Build-manifest
-     * contributions belong in `prepareBuildContributions()` and runtime-only setup
-     * belongs in `setup()`.
-     */
-    constructor(config: IntegrationPluginConfig);
-    /**
-     * Attaches the finalized app config to the integration.
-     *
-     * Core calls this during config finalization before runtime setup so the
-     * integration can resolve asset paths and other app-owned services later.
-     */
-    setConfig(appConfig: EcoPagesAppConfig): void;
-    /**
-     * Records the runtime origin used for page-module loading and renderer setup.
-     */
-    setRuntimeOrigin(runtimeOrigin: string): void;
-    /**
-     * Returns an HMR strategy for this integration, if applicable.
-     * The strategy will be registered with the HmrManager during initialization.
-     *
-     * @returns HmrStrategy instance or undefined if no custom HMR handling needed
-     *
-     * @example
-     * ```typescript
-     * getHmrStrategy(): HmrStrategy {
-     *   const context = this.hmrManager!.getDefaultContext();
-     *   return new ReactHmrStrategy({ context, pageMetadataCache, runtimeManifest });
-     * }
-     * ```
-     */
-    getHmrStrategy?(): HmrStrategy | undefined;
-    /**
-     * Attaches the shared HMR manager and registers integration-owned development hooks.
-     *
-     * @remarks
-     * The default implementation registers the optional integration HMR strategy.
-     * Integrations should override this only when they need to extend that shared
-     * behavior rather than replace it.
-     */
-    setHmrManager(hmrManager: IHmrManager): void;
-    /**
-     * Creates the asset-processing service used for global integration dependencies.
-     */
-    initializeAssetDefinitionService(): void;
-    /**
-     * Returns processed global assets resolved during `setup()`.
-     */
-    getResolvedIntegrationDependencies(): ProcessedAsset[];
-    /**
-     * Creates the shared renderer options owned by core lifecycle setup.
-     */
-    protected createRendererOptions(options?: {
-        rendererModules?: unknown;
-    }): {
-        appConfig: EcoPagesAppConfig;
-        assetProcessingService: AssetProcessingService;
-        resolvedIntegrationDependencies: ProcessedAsset[];
-        rendererModules: unknown;
-        runtimeOrigin: string;
-    };
-    /**
-     * Attaches runtime-only services after a renderer instance has been created.
-     */
-    protected attachRendererRuntimeServices<T extends IntegrationRenderer<C>>(renderer: T): T;
-    /**
-     * Instantiates the integration renderer with app-owned services.
-     *
-     * @remarks
-     * Renderers are cheap runtime objects. They receive the finalized app config,
-     * a fresh asset-processing service, integration-global processed assets, and
-     * any renderer module context supplied by the active runtime.
-            renderer.name ||= this.name;
-     */
-    initializeRenderer(options?: {
-        rendererModules?: unknown;
-    }): IntegrationRenderer<C>;
-    /**
-     * Prepares build-facing contributions before the app build manifest is sealed.
-     *
-     * @remarks
-     * Integrations can override this when runtime or build plugin declarations must
-     * be materialized ahead of runtime startup. Runtime-only side effects stay in
-     * `setup()`.
-     */
-    prepareBuildContributions(): Promise<void>;
-    /**
-     * Performs runtime-only integration setup after config build has already
-     * sealed manifest contributions.
-     */
-    setup(): Promise<void>;
-    /**
-     * Releases runtime resources owned by the integration.
-     *
-     * @remarks
-     * Most integrations do not need custom teardown. Override this only for
-     * explicit cleanup such as watchers, compiler handles, or runtime registries
-     * that outlive individual requests.
-     */
-    teardown(): Promise<void>;
-}