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

package/src/services/module-loading/page-module-import.service.ts

@@ -1,302 +0,0 @@
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { fileSystem } from '@ecopages/file-system';
-import { build, type BuildExecutor, type BuildResult } from '../../build/build-adapter.ts';
-import { normalizeNodeRuntimeBuildOutputFile } from '../../build/runtime-build-output-normalizer.ts';
-import type { EcoBuildPlugin } from '../../build/build-types.ts';
-import type { SourceModuleLoaderFactory } from './module-loading-types.ts';
-import { supportsSourceModuleLoading } from './source-module-support.ts';
-
-interface PageModuleImportBaseOptions {
-	filePath: string;
-	bypassCache?: boolean;
-	cacheScope?: string;
-	invalidationVersion?: number;
-}
-
-/**
- * Options for imports that must pass through the Ecopages build pipeline.
- *
- * @remarks
- * Callers should use build mode for framework-owned page modules and any other
- * source that relies on Ecopages build resolution before runtime execution.
- */
-export interface PageModuleBuildImportOptions extends PageModuleImportBaseOptions {
-	rootDir: string;
-	outdir: string;
-	buildExecutor?: BuildExecutor;
-	splitting?: boolean;
-	externalPackages?: boolean;
-	jsx?: {
-		development?: boolean;
-		factory?: string;
-		fragment?: string;
-		importSource?: string;
-		runtime?: 'classic' | 'automatic';
-		sideEffects?: boolean;
-	};
-	plugins?: EcoBuildPlugin[];
-	transpileErrorMessage?: (details: string) => string;
-	noOutputMessage?: (filePath: string) => string;
-}
-/**
- * Minimal runtime dependencies required to load page modules.
- *
- * @remarks
- * This service owns cache and runtime import policy. Hashing and build
- * execution are injected so tests can provide explicit fakes without module
- * interception.
- */
-export interface PageModuleImportDependencies {
-	hashFile(filePath: string): string;
-	buildModule(options: Parameters<typeof build>[0], buildExecutor?: BuildExecutor): Promise<BuildResult>;
-	canLoadSourceModuleFromHost(filePath: string): boolean;
-	getHostModuleLoader: SourceModuleLoaderFactory;
-}
-
-/**
- * Loads page-like modules through the Ecopages build pipeline.
- *
- * This service centralizes the shared build-first import strategy used by route
- * scanning, page data loading, and request-time page inspection. In Node
- * development it can still delegate compatible source imports to the active
- * host loader, but the public contract remains one transpile-targeted module
- * loading path.
- *
- * Keeping this logic in one place prevents subtle drift in cache-busting,
- * transpilation settings, and error semantics across the different callers.
- */
-export class PageModuleImportService {
-	private readonly dependencies: PageModuleImportDependencies;
-	private readonly importCache = new Map<string, Promise<unknown>>();
-	private developmentInvalidationVersion = 0;
-
-	constructor(dependencies?: Partial<PageModuleImportDependencies>) {
-		this.dependencies = {
-			hashFile: dependencies?.hashFile ?? ((filePath) => fileSystem.hash(filePath)),
-			buildModule: dependencies?.buildModule ?? ((options, buildExecutor) => build(options, buildExecutor)),
-			canLoadSourceModuleFromHost: dependencies?.canLoadSourceModuleFromHost ?? supportsSourceModuleLoading,
-			getHostModuleLoader: dependencies?.getHostModuleLoader ?? (() => undefined),
-		};
-	}
-
-	/**
-	 * Clears the shared import cache used by framework-owned page-module loads.
-	 */
-	clearImportCache(): void {
-		this.importCache.clear();
-	}
-
-	/**
-	 * Invalidates all previously imported modules in development by clearing the
-	 * import cache and incrementing the invalidation version included in cache keys.
-	 *
-	 * This forces all modules to be reloaded on the next import, even if their
-	 * source content hasn't changed. This is necessary to ensure that changes to
-	 * non-content aspects of modules (e.g. dependencies, transpilation output)
-	 * are picked up during development.
-	 */
-	invalidateDevelopmentGraph(): void {
-		this.clearImportCache();
-		this.developmentInvalidationVersion += 1;
-	}
-
-	/**
-	 * Imports a page-like module from source.
-	 *
-	 * The caller controls the output directory and error wording so different
-	 * subsystems can reuse the same loading mechanism while preserving their
-	 * current diagnostics. Module identities stay stable for unchanged files and
-	 * roll forward automatically when the source hash changes during watch mode.
-	 *
-	 * @typeParam T Expected module shape.
-	 * @param options Runtime-specific import settings.
-	 * @returns The loaded module.
-	 */
-	async importModule<T = unknown>(options: PageModuleBuildImportOptions): Promise<T> {
-		const { filePath } = options;
-		const invalidationVersion = options.invalidationVersion ?? this.developmentInvalidationVersion;
-		const { externalPackages, splitting } = options;
-
-		const fileHash = this.dependencies.hashFile(filePath);
-		const hostModuleLoader =
-			typeof Bun === 'undefined' &&
-			process.env.NODE_ENV === 'development' &&
-			this.dependencies.canLoadSourceModuleFromHost(filePath)
-				? this.dependencies.getHostModuleLoader()
-				: undefined;
-
-		if (hostModuleLoader) {
-			const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, options.cacheScope);
-			return (await hostModuleLoader(sourceModuleUrl.href)) as T;
-		}
-
-		if (options.bypassCache) {
-			this.developmentInvalidationVersion += 1;
-			return await this.loadModule<T>({
-				...options,
-				invalidationVersion: this.developmentInvalidationVersion,
-				fileHash,
-			});
-		}
-
-		const runtime = typeof Bun !== 'undefined' ? 'bun' : 'node-build';
-		const cacheKey = [
-			runtime,
-			filePath,
-			options.rootDir,
-			splitting ?? 'default',
-			externalPackages ?? 'default',
-			options.cacheScope ?? 'default',
-			createJsxCacheKey(options.jsx),
-			createPluginCacheKey(options.plugins),
-			fileHash,
-			invalidationVersion,
-		].join('::');
-		const cachedModule = this.importCache.get(cacheKey);
-
-		if (cachedModule) {
-			return (await cachedModule) as T;
-		}
-
-		const importPromise = this.loadModule<T>({
-			...options,
-			fileHash,
-		});
-
-		this.importCache.set(cacheKey, importPromise);
-
-		try {
-			return await importPromise;
-		} catch (error) {
-			this.importCache.delete(cacheKey);
-			throw error;
-		}
-	}
-
-	private async loadModule<T = unknown>(
-		options: PageModuleBuildImportOptions & {
-			fileHash: string;
-		},
-	): Promise<T> {
-		const { filePath, invalidationVersion = this.developmentInvalidationVersion, cacheScope, fileHash } = options;
-
-		const {
-			rootDir,
-			outdir,
-			splitting,
-			externalPackages,
-			transpileErrorMessage = (details) => `Error transpiling page module: ${details}`,
-			noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`,
-		} = options;
-
-		const fileBaseName = path.basename(filePath, path.extname(filePath));
-		const cacheScopeSuffix = cacheScope ? `-${sanitizeCacheScope(cacheScope)}` : '';
-		const invalidationSuffix = shouldVersionBuildOutputPath(invalidationVersion) ? `-v${invalidationVersion}` : '';
-		const outputFileName = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${invalidationSuffix}.mjs`;
-		const outputNamingTemplate = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${invalidationSuffix}.[ext]`;
-
-		const buildResult = await this.dependencies.buildModule(
-			{
-				entrypoints: [filePath],
-				root: rootDir,
-				outdir,
-				target: 'es2022',
-				format: 'esm',
-				sourcemap: 'none',
-				splitting: splitting ?? true,
-				minify: false,
-				naming: outputNamingTemplate,
-				externalPackages: true,
-				jsx: options.jsx,
-				plugins: options.plugins,
-				...(externalPackages !== undefined ? { externalPackages } : {}),
-			},
-			options.buildExecutor,
-		);
-
-		if (!buildResult.success) {
-			const details = buildResult.logs.map((log) => log.message).join(' | ');
-			throw new Error(transpileErrorMessage(details));
-		}
-
-		const preferredOutputPath = path.join(outdir, outputFileName);
-		const compiledOutput =
-			buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ??
-			buildResult.outputs.find((output) => /\.(?:[cm]?js)$/u.test(output.path))?.path;
-
-		if (!compiledOutput) {
-			throw new Error(noOutputMessage(filePath));
-		}
-
-		normalizeNodeRuntimeBuildOutputFile(compiledOutput, rootDir);
-
-		const compiledOutputUrl = pathToFileURL(compiledOutput);
-
-		if (shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope)) {
-			compiledOutputUrl.searchParams.set(
-				'update',
-				[fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : undefined]
-					.filter((value) => value !== undefined)
-					.join('-'),
-			);
-		}
-
-		return (await import(/* @vite-ignore */ compiledOutputUrl.href)) as T;
-	}
-}
-
-function createRuntimeModuleUrl(
-	filePath: string,
-	fileHash: string,
-	invalidationVersion: number,
-	cacheScope?: string,
-): URL {
-	const moduleUrl = pathToFileURL(filePath);
-
-	if (shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope)) {
-		moduleUrl.searchParams.set(
-			'update',
-			[fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : undefined]
-				.filter((value) => value !== undefined)
-				.join('-'),
-		);
-	}
-
-	return moduleUrl;
-}
-
-function shouldAddRuntimeUpdateQuery(invalidationVersion: number, cacheScope?: string): boolean {
-	return process.env.NODE_ENV === 'development' || invalidationVersion > 0 || !!cacheScope;
-}
-
-function shouldVersionBuildOutputPath(invalidationVersion: number): boolean {
-	return typeof Bun !== 'undefined' && invalidationVersion > 0;
-}
-
-function sanitizeCacheScope(cacheScope: string): string {
-	return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, '-');
-}
-
-function createJsxCacheKey(jsx: PageModuleBuildImportOptions['jsx']): string {
-	if (!jsx) {
-		return 'jsx:default';
-	}
-
-	return JSON.stringify({
-		development: jsx.development ?? false,
-		factory: jsx.factory ?? null,
-		fragment: jsx.fragment ?? null,
-		importSource: jsx.importSource ?? null,
-		runtime: jsx.runtime ?? null,
-		sideEffects: jsx.sideEffects ?? null,
-	});
-}
-
-function createPluginCacheKey(plugins?: EcoBuildPlugin[]): string {
-	if (!plugins || plugins.length === 0) {
-		return 'plugins:default';
-	}
-
-	return `plugins:${plugins.map((plugin) => plugin.name).join(',')}`;
-}

package/src/services/module-loading/server-module-transpiler.service.test.ts

@@ -1,242 +0,0 @@
-import assert from 'node:assert/strict';
-import { describe, it } from 'vitest';
-import type { BuildResult } from '../../build/build-adapter.js';
-import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
-import { CounterServerInvalidationState } from '../runtime-state/server-invalidation-state.service.ts';
-import { getAppModuleLoader, setAppHostModuleLoader } from './app-server-module-transpiler.service.ts';
-import { ServerModuleTranspiler, type ServerModuleImportDependency } from './server-module-transpiler.service.ts';
-
-function createBuildResult(): BuildResult {
-	return {
-		success: true,
-		logs: [],
-		outputs: [],
-	};
-}
-
-function createFakeImportService(): {
-	dependency: ServerModuleImportDependency;
-	calls: {
-		importModule: Array<unknown>;
-		invalidateDevelopmentGraph: number;
-	};
-	setResult(result: unknown): void;
-} {
-	const calls = {
-		importModule: [] as Array<unknown>,
-		invalidateDevelopmentGraph: 0,
-	};
-	let nextResult: unknown = undefined;
-
-	return {
-		dependency: {
-			async importModule<T = unknown>(
-				options: Parameters<ServerModuleImportDependency['importModule']>[0],
-			): Promise<T> {
-				calls.importModule.push(options);
-				return nextResult as T;
-			},
-			invalidateDevelopmentGraph(): void {
-				calls.invalidateDevelopmentGraph += 1;
-			},
-		},
-		calls,
-		setResult(result: unknown): void {
-			nextResult = result;
-		},
-	};
-}
-
-describe('ServerModuleTranspiler', () => {
-	it('injects app root dir and build executor into page module imports', async () => {
-		const buildExecutor = { build: async () => createBuildResult() };
-		const fakeImportService = createFakeImportService();
-		fakeImportService.setResult({ default: { ok: true } });
-
-		const service = new ServerModuleTranspiler({
-			rootDir: '/app',
-			getBuildExecutor: () => buildExecutor,
-			pageModuleImportService: fakeImportService.dependency,
-		});
-
-		await service.importModule({
-			filePath: '/app/src/pages/index.tsx',
-			outdir: '/app/.eco/.server-modules',
-		});
-
-		assert.deepEqual(fakeImportService.calls.importModule, [
-			{
-				filePath: '/app/src/pages/index.tsx',
-				outdir: '/app/.eco/.server-modules',
-				rootDir: '/app',
-				buildExecutor,
-				invalidationVersion: undefined,
-			},
-		]);
-	});
-
-	it('supports explicit bootstrap root and executor without a full app config', async () => {
-		const buildExecutor = { build: async () => createBuildResult() };
-		const fakeImportService = createFakeImportService();
-		fakeImportService.setResult({ default: { ok: true } });
-
-		const service = new ServerModuleTranspiler({
-			rootDir: '/bootstrap-app',
-			getBuildExecutor: () => buildExecutor,
-			pageModuleImportService: fakeImportService.dependency,
-		});
-
-		await service.importModule({
-			filePath: '/bootstrap-app/eco.config.ts',
-			outdir: '/bootstrap-app/.eco/.server-modules',
-		});
-
-		assert.deepEqual(fakeImportService.calls.importModule, [
-			{
-				filePath: '/bootstrap-app/eco.config.ts',
-				outdir: '/bootstrap-app/.eco/.server-modules',
-				rootDir: '/bootstrap-app',
-				buildExecutor,
-				invalidationVersion: undefined,
-			},
-		]);
-	});
-
-	it('invalidates the owned import graph when no app invalidation callback is provided', () => {
-		const fakeImportService = createFakeImportService();
-
-		const service = new ServerModuleTranspiler({
-			rootDir: '/bootstrap-app',
-			getBuildExecutor: () => ({ build: async () => createBuildResult() }),
-			pageModuleImportService: fakeImportService.dependency,
-		});
-
-		service.invalidate(['/bootstrap-app/src/pages/index.tsx']);
-
-		assert.equal(fakeImportService.calls.invalidateDevelopmentGraph, 1);
-	});
-
-	it('forwards an abstract host module loader into the default page import service', () => {
-		const hostModuleLoader = async (_id: string) => ({ default: { ok: true } });
-		const service = new ServerModuleTranspiler({
-			rootDir: '/bootstrap-app',
-			getBuildExecutor: () => ({ build: async () => createBuildResult() }),
-			getHostModuleLoader: () => hostModuleLoader,
-		});
-
-		const internal = service as unknown as {
-			pageModuleImportService: { dependencies: { getHostModuleLoader: () => unknown } };
-		};
-
-		assert.equal(internal.pageModuleImportService.dependencies.getHostModuleLoader(), hostModuleLoader);
-	});
-
-	it('reuses one app-owned module loader per app config', () => {
-		const appConfig = {
-			rootDir: '/app',
-			absolutePaths: {
-				pagesDir: '/app/src/pages',
-				includesDir: '/app/src/includes',
-				layoutsDir: '/app/src/layouts',
-				componentsDir: '/app/src/components',
-			},
-			templatesExt: ['.tsx'],
-			runtime: {},
-		} as unknown as EcoPagesAppConfig;
-
-		const firstLoader = getAppModuleLoader(appConfig);
-		const secondLoader = getAppModuleLoader(appConfig);
-
-		assert.equal(firstLoader, secondLoader);
-		assert.equal(firstLoader.owner, 'app');
-	});
-
-	it('reflects host ownership on the app-owned module loader after runtime wiring changes', () => {
-		const appConfig = {
-			rootDir: '/app',
-			absolutePaths: {
-				pagesDir: '/app/src/pages',
-				includesDir: '/app/src/includes',
-				layoutsDir: '/app/src/layouts',
-				componentsDir: '/app/src/components',
-			},
-			templatesExt: ['.tsx'],
-			runtime: {},
-		} as unknown as EcoPagesAppConfig;
-		const moduleLoader = getAppModuleLoader(appConfig);
-
-		setAppHostModuleLoader(appConfig, async () => ({ default: { ok: true } }));
-
-		assert.equal(moduleLoader.owner, 'host');
-	});
-
-	it('applies the app invalidation version to app-owned module imports', async () => {
-		const calls: Array<unknown> = [];
-		const buildExecutor = { build: async () => createBuildResult() };
-		const appConfig = {
-			rootDir: '/app',
-			absolutePaths: {
-				pagesDir: '/app/src/pages',
-				includesDir: '/app/src/includes',
-				layoutsDir: '/app/src/layouts',
-				componentsDir: '/app/src/components',
-			},
-			templatesExt: ['.tsx'],
-			runtime: {
-				buildExecutor,
-				serverInvalidationState: new CounterServerInvalidationState(),
-			},
-		} as unknown as EcoPagesAppConfig;
-
-		const moduleLoader = getAppModuleLoader(appConfig) as unknown as {
-			pageModuleImportService: {
-				importModule: <T = unknown>(options: unknown) => Promise<T>;
-			};
-		};
-
-		const originalImportModule = moduleLoader.pageModuleImportService.importModule.bind(
-			moduleLoader.pageModuleImportService,
-		);
-		moduleLoader.pageModuleImportService.importModule = async <T = unknown>(options: unknown): Promise<T> => {
-			calls.push(options);
-			return { default: { ok: true } } as T;
-		};
-
-		appConfig.runtime!.serverInvalidationState!.invalidateServerModules(['/app/src/includes/seo.kita.tsx']);
-
-		await getAppModuleLoader(appConfig).importModule({
-			filePath: '/app/src/includes/html.kita.tsx',
-			rootDir: '/app',
-			outdir: '/app/.eco/.server-modules',
-		});
-
-		moduleLoader.pageModuleImportService.importModule = originalImportModule;
-
-		assert.equal(calls.length, 1);
-		const importOptions = calls[0] as {
-			buildExecutor: unknown;
-			filePath: string;
-			invalidationVersion: number;
-			outdir: string;
-			plugins?: Array<{ name: string }>;
-			rootDir: string;
-		};
-
-		assert.deepEqual(
-			{
-				buildExecutor: importOptions.buildExecutor,
-				filePath: importOptions.filePath,
-				invalidationVersion: importOptions.invalidationVersion,
-				outdir: importOptions.outdir,
-				rootDir: importOptions.rootDir,
-			},
-			{
-				filePath: '/app/src/includes/html.kita.tsx',
-				rootDir: '/app',
-				outdir: '/app/.eco/.server-modules',
-				buildExecutor,
-				invalidationVersion: 1,
-			},
-		);
-	});
-});

package/src/services/module-loading/server-module-transpiler.service.ts

@@ -1,104 +0,0 @@
-import type { BuildExecutor } from '../../build/build-adapter.ts';
-import type { EcoBuildPlugin } from '../../build/build-types.ts';
-import type { AppModuleLoader } from './app-module-loader.service.ts';
-import { PageModuleImportService, type PageModuleBuildImportOptions } from './page-module-import.service.ts';
-import type { SourceModuleLoaderFactory } from './module-loading-types.ts';
-
-export type ServerModuleTranspilerOptions = Omit<PageModuleBuildImportOptions, 'rootDir' | 'buildExecutor'>;
-
-export type ServerModuleImportDependency = Pick<AppModuleLoader, 'importModule' | 'invalidateDevelopmentGraph'>;
-
-/**
- * Immutable execution context for one server-transpiler instance.
- *
- * @remarks
- * Callers own when and why a new transpiler is created. This service only owns
- * applying the supplied root/build-executor pair consistently to every module
- * load that passes through it.
- */
-export type ServerModuleTranspilerBootstrapArgs = {
-	rootDir: string;
-	getBuildExecutor?: () => BuildExecutor | undefined;
-	canLoadSourceModuleFromHost?: (filePath: string) => boolean;
-	getHostModuleLoader?: SourceModuleLoaderFactory;
-	getInvalidationVersion?: () => number;
-	invalidateModules?: (changedFiles?: string[]) => void;
-	pageModuleImportService?: ServerModuleImportDependency;
-	/** Factory evaluated on each importModule call to produce plugins applied to every load. */
-	getDefaultPlugins?: () => EcoBuildPlugin[];
-};
-
-/**
- * App-owned boundary for server-side source module loading.
- *
- * @remarks
- * This service centralizes server-side module transpilation and import behind
- * an explicit caller-owned root and build executor.
- */
-export class ServerModuleTranspiler {
-	private readonly pageModuleImportService: ServerModuleImportDependency;
-	private readonly getRootDir: () => string;
-	private readonly getBuildExecutor: () => BuildExecutor | undefined;
-	private readonly getInvalidationVersion: () => number | undefined;
-	private readonly invalidateModules: (changedFiles?: string[]) => void;
-	private readonly getDefaultPlugins: () => EcoBuildPlugin[];
-
-	/**
-	 * Creates one explicit server-transpiler boundary for a given execution
-	 * context.
-	 */
-	constructor(args: ServerModuleTranspilerBootstrapArgs) {
-		this.pageModuleImportService =
-			args.pageModuleImportService ??
-			new PageModuleImportService({
-				canLoadSourceModuleFromHost: args.canLoadSourceModuleFromHost,
-				getHostModuleLoader: args.getHostModuleLoader,
-			});
-		this.getRootDir = () => args.rootDir;
-		this.getBuildExecutor = args.getBuildExecutor ?? (() => undefined);
-		this.getInvalidationVersion = () => args.getInvalidationVersion?.();
-		this.getDefaultPlugins = args.getDefaultPlugins ?? (() => []);
-		this.invalidateModules = (changedFiles) => {
-			if (args.invalidateModules) {
-				args.invalidateModules(changedFiles);
-				return;
-			}
-
-			this.pageModuleImportService.invalidateDevelopmentGraph();
-		};
-	}
-
-	/**
-	 * Loads a server-side source module through the caller-owned transpile
-	 * context.
-	 */
-	async importModule<T = unknown>(options: ServerModuleTranspilerOptions): Promise<T> {
-		const mergedPlugins = [...this.getDefaultPlugins(), ...(options.plugins ?? [])];
-		const { plugins: _plugins, ...baseOptions } = options;
-		return await this.pageModuleImportService.importModule<T>({
-			...baseOptions,
-			...(mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {}),
-			rootDir: this.getRootDir(),
-			buildExecutor: this.getBuildExecutor(),
-			invalidationVersion: this.getInvalidationVersion(),
-		});
-	}
-
-	/**
-	 * Invalidates cached module state for development reloads.
-	 */
-	invalidate(changedFiles?: string[]): void {
-		this.invalidateModules(changedFiles);
-	}
-
-	/**
-	 * Releases transpiler-owned resources.
-	 *
-	 * @remarks
-	 * The current implementation delegates cache ownership to lower-level module
-	 * loading services, so disposal is intentionally a no-op for now.
-	 */
-	async dispose(): Promise<void> {
-		return;
-	}
-}

package/src/services/module-loading/source-module-support.ts

@@ -1,19 +0,0 @@
-import path from 'node:path';
-
-/**
- * Returns whether a source module can be loaded directly by the host runtime without
- * first going through the transpile/import pipeline.
- */
-export function supportsSourceModuleLoading(filePath: string): boolean {
-	const extension = path.extname(filePath);
-	return (
-		extension === '.js' ||
-		extension === '.jsx' ||
-		extension === '.ts' ||
-		extension === '.tsx' ||
-		extension === '.mjs' ||
-		extension === '.mts' ||
-		extension === '.cjs' ||
-		extension === '.cts'
-	);
-}