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

package/src/cache/module-parse-cache.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Process-wide parse cache for `oxc-parser.parseSync`.
+ *
+ * @remarks
+ * Several build plugins (eco-component-meta, client-graph-boundary,
+ * browser-runtime) each call `parseSync` on the same source file with
+ * overlapping options. This cache memoizes the parse result keyed by
+ * `(absolute path, source, options)`. When the source is unchanged,
+ * subsequent calls return the cached result without re-parsing.
+ *
+ * The cache is LRU-bounded (10 000 entries) and key-stable across a
+ * single HMR session. It is **content-hashed** rather than
+ * mtime-hashed so that `touch`/`utimes` does not invalidate a
+ * still-valid parse.
+ */
+import { type ParseResult, type ParserOptions } from 'oxc-parser';
+export type ModuleParseOptions = ParserOptions & {
+    /**
+     * Optional parser language override. If omitted, derived from the file
+     * extension at lookup time. Set this explicitly if your caller already
+     * computed the language (avoids re-deriving inside the cache).
+     */
+    lang?: ParserOptions['lang'];
+};
+/**
+ * LRU-bounded module parse cache.
+ *
+ * Single instance shared across the process. Constructed lazily; use
+ * {@link moduleParseCache} for the default shared instance.
+ */
+export declare class ModuleParseCache {
+    private readonly entries;
+    private readonly maxEntries;
+    private hits;
+    private misses;
+    constructor(maxEntries?: number);
+    /**
+     * Parse `source` for `filePath`, memoizing by (filePath, source, options).
+     *
+     * @returns the {@link ParseResult} from `oxc-parser.parseSync`.
+     */
+    getOrParse(filePath: string, source: string, options?: ModuleParseOptions): ParseResult;
+    /** Clear all cached entries. Useful in tests and on full-rebuild signals. */
+    clear(): void;
+    /** Current cache size (for observability). */
+    get size(): number;
+    /** Cumulative hit/miss counters (for observability). */
+    stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+        hitRate: number;
+    };
+}
+/**
+ * Default shared cache. Use this from plugin code so the cache is
+ * amortized across plugins and build invocations.
+ */
+export declare const moduleParseCache: ModuleParseCache;
+/**
+ * Drop-in replacement for `oxc-parser.parseSync` that uses the shared
+ * {@link moduleParseCache}. Use everywhere we currently call `parseSync`
+ * on user/source files during a build.
+ */
+export declare function cachedParseSync(filePath: string, source: string, options?: ModuleParseOptions): ParseResult;

package/src/cache/module-parse-cache.js

@@ -0,0 +1,75 @@
+import { parseSync } from "oxc-parser";
+import { rapidhash } from "../utils/hash.js";
+const DEFAULT_MAX_ENTRIES = 1e4;
+class ModuleParseCache {
+  entries = /* @__PURE__ */ new Map();
+  maxEntries;
+  hits = 0;
+  misses = 0;
+  constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+    if (maxEntries <= 0) {
+      throw new Error(`ModuleParseCache: maxEntries must be > 0, got ${maxEntries}`);
+    }
+    this.maxEntries = maxEntries;
+  }
+  /**
+   * Parse `source` for `filePath`, memoizing by (filePath, source, options).
+   *
+   * @returns the {@link ParseResult} from `oxc-parser.parseSync`.
+   */
+  getOrParse(filePath, source, options = {}) {
+    const hash = rapidhash(source);
+    const key = makeKey(filePath, hash, options);
+    const existing = this.entries.get(key);
+    if (existing && existing.hash === hash) {
+      this.hits += 1;
+      this.entries.delete(key);
+      this.entries.set(key, existing);
+      return existing.result;
+    }
+    this.misses += 1;
+    const result = parseSync(filePath, source, options);
+    this.entries.set(key, { hash, result });
+    if (this.entries.size > this.maxEntries) {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey !== void 0) {
+        this.entries.delete(oldestKey);
+      }
+    }
+    return result;
+  }
+  /** Clear all cached entries. Useful in tests and on full-rebuild signals. */
+  clear() {
+    this.entries.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+  /** Current cache size (for observability). */
+  get size() {
+    return this.entries.size;
+  }
+  /** Cumulative 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
+    };
+  }
+}
+const moduleParseCache = new ModuleParseCache();
+function cachedParseSync(filePath, source, options = {}) {
+  return moduleParseCache.getOrParse(filePath, source, options);
+}
+function makeKey(filePath, sourceHash, options) {
+  const lang = options.lang ?? "";
+  const sourceType = options.sourceType ?? "";
+  return `${filePath} ${sourceHash.toString(36)} ${lang} ${sourceType}`;
+}
+export {
+  ModuleParseCache,
+  cachedParseSync,
+  moduleParseCache
+};

package/src/config/config-builder.d.ts

@@ -0,0 +1,252 @@
+/**
+ * This module contains the ConfigBuilder class, which is used to build the EcoPagesAppConfig object.
+ * @module
+ */
+import { type BuildOwnership } from '../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoPagesAppConfig, RobotsPreference } from '../types/internal-types.js';
+import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
+import type { Processor } from '../plugins/processor.js';
+import type { EcoSourceTransform } from '../plugins/source-transform.js';
+import type { PageMetadataProps } from '../types/public-types.js';
+import type { CacheConfig } from '../services/cache/cache.types.js';
+export declare const CONFIG_BUILDER_ERRORS: {
+    readonly DUPLICATE_INTEGRATION_NAMES: "Integrations names must be unique";
+    readonly DUPLICATE_INTEGRATION_EXTENSIONS: "Integrations extensions must be unique";
+    readonly MIXED_JSX_ENGINES: "Both kitajs and react integrations are enabled. Use per-file JSX import source/pragma consistently (e.g. `/** @jsxImportSource react */` for React files and `/** @jsxImportSource @kitajs/html */` for Kita files).";
+    readonly duplicateProcessorName: (name: string) => string;
+    readonly duplicateLoaderName: (name: string) => string;
+    readonly duplicateSemanticTemplate: (kind: "html" | "404", matches: string[]) => string;
+    readonly incompatibleRuntimeCapability: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, reason: string) => string;
+    readonly unsupportedRuntimeVersion: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, current: string, min: string) => string;
+    readonly invalidRuntimeVersion: (kind: "integration" | "processor", name: string, version: string) => string;
+};
+type RuntimeKind = 'node' | 'bun';
+/**
+ * A builder class for creating and configuring EcoPages application configuration.
+ * Provides a fluent interface for setting various configuration options and managing
+ * application settings.
+ *
+ * @remarks
+ * The ConfigBuilder follows the builder pattern and allows for:
+ * - Setting directory paths for various components (pages, includes, layouts, etc.)
+ * - Configuring templates and includes
+ * - Managing integrations and plugins
+ * - Setting up processors and loaders
+ * - Configuring API handlers
+ * - Managing metadata and robots.txt preferences
+ *
+ * All setter methods return the instance of the builder for method chaining.
+ * The configuration is finalized by calling the `build()` method, which performs
+ * validation and initialization of the configuration.
+ *
+ * @throws {Error} When building configuration without required fields (e.g., baseUrl)
+ * @throws {Error} When adding duplicate processors or loaders
+ */
+export declare class ConfigBuilder {
+    private buildOwnership;
+    config: EcoPagesAppConfig;
+    /**
+     * Sets the base URL for the application.
+     * This URL is used as the root URL for all pages and assets.
+     *
+     * @param baseUrl - The base URL for the application (e.g., 'https://example.com')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setBaseUrl(baseUrl: string): this;
+    /**
+     * Sets the root directory of the project.
+     * This is the base directory from which all other paths are resolved.
+     *
+     * @param rootDir - The root directory path
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setRootDir(rootDir: string): this;
+    /**
+     * Sets which runtime path owns build execution for the finalized app config.
+     *
+     * @remarks
+     * The app-owned build path is the default. The host-owned path should be
+     * selected only for host-driven compatibility flows where core must not
+     * silently fall back to app build execution.
+     */
+    setBuildOwnership(buildOwnership: BuildOwnership): this;
+    /**
+     * Sets the source directory relative to the root directory.
+     * This directory contains all the source files for the application.
+     *
+     * @param srcDir - The source directory name (default: 'src')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setSrcDir(srcDir: string): this;
+    /**
+     * Sets the pages directory relative to the source directory.
+     * This directory contains all the page files for the application.
+     *
+     * @param pagesDir - The pages directory name (default: 'pages')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setPagesDir(pagesDir: string): this;
+    /**
+     * Sets the includes directory relative to the source directory.
+     * This directory contains template includes and partials.
+     *
+     * @param includesDir - The includes directory name (default: 'includes')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setIncludesDir(includesDir: string): this;
+    /**
+     * Sets the components directory relative to the source directory.
+     * This directory contains reusable components.
+     *
+     * @param componentsDir - The components directory name (default: 'components')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setComponentsDir(componentsDir: string): this;
+    /**
+     * Sets the layouts directory relative to the source directory.
+     * This directory contains layout templates.
+     *
+     * @param layoutsDir - The layouts directory name (default: 'layouts')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setLayoutsDir(layoutsDir: string): this;
+    /**
+     * Sets the public directory relative to the source directory.
+     * This directory contains static assets that should be served as-is.
+     *
+     * @param publicDir - The public directory name (default: 'public')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setPublicDir(publicDir: string): this;
+    /**
+     * Sets the robots.txt configuration.
+     * This determines which paths are allowed/disallowed for search engines.
+     *
+     * @param robotsTxt - The robots.txt configuration object
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setRobotsTxt(robotsTxt: {
+        preferences: RobotsPreference;
+    }): this;
+    /**
+     * Sets the integration plugins to use.
+     * These plugins provide additional functionality to the application.
+     *
+     * @param integrations - An array of integration plugins
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setIntegrations(integrations: AnyIntegrationPlugin[]): this;
+    /**
+     * Sets the output directory for the built application.
+     *
+     * @param distDir - The distribution directory name (default: 'dist')
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setDistDir(distDir: string): this;
+    /**
+     * Sets the internal work directory for runtime-only artifacts.
+     *
+     * @remarks
+     * Use this when deployable output should stay clean while Ecopages still
+     * needs a separate workspace for server transpilation caches, runtime
+     * manifests, and other internal build products.
+     *
+     * @param workDir - The internal work directory name
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setWorkDir(workDir: string): this;
+    /**
+     * Sets the default metadata for pages.
+     * This is used when a page doesn't specify its own metadata.
+     *
+     * @param defaultMetadata - The default metadata object
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setDefaultMetadata(defaultMetadata: PageMetadataProps): this;
+    /**
+     * Sets additional paths to watch for changes during development.
+     *
+     * @param additionalWatchPaths - An array of additional paths to watch
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setAdditionalWatchPaths(additionalWatchPaths: string[]): this;
+    /**
+     * Sets the processors to use for the application.
+     * This replaces any existing processors.
+     *
+     * @param processors - An array of processors
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setProcessors(processors: Processor<any>[]): this;
+    /**
+     * Adds a processor to the application.
+     *
+     * @param processor - The processor to add
+     * @returns The ConfigBuilder instance for method chaining
+     * @throws Error if a processor with the same name already exists
+     */
+    addProcessor(processor: Processor): this;
+    /**
+     * Sets the loaders to use for the application.
+     * This replaces any existing loaders.
+     *
+     * @param loaders - An array of build plugins to use as loaders
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setLoaders(loaders: EcoBuildPlugin[]): this;
+    /**
+     * Sets the source transforms to use for transform-first bundlers such as Vite.
+     * This replaces any existing source transforms.
+     */
+    setSourceTransforms(sourceTransforms: EcoSourceTransform[]): this;
+    /**
+     * Adds a loader to the application.
+     *
+     * @param name - The name of the loader
+     * @param loader - The build plugin to use as a loader
+     * @returns The ConfigBuilder instance for method chaining
+     * @throws Error if a loader with the same name already exists
+     */
+    addLoader(name: string, loader: EcoBuildPlugin): this;
+    /**
+     * Adds a source transform to the application.
+     *
+     * @throws Error if a source transform with the same name already exists.
+     */
+    addSourceTransform(name: string, sourceTransform: EcoSourceTransform): this;
+    /**
+     * Sets the cache configuration for ISR and page caching.
+     *
+     * @param cacheConfig - The cache configuration object
+     * @returns The ConfigBuilder instance for method chaining
+     */
+    setCacheConfig(cacheConfig: CacheConfig): this;
+    setExperimental(experimental: NonNullable<EcoPagesAppConfig['experimental']>): this;
+    private createAbsolutePaths;
+    private resolveSemanticTemplatePath;
+    private createIntegrationTemplatesExt;
+    private initializeProcessors;
+    private validateRuntimeCapabilities;
+    private validateRuntimeCapability;
+    private detectRuntimeEnvironment;
+    private getBunVersion;
+    private describeUnsupportedRuntimeTag;
+    private parseVersion;
+    private compareVersions;
+    /**
+     * Initializes default loaders that are required for EcoPages to function.
+     * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
+     */
+    private initializeDefaultLoaders;
+    private reviewBaseUrl;
+    /**
+     * Builds and returns the final configuration object.
+     * This performs validation and initialization of the configuration.
+     *
+     * @returns A promise that resolves to the final EcoPagesAppConfig
+     * @throws Error if required configuration is missing (e.g., baseUrl)
+     */
+    build(): Promise<EcoPagesAppConfig>;
+}
+export {};