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

package/src/build/browser-runtime-manifest.test.ts

@@ -0,0 +1,121 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import {
+	BrowserRuntimeManifestConflictError,
+	createBrowserRuntimeManifest,
+	getBrowserRuntimeSpecifierMap,
+	mergeBrowserRuntimeManifests,
+} from './browser-runtime-manifest.ts';
+
+test('createBrowserRuntimeManifest indexes runtime assets by specifier', () => {
+	const manifest = createBrowserRuntimeManifest([
+		{
+			specifier: 'react',
+			owner: '@ecopages/react',
+			importPath: 'react',
+			publicPath: '/assets/vendors/react.js',
+			mode: 'development',
+			externals: ['react-dom'],
+		},
+	]);
+
+	assert.equal(manifest.assets.length, 1);
+	assert.deepEqual(manifest.bySpecifier.get('react'), {
+		specifier: 'react',
+		owner: '@ecopages/react',
+		importPath: 'react',
+		publicPath: '/assets/vendors/react.js',
+		mode: 'development',
+		externals: ['react-dom'],
+	});
+});
+
+test('createBrowserRuntimeManifest deduplicates identical declarations', () => {
+	const manifest = createBrowserRuntimeManifest([
+		{
+			specifier: 'react',
+			owner: '@ecopages/react',
+			importPath: 'react',
+			publicPath: '/assets/vendors/react.js',
+		},
+		{
+			specifier: 'react',
+			owner: '@ecopages/react',
+			importPath: 'react',
+			publicPath: '/assets/vendors/react.js',
+		},
+	]);
+
+	assert.equal(manifest.assets.length, 1);
+});
+
+test('createBrowserRuntimeManifest rejects conflicting declarations', () => {
+	assert.throws(
+		() =>
+			createBrowserRuntimeManifest([
+				{
+					specifier: 'react',
+					owner: '@ecopages/react',
+					importPath: 'react',
+					publicPath: '/assets/vendors/react.js',
+				},
+				{
+					specifier: 'react',
+					owner: 'custom-runtime',
+					importPath: 'react',
+					publicPath: '/assets/custom/react.js',
+				},
+			]),
+		(error) => {
+			assert.ok(error instanceof BrowserRuntimeManifestConflictError);
+			assert.equal(error.specifier, 'react');
+			assert.match(error.message, /@ecopages\/react maps to \/assets\/vendors\/react\.js/u);
+			return true;
+		},
+	);
+});
+
+test('mergeBrowserRuntimeManifests combines manifest declarations with conflict detection', () => {
+	const reactManifest = createBrowserRuntimeManifest([
+		{
+			specifier: 'react',
+			owner: '@ecopages/react',
+			importPath: 'react',
+			publicPath: '/assets/vendors/react.js',
+		},
+	]);
+	const routerManifest = createBrowserRuntimeManifest([
+		{
+			specifier: '@ecopages/react-router/browser',
+			owner: '@ecopages/react-router',
+			importPath: '@ecopages/react-router/browser',
+			publicPath: '/assets/vendors/react-router.js',
+		},
+	]);
+
+	const manifest = mergeBrowserRuntimeManifests(reactManifest, undefined, routerManifest);
+
+	assert.deepEqual(Array.from(manifest.bySpecifier.keys()), ['react', '@ecopages/react-router/browser']);
+});
+
+test('getBrowserRuntimeSpecifierMap returns concrete public URLs for rewriting', () => {
+	const manifest = createBrowserRuntimeManifest([
+		{
+			specifier: 'react',
+			owner: '@ecopages/react',
+			importPath: 'react',
+			publicPath: '/assets/vendors/react.js',
+		},
+		{
+			specifier: 'react-dom/client',
+			owner: '@ecopages/react',
+			importPath: 'react-dom/client',
+			publicPath: '/assets/vendors/react-dom-client.js',
+		},
+	]);
+
+	assert.deepEqual(Array.from(getBrowserRuntimeSpecifierMap(manifest).entries()), [
+		['react', '/assets/vendors/react.js'],
+		['react-dom/client', '/assets/vendors/react-dom-client.js'],
+	]);
+});

package/src/build/browser-runtime-manifest.ts

@@ -0,0 +1,105 @@
+export type BrowserRuntimeMode = 'development' | 'production';
+
+export type BrowserRuntimeAssetDeclaration = {
+	/** Bare or virtual specifier used by authored/generated browser modules. */
+	specifier: string;
+	/** Integration, processor, or core subsystem that owns this runtime asset. */
+	owner: string;
+	/** Source import path used to build or resolve the runtime asset. */
+	importPath: string;
+	/** Concrete browser URL emitted or served for this runtime asset. */
+	publicPath: string;
+	/** Runtime mode this declaration applies to. Omit when the URL is mode-independent. */
+	mode?: BrowserRuntimeMode;
+	/** Specifiers that should be treated as external while building this runtime asset. */
+	externals?: readonly string[];
+};
+
+export type BrowserRuntimeAsset = BrowserRuntimeAssetDeclaration & {
+	externals: readonly string[];
+};
+
+export type BrowserRuntimeManifest = {
+	assets: readonly BrowserRuntimeAsset[];
+	bySpecifier: ReadonlyMap<string, BrowserRuntimeAsset>;
+};
+
+export class BrowserRuntimeManifestConflictError extends Error {
+	readonly specifier: string;
+	readonly existing: BrowserRuntimeAsset;
+	readonly incoming: BrowserRuntimeAsset;
+
+	constructor(specifier: string, existing: BrowserRuntimeAsset, incoming: BrowserRuntimeAsset) {
+		super(
+			`Browser runtime asset conflict for ${specifier}: ${existing.owner} maps to ${existing.publicPath}, ` +
+				`${incoming.owner} maps to ${incoming.publicPath}`,
+		);
+		this.name = 'BrowserRuntimeManifestConflictError';
+		this.specifier = specifier;
+		this.existing = existing;
+		this.incoming = incoming;
+	}
+}
+
+function normalizeDeclaration(declaration: BrowserRuntimeAssetDeclaration): BrowserRuntimeAsset {
+	return {
+		...declaration,
+		externals: declaration.externals ?? [],
+	};
+}
+
+function hasCompatibleRuntimeAsset(existing: BrowserRuntimeAsset, incoming: BrowserRuntimeAsset): boolean {
+	return (
+		existing.owner === incoming.owner &&
+		existing.importPath === incoming.importPath &&
+		existing.publicPath === incoming.publicPath &&
+		existing.mode === incoming.mode &&
+		arrayEquals(existing.externals, incoming.externals)
+	);
+}
+
+function arrayEquals(left: readonly string[], right: readonly string[]): boolean {
+	if (left.length !== right.length) {
+		return false;
+	}
+
+	return left.every((value, index) => value === right[index]);
+}
+
+export function createBrowserRuntimeManifest(
+	declarations: readonly BrowserRuntimeAssetDeclaration[] = [],
+): BrowserRuntimeManifest {
+	const assets: BrowserRuntimeAsset[] = [];
+	const bySpecifier = new Map<string, BrowserRuntimeAsset>();
+
+	for (const declaration of declarations) {
+		const asset = normalizeDeclaration(declaration);
+		const existing = bySpecifier.get(asset.specifier);
+
+		if (existing) {
+			if (!hasCompatibleRuntimeAsset(existing, asset)) {
+				throw new BrowserRuntimeManifestConflictError(asset.specifier, existing, asset);
+			}
+
+			continue;
+		}
+
+		assets.push(asset);
+		bySpecifier.set(asset.specifier, asset);
+	}
+
+	return {
+		assets,
+		bySpecifier,
+	};
+}
+
+export function mergeBrowserRuntimeManifests(
+	...manifests: Array<BrowserRuntimeManifest | undefined>
+): BrowserRuntimeManifest {
+	return createBrowserRuntimeManifest(manifests.flatMap((manifest) => manifest?.assets ?? []));
+}
+
+export function getBrowserRuntimeSpecifierMap(manifest: BrowserRuntimeManifest): ReadonlyMap<string, string> {
+	return new Map(manifest.assets.map((asset) => [asset.specifier, asset.publicPath]));
+}

package/src/build/browser-runtime-plugin-helpers.test.ts

@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { buildSpecifierFilter, escapeRegExp } from './browser-runtime-plugin-helpers.ts';
+
+test('escapeRegExp escapes all regex metacharacters', () => {
+	const sample = 'a.b*c+d?e^f$g{h}i(j)k|l[m]n\\o';
+	const escaped = escapeRegExp(sample);
+	assert.equal(escaped, 'a\\.b\\*c\\+d\\?e\\^f\\$g\\{h\\}i\\(j\\)k\\|l\\[m\\]n\\\\o');
+	const matcher = new RegExp(`^${escaped}$`);
+	assert.equal(matcher.test(sample), true);
+	assert.equal(matcher.test('aXbXcXdXeXfXgXhXiXjXkXlXmXnXo'), false);
+});
+
+test('buildSpecifierFilter returns null for an empty map', () => {
+	assert.equal(buildSpecifierFilter(new Map()), null);
+});
+
+test('buildSpecifierFilter matches a single specifier exactly', () => {
+	const filter = buildSpecifierFilter(new Map([['react', '/vendor/react.js']]))!;
+	assert.equal(filter.test('react'), true);
+	assert.equal(filter.test('react-dom'), false);
+	assert.equal(filter.test('react/extra'), false);
+	assert.equal(filter.test('xreact'), false);
+});
+
+test('buildSpecifierFilter matches any of multiple specifiers', () => {
+	const filter = buildSpecifierFilter(
+		new Map([
+			['react', '/vendor/react.js'],
+			['react-dom', '/vendor/react-dom.js'],
+		]),
+	)!;
+	assert.equal(filter.test('react'), true);
+	assert.equal(filter.test('react-dom'), true);
+	assert.equal(filter.test('vue'), false);
+});
+
+test('buildSpecifierFilter escapes regex metacharacters in specifier keys', () => {
+	const filter = buildSpecifierFilter(
+		new Map([
+			['@scope/pkg', '/vendor/scope-pkg.js'],
+			['plain.spec', '/vendor/plain.js'],
+		]),
+	)!;
+	assert.equal(filter.test('@scope/pkg'), true);
+	assert.equal(filter.test('@scopeXpkg'), false, 'dot must be escaped, not interpreted as wildcard');
+	assert.equal(filter.test('plain.spec'), true);
+	assert.equal(filter.test('plainXspec'), false);
+});

package/src/build/browser-runtime-plugin-helpers.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared helpers for the browser-runtime plugin.
+ *
+ * @remarks
+ * `createBrowserRuntimePlugin` needs to:
+ *
+ * 1. Escape each specifier for inclusion in a regex filter.
+ * 2. Build a `RegExp` whose alternation matches any of those specifiers.
+ *
+ * These utilities are extracted here so the plugin does not duplicate
+ * the same code path.
+ */
+
+/**
+ * Escapes a literal specifier for inclusion in a regular expression.
+ *
+ * Only the regex metacharacters are escaped: `. * + ? ^ $ { } ( ) | [ ] \`
+ */
+export function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Builds a `RegExp` whose alternation matches any of the keys in
+ * `specifierMap`.
+ *
+ * Returns `null` for an empty map so callers can short-circuit and
+ * avoid registering a no-op `onResolve` / `onLoad` filter.
+ */
+export function buildSpecifierFilter(specifierMap: ReadonlyMap<string, string>): RegExp | null {
+	if (specifierMap.size === 0) {
+		return null;
+	}
+
+	const alternation = Array.from(specifierMap.keys()).map(escapeRegExp).join('|');
+	return new RegExp(`^(${alternation})$`);
+}

package/src/build/browser-runtime-plugin.test.ts

@@ -0,0 +1,256 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { test } from 'vitest';
+import { createBrowserRuntimeManifest } from './browser-runtime-manifest.ts';
+import {
+	BROWSER_RUNTIME_IMPORT_REWRITE_MAP,
+	DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME,
+	createBrowserRuntimePlugin,
+	getBrowserRuntimeImportRewriteMap,
+} from './browser-runtime-plugin.ts';
+import type { EcoBuildOnLoadResult, EcoBuildOnResolveResult } from './build-types.ts';
+
+const manifest = createBrowserRuntimeManifest([
+	{
+		specifier: 'react',
+		owner: '@ecopages/react',
+		importPath: 'react',
+		publicPath: '/assets/vendors/react.js',
+	},
+	{
+		specifier: 'react-dom/client',
+		owner: '@ecopages/react',
+		importPath: 'react-dom/client',
+		publicPath: '/assets/vendors/react-dom.js',
+	},
+]);
+
+type ResolveCallback = (args: {
+	path: string;
+}) => EcoBuildOnResolveResult | undefined | Promise<EcoBuildOnResolveResult | undefined>;
+type LoadCallback = (args: {
+	path: string;
+}) => EcoBuildOnLoadResult | undefined | Promise<EcoBuildOnLoadResult | undefined>;
+
+function captureCallbacks(): {
+	resolveCallbacks: ResolveCallback[];
+	loadCallbacks: LoadCallback[];
+} {
+	const resolveCallbacks: ResolveCallback[] = [];
+	const loadCallbacks: LoadCallback[] = [];
+	return {
+		resolveCallbacks,
+		loadCallbacks,
+	};
+}
+
+function setupPlugin(
+	plugin: ReturnType<typeof createBrowserRuntimePlugin>,
+	callbacks: ReturnType<typeof captureCallbacks>,
+): void {
+	assert.ok(plugin);
+	plugin.setup({
+		onResolve(_options, callback) {
+			callbacks.resolveCallbacks.push(callback as ResolveCallback);
+		},
+		onLoad(_options, callback) {
+			callbacks.loadCallbacks.push(callback as LoadCallback);
+		},
+		module() {},
+	});
+}
+
+test('createBrowserRuntimePlugin returns null for an empty manifest', () => {
+	assert.equal(createBrowserRuntimePlugin({ manifest: createBrowserRuntimeManifest() }), null);
+});
+
+test('createBrowserRuntimePlugin uses default name when not provided', () => {
+	const plugin = createBrowserRuntimePlugin({ manifest });
+	assert.ok(plugin);
+	assert.equal(plugin.name, DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME);
+});
+
+test('createBrowserRuntimePlugin honors a custom name', () => {
+	const plugin = createBrowserRuntimePlugin({ manifest, name: 'custom-runtime-plugin' });
+	assert.ok(plugin);
+	assert.equal(plugin.name, 'custom-runtime-plugin');
+});
+
+test('createBrowserRuntimePlugin exposes the specifier map under the canonical symbol', () => {
+	const plugin = createBrowserRuntimePlugin({ manifest });
+	assert.ok(plugin);
+	const map = getBrowserRuntimeImportRewriteMap(plugin);
+	assert.ok(map);
+	assert.deepEqual(Array.from(map.entries()), [
+		['react', '/assets/vendors/react.js'],
+		['react-dom/client', '/assets/vendors/react-dom.js'],
+	]);
+	assert.equal((plugin as Record<symbol, unknown>)[BROWSER_RUNTIME_IMPORT_REWRITE_MAP], map);
+});
+
+test('createBrowserRuntimePlugin in full mode registers alias, publicPath, and onLoad hooks', () => {
+	const callbacks = captureCallbacks();
+	const plugin = createBrowserRuntimePlugin({ manifest });
+	setupPlugin(plugin, callbacks);
+	assert.equal(callbacks.resolveCallbacks.length, 2, 'alias + publicPath');
+	assert.equal(callbacks.loadCallbacks.length, 1, 'source rewrite');
+});
+
+test('createBrowserRuntimePlugin in alias-only mode skips rewrite and publicPath hooks', () => {
+	const callbacks = captureCallbacks();
+	const plugin = createBrowserRuntimePlugin({
+		manifest,
+		name: 'alias-only',
+		rewriteImports: false,
+		matchPublicPaths: false,
+	});
+	setupPlugin(plugin, callbacks);
+	assert.equal(callbacks.resolveCallbacks.length, 1, 'alias only');
+	assert.equal(callbacks.loadCallbacks.length, 0, 'no source rewrite');
+});
+
+test('createBrowserRuntimePlugin in rewrite-only mode registers alias and onLoad but skips publicPath', () => {
+	const callbacks = captureCallbacks();
+	const plugin = createBrowserRuntimePlugin({
+		manifest,
+		name: 'rewrite-only',
+		external: false,
+		matchPublicPaths: false,
+	});
+	setupPlugin(plugin, callbacks);
+	assert.equal(callbacks.resolveCallbacks.length, 1, 'alias only');
+	assert.equal(callbacks.loadCallbacks.length, 1, 'source rewrite still on');
+});
+
+test('createBrowserRuntimePlugin alias resolve honors custom external flag', async () => {
+	const callbacks = captureCallbacks();
+	const plugin = createBrowserRuntimePlugin({ manifest, external: false });
+	setupPlugin(plugin, callbacks);
+	const resolve = async (specifier: string) => {
+		for (const callback of callbacks.resolveCallbacks) {
+			const result = await callback({ path: specifier });
+			if (result) return result;
+		}
+		return undefined;
+	};
+	assert.deepEqual(await resolve('react'), {
+		path: '/assets/vendors/react.js',
+		external: false,
+	});
+});
+
+test('createBrowserRuntimePlugin alias resolve defaults to external: true', async () => {
+	const callbacks = captureCallbacks();
+	const plugin = createBrowserRuntimePlugin({ manifest });
+	setupPlugin(plugin, callbacks);
+	const resolve = async (specifier: string) => {
+		for (const callback of callbacks.resolveCallbacks) {
+			const result = await callback({ path: specifier });
+			if (result) return result;
+		}
+		return undefined;
+	};
+	assert.deepEqual(await resolve('react'), {
+		path: '/assets/vendors/react.js',
+		external: true,
+	});
+});
+
+test('createBrowserRuntimePlugin publicPath resolve only matches in-set paths', async () => {
+	const callbacks = captureCallbacks();
+	const plugin = createBrowserRuntimePlugin({ manifest, name: 'with-public-paths' });
+	setupPlugin(plugin, callbacks);
+	const resolve = async (specifier: string) => {
+		for (const callback of callbacks.resolveCallbacks) {
+			const result = await callback({ path: specifier });
+			if (result) return result;
+		}
+		return undefined;
+	};
+	assert.deepEqual(await resolve('/assets/vendors/react.js'), {
+		path: '/assets/vendors/react.js',
+		external: true,
+	});
+	assert.equal(await resolve('/assets/vendors/other.js'), undefined);
+	assert.deepEqual(
+		await resolve('react'),
+		{
+			path: '/assets/vendors/react.js',
+			external: true,
+		},
+		'alias filter still matches plain specifiers',
+	);
+});
+
+test('createBrowserRuntimePlugin with matchPublicPaths: false skips /-prefixed resolves', async () => {
+	const callbacks = captureCallbacks();
+	const plugin = createBrowserRuntimePlugin({
+		manifest,
+		name: 'no-public-paths',
+		matchPublicPaths: false,
+	});
+	setupPlugin(plugin, callbacks);
+	const resolve = async (specifier: string) => {
+		for (const callback of callbacks.resolveCallbacks) {
+			const result = await callback({ path: specifier });
+			if (result) return result;
+		}
+		return undefined;
+	};
+	assert.deepEqual(
+		await resolve('react'),
+		{
+			path: '/assets/vendors/react.js',
+			external: true,
+		},
+		'alias filter still active',
+	);
+	assert.equal(await resolve('/assets/vendors/react.js'), undefined, 'no publicPath hook registered');
+});
+
+test('createBrowserRuntimePlugin onLoad rewrites JS/TS sources that import manifest specifiers', async () => {
+	const tempDir = mkdtempSync(path.join(tmpdir(), 'ecopages-unified-rewrite-'));
+	const filePath = path.join(tempDir, 'entry.tsx');
+	writeFileSync(filePath, "import React from 'react';\n", 'utf-8');
+
+	try {
+		const callbacks = captureCallbacks();
+		const plugin = createBrowserRuntimePlugin({ manifest });
+		setupPlugin(plugin, callbacks);
+		assert.equal(callbacks.loadCallbacks.length, 1);
+		assert.deepEqual(await callbacks.loadCallbacks[0]?.({ path: filePath }), {
+			contents: "import React from '/assets/vendors/react.js';\n",
+			loader: 'tsx',
+			resolveDir: tempDir,
+		});
+	} finally {
+		rmSync(tempDir, { recursive: true, force: true });
+	}
+});
+
+test('createBrowserRuntimePlugin onLoad short-circuits when the source has no manifest specifier', async () => {
+	const tempDir = mkdtempSync(path.join(tmpdir(), 'ecopages-unified-rewrite-'));
+	const filePath = path.join(tempDir, 'entry.tsx');
+	writeFileSync(filePath, "import { foo } from 'local-package';\n", 'utf-8');
+
+	try {
+		const callbacks = captureCallbacks();
+		const plugin = createBrowserRuntimePlugin({ manifest });
+		setupPlugin(plugin, callbacks);
+		assert.equal(callbacks.loadCallbacks.length, 1);
+		assert.equal(await callbacks.loadCallbacks[0]?.({ path: filePath }), undefined);
+	} finally {
+		rmSync(tempDir, { recursive: true, force: true });
+	}
+});
+
+test('createBrowserRuntimePlugin onLoad returns undefined for non-absolute paths', async () => {
+	const callbacks = captureCallbacks();
+	const plugin = createBrowserRuntimePlugin({ manifest });
+	setupPlugin(plugin, callbacks);
+	assert.equal(callbacks.loadCallbacks.length, 1);
+	assert.equal(await callbacks.loadCallbacks[0]?.({ path: 'virtual:entry' }), undefined);
+});