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

package/src/build/serialized-build-executor.test.ts

@@ -0,0 +1,96 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { SerializedBuildExecutor } from './serialized-build-executor.ts';
+import type { BuildExecutor, BuildOptions, BuildResult } from './build-adapter.ts';
+
+function createFakeExecutor(): BuildExecutor & { callOrder: number[]; active: number; maxActive: number } {
+	const state = { callOrder: [] as number[], active: 0, maxActive: 0 };
+	let counter = 0;
+	return {
+		get callOrder() {
+			return state.callOrder;
+		},
+		get active() {
+			return state.active;
+		},
+		get maxActive() {
+			return state.maxActive;
+		},
+		async build(options: BuildOptions): Promise<BuildResult> {
+			const id = ++counter;
+			state.callOrder.push(id);
+			state.active += 1;
+			state.maxActive = Math.max(state.maxActive, state.active);
+			try {
+				const delay = typeof options.naming === 'string' ? Number.parseInt(options.naming, 10) || 10 : 10;
+				await new Promise((resolve) => setTimeout(resolve, delay));
+				return { success: true, logs: [], outputs: [{ path: `/out/${id}.js` }] };
+			} finally {
+				state.active -= 1;
+			}
+		},
+	};
+}
+
+test('SerializedBuildExecutor returns the inner executor via unwrap', () => {
+	const inner = createFakeExecutor();
+	const serialized = new SerializedBuildExecutor(inner);
+	assert.equal(serialized.unwrap(), inner);
+});
+
+test('SerializedBuildExecutor runs a single build through the inner executor', async () => {
+	const inner = createFakeExecutor();
+	const serialized = new SerializedBuildExecutor(inner);
+	const result = await serialized.build({ entrypoints: ['/in/index.ts'] });
+	assert.equal(result.success, true);
+	assert.equal(inner.callOrder.length, 1);
+});
+
+test('SerializedBuildExecutor runs concurrent builds in order, never overlapping', async () => {
+	const inner = createFakeExecutor();
+	const serialized = new SerializedBuildExecutor(inner);
+	const builds = [
+		serialized.build({ entrypoints: ['/in/a.ts'], naming: '20' }),
+		serialized.build({ entrypoints: ['/in/b.ts'], naming: '10' }),
+		serialized.build({ entrypoints: ['/in/c.ts'], naming: '5' }),
+	];
+	const results = await Promise.all(builds);
+	assert.deepEqual(
+		results.map((result) => result.outputs[0]?.path),
+		['/out/1.js', '/out/2.js', '/out/3.js'],
+	);
+	assert.equal(inner.callOrder.length, 3);
+	assert.equal(inner.maxActive, 1, 'no two inner builds ever ran concurrently');
+});
+
+test('SerializedBuildExecutor releases the queue on failure so the next build can run', async () => {
+	let shouldFail = true;
+	const inner: BuildExecutor = {
+		async build(_options) {
+			if (shouldFail) {
+				shouldFail = false;
+				throw new Error('synthetic build failure');
+			}
+			return { success: true, logs: [], outputs: [{ path: '/out/recovered.js' }] };
+		},
+	};
+	const serialized = new SerializedBuildExecutor(inner);
+
+	await assert.rejects(() => serialized.build({ entrypoints: ['/in/a.ts'] }), /synthetic build failure/);
+	const result = await serialized.build({ entrypoints: ['/in/b.ts'] });
+	assert.equal(result.success, true);
+	assert.equal(result.outputs[0]?.path, '/out/recovered.js');
+});
+
+test('SerializedBuildExecutor.resetForTests clears the queue tail', async () => {
+	const inner = createFakeExecutor();
+	const serialized = new SerializedBuildExecutor(inner);
+
+	const pending = serialized.build({ entrypoints: ['/in/a.ts'] });
+	serialized.resetForTests();
+	const result = await pending;
+	assert.equal(result.success, true);
+
+	const followUp = await serialized.build({ entrypoints: ['/in/b.ts'] });
+	assert.equal(followUp.outputs[0]?.path, '/out/2.js');
+});

package/src/build/serialized-build-executor.ts

@@ -0,0 +1,90 @@
+import type { BuildExecutor, BuildOptions, BuildResult } from './build-adapter.ts';
+
+/**
+ * FIFO-serialized build executor wrapper.
+ *
+ * @remarks
+ * Wraps any `BuildExecutor` and ensures that no two builds run
+ * concurrently. The next build waits for the previous one to finish
+ * (success or failure) before starting.
+ *
+ * This is a bundler-agnostic primitive. It is unaware of bundler
+ * lifecycle events and exists purely to enforce one build at a time.
+ * Use it from the dev watch pipeline, the static preview path, or any
+ * caller that issues builds concurrently.
+ */
+
+/**
+ * FIFO-serialized wrapper around a {@link BuildExecutor}.
+ *
+ * Every `build()` call enqueues onto the wrapper's internal queue. A
+ * build only starts after the previous build's promise has settled.
+ */
+export class SerializedBuildExecutor implements BuildExecutor {
+	private readonly inner: BuildExecutor;
+	private tail: Promise<unknown> = Promise.resolve();
+
+	constructor(inner: BuildExecutor) {
+		this.inner = inner;
+	}
+
+	/**
+	 * Run a build through the serialized queue. The returned promise
+	 * resolves with the inner executor's `BuildResult`. A rejected
+	 * inner build does not block the queue — the next caller can
+	 * proceed.
+	 */
+	build(options: BuildOptions): Promise<BuildResult> {
+		return this.run(() => this.inner.build(options));
+	}
+
+	/**
+	 * Run an arbitrary async operation through the serialized queue.
+	 *
+	 * Use this when the work is not a `build()` call against a wrapped
+	 * executor (e.g. when composing with a coordinator that needs to
+	 * inject recovery around the inner call). The returned promise
+	 * resolves with the operation's result. A rejected operation does
+	 * not block the queue.
+	 */
+	run<T>(operation: () => Promise<T>): Promise<T> {
+		const next = this.tail.catch(() => undefined).then(() => operation());
+
+		this.tail = next.catch(() => undefined);
+		return next;
+	}
+
+	/**
+	 * Returns the wrapped executor. Tests use this to assert the
+	 * delegation chain.
+	 */
+	unwrap(): BuildExecutor {
+		return this.inner;
+	}
+
+	/**
+	 * Reset the queue to an empty state. Tests use this to recover
+	 * from a poisoned tail.
+	 */
+	resetForTests(): void {
+		this.tail = Promise.resolve();
+	}
+
+	/**
+	 * Overrides the internal queue tail for fault-recovery tests. The
+	 * supplied promise is awaited before the next enqueued operation
+	 * starts.
+	 */
+	setBuildQueueForTests(queue: Promise<unknown>): void {
+		this.tail = queue;
+	}
+
+	/**
+	 * Returns the current internal queue tail for fault-recovery
+	 * tests. Tests await this to assert that recovery has cleared a
+	 * wedged queue.
+	 */
+	getBuildQueueForTests(): Promise<unknown> {
+		return this.tail;
+	}
+}

package/src/build/server-side-css-shim-plugin.ts

@@ -0,0 +1,77 @@
+/**
+ * Server-side CSS shim plugin for the bundler adapter.
+ *
+ * @remarks
+ * Page modules imported by the server (so the framework can read
+ * `getStaticProps` / `staticPaths` / page metadata) commonly have
+ * `import './style.css'` at the top. The bundler does not bundle
+ * CSS, and the server only needs the JS exports — the CSS itself
+ * is delivered to the browser via the page's `dependencies.stylesheets`
+ * declarations. This plugin:
+ *
+ * - Resolves `.css` imports to the absolute on-disk path.
+ * - Loads them and returns an empty ESM module with
+ *   `moduleSideEffects: true` so the bundler keeps the import in
+ *   the dependency graph without trying to bundle the bytes.
+ *
+ * The plugin is added by the adapter on every server-side build.
+ * Browser-side builds that want real CSS bundling should keep using
+ * a dedicated CSS pipeline (e.g. the postcss processor's output)
+ * and continue to declare stylesheets in `dependencies.stylesheets`
+ * — the shim is intentionally inert for those flows.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+type RolldownPluginLike = {
+	name: string;
+	resolveId: (source: string, importer: string | undefined) => Promise<string | null> | string | null;
+	load: (id: string) =>
+		| Promise<{ code: string; moduleType: 'js'; moduleSideEffects: boolean } | null>
+		| {
+				code: string;
+				moduleType: 'js';
+				moduleSideEffects: boolean;
+		  }
+		| null;
+};
+
+const CSS_PATH = /\.css$/u;
+const CSS_QUERY = '?ecopages-css-shim';
+
+function stripShimQuery(id: string): string {
+	const queryIndex = id.indexOf('?');
+	return queryIndex === -1 ? id : id.slice(0, queryIndex);
+}
+
+/**
+ * Builds a Rolldown plugin that turns `.css` imports into no-op ESM
+ * modules while preserving the dependency graph.
+ */
+export function createServerSideCssShimPlugin(): RolldownPluginLike {
+	return {
+		name: 'ecopages:server-side-css-shim',
+		async resolveId(source, importer) {
+			if (!CSS_PATH.test(source)) {
+				return null;
+			}
+
+			const resolved = importer ? path.resolve(path.dirname(importer), source) : path.resolve(source);
+			return existsSync(resolved) ? `${resolved}${CSS_QUERY}` : null;
+		},
+		async load(id) {
+			if (!id.endsWith(CSS_QUERY)) {
+				return null;
+			}
+
+			const realPath = stripShimQuery(id);
+			readFileSync(realPath, 'utf-8');
+			return {
+				code: 'export default "";',
+				moduleType: 'js',
+				moduleSideEffects: true,
+			};
+		},
+	};
+}

package/src/cache/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Public cache exports for the bundler plugin chain.
+ *
+ * @module @ecopages/core/cache
+ */
+export { ModuleParseCache, moduleParseCache, cachedParseSync, type ModuleParseOptions } from './module-parse-cache.ts';

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

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { ModuleParseCache, moduleParseCache, cachedParseSync } from './module-parse-cache.ts';
+
+describe('ModuleParseCache', () => {
+	it('returns the same result for identical (path, source, options)', () => {
+		const cache = new ModuleParseCache();
+		const source = 'export const x = 1;';
+		const first = cache.getOrParse('/a.ts', source, { sourceType: 'module' });
+		const second = cache.getOrParse('/a.ts', source, { sourceType: 'module' });
+		expect(second).toBe(first);
+		expect(cache.stats().hits).toBe(1);
+		expect(cache.stats().misses).toBe(1);
+	});
+
+	it('re-parses when source changes', () => {
+		const cache = new ModuleParseCache();
+		const a = cache.getOrParse('/a.ts', 'export const x = 1;');
+		const b = cache.getOrParse('/a.ts', 'export const x = 2;');
+		expect(b).not.toBe(a);
+		expect(cache.stats().misses).toBe(2);
+	});
+
+	it('re-parses when options differ', () => {
+		const cache = new ModuleParseCache();
+		const source = 'export const x = 1;';
+		const a = cache.getOrParse('/a.ts', source, { sourceType: 'module' });
+		const b = cache.getOrParse('/a.ts', source, { sourceType: 'script' });
+		expect(b).not.toBe(a);
+	});
+
+	it('does not cross-contaminate across file paths', () => {
+		const cache = new ModuleParseCache();
+		const source = 'export const x = 1;';
+		const a = cache.getOrParse('/a.ts', source);
+		const b = cache.getOrParse('/b.ts', source);
+		expect(b).not.toBe(a);
+	});
+
+	it('evicts oldest entry when capacity exceeded', () => {
+		const cache = new ModuleParseCache(2);
+		cache.getOrParse('/a.ts', 'a');
+		cache.getOrParse('/b.ts', 'b');
+		cache.getOrParse('/c.ts', 'c');
+		expect(cache.size).toBe(2);
+		// /a.ts should have been evicted
+		const d = cache.getOrParse('/a.ts', 'a');
+		expect(d).toBeDefined();
+		expect(cache.size).toBe(2);
+	});
+
+	it('clear() resets state', () => {
+		const cache = new ModuleParseCache();
+		cache.getOrParse('/a.ts', 'export const x = 1;');
+		cache.clear();
+		expect(cache.size).toBe(0);
+		expect(cache.stats().hits).toBe(0);
+		expect(cache.stats().misses).toBe(0);
+	});
+
+	it('cachedParseSync uses the shared default cache', () => {
+		const source = 'export const y = 1;';
+		const a = cachedParseSync('/y.ts', source);
+		const b = cachedParseSync('/y.ts', source);
+		expect(b).toBe(a);
+		// Re-touching hits the same instance, so its stats reflect our call.
+		const stats = moduleParseCache.stats();
+		expect(stats.hits).toBeGreaterThanOrEqual(1);
+	});
+
+	it('throws on invalid maxEntries', () => {
+		expect(() => new ModuleParseCache(0)).toThrow();
+	});
+});

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

@@ -0,0 +1,137 @@
+/**
+ * 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 { parseSync, type ParseResult, type ParserOptions } from 'oxc-parser';
+import { rapidhash } from '../utils/hash.ts';
+
+const DEFAULT_MAX_ENTRIES = 10_000;
+
+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'];
+};
+
+type CacheKey = string;
+
+type CacheEntry = {
+	hash: number | bigint;
+	result: ParseResult;
+};
+
+/**
+ * LRU-bounded module parse cache.
+ *
+ * Single instance shared across the process. Constructed lazily; use
+ * {@link moduleParseCache} for the default shared instance.
+ */
+export class ModuleParseCache {
+	private readonly entries = new Map<CacheKey, CacheEntry>();
+	private readonly maxEntries: number;
+	private hits = 0;
+	private misses = 0;
+
+	constructor(maxEntries: number = 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: string, source: string, options: ModuleParseOptions = {}): ParseResult {
+		const hash = rapidhash(source);
+		const key = makeKey(filePath, hash, options);
+
+		const existing = this.entries.get(key);
+		if (existing && existing.hash === hash) {
+			this.hits += 1;
+			// Refresh LRU position.
+			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) {
+			// Map iteration order is insertion order; the first key is the
+			// least recently used (we delete-then-set on hits, so the
+			// oldest still-present entry is the LRU one).
+			const oldestKey = this.entries.keys().next().value;
+			if (oldestKey !== undefined) {
+				this.entries.delete(oldestKey);
+			}
+		}
+
+		return result;
+	}
+
+	/** Clear all cached entries. Useful in tests and on full-rebuild signals. */
+	clear(): void {
+		this.entries.clear();
+		this.hits = 0;
+		this.misses = 0;
+	}
+
+	/** Current cache size (for observability). */
+	get size(): number {
+		return this.entries.size;
+	}
+
+	/** Cumulative hit/miss counters (for observability). */
+	stats(): { hits: number; misses: number; size: number; hitRate: number } {
+		const total = this.hits + this.misses;
+		return {
+			hits: this.hits,
+			misses: this.misses,
+			size: this.entries.size,
+			hitRate: total === 0 ? 0 : this.hits / total,
+		};
+	}
+}
+
+/**
+ * Default shared cache. Use this from plugin code so the cache is
+ * amortized across plugins and build invocations.
+ */
+export const moduleParseCache = new 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 function cachedParseSync(filePath: string, source: string, options: ModuleParseOptions = {}): ParseResult {
+	return moduleParseCache.getOrParse(filePath, source, options);
+}
+
+function makeKey(filePath: string, sourceHash: number | bigint, options: ModuleParseOptions): CacheKey {
+	// Stringify only the option keys we actually use; `parseSync` does
+	// not deeply equal-check options so any extra keys would be noise.
+	const lang = options.lang ?? '';
+	const sourceType = options.sourceType ?? '';
+	return `${filePath} ${sourceHash.toString(36)} ${lang} ${sourceType}`;
+}

package/src/config/README.md

@@ -27,7 +27,7 @@ It is responsible for:
 - `ConfigBuilder.build()` decides ordering, validates compatibility, and seals build ownership for the finalized app config.
 - Runtime startup reuses finalized config/build state; it should not recompute manifest ownership.
 
-Bun-native is the default ownership path. Vite-host ownership is explicit and should be selected during config construction when a host-driven compatibility flow must avoid silently falling back to Bun build execution.
+App-owned is the default ownership path. Host-owned is explicit and should be selected during config construction when a host-driven compatibility flow must avoid silently falling back to app build execution.
 
 ## Output