@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.7

package/src/route-renderer/page-loading/dependency-resolver.test.ts

@@ -0,0 +1,345 @@
+import { describe, expect, it, vi } from 'vitest';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { DEPENDENCY_ERRORS, DependencyResolverService } from './dependency-resolver.ts';
+import type { EcoPagesAppConfig } from '../../internal-types.ts';
+import type {
+	AssetDefinition,
+	AssetProcessingService,
+	ProcessedAsset,
+	ContentScriptAsset,
+} from '../../services/assets/asset-processing-service/index.ts';
+import type { EcoComponent } from '../../public-types.ts';
+
+describe('DependencyResolverService', () => {
+	const appConfig = {
+		srcDir: '/app',
+	} as EcoPagesAppConfig;
+
+	it('should resolve dependency and lazy script paths', () => {
+		const assetProcessingService = {
+			processDependencies: vi.fn(async () => []),
+		} as unknown as AssetProcessingService;
+		const service = new DependencyResolverService(appConfig, assetProcessingService);
+
+		expect(service.resolveDependencyPath('/app/components/card', './style.css')).toBe(
+			'/app/components/card/style.css',
+		);
+		expect(service.resolveLazyScripts('/app/components/card', ['./client.ts', './widget.tsx'])).toBe(
+			'/assets/components/card/client.js,/assets/components/card/widget.js',
+		);
+	});
+
+	it('should emit module dependencies as content scripts and resolve lazy triggers by default', async () => {
+		let capturedDeps: AssetDefinition[] = [];
+		const assetProcessingService = {
+			processDependencies: vi.fn(async (deps: AssetDefinition[]) => {
+				capturedDeps = deps;
+				return [
+					{
+						kind: 'script',
+						filepath: '/app/components/table/table.client.ts',
+						srcUrl: '/assets/components/table/table.client.js',
+					},
+				] as ProcessedAsset[];
+			}),
+		} as unknown as AssetProcessingService;
+		const service = new DependencyResolverService(appConfig, assetProcessingService);
+
+		const component = ((_) => '<table></table>') as EcoComponent<Record<string, unknown>>;
+		component.config = {
+			__eco: {
+				id: 'table',
+				integration: 'react',
+				file: '/app/components/table/table.tsx',
+			},
+			dependencies: {
+				modules: ['react-aria-components{Table,Button}', './client-utils'],
+				scripts: [{ src: './table.client.ts', lazy: { 'on:interaction': 'click' } }],
+			},
+		};
+
+		await service.processComponentDependencies([component], 'react');
+
+		const contentScripts = capturedDeps.filter(
+			(dep): dep is ContentScriptAsset => dep.kind === 'script' && dep.source === 'content',
+		);
+
+		expect(
+			contentScripts.some((script) =>
+				script.content.includes("export { Table, Button } from 'react-aria-components';"),
+			),
+		).toBe(true);
+		expect(contentScripts.some((script) => script.content.includes("export * from './client-utils';"))).toBe(true);
+		expect(contentScripts.every((script) => /^module-[a-f0-9]+$/.test(script.name ?? ''))).toBe(true);
+
+		const hasInjector = capturedDeps.some(
+			(dep) =>
+				dep.kind === 'script' &&
+				dep.source === 'node-module' &&
+				dep.importPath === '@ecopages/scripts-injector',
+		);
+		expect(hasInjector).toBe(false);
+
+		expect(component.config._resolvedLazyScripts).toBeUndefined();
+		expect(component.config._resolvedLazyTriggers).toHaveLength(1);
+		expect(component.config._resolvedLazyTriggers?.[0]?.rules).toEqual([
+			{
+				'on:interaction': {
+					value: 'click',
+					scripts: ['/assets/components/table/table.client.js'],
+				},
+			},
+		]);
+	});
+
+	it('should detect ecopages virtual imports via parser', async () => {
+		const tempDir = mkdtempSync(join(tmpdir(), 'ecopages-dependency-resolver-'));
+		const componentFile = join(tempDir, 'component.tsx');
+
+		writeFileSync(
+			componentFile,
+			"import { heroImage as imageAsset } from 'ecopages:images';\nexport const ok = imageAsset.src;\n",
+			'utf-8',
+		);
+
+		let capturedDeps: AssetDefinition[] = [];
+		const assetProcessingService = {
+			processDependencies: vi.fn(async (deps: AssetDefinition[]) => {
+				capturedDeps = deps;
+				return [] as ProcessedAsset[];
+			}),
+		} as unknown as AssetProcessingService;
+
+		const service = new DependencyResolverService(appConfig, assetProcessingService);
+		const component = ((_) => '<div></div>') as EcoComponent<Record<string, unknown>>;
+		component.config = {
+			__eco: {
+				id: 'component',
+				integration: 'react',
+				file: componentFile,
+			},
+		};
+
+		try {
+			await service.processComponentDependencies([component], 'react');
+
+			const contentScripts = capturedDeps.filter(
+				(dep): dep is ContentScriptAsset => dep.kind === 'script' && dep.source === 'content',
+			);
+
+			expect(contentScripts.some((script) => script.content.includes("from 'ecopages:images';"))).toBe(true);
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('should pass entry attributes and support inline stylesheet content', async () => {
+		let capturedDeps: AssetDefinition[] = [];
+		const assetProcessingService = {
+			processDependencies: vi.fn(async (deps: AssetDefinition[]) => {
+				capturedDeps = deps;
+				return [] as ProcessedAsset[];
+			}),
+		} as unknown as AssetProcessingService;
+
+		const service = new DependencyResolverService(appConfig, assetProcessingService);
+		const component = ((_) => '<div></div>') as EcoComponent<Record<string, unknown>>;
+		component.config = {
+			__eco: {
+				id: 'attrs-inline',
+				integration: 'react',
+				file: '/app/components/attrs-inline/component.tsx',
+			},
+			dependencies: {
+				scripts: [
+					{
+						src: './client.ts',
+						attributes: {
+							async: '',
+							'data-script-id': 'main-client',
+						},
+					},
+				],
+				stylesheets: [
+					{
+						src: './styles.css',
+						attributes: {
+							media: 'print',
+						},
+					},
+					{
+						content: 'body { background: red; }',
+						attributes: {
+							media: 'screen',
+						},
+					},
+				],
+			},
+		};
+
+		await service.processComponentDependencies([component], 'react');
+
+		expect(
+			capturedDeps.some((dep) => {
+				if (dep.kind !== 'script' || dep.source !== 'file') return false;
+				return (
+					dep.filepath === '/app/components/attrs-inline/client.ts' &&
+					dep.attributes?.type === 'module' &&
+					dep.attributes?.defer === '' &&
+					dep.attributes?.async === '' &&
+					dep.attributes?.['data-script-id'] === 'main-client'
+				);
+			}),
+		).toBe(true);
+
+		expect(
+			capturedDeps.some((dep) => {
+				if (dep.kind !== 'stylesheet' || dep.source !== 'file') return false;
+				return (
+					dep.filepath === '/app/components/attrs-inline/styles.css' &&
+					dep.attributes?.rel === 'stylesheet' &&
+					dep.attributes?.media === 'print'
+				);
+			}),
+		).toBe(true);
+
+		expect(
+			capturedDeps.some((dep) => {
+				if (dep.kind !== 'stylesheet' || dep.source !== 'content') return false;
+				return dep.content === 'body { background: red; }' && dep.attributes?.media === 'screen';
+			}),
+		).toBe(true);
+	});
+
+	it('should reject lazy script entry without src or content', async () => {
+		const assetProcessingService = {
+			processDependencies: vi.fn(async () => [] as ProcessedAsset[]),
+		} as unknown as AssetProcessingService;
+
+		const service = new DependencyResolverService(appConfig, assetProcessingService);
+		const component = ((_) => '<div></div>') as EcoComponent<Record<string, unknown>>;
+		component.config = {
+			__eco: {
+				id: 'invalid-lazy-entry',
+				integration: 'react',
+				file: '/app/components/invalid-lazy-entry/component.tsx',
+			},
+			dependencies: {
+				scripts: [
+					{
+						lazy: { 'on:idle': true },
+					},
+				],
+			},
+		};
+
+		await expect(service.processComponentDependencies([component], 'react')).rejects.toThrow(
+			DEPENDENCY_ERRORS.LAZY_SCRIPT_MISSING_SRC,
+		);
+	});
+
+	it('should resolve lazy triggers by group, including lazy content entries', async () => {
+		const assetProcessingService = {
+			processDependencies: vi.fn(async (deps: AssetDefinition[]) => {
+				return deps.map((dep, index) => {
+					const lazyKey = dep.attributes?.['data-eco-lazy-key'];
+					const hasContent = dep.source === 'content' && typeof (dep as any).content === 'string';
+					const isLazyScript = dep.kind === 'script' && Boolean(lazyKey);
+					const srcUrl = isLazyScript
+						? hasContent
+							? `/assets/lazy/content-${index}.js`
+							: `/assets/lazy/file-${index}.js`
+						: undefined;
+
+					return {
+						kind: dep.kind ?? 'script',
+						filepath: (dep as Record<string, any>).filepath,
+						attributes: dep.attributes,
+						srcUrl,
+					} as ProcessedAsset;
+				});
+			}),
+		} as unknown as AssetProcessingService;
+
+		const service = new DependencyResolverService(appConfig, assetProcessingService);
+		const component = ((_) => '<div></div>') as EcoComponent<Record<string, unknown>>;
+		component.config = {
+			__eco: {
+				id: 'multi-lazy-groups',
+				integration: 'lit',
+				file: '/app/components/multi-lazy-groups/component.tsx',
+			},
+			dependencies: {
+				scripts: [
+					{ src: './idle.ts', lazy: { 'on:idle': true } },
+					{ content: 'console.log("visible")', lazy: { 'on:visible': '0.25' } },
+				],
+			},
+		};
+
+		await service.processComponentDependencies([component], 'lit');
+
+		expect(component.config._resolvedLazyScripts).toBeUndefined();
+		expect(component.config._resolvedLazyTriggers).toHaveLength(1);
+
+		const rules = component.config._resolvedLazyTriggers?.[0]?.rules ?? [];
+		const idleRule = rules.find((rule) => 'on:idle' in rule);
+		const visibleRule = rules.find((rule) => 'on:visible' in rule);
+
+		expect(idleRule && 'on:idle' in idleRule ? idleRule['on:idle'].scripts[0] : undefined).toMatch(
+			/^\/assets\/lazy\/file-\d+\.js$/,
+		);
+		expect(visibleRule && 'on:visible' in visibleRule ? visibleRule['on:visible'].scripts[0] : undefined).toMatch(
+			/^\/assets\/lazy\/content-\d+\.js$/,
+		);
+	});
+
+	it('should ignore undefined component entries when collecting nested dependencies', async () => {
+		let capturedDeps: AssetDefinition[] = [];
+		const assetProcessingService = {
+			processDependencies: vi.fn(async (deps: AssetDefinition[]) => {
+				capturedDeps = deps;
+				return [] as ProcessedAsset[];
+			}),
+		} as unknown as AssetProcessingService;
+
+		const service = new DependencyResolverService(appConfig, assetProcessingService);
+		const nestedComponent = ((_) => '<button></button>') as EcoComponent<Record<string, unknown>>;
+		nestedComponent.config = {
+			__eco: {
+				id: 'theme-toggle',
+				integration: 'react',
+				file: '/app/components/theme-toggle.tsx',
+			},
+			dependencies: {
+				scripts: ['./theme-toggle.client.ts'],
+			},
+		};
+
+		const component = ((_) => '<div></div>') as EcoComponent<Record<string, unknown>>;
+		component.config = {
+			__eco: {
+				id: 'page',
+				integration: 'kitajs',
+				file: '/app/views/page.tsx',
+			},
+			dependencies: {
+				components: [undefined, nestedComponent] as unknown as EcoComponent[],
+			},
+		};
+
+		await expect(
+			service.processComponentDependencies([undefined as unknown as EcoComponent, component], 'kitajs'),
+		).resolves.toEqual([]);
+
+		expect(capturedDeps).toEqual([
+			expect.objectContaining({
+				kind: 'script',
+				source: 'file',
+				filepath: '/app/components/theme-toggle.client.ts',
+			}),
+		]);
+	});
+});

package/src/route-renderer/{dependency-resolver.ts → page-loading/dependency-resolver.ts}

@@ -6,16 +6,16 @@ import type {
 	EcoComponentScriptEntry,
 	LazyTriggerRule,
 	ResolvedLazyTrigger,
-} from '../public-types.ts';
-import type { EcoPagesAppConfig } from '../internal-types.ts';
+} from '../../public-types.ts';
+import type { EcoPagesAppConfig } from '../../internal-types.ts';
 import type {
 	AssetDefinition,
 	AssetProcessingService,
 	ProcessedAsset,
-} from '../services/asset-processing-service/index.ts';
-import { rapidhash } from '../utils/hash.ts';
-import { AssetFactory } from '../services/asset-processing-service/index.ts';
-import { normalizeModuleDeclarations } from '../eco/module-dependencies.ts';
+} from '../../services/assets/asset-processing-service/index.ts';
+import { rapidhash } from '../../utils/hash.ts';
+import { AssetFactory } from '../../services/assets/asset-processing-service/index.ts';
+import { normalizeModuleDeclarations } from '../../eco/module-dependencies.ts';
 import { parseSync } from 'oxc-parser';
 
 export const DEPENDENCY_ERRORS = {
@@ -243,11 +243,25 @@ function buildResolvedLazyTriggers(
 }
 
 export class DependencyResolverService {
-	constructor(
-		private appConfig: EcoPagesAppConfig,
-		private assetProcessingService: AssetProcessingService,
-	) {}
+	private appConfig: EcoPagesAppConfig;
+	private assetProcessingService: AssetProcessingService;
 
+	/**
+	 * Creates the dependency resolver used by route and component rendering.
+	 *
+	 * @remarks
+	 * The resolver stays intentionally separate from HTML rendering so component
+	 * dependency collection, lazy trigger grouping, and processed-asset generation
+	 * can evolve without changing renderer implementations.
+	 */
+	constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService) {
+		this.appConfig = appConfig;
+		this.assetProcessingService = assetProcessingService;
+	}
+
+	/**
+	 * Resolves one dependency path relative to the component that declared it.
+	 */
 	resolveDependencyPath(componentDir: string, pathUrl: string): string {
 		return resolveDependencyPath(componentDir, pathUrl);
 	}
@@ -265,7 +279,7 @@ export class DependencyResolverService {
 	 * Lazy dependencies are always resolved into global-injector trigger maps.
 	 */
 	async processComponentDependencies(
-		components: (EcoComponent | Partial<EcoComponent>)[],
+		components: Array<EcoComponent | Partial<EcoComponent> | undefined | null>,
 		integrationName: string,
 	): Promise<ProcessedAsset[]> {
 		if (!this.assetProcessingService?.processDependencies) return [];
@@ -282,6 +296,8 @@ export class DependencyResolverService {
 		const lazyDependencyKeys = new Set<string>();
 
 		for (const component of components) {
+			if (!component) continue;
+
 			const componentFile = component.config?.__eco?.file;
 			if (!componentFile) continue;
 
@@ -511,7 +527,7 @@ export class DependencyResolverService {
 
 				if (dependenciesConfig?.components) {
 					for (const nestedComponent of dependenciesConfig.components) {
-						if (nestedComponent.config) {
+						if (nestedComponent?.config) {
 							collect(nestedComponent.config);
 						}
 					}

package/src/route-renderer/page-loading/page-module-loader.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+import { PageModuleLoaderService } from './page-module-loader.ts';
+import type { EcoPagesAppConfig } from '../../internal-types.ts';
+import type { EcoPageFile } from '../../public-types.ts';
+import type { EcoPageComponent } from '../../eco/eco.types.ts';
+
+describe('PageModuleLoaderService', () => {
+	const appConfig = {
+		defaultMetadata: {
+			title: 'Default title',
+			description: 'Default description',
+		},
+	} as EcoPagesAppConfig;
+
+	it('should resolve static props via getStaticPropsForPage', async () => {
+		const service = new PageModuleLoaderService(appConfig, 'http://localhost:3000');
+		const result = await service.getStaticPropsForPage({
+			getStaticProps: async () => ({
+				props: { title: 'Page title' },
+			}),
+			params: { slug: 'a' },
+		});
+
+		expect(result.props).toEqual({ title: 'Page title' });
+	});
+
+	it('should merge default and dynamic metadata', async () => {
+		const service = new PageModuleLoaderService(appConfig, 'http://localhost:3000');
+		const metadata = await service.getMetadataPropsForPage({
+			getMetadata: async ({ props }) => ({
+				title: String(props.title),
+				description: 'Dynamic description',
+			}),
+			context: {
+				props: { title: 'Dynamic title' },
+				appConfig,
+				params: {},
+				query: {},
+			},
+		});
+
+		expect(metadata).toEqual({
+			title: 'Dynamic title',
+			description: 'Dynamic description',
+		});
+	});
+
+	it('should resolve page module using provided importer and prefer component static exports', async () => {
+		const service = new PageModuleLoaderService(appConfig, 'http://localhost:3000');
+		const Page = (() => 'ok') as EcoPageComponent<any>;
+		Page.staticProps = async () => ({ props: { from: 'component-static' } });
+		Page.metadata = async () => ({
+			title: 'component-metadata',
+			description: 'component-description',
+		});
+
+		const module = {
+			default: Page,
+			getStaticProps: async () => ({ props: { from: 'module-static' } }),
+			getMetadata: async () => ({ title: 'module-metadata' }),
+			extra: 'integration-value',
+		} as unknown as EcoPageFile;
+
+		const result = await service.resolvePageModule({
+			file: '/app/pages/index.tsx',
+			importPageFileFn: async () => module,
+		});
+
+		expect(result.getStaticProps).toBe(Page.staticProps);
+		expect(result.getMetadata).toBe(Page.metadata);
+		expect(result.integrationSpecificProps).toEqual({ extra: 'integration-value' });
+	});
+
+	it('should resolve page data end-to-end', async () => {
+		const service = new PageModuleLoaderService(appConfig, 'http://localhost:3000');
+		const result = await service.resolvePageData({
+			pageModule: {
+				getStaticProps: async () => ({ props: { title: 'From props' } }),
+				getMetadata: async ({ props }) => ({
+					title: String(props.title),
+					description: 'From metadata',
+				}),
+			},
+			routeOptions: {
+				file: '/app/pages/index.tsx',
+				params: {},
+				query: {},
+			},
+		});
+
+		expect(result).toEqual({
+			props: { title: 'From props' },
+			metadata: { title: 'From props', description: 'From metadata' },
+		});
+	});
+});

package/src/route-renderer/{page-module-loader.ts → page-loading/page-module-loader.ts}

@@ -1,4 +1,4 @@
-import { invariant } from '../utils/invariant.ts';
+import { invariant } from '../../utils/invariant.ts';
 import type {
 	EcoPageFile,
 	GetMetadata,
@@ -7,33 +7,50 @@ import type {
 	PageMetadataProps,
 	RouteRendererOptions,
 	EcoPageComponent,
-} from '../public-types.ts';
-import type { EcoPagesAppConfig } from '../internal-types.ts';
-import { PageModuleImportService } from '../services/page-module-import.service.ts';
+} from '../../public-types.ts';
+import type { EcoPagesAppConfig } from '../../internal-types.ts';
+import { getAppServerModuleTranspiler } from '../../services/module-loading/app-server-module-transpiler.service.ts';
+import type { ServerModuleTranspiler } from '../../services/module-loading/server-module-transpiler.service.ts';
+import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.ts';
 
 /**
- * Handles page module loading plus static props/metadata resolution.
+ * Loads route page modules and normalizes their data hooks for rendering.
+ *
+ * @remarks
+ * This service keeps the render pipeline from depending directly on raw module
+ * imports. It owns the shared server-module transpiler setup, the precedence
+ * rules between component statics and module exports, and the normalization of
+ * page props and metadata into one renderer-facing shape.
  */
 export class PageModuleLoaderService {
-	private pageModuleImportService: PageModuleImportService;
+	private serverModuleTranspiler: ServerModuleTranspiler;
+	private appConfig: EcoPagesAppConfig;
+	private runtimeOrigin: string;
 
-	constructor(
-		private appConfig: EcoPagesAppConfig,
-		private runtimeOrigin: string,
-	) {
-		this.pageModuleImportService = new PageModuleImportService();
+	/**
+	 * Creates the page-module loader for one app/runtime instance.
+	 *
+	 * @param appConfig Finalized app config that owns build and invalidation state.
+	 * @param runtimeOrigin Runtime origin exposed to page data hooks.
+	 */
+	constructor(appConfig: EcoPagesAppConfig, runtimeOrigin: string) {
+		this.appConfig = appConfig;
+		this.runtimeOrigin = runtimeOrigin;
+		this.serverModuleTranspiler = getAppServerModuleTranspiler(appConfig);
 	}
 
 	/**
-	 * Imports a page module from source.
-	 * Uses direct dynamic import in Bun and transpile+import fallback for other runtimes.
+	 * Imports one page module through the shared server-side module loading path.
+	 *
+	 * @remarks
+	 * The underlying transpiler keeps Bun and Node aligned on one framework-owned
+	 * loading contract even though the runtime-specific execution transport differs.
 	 */
 	async importPageFile(file: string): Promise<EcoPageFile> {
 		try {
-			return await this.pageModuleImportService.importModule<EcoPageFile>({
+			return await this.serverModuleTranspiler.importModule<EcoPageFile>({
 				filePath: file,
-				rootDir: this.appConfig.rootDir,
-				outdir: `${this.appConfig.absolutePaths.distDir}/.server-modules`,
+				outdir: `${resolveInternalExecutionDir(this.appConfig)}/.server-modules`,
 				transpileErrorMessage: (details) => `Error transpiling page file: ${details}`,
 				noOutputMessage: (targetFilePath) => `No transpiled output generated for page: ${targetFilePath}`,
 			});
@@ -43,8 +60,11 @@ export class PageModuleLoaderService {
 	}
 
 	/**
-	 * Executes `getStaticProps` with Ecopages runtime context.
-	 * Returns an empty props object when no static props function is defined.
+	 * Executes the page's static-props hook with Ecopages runtime context.
+	 *
+	 * @remarks
+	 * Pages without a static-props hook still return a normalized empty props
+	 * object so downstream render preparation does not branch on hook presence.
 	 */
 	async getStaticPropsForPage(options: {
 		getStaticProps?: GetStaticProps<Record<string, unknown>>;
@@ -71,8 +91,11 @@ export class PageModuleLoaderService {
 	}
 
 	/**
-	 * Builds final page metadata using app-level defaults as a baseline.
-	 * If `getMetadata` exists, its result overlays defaults so page-level fields take precedence.
+	 * Builds the final page metadata object for one render request.
+	 *
+	 * @remarks
+	 * App-level default metadata forms the baseline, then page-level metadata is
+	 * overlaid so route-specific fields win without dropping global defaults.
 	 */
 	async getMetadataPropsForPage(options: {
 		getMetadata: GetMetadata | undefined;
@@ -122,7 +145,12 @@ export class PageModuleLoaderService {
 	}
 
 	/**
-	 * Resolves render-time page data in order: static props first, then metadata derived from those props.
+	 * Resolves the page data needed by the render pipeline.
+	 *
+	 * @remarks
+	 * Static props are resolved first because page metadata may depend on those
+	 * props. This preserves the same ordering whether data hooks are declared as
+	 * component statics or module exports.
 	 */
 	async resolvePageData(options: {
 		pageModule: {