@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.31

package/src/build/esbuild-build-adapter.ts

@@ -1,510 +0,0 @@
-import type {
-	Loader as EsbuildLoader,
-	OnLoadResult as EsbuildOnLoadResult,
-	OnResolveResult as EsbuildOnResolveResult,
-	Plugin as EsbuildPlugin,
-} from 'esbuild';
-import path from 'node:path';
-import { createRequire } from 'node:module';
-import { fileSystem } from '@ecopages/file-system';
-import type {
-	EcoBuildOnLoadResult,
-	EcoBuildPlugin,
-	EcoBuildPluginBuilder,
-	EcoBuildOnResolveResult,
-} from './build-types.ts';
-import type {
-	BuildAdapter,
-	BuildDependencyGraph,
-	BuildLog,
-	BuildOptions,
-	BuildResult,
-	BuildTranspileOptions,
-	BuildTranspileProfile,
-} from './build-adapter.ts';
-
-/**
- * Provides common transpile output defaults shared across build profiles.
- */
-function transpileProfileToOptions(profile: BuildTranspileProfile): BuildTranspileOptions {
-	switch (profile) {
-		case 'browser-script':
-			return {
-				target: 'browser',
-				format: 'esm',
-				sourcemap: 'none',
-			};
-		case 'hmr-runtime':
-			return {
-				target: 'browser',
-				format: 'esm',
-				sourcemap: 'none',
-			};
-		case 'hmr-entrypoint':
-			return {
-				target: 'browser',
-				format: 'esm',
-				sourcemap: 'none',
-			};
-	}
-}
-
-/**
- * Node build adapter backed by esbuild.
- *
- * This adapter keeps Ecopages build plugin compatibility (`onResolve`, `onLoad`,
- * and `module`) while delegating bundling and TypeScript/decorator transforms to esbuild.
- */
-export class EsbuildBuildAdapter implements BuildAdapter {
-	private registeredPlugins: EcoBuildPlugin[] = [];
-
-	private escapeRegExp(value: string): string {
-		return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-	}
-
-	private getPluginsForBuild(additionalPlugins?: EcoBuildPlugin[]): EcoBuildPlugin[] {
-		const merged = [...(additionalPlugins ?? []), ...this.registeredPlugins];
-		const byName = new Map<string, EcoBuildPlugin>();
-
-		for (const plugin of merged) {
-			if (!byName.has(plugin.name)) {
-				byName.set(plugin.name, plugin);
-			}
-		}
-
-		return Array.from(byName.values());
-	}
-
-	private normalizeEsbuildLoader(loader: unknown): EsbuildLoader | undefined {
-		switch (loader) {
-			case 'base64':
-			case 'binary':
-			case 'copy':
-			case 'css':
-			case 'dataurl':
-			case 'empty':
-			case 'file':
-			case 'global-css':
-			case 'js':
-			case 'json':
-			case 'jsx':
-			case 'local-css':
-			case 'text':
-			case 'ts':
-			case 'tsx':
-				return loader as EsbuildLoader;
-			default:
-				return undefined;
-		}
-	}
-
-	private inferEsbuildLoaderFromPath(filePath: string): EsbuildLoader {
-		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';
-		}
-	}
-
-	private convertLoadResultToModuleSource(result: unknown): string | undefined {
-		if (!result || typeof result !== 'object') {
-			return undefined;
-		}
-
-		const candidate = result as {
-			contents?: string;
-			loader?: unknown;
-			exports?: Record<string, unknown>;
-		};
-
-		if (typeof candidate.contents === 'string') {
-			return candidate.contents;
-		}
-
-		if (candidate.loader === 'object' && candidate.exports && typeof candidate.exports === 'object') {
-			const entries = Object.entries(candidate.exports)
-				.map(([key, value]) =>
-					key === 'default'
-						? `export default ${JSON.stringify(value)};`
-						: `export const ${key} = ${JSON.stringify(value)};`,
-				)
-				.join('\n');
-
-			return entries;
-		}
-
-		return undefined;
-	}
-
-	private convertPluginOnLoadResult(args: { path: string }, result: unknown): EsbuildOnLoadResult | undefined {
-		if (!result || typeof result !== 'object') {
-			return undefined;
-		}
-
-		const candidate = result as EcoBuildOnLoadResult;
-
-		const sourceFromExports =
-			candidate.loader === 'object' && candidate.exports && typeof candidate.exports === 'object'
-				? this.convertLoadResultToModuleSource(candidate)
-				: undefined;
-
-		if (sourceFromExports) {
-			return {
-				contents: sourceFromExports,
-				loader: 'js',
-				resolveDir: path.dirname(args.path),
-			};
-		}
-
-		if (typeof candidate.contents === 'string' || candidate.contents instanceof Uint8Array) {
-			return {
-				contents: candidate.contents,
-				loader: this.normalizeEsbuildLoader(candidate.loader) ?? this.inferEsbuildLoaderFromPath(args.path),
-				resolveDir: typeof candidate.resolveDir === 'string' ? candidate.resolveDir : path.dirname(args.path),
-			};
-		}
-
-		return undefined;
-	}
-
-	private resolvePluginPath(value: string, args: { importer: string }, contextRoot: string): string {
-		if (path.isAbsolute(value)) {
-			return value;
-		}
-
-		if (value.startsWith('.') || value.startsWith('..')) {
-			const baseDir = args.importer ? path.dirname(args.importer) : contextRoot;
-			return path.resolve(baseDir, value);
-		}
-
-		return value;
-	}
-
-	/**
-	 * Creates an esbuild plugin bridge compatible with the existing Ecopages
-	 * plugin API shape.
-	 *
-	 * **Plugin ordering is semantically significant.**
-	 *
-	 * Esbuild applies `onResolve` and `onLoad` hooks in the order they are
-	 * registered: the first handler whose filter matches wins for `onResolve`,
-	 * and the first handler that returns a non-`undefined` result wins for
-	 * `onLoad`. Because we call `plugin.setup(bridge)` sequentially here, the
-	 * position of each plugin in the `plugins` array determines its priority:
-	 *
-	 * - **Index 0** has the highest priority (its hooks run first).
-	 * - **Last index** has the lowest priority (its hooks only run if no earlier
-	 *   plugin claimed the path).
-	 *
-	 * 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.
-	 *
-	 * There is currently no priority system or validation — correct ordering is
-	 * the caller's responsibility.
-	 */
-	private createEcoPluginBridge(plugins: EcoBuildPlugin[], contextRoot: string): EsbuildPlugin {
-		return {
-			name: 'ecopages-plugin-bridge',
-			setup: async (build) => {
-				let moduleCounter = 0;
-
-				const bridge: EcoBuildPluginBuilder = {
-					onResolve: (options: { filter: RegExp; namespace?: string }, callback): void => {
-						build.onResolve(options, async (args) => {
-							const result = await callback({
-								path: args.path,
-								importer: args.importer,
-								namespace: args.namespace,
-							});
-
-							if (!result || typeof result !== 'object') {
-								return undefined;
-							}
-
-							const candidate = result as EcoBuildOnResolveResult;
-
-							const resolveResult: EsbuildOnResolveResult = {};
-
-							if (typeof candidate.path === 'string') {
-								resolveResult.path = this.resolvePluginPath(candidate.path, args, contextRoot);
-							}
-
-							if (typeof candidate.namespace === 'string') {
-								resolveResult.namespace = candidate.namespace;
-							}
-
-							if (typeof candidate.external === 'boolean') {
-								resolveResult.external = candidate.external;
-							}
-
-							return Object.keys(resolveResult).length > 0 ? resolveResult : undefined;
-						});
-					},
-					onLoad: (options: { filter: RegExp; namespace?: string }, callback): void => {
-						build.onLoad(options, async (args) => {
-							const result = await callback({
-								path: args.path,
-								namespace: args.namespace,
-							});
-
-							return this.convertPluginOnLoadResult(args, result);
-						});
-					},
-					module: (specifier: string, callback): void => {
-						const namespace = `ecopages-module-${moduleCounter}`;
-						moduleCounter += 1;
-						const filter = new RegExp(`^${this.escapeRegExp(specifier)}$`);
-
-						build.onResolve({ filter }, () => ({
-							path: specifier,
-							namespace,
-						}));
-
-						build.onLoad({ filter, namespace }, async (args) => {
-							const result = await callback();
-							return this.convertPluginOnLoadResult(args, result);
-						});
-					},
-				};
-
-				for (const plugin of plugins) {
-					await plugin.setup(bridge);
-				}
-			},
-		};
-	}
-
-	private async loadEsbuildModule(): Promise<typeof import('esbuild')> {
-		const esbuildModule = (await import('esbuild')) as typeof import('esbuild');
-
-		if (typeof esbuildModule.build !== 'function') {
-			throw new Error('esbuild is not available. Install esbuild to use Node bundling.');
-		}
-
-		return esbuildModule;
-	}
-
-	private mapEsbuildSourcemap(value: string | undefined): false | 'linked' | 'inline' | 'external' | 'both' {
-		switch (value) {
-			case 'none':
-				return false;
-			case 'inline':
-				return 'inline';
-			case 'both':
-				return 'both';
-			case 'external':
-				return 'external';
-			default:
-				return 'linked';
-		}
-	}
-
-	private mapEsbuildFormat(value: string | undefined): 'esm' | 'cjs' | 'iife' {
-		switch (value) {
-			case 'cjs':
-				return 'cjs';
-			case 'iife':
-				return 'iife';
-			default:
-				return 'esm';
-		}
-	}
-
-	private hasTemplateTokens(value: string | undefined): boolean {
-		return typeof value === 'string' && /\[[^\]]+\]/.test(value);
-	}
-
-	private toEntryNamePattern(value: string | undefined): string {
-		if (!value) {
-			return '[name]';
-		}
-
-		const pattern = value.replaceAll(/\.?\[ext\]/g, '');
-		return pattern.length > 0 ? pattern : '[name]';
-	}
-
-	private normalizeMetafilePath(value: string, contextRoot: string): string {
-		if (path.isAbsolute(value)) {
-			return path.normalize(value);
-		}
-
-		return path.normalize(path.resolve(contextRoot, value));
-	}
-
-	private extractDependencyGraph(
-		metafile: {
-			outputs: Record<string, { entryPoint?: string; inputs?: Record<string, unknown> }>;
-		},
-		contextRoot: string,
-	): BuildDependencyGraph {
-		const entrypoints = new Map<string, Set<string>>();
-
-		for (const outputMeta of Object.values(metafile.outputs)) {
-			if (!outputMeta.entryPoint) {
-				continue;
-			}
-
-			const entrypointPath = this.normalizeMetafilePath(outputMeta.entryPoint, contextRoot);
-			const dependencies = entrypoints.get(entrypointPath) ?? new Set<string>();
-			dependencies.add(entrypointPath);
-
-			for (const inputPath of Object.keys(outputMeta.inputs ?? {})) {
-				dependencies.add(this.normalizeMetafilePath(inputPath, contextRoot));
-			}
-
-			entrypoints.set(entrypointPath, dependencies);
-		}
-
-		return {
-			entrypoints: Object.fromEntries(
-				Array.from(entrypoints.entries(), ([entrypointPath, dependencies]) => [
-					entrypointPath,
-					Array.from(dependencies),
-				]),
-			),
-		};
-	}
-
-	/**
-	 * Normalizes esbuild errors into Ecopages `BuildLog` entries.
-	 */
-	private toBuildLogs(error: unknown): BuildLog[] {
-		if (error && typeof error === 'object') {
-			const candidate = error as {
-				errors?: Array<{ text?: string; location?: { file?: string; line?: number; column?: number } }>;
-				message?: string;
-			};
-
-			if (Array.isArray(candidate.errors) && candidate.errors.length > 0) {
-				return candidate.errors.map((entry) => {
-					const locationPrefix = entry.location?.file
-						? `${entry.location.file}:${entry.location.line ?? 0}:${entry.location.column ?? 0} `
-						: '';
-
-					return {
-						message: `${locationPrefix}${entry.text ?? 'Unknown esbuild error'}`,
-					};
-				});
-			}
-
-			if (typeof candidate.message === 'string') {
-				return [{ message: candidate.message }];
-			}
-		}
-
-		return [{ message: 'Unknown esbuild error' }];
-	}
-
-	/**
-	 * Bundles entrypoints using esbuild for Node runtime builds.
-	 */
-	async build(options: BuildOptions): Promise<BuildResult> {
-		const esbuild = await this.loadEsbuildModule();
-		const contextRoot = options.root ? path.resolve(options.root) : process.cwd();
-		const outdir = path.resolve(options.outdir ?? '.eco/assets');
-		const tsconfigPath = path.join(contextRoot, 'tsconfig.json');
-		const tsconfigExists = fileSystem.exists(tsconfigPath);
-
-		const plugins = this.getPluginsForBuild(options.plugins);
-		const esbuildPlugins: EsbuildPlugin[] = [
-			...(plugins.length > 0 ? [this.createEcoPluginBridge(plugins, contextRoot)] : []),
-		];
-		const transpileTarget = 'es2022';
-
-		const usesTemplatedNaming = this.hasTemplateTokens(options.naming);
-		const outfile = options.naming && !usesTemplatedNaming ? path.join(outdir, options.naming) : undefined;
-		if (outfile) {
-			fileSystem.ensureDir(path.dirname(outfile));
-		}
-
-		const outputOptions = outfile
-			? { outfile }
-			: {
-					outdir,
-					entryNames: usesTemplatedNaming ? this.toEntryNamePattern(options.naming) : '[name]',
-					chunkNames: '[name]-[hash]',
-					assetNames: '[name]-[hash]',
-				};
-
-		try {
-			const result = await esbuild.build({
-				absWorkingDir: contextRoot,
-				entryPoints: options.entrypoints,
-				bundle: options.bundle ?? true,
-				...outputOptions,
-				format: this.mapEsbuildFormat(options.format),
-				platform: (options.target === 'browser' ? 'browser' : 'node') as 'browser' | 'node',
-				sourcemap: this.mapEsbuildSourcemap(options.sourcemap),
-				splitting: outfile ? false : !!options.splitting,
-				minify: !!options.minify,
-				...(typeof options.treeshaking === 'boolean' ? { treeShaking: options.treeshaking } : {}),
-				external: options.external,
-				...(options.target !== 'browser' && options.externalPackages !== false
-					? { packages: 'external' as const }
-					: {}),
-				target: transpileTarget,
-				metafile: true,
-				write: true,
-				plugins: esbuildPlugins,
-				jsx: 'automatic',
-				tsconfig: tsconfigExists ? tsconfigPath : undefined,
-				logLevel: 'silent',
-			});
-
-			const outputs = Object.keys(result.metafile.outputs).map((outputPath) => ({
-				path: path.isAbsolute(outputPath) ? outputPath : path.join(contextRoot, outputPath),
-			}));
-			const logs = result.warnings.map((warning) => ({ message: warning.text }));
-			const dependencyGraph = this.extractDependencyGraph(result.metafile, contextRoot);
-
-			return {
-				success: true,
-				logs,
-				outputs,
-				dependencyGraph,
-			};
-		} catch (error) {
-			return {
-				success: false,
-				logs: this.toBuildLogs(error),
-				outputs: [],
-			};
-		}
-	}
-
-	/**
-	 * Resolves module specifiers from a project root.
-	 */
-	resolve(importPath: string, rootDir: string): string {
-		const localRequire = createRequire(path.join(rootDir, 'package.json'));
-		return localRequire.resolve(importPath);
-	}
-
-	/**
-	 * Registers a build plugin once by plugin name.
-	 */
-	registerPlugin(plugin: EcoBuildPlugin): void {
-		if (!this.registeredPlugins.find((registered) => registered.name === plugin.name)) {
-			this.registeredPlugins.push(plugin);
-		}
-	}
-
-	/**
-	 * Returns transpile defaults for a known transpile profile.
-	 */
-	getTranspileOptions(profile: BuildTranspileProfile): BuildTranspileOptions {
-		return transpileProfileToOptions(profile);
-	}
-}