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

package/src/plugins/alias-resolver-cache.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Per-plugin cache for `@/...` alias resolution.
+ *
+ * @remarks
+ * The `ecopages-alias-resolver` plugin resolves project aliases like
+ * `@/components/Button` to concrete file paths under the app's `srcDir`.
+ * Each resolution can trigger up to 22 `existsSync` calls and (when
+ * the resolved path is a barrel) a `readFileSync` to detect
+ * `export * from './...'` forwarding.
+ *
+ * This cache memoizes the result keyed by `(srcDir, specifier)`. It is
+ * process-local and not currently invalidated by the file watcher —
+ * `srcDir` contents are assumed to be stable for the lifetime of the
+ * process.
+ */
+export declare class AliasResolverCache {
+    private readonly entries;
+    private readonly maxEntries;
+    private hits;
+    private misses;
+    constructor(maxEntries?: number);
+    /**
+     * Look up a previously-computed resolution for `(srcDir, specifier)`.
+     *
+     * Returns `{ hit: true, resolved }` on cache hit (resolved may be
+     * `undefined` for an unresolvable specifier), or `{ hit: false }` on
+     * miss. The caller is responsible for re-running the resolver and
+     * calling `set` to store the new entry.
+     */
+    get(srcDir: string, specifier: string): {
+        hit: true;
+        resolved: string | undefined;
+    } | {
+        hit: false;
+    };
+    /**
+     * Store a resolution result.
+     *
+     * Pass `undefined` for `resolved` to memoize the negative case
+     * (specifier did not resolve) and avoid repeating the FS walk on
+     * every `@/...` import.
+     */
+    set(srcDir: string, specifier: string, resolved: string | undefined): void;
+    /**
+     * Drop all entries whose `srcDir` is under `rootDir`. Use this from
+     * the file watcher when files are added or removed under the app's
+     * source tree.
+     *
+     * Path comparison is path-aware (handles both POSIX `/` and
+     * Windows `\` separators) via `path.relative` so cached entries
+     * normalized on one platform still match the watcher's `rootDir`
+     * on another. Without this, a Windows build that sees
+     * `entry.srcDir === 'C:\app\src'` would miss
+     * `entry.srcDir.startsWith('C:/app/src/')` and leave stale entries.
+     */
+    invalidateUnder(rootDir: string): number;
+    /** Clear all entries. */
+    clear(): void;
+    /** Current cache size. */
+    get size(): number;
+    /** Hit/miss counters for observability. */
+    stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+        hitRate: number;
+    };
+}

package/src/plugins/alias-resolver-cache.js

@@ -0,0 +1,106 @@
+import path from "node:path";
+const DEFAULT_MAX_ENTRIES = 2e3;
+class AliasResolverCache {
+  entries = /* @__PURE__ */ new Map();
+  maxEntries;
+  hits = 0;
+  misses = 0;
+  constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+    if (maxEntries <= 0) {
+      throw new Error(`AliasResolverCache: maxEntries must be > 0, got ${maxEntries}`);
+    }
+    this.maxEntries = maxEntries;
+  }
+  /**
+   * Look up a previously-computed resolution for `(srcDir, specifier)`.
+   *
+   * Returns `{ hit: true, resolved }` on cache hit (resolved may be
+   * `undefined` for an unresolvable specifier), or `{ hit: false }` on
+   * miss. The caller is responsible for re-running the resolver and
+   * calling `set` to store the new entry.
+   */
+  get(srcDir, specifier) {
+    const key = makeKey(srcDir, specifier);
+    const existing = this.entries.get(key);
+    if (existing) {
+      this.hits += 1;
+      this.entries.delete(key);
+      this.entries.set(key, existing);
+      return { hit: true, resolved: existing.resolved };
+    }
+    this.misses += 1;
+    return { hit: false };
+  }
+  /**
+   * Store a resolution result.
+   *
+   * Pass `undefined` for `resolved` to memoize the negative case
+   * (specifier did not resolve) and avoid repeating the FS walk on
+   * every `@/...` import.
+   */
+  set(srcDir, specifier, resolved) {
+    const key = makeKey(srcDir, specifier);
+    this.entries.set(key, { srcDir, resolved });
+    if (this.entries.size > this.maxEntries) {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey !== void 0) {
+        this.entries.delete(oldestKey);
+      }
+    }
+  }
+  /**
+   * Drop all entries whose `srcDir` is under `rootDir`. Use this from
+   * the file watcher when files are added or removed under the app's
+   * source tree.
+   *
+   * Path comparison is path-aware (handles both POSIX `/` and
+   * Windows `\` separators) via `path.relative` so cached entries
+   * normalized on one platform still match the watcher's `rootDir`
+   * on another. Without this, a Windows build that sees
+   * `entry.srcDir === 'C:\app\src'` would miss
+   * `entry.srcDir.startsWith('C:/app/src/')` and leave stale entries.
+   */
+  invalidateUnder(rootDir) {
+    const normalizedRoot = path.resolve(rootDir);
+    let removed = 0;
+    for (const [key, entry] of this.entries) {
+      if (isUnderDirectory(path.resolve(entry.srcDir), normalizedRoot)) {
+        this.entries.delete(key);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+  /** Clear all entries. */
+  clear() {
+    this.entries.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+  /** Current cache size. */
+  get size() {
+    return this.entries.size;
+  }
+  /** Hit/miss counters for observability. */
+  stats() {
+    const total = this.hits + this.misses;
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      size: this.entries.size,
+      hitRate: total === 0 ? 0 : this.hits / total
+    };
+  }
+}
+function makeKey(srcDir, specifier) {
+  return `${srcDir} ${specifier}`;
+}
+function isUnderDirectory(candidate, parent) {
+  if (candidate === parent) return true;
+  const rel = path.relative(parent, candidate);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return false;
+  return true;
+}
+export {
+  AliasResolverCache
+};

package/src/plugins/alias-resolver-plugin.d.ts

@@ -0,0 +1,6 @@
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import { AliasResolverCache } from './alias-resolver-cache.js';
+export declare function resolveAppSourceAliasPath(srcDir: string, specifier: string): string | undefined;
+export declare function createAliasResolverPlugin(srcDir: string, options?: {
+    cache?: AliasResolverCache;
+}): EcoBuildPlugin;

package/src/plugins/alias-resolver-plugin.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { AliasResolverCache } from "./alias-resolver-cache.js";
+const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx", ".css", ".scss", ".sass", ".less"];
+function findResolvablePath(candidate) {
+  if (path.extname(candidate)) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  for (const extension of RESOLVABLE_EXTENSIONS) {
+    const fileCandidate = `${candidate}${extension}`;
+    if (existsSync(fileCandidate)) {
+      return fileCandidate;
+    }
+  }
+  for (const extension of RESOLVABLE_EXTENSIONS) {
+    const indexCandidate = path.join(candidate, `index${extension}`);
+    if (existsSync(indexCandidate)) {
+      return indexCandidate;
+    }
+  }
+  return void 0;
+}
+function resolveAliasedBarrelTarget(resolvedPath) {
+  if (!path.basename(resolvedPath).startsWith("index.")) {
+    return resolvedPath;
+  }
+  const source = readFileSync(resolvedPath, "utf8").trim();
+  const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
+  if (!match?.[1]?.startsWith(".")) {
+    return resolvedPath;
+  }
+  const target = findResolvablePath(path.resolve(path.dirname(resolvedPath), match[1]));
+  return target ?? resolvedPath;
+}
+function resolveAppSourceAliasPath(srcDir, specifier) {
+  if (!specifier.startsWith("@/")) {
+    return void 0;
+  }
+  const candidate = path.join(srcDir, specifier.slice(2));
+  const resolved = findResolvablePath(candidate);
+  return resolved ? resolveAliasedBarrelTarget(resolved) : void 0;
+}
+function createAliasResolverPlugin(srcDir, options) {
+  const cache = options?.cache ?? new AliasResolverCache();
+  return {
+    name: "ecopages-alias-resolver",
+    setup(build) {
+      build.onResolve({ filter: /^@\// }, (args) => {
+        const cached = cache.get(srcDir, args.path);
+        if (cached.hit) {
+          return cached.resolved ? { path: cached.resolved } : {};
+        }
+        const resolved = resolveAppSourceAliasPath(srcDir, args.path);
+        cache.set(srcDir, args.path, resolved);
+        return resolved ? { path: resolved } : {};
+      });
+    }
+  };
+}
+export {
+  createAliasResolverPlugin,
+  resolveAppSourceAliasPath
+};

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

@@ -0,0 +1,108 @@
+/**
+ * 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

@@ -0,0 +1,175 @@
+import { cachedParseSync } from "../cache/module-parse-cache.js";
+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 = cachedParseSync(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

@@ -0,0 +1,33 @@
+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 the bundler 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

@@ -0,0 +1,41 @@
+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
+};