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

package/src/build/rolldown-plugin-bridge.ts

@@ -0,0 +1,309 @@
+/**
+ * Bundler plugin bridge.
+ *
+ * @remarks
+ * Translates an array of `EcoBuildPlugin` instances (the runtime-agnostic
+ * plugin contract used by Ecopages processors and integrations) into
+ * the bundler's native `Plugin` array. The bridge exposes the same
+ * three hooks (`onResolve`, `onLoad`, `module`) the `EcoBuildPlugin`
+ * contract uses, but maps them to the bundler's `resolveId`/`load`
+ * hooks.
+ *
+ * The shared `EcoBuildPlugin` contract stays the boundary between
+ * integrations and bundler backends.
+ *
+ * **Namespace handling.**
+ *
+ * The shared `EcoBuildPlugin` contract scopes `onResolve`/`onLoad`
+ * handlers with a `namespace` string. The bundler encodes namespaces
+ * into the module id (no separate field). The bridge prepends
+ * `<namespace>:` to the resolved id when the result includes a
+ * namespace, and matches `onLoad`/`onResolve` filters against that
+ * prefix. The bridge strips the prefix before forwarding the id back
+ * to the callback so plugin code keeps seeing the same `path` shape
+ * it did on the historical contract.
+ *
+ * **Plugin ordering is semantically significant.**
+ *
+ * The bundler's `resolveId` and `load` are "first" hooks: the first
+ * plugin that returns a non-null value wins. Because the bridge
+ * translates each `EcoBuildPlugin` into its own bundler plugin and
+ * preserves the array order, the position of each plugin in the
+ * `plugins` array determines its priority:
+ *
+ * - **Index 0** has the highest priority.
+ * - **Last index** has the lowest priority.
+ *
+ * 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.
+ */
+
+import path from 'node:path';
+import type { LoadResult, PartialResolvedId, Plugin, ResolveIdResult, SourceDescription } from 'rolldown';
+import { escapeRegExp } from './browser-runtime-plugin-helpers.ts';
+import type {
+	EcoBuildOnLoadArgs,
+	EcoBuildOnLoadResult,
+	EcoBuildOnResolveArgs,
+	EcoBuildOnResolveResult,
+	EcoBuildPlugin,
+	EcoBuildPluginBuilder,
+} from './build-types.ts';
+
+const NAMESPACE_SEPARATOR = ':';
+
+function joinNamespace(namespace: string | undefined, value: string): string {
+	return namespace ? `${namespace}${NAMESPACE_SEPARATOR}${value}` : value;
+}
+
+function splitNamespace(id: string): { namespace: string | undefined; path: string } {
+	const separatorIndex = id.indexOf(NAMESPACE_SEPARATOR);
+	if (separatorIndex <= 0) {
+		return { namespace: undefined, path: id };
+	}
+	return {
+		namespace: id.slice(0, separatorIndex),
+		path: id.slice(separatorIndex + 1),
+	};
+}
+
+function inferRolldownModuleTypeFromPath(filePath: string): string {
+	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';
+	}
+}
+
+function normalizeRolldownModuleType(loader: unknown): string | undefined {
+	switch (loader) {
+		case 'js':
+		case 'jsx':
+		case 'ts':
+		case 'tsx':
+		case 'json':
+		case 'css':
+		case 'text':
+		case 'base64':
+		case 'dataurl':
+		case 'binary':
+		case 'empty':
+			return loader;
+		case 'global-css':
+		case 'local-css':
+			return 'css';
+		case 'file':
+		case 'copy':
+			return 'asset';
+		default:
+			return undefined;
+	}
+}
+
+function convertLoadResultToModuleSource(result: EcoBuildOnLoadResult): string | undefined {
+	if (result.loader === 'object' && result.exports && typeof result.exports === 'object') {
+		return Object.entries(result.exports)
+			.map(([key, value]) =>
+				key === 'default'
+					? `export default ${JSON.stringify(value)};`
+					: `export const ${key} = ${JSON.stringify(value)};`,
+			)
+			.join('\n');
+	}
+
+	return undefined;
+}
+
+function buildIdFilter(filter: RegExp, namespace: string | undefined): RegExp {
+	if (!namespace) {
+		return filter;
+	}
+	return new RegExp(`^${escapeRegExp(namespace)}${NAMESPACE_SEPARATOR}${filter.source.slice(1)}`);
+}
+
+function resolvePluginPath(value: string, importer: string | undefined, contextRoot: string): string {
+	if (path.isAbsolute(value)) {
+		return value;
+	}
+
+	if (value.startsWith('.') || value.startsWith('..')) {
+		const baseDir = importer ? path.dirname(importer) : contextRoot;
+		return path.resolve(baseDir, value);
+	}
+
+	return value;
+}
+
+function convertPluginOnLoadResult(args: { id: string }, result: unknown): LoadResult | undefined {
+	if (!result || typeof result !== 'object') {
+		return undefined;
+	}
+
+	const candidate = result as EcoBuildOnLoadResult;
+	const { path: sourcePath } = splitNamespace(args.id);
+
+	const sourceFromExports = convertLoadResultToModuleSource(candidate);
+
+	if (sourceFromExports) {
+		const description: SourceDescription = {
+			code: sourceFromExports,
+			moduleType: 'js',
+		};
+		return description;
+	}
+
+	if (typeof candidate.contents === 'string' || candidate.contents instanceof Uint8Array) {
+		const code =
+			typeof candidate.contents === 'string' ? candidate.contents : new TextDecoder().decode(candidate.contents);
+		const description: SourceDescription = {
+			code,
+			moduleType: (normalizeRolldownModuleType(candidate.loader) ??
+				inferRolldownModuleTypeFromPath(sourcePath)) as SourceDescription['moduleType'],
+		};
+		return description;
+	}
+
+	return undefined;
+}
+
+function convertPluginOnResolveResult(
+	result: unknown,
+	importer: string | undefined,
+	contextRoot: string,
+): ResolveIdResult | undefined {
+	if (!result || typeof result !== 'object') {
+		return undefined;
+	}
+
+	const candidate = result as EcoBuildOnResolveResult;
+
+	if (typeof candidate.path !== 'string' && typeof candidate.namespace !== 'string') {
+		if (typeof candidate.external !== 'boolean') {
+			return undefined;
+		}
+	}
+
+	const partial: PartialResolvedId = { id: '' };
+
+	if (typeof candidate.path === 'string') {
+		partial.id = joinNamespace(candidate.namespace, resolvePluginPath(candidate.path, importer, contextRoot));
+	} else if (typeof candidate.namespace === 'string') {
+		partial.id = joinNamespace(candidate.namespace, '');
+	}
+
+	if (typeof candidate.external === 'boolean') {
+		partial.external = candidate.external;
+	}
+
+	return partial;
+}
+
+type ResolveCallback = (
+	args: EcoBuildOnResolveArgs,
+) => EcoBuildOnResolveResult | undefined | Promise<EcoBuildOnResolveResult | undefined>;
+
+type LoadCallback = (
+	args: EcoBuildOnLoadArgs,
+) => EcoBuildOnLoadResult | undefined | Promise<EcoBuildOnLoadResult | undefined>;
+
+interface ResolveRegistration {
+	filter: RegExp;
+	callback: ResolveCallback;
+}
+
+interface LoadRegistration {
+	filter: RegExp;
+	callback: LoadCallback;
+}
+
+function wrapEcoPlugin(ecoPlugin: EcoBuildPlugin, contextRoot: string, moduleCounter: { value: number }): Plugin {
+	const resolveRegistrations: ResolveRegistration[] = [];
+	const loadRegistrations: LoadRegistration[] = [];
+
+	const registerResolve = (filter: RegExp, callback: ResolveCallback): void => {
+		resolveRegistrations.push({ filter, callback });
+	};
+
+	const registerLoad = (filter: RegExp, callback: LoadCallback): void => {
+		loadRegistrations.push({ filter, callback });
+	};
+
+	return {
+		name: `ecopages-plugin-bridge:${ecoPlugin.name}`,
+		buildStart: async (): Promise<void> => {
+			const bridge: EcoBuildPluginBuilder = {
+				onResolve: (options, callback) => {
+					registerResolve(buildIdFilter(options.filter, options.namespace), callback);
+				},
+				onLoad: (options, callback) => {
+					registerLoad(buildIdFilter(options.filter, options.namespace), callback);
+				},
+				module: (specifier, callback) => {
+					const namespace = `ecopages-module-${moduleCounter.value}`;
+					moduleCounter.value += 1;
+					const filter = new RegExp(`^${escapeRegExp(specifier)}$`);
+
+					registerResolve(filter, async () => ({
+						path: joinNamespace(namespace, specifier),
+					}));
+
+					registerLoad(buildIdFilter(/.*/, namespace), async () => callback());
+				},
+			};
+
+			await ecoPlugin.setup(bridge);
+		},
+		resolveId: async (source, importer, _extraOptions) => {
+			for (const { filter, callback } of resolveRegistrations) {
+				if (!filter.test(source)) {
+					continue;
+				}
+				const { namespace, path: sourcePath } = splitNamespace(source);
+				const result = await callback({ path: sourcePath, importer, namespace });
+				const converted = convertPluginOnResolveResult(result, importer, contextRoot);
+				if (converted !== undefined) {
+					return converted;
+				}
+			}
+			return undefined;
+		},
+		load: async (id) => {
+			for (const { filter, callback } of loadRegistrations) {
+				if (!filter.test(id)) {
+					continue;
+				}
+				const { namespace, path: sourcePath } = splitNamespace(id);
+				const result = await callback({ path: sourcePath, namespace });
+				const converted = convertPluginOnLoadResult({ id }, result);
+				if (converted !== undefined) {
+					return converted;
+				}
+			}
+			return undefined;
+		},
+	};
+}
+
+/**
+ * Creates a Rolldown `Plugin` array that drives the supplied
+ * `EcoBuildPlugin` instances. Each `EcoBuildPlugin` becomes its own
+ * Rolldown plugin so that the order of registrations is preserved as
+ * plugin priority.
+ */
+export function createRolldownPluginBridge(plugins: EcoBuildPlugin[], contextRoot: string): Plugin[] {
+	const moduleCounter = { value: 0 };
+	return plugins.map((ecoPlugin) => wrapEcoPlugin(ecoPlugin, contextRoot, moduleCounter));
+}

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

@@ -0,0 +1,130 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { createAppBuildManifest } from './build-manifest.ts';
+import {
+	getAppBuildAdapter,
+	getAppBuildOwnership,
+	setAppBuildAdapter,
+	setAppBuildExecutor,
+	setAppBuildManifest,
+	ViteHostBuildAdapter,
+	withBuildExecutorPlugins,
+} from './build-adapter.ts';
+import { SerializedBuildExecutor } from './serialized-build-executor.ts';
+import { RolldownBuildAdapter } from './rolldown-build-adapter.ts';
+import { installAppRuntimeBuildExecutor } from './runtime-build-executor.ts';
+
+test('installAppRuntimeBuildExecutor wraps the active adapter in a SerializedBuildExecutor', () => {
+	const staleExecutor = new RolldownBuildAdapter();
+	const appConfig = {
+		runtime: {
+			buildExecutor: staleExecutor,
+		},
+		loaders: new Map(),
+	} as never;
+
+	setAppBuildAdapter(appConfig, new ViteHostBuildAdapter());
+	setAppBuildManifest(
+		appConfig,
+		createAppBuildManifest({
+			runtimePlugins: [],
+		}),
+	);
+
+	const executor = installAppRuntimeBuildExecutor(appConfig);
+
+	assert.notEqual(executor, staleExecutor);
+	assert.ok(executor instanceof SerializedBuildExecutor, 'wraps the executor in a FIFO-serialized layer');
+});
+
+test('installAppRuntimeBuildExecutor rejects when the app-owned adapter is a Vite-host boundary', async () => {
+	const appConfig = {
+		runtime: {},
+		loaders: new Map(),
+	} as never;
+
+	setAppBuildAdapter(appConfig, new ViteHostBuildAdapter());
+	setAppBuildManifest(
+		appConfig,
+		createAppBuildManifest({
+			runtimePlugins: [],
+		}),
+	);
+
+	const executor = installAppRuntimeBuildExecutor(appConfig);
+
+	await assert.rejects(
+		executor.build({
+			entrypoints: ['/tmp/entry.ts'],
+			root: '/tmp',
+			outdir: '/tmp/out',
+			target: 'browser',
+			format: 'esm',
+			sourcemap: 'none',
+			splitting: false,
+			minify: false,
+		}),
+		/Vite-hosted builds are owned by the host runtime/,
+	);
+});
+
+test('installAppRuntimeBuildExecutor merges app-owned server plugins into every build', async () => {
+	const injectedPlugin = {
+		name: 'test-injected-plugin',
+		setup() {},
+	};
+	const observed: Array<unknown> = [];
+	const baseAdapter = new RolldownBuildAdapter();
+	const wrappedAdapter: import('./build-adapter.ts').BuildAdapter = {
+		ownership: baseAdapter.ownership,
+		resolve: baseAdapter.resolve.bind(baseAdapter),
+		getTranspileOptions: baseAdapter.getTranspileOptions.bind(baseAdapter),
+		async build(options) {
+			observed.push(options.plugins);
+			return { success: true, logs: [], outputs: [] };
+		},
+	};
+	const appConfig = {
+		runtime: { buildAdapter: wrappedAdapter },
+		loaders: new Map(),
+	} as never;
+
+	setAppBuildManifest(
+		appConfig,
+		createAppBuildManifest({
+			runtimePlugins: [injectedPlugin],
+		}),
+	);
+
+	const executor = installAppRuntimeBuildExecutor(appConfig);
+	await executor.build({
+		entrypoints: ['/tmp/entry.ts'],
+		root: '/tmp',
+		outdir: '/tmp/out',
+		target: 'browser',
+		format: 'esm',
+		sourcemap: 'none',
+	});
+
+	assert.equal(observed.length, 1, 'inner adapter received one build call');
+	const observedPlugins = observed[0] as Array<{ name: string }> | undefined;
+	assert.ok(observedPlugins?.some((plugin) => plugin.name === injectedPlugin.name));
+});
+
+test('installAppRuntimeBuildExecutor does not double-wrap an already-wrapped executor', () => {
+	const appConfig = {
+		runtime: {},
+		loaders: new Map(),
+	} as never;
+
+	setAppBuildAdapter(appConfig, new RolldownBuildAdapter());
+	setAppBuildExecutor(
+		appConfig,
+		withBuildExecutorPlugins(new RolldownBuildAdapter(), () => []),
+	);
+
+	const installed = installAppRuntimeBuildExecutor(appConfig);
+	assert.ok(installed instanceof SerializedBuildExecutor);
+	assert.equal(getAppBuildAdapter(appConfig).ownership, 'rolldown');
+	assert.equal(getAppBuildOwnership(appConfig), 'rolldown');
+});

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

@@ -0,0 +1,37 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.ts';
+import {
+	getAppBuildAdapter,
+	getAppBuildExecutor,
+	getAppServerBuildPlugins,
+	setAppBuildExecutor,
+	withBuildExecutorPlugins,
+	type BuildExecutor,
+} from './build-adapter.ts';
+import { SerializedBuildExecutor } from './serialized-build-executor.ts';
+
+/**
+ * Installs the app-owned runtime build executor for one app instance.
+ *
+ * @remarks
+ * Wraps the app-owned adapter in a {@link SerializedBuildExecutor} so
+ * every dev-watch caller issues builds against a single FIFO queue.
+ * Plugin injection is applied here via {@link withBuildExecutorPlugins}
+ * so app-owned plugins are merged into every rebuild without callers
+ * having to know about the manifest.
+ *
+ * Idempotent across calls: re-invoking replaces the existing executor
+ * on `appConfig.runtime` with a fresh wrapper.
+ *
+ * @param appConfig - The app config whose runtime state is updated.
+ *   The function reads the existing executor (falling back to the
+ *   app-owned adapter) and writes the wrapped executor back.
+ * @returns The installed {@link BuildExecutor}.
+ */
+export function installAppRuntimeBuildExecutor(appConfig: EcoPagesAppConfig): BuildExecutor {
+	const baseExecutor = getAppBuildExecutor(appConfig) ?? getAppBuildAdapter(appConfig);
+	const buildExecutor = new SerializedBuildExecutor(
+		withBuildExecutorPlugins(baseExecutor, () => getAppServerBuildPlugins(appConfig)),
+	);
+	setAppBuildExecutor(appConfig, buildExecutor);
+	return buildExecutor;
+}

package/src/build/runtime-build-output-normalizer.ts

@@ -0,0 +1,137 @@
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const corePackageRequire = createRequire(new URL('../../package.json', import.meta.url));
+const appDeclaredPackageCache = new Map<string, Set<string>>();
+
+function tryResolveRuntimeImport(specifier: string, resolver: NodeJS.Require): string | undefined {
+	try {
+		return resolver.resolve(specifier);
+	} catch {
+		return undefined;
+	}
+}
+
+function isBareRuntimeImport(specifier: string): boolean {
+	return (
+		!specifier.startsWith('.') &&
+		!path.isAbsolute(specifier) &&
+		!specifier.startsWith('/') &&
+		!specifier.startsWith('node:') &&
+		!specifier.startsWith('@/') &&
+		!specifier.startsWith('~/') &&
+		!specifier.startsWith('#') &&
+		!specifier.includes(':')
+	);
+}
+
+function getPackageNameFromSpecifier(specifier: string): string {
+	if (specifier.startsWith('@')) {
+		return specifier.split('/').slice(0, 2).join('/');
+	}
+
+	return specifier.split('/')[0] ?? specifier;
+}
+
+function getDeclaredAppPackages(rootDir: string): Set<string> {
+	const cacheKey = path.resolve(rootDir);
+	const cached = appDeclaredPackageCache.get(cacheKey);
+	if (cached) {
+		return cached;
+	}
+
+	const packageJsonPath = path.resolve(rootDir, 'package.json');
+	const declaredPackages = new Set<string>();
+
+	try {
+		const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as Record<string, unknown>;
+		for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'] as const) {
+			const entries = packageJson[field];
+			if (!entries || typeof entries !== 'object') {
+				continue;
+			}
+
+			for (const packageName of Object.keys(entries as Record<string, unknown>)) {
+				declaredPackages.add(packageName);
+			}
+		}
+	} catch {
+		appDeclaredPackageCache.set(cacheKey, declaredPackages);
+		return declaredPackages;
+	}
+
+	appDeclaredPackageCache.set(cacheKey, declaredPackages);
+	return declaredPackages;
+}
+
+export function isDeclaredAppPackageImport(specifier: string, rootDir: string): boolean {
+	return getDeclaredAppPackages(rootDir).has(getPackageNameFromSpecifier(specifier));
+}
+
+function rewriteRuntimeImportSpecifier(specifier: string, quote: string, rootDir: string): string | undefined {
+	if (!isBareRuntimeImport(specifier)) {
+		return undefined;
+	}
+
+	if (isDeclaredAppPackageImport(specifier, rootDir)) {
+		return undefined;
+	}
+
+	const resolvedPath = tryResolveRuntimeImport(specifier, corePackageRequire);
+	if (!resolvedPath || !/\.(?:[cm]?[jt]s|tsx|jsx)$/u.test(resolvedPath)) {
+		return undefined;
+	}
+
+	return `${quote}${pathToFileURL(resolvedPath).href}${quote}`;
+}
+
+function rewriteRuntimeBuildOutputImports(code: string, rootDir: string): string {
+	const rewriteSpecifier = (prefix: string, quote: string, specifier: string) => {
+		const rewrittenSpecifier = rewriteRuntimeImportSpecifier(specifier, quote, rootDir);
+		return `${prefix}${rewrittenSpecifier ?? `${quote}${specifier}${quote}`}`;
+	};
+
+	const withResolvedPackages = code
+		.replace(/(\bfrom\s+)(['"])([^'"\\]+)\2/g, (_match, prefix, quote, specifier) =>
+			rewriteSpecifier(prefix, quote, specifier),
+		)
+		.replace(/(\bimport\s+)(['"])([^'"\\]+)\2/g, (_match, prefix, quote, specifier) =>
+			rewriteSpecifier(prefix, quote, specifier),
+		)
+		.replace(/(\bimport\s*\(\s*)(['"])([^'"\\]+)\2/g, (_match, prefix, quote, specifier) =>
+			rewriteSpecifier(prefix, quote, specifier),
+		);
+
+	return withResolvedPackages.replace(
+		/(['"])(@oxc-project\/runtime\/(?:helpers(?:\/esm)?\/[^'"\\]+))\1/g,
+		(match, quote, specifier) => {
+			const resolvedPath = tryResolveRuntimeImport(specifier as string, corePackageRequire);
+			return resolvedPath ? `${quote}${pathToFileURL(resolvedPath).href}${quote}` : match;
+		},
+	);
+}
+
+export function normalizeNodeRuntimeBuildOutputFile(filePath: string, rootDir: string): void {
+	if (!/\.(?:[cm]?js)$/u.test(filePath)) {
+		return;
+	}
+
+	const fileSystem = corePackageRequire('node:fs') as typeof import('node:fs');
+	if (!fileSystem.existsSync(filePath)) {
+		return;
+	}
+
+	const code = fileSystem.readFileSync(filePath, 'utf-8');
+	const rewritten = rewriteRuntimeBuildOutputImports(code, rootDir);
+	if (rewritten !== code) {
+		fileSystem.writeFileSync(filePath, rewritten);
+	}
+}
+
+export function normalizeNodeRuntimeBuildOutputs(outputPaths: string[], rootDir: string): void {
+	for (const outputPath of outputPaths) {
+		normalizeNodeRuntimeBuildOutputFile(outputPath, rootDir);
+	}
+}