@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.27

package/src/route-renderer/page-loading/page-dependency-bundling.ts

@@ -0,0 +1,244 @@
+import { existsSync, readFileSync } from 'node:fs';
+import type {
+	AssetDefinition,
+	FileScriptAsset,
+	FileStylesheetAsset,
+} from '../../services/assets/asset-processing-service/index.ts';
+import { AssetFactory } from '../../services/assets/asset-processing-service/index.ts';
+import { rapidhash } from '../../utils/hash.ts';
+
+/**
+ * Returns `true` when the asset attributes match the exact shape required for
+ * safe page-owned bundling.
+ */
+function hasOnlyExpectedAttributes(
+	attributes: Record<string, string> | undefined,
+	expected: Record<string, string>,
+): boolean {
+	const keys = Object.keys(attributes ?? {});
+	const expectedKeys = Object.keys(expected);
+
+	if (keys.length !== expectedKeys.length) {
+		return false;
+	}
+
+	return expectedKeys.every((key) => attributes?.[key] === expected[key]);
+}
+
+function isSafeBundledStylesheetReference(reference: string): boolean {
+	return (
+		reference.startsWith('/') ||
+		reference.startsWith('data:') ||
+		reference.startsWith('http://') ||
+		reference.startsWith('https://') ||
+		reference.startsWith('#')
+	);
+}
+
+/**
+ * Normalizes CSS URL tokens before safety checks so quoted and unquoted forms are treated equally.
+ */
+function normalizeCssReferenceToken(token: string): string {
+	return token.trim().replace(/^['"]|['"]$/g, '');
+}
+
+/**
+ * Rejects stylesheet content that contains relative references which would stop
+ * working once multiple files are collapsed into one page-owned bundle.
+ */
+function isSafeBundledStylesheetContent(content: string): boolean {
+	for (const match of content.matchAll(/@import\s+(?:url\()?['"]?([^'")\s]+)['"]?\)?/g)) {
+		const reference = normalizeCssReferenceToken(match[1] ?? '');
+		if (reference && !isSafeBundledStylesheetReference(reference)) {
+			return false;
+		}
+	}
+
+	for (const match of content.matchAll(/url\(([^)]+)\)/g)) {
+		const reference = normalizeCssReferenceToken(match[1] ?? '');
+		if (reference && !isSafeBundledStylesheetReference(reference)) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+function isBundleableFileStylesheetAsset(dependency: AssetDefinition): dependency is FileStylesheetAsset {
+	return dependency.kind === 'stylesheet' && dependency.source === 'file';
+}
+
+function isBundleableFileScriptAsset(dependency: AssetDefinition): dependency is FileScriptAsset {
+	return dependency.kind === 'script' && dependency.source === 'file';
+}
+
+type PageDependencyPackagingPlan = {
+	bundledStylesheet?: AssetDefinition;
+	bundledScript?: AssetDefinition;
+	bundleableStyleFilepaths: Set<string>;
+	bundleableScriptFilepaths: Set<string>;
+};
+
+/**
+ * Returns whether the current integration should collapse eligible page assets into
+ * page-owned bundle entries.
+ */
+export function shouldBundlePageDependencies(integrationName: string): boolean {
+	return integrationName === 'react' || integrationName === 'ecopages-jsx';
+}
+
+function createPageDependencyPackagingPlan(
+	dependencies: AssetDefinition[],
+	integrationName: string,
+): PageDependencyPackagingPlan | undefined {
+	const shouldBundleDependencies = process.env.NODE_ENV === 'production';
+
+	const bundleableStyles = dependencies
+		.filter((dependency) => {
+			if (!shouldBundleDependencies) {
+				return false;
+			}
+
+			if (dependency.kind !== 'stylesheet' || dependency.inline || dependency.position === 'body') {
+				return false;
+			}
+
+			if (dependency.packageRole || !hasOnlyExpectedAttributes(dependency.attributes, { rel: 'stylesheet' })) {
+				return false;
+			}
+
+			if (dependency.source === 'content') {
+				return isSafeBundledStylesheetContent(dependency.content);
+			}
+
+			if (!existsSync(dependency.filepath)) {
+				return false;
+			}
+
+			return isSafeBundledStylesheetContent(readFileSync(dependency.filepath, 'utf8'));
+		})
+		.filter(isBundleableFileStylesheetAsset);
+
+	const bundleableScripts = dependencies
+		.filter((dependency) => {
+			if (!shouldBundleDependencies) {
+				return false;
+			}
+
+			return (
+				dependency.kind === 'script' &&
+				dependency.source === 'file' &&
+				!dependency.inline &&
+				!dependency.excludeFromHtml &&
+				dependency.position !== 'body' &&
+				!dependency.packageRole &&
+				dependency.bundle !== false &&
+				hasOnlyExpectedAttributes(dependency.attributes, { type: 'module', defer: '' }) &&
+				existsSync(dependency.filepath)
+			);
+		})
+		.filter(isBundleableFileScriptAsset);
+
+	const bundledStylesheet =
+		bundleableStyles.length > 1
+			? AssetFactory.createContentStylesheet({
+					content: bundleableStyles.map((dependency) => readFileSync(dependency.filepath, 'utf8')).join('\n'),
+					position: 'head',
+					attributes: { rel: 'stylesheet' },
+					packageRole: 'page-style',
+					bundledSourceFilepaths: bundleableStyles.map((dependency) => dependency.filepath),
+				})
+			: undefined;
+
+	const pageScriptImports = [...new Set(bundleableScripts.map((dependency) => dependency.filepath))];
+	const shouldBundlePageScript = pageScriptImports.length > 0 && bundleableScripts.length > 1;
+	const bundledScript = shouldBundlePageScript
+		? AssetFactory.createContentScript({
+				name: `${integrationName}-page-${rapidhash(pageScriptImports.join('|')).toString(16)}`,
+				content: pageScriptImports.map((filepath) => `import ${JSON.stringify(filepath)};`).join('\n'),
+				position: 'head',
+				attributes: { type: 'module', defer: '' },
+				packageRole: 'page-script',
+				bundledSourceFilepaths: pageScriptImports,
+			})
+		: undefined;
+
+	if (!bundledStylesheet && !bundledScript) {
+		return undefined;
+	}
+
+	return {
+		bundledStylesheet,
+		bundledScript,
+		bundleableStyleFilepaths: new Set(bundleableStyles.map((dependency) => dependency.filepath)),
+		bundleableScriptFilepaths: new Set(pageScriptImports),
+	};
+}
+
+function applyPageDependencyPackagingPlan(
+	dependencies: AssetDefinition[],
+	plan: PageDependencyPackagingPlan,
+): AssetDefinition[] {
+	const unifiedDependencies: AssetDefinition[] = [];
+	let insertedStylesheet = false;
+	let insertedScript = false;
+
+	for (const dependency of dependencies) {
+		if (
+			plan.bundledStylesheet &&
+			dependency.kind === 'stylesheet' &&
+			dependency.source === 'file' &&
+			plan.bundleableStyleFilepaths.has(dependency.filepath)
+		) {
+			if (!insertedStylesheet) {
+				unifiedDependencies.push(plan.bundledStylesheet);
+				insertedStylesheet = true;
+			}
+			continue;
+		}
+
+		if (
+			plan.bundledScript &&
+			dependency.kind === 'script' &&
+			dependency.source === 'file' &&
+			plan.bundleableScriptFilepaths.has(dependency.filepath)
+		) {
+			if (!insertedScript) {
+				unifiedDependencies.push(plan.bundledScript);
+				insertedScript = true;
+			}
+			continue;
+		}
+
+		unifiedDependencies.push(dependency);
+	}
+
+	if (plan.bundledScript && !insertedScript) {
+		unifiedDependencies.push(plan.bundledScript);
+	}
+
+	if (plan.bundledStylesheet && !insertedStylesheet) {
+		unifiedDependencies.push(plan.bundledStylesheet);
+	}
+
+	return unifiedDependencies;
+}
+
+/**
+ * Rewrites eligible flat dependency declarations into page-owned stylesheet and script bundles.
+ *
+ * Only assets with the default attribute shape and without explicit packaging roles are
+ * collapsed so integration-specific or lazy behavior keeps its existing ownership model.
+ */
+export function packagePageDependencies(dependencies: AssetDefinition[], integrationName: string): AssetDefinition[] {
+	if (!shouldBundlePageDependencies(integrationName)) {
+		return dependencies;
+	}
+
+	const plan = createPageDependencyPackagingPlan(dependencies, integrationName);
+	if (!plan) {
+		return dependencies;
+	}
+
+	return applyPageDependencyPackagingPlan(dependencies, plan);
+}

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

@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest';
+import { PageModuleLoaderService } from './page-module-loader.ts';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type { EcoPageFile } from '../../types/public-types.ts';
+import type { EcoPageComponent } from '../../eco/eco.types.ts';
+import type { AppModuleLoader } from '../../services/module-loading/app-module-loader.service.ts';
+
+describe('PageModuleLoaderService', () => {
+	const appConfig = {
+		rootDir: '/app',
+		defaultMetadata: {
+			title: 'Default title',
+			description: 'Default description',
+		},
+		runtime: {},
+	} 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',
+				description: 'module-description',
+			}),
+			extra: 'integration-value',
+		} satisfies EcoPageFile<{ extra: string }>;
+
+		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' },
+		});
+	});
+
+	it('should import page files through the app-owned module loader', async () => {
+		const calls: Array<unknown> = [];
+		const expectedModule = {
+			default: (() => 'ok') as EcoPageComponent<any>,
+		} as EcoPageFile;
+		const service = new PageModuleLoaderService(
+			{
+				...appConfig,
+				runtime: {
+					appModuleLoader: {
+						owner: 'bun',
+						async importModule<T = unknown>(options: unknown): Promise<T> {
+							calls.push(options);
+							return expectedModule as T;
+						},
+						invalidateDevelopmentGraph(): void {
+							return;
+						},
+					} satisfies AppModuleLoader,
+				},
+			} as EcoPagesAppConfig,
+			'http://localhost:3000',
+		);
+
+		const result = await service.importPageFile('/app/src/pages/index.tsx');
+
+		expect(result).toBe(expectedModule);
+		expect(calls).toEqual([
+			{
+				filePath: '/app/src/pages/index.tsx',
+				rootDir: '/app',
+				outdir: '/app/.eco/.server-modules',
+				bypassCache: undefined,
+				cacheScope: undefined,
+				transpileErrorMessage: expect.any(Function),
+				noOutputMessage: expect.any(Function),
+			},
+		]);
+	});
+
+	it('should forward cache scope options to the app-owned module loader', async () => {
+		const calls: Array<unknown> = [];
+		const expectedModule = {
+			default: (() => 'ok') as EcoPageComponent<any>,
+		} as EcoPageFile;
+		const service = new PageModuleLoaderService(
+			{
+				...appConfig,
+				runtime: {
+					appModuleLoader: {
+						owner: 'bun',
+						async importModule<T = unknown>(options: unknown): Promise<T> {
+							calls.push(options);
+							return expectedModule as T;
+						},
+						invalidateDevelopmentGraph(): void {
+							return;
+						},
+					} satisfies AppModuleLoader,
+				},
+			} as EcoPagesAppConfig,
+			'http://localhost:3000',
+		);
+
+		await service.importPageFile('/app/src/pages/index.tsx', {
+			cacheScope: 'request-metadata',
+		});
+
+		expect(calls).toEqual([
+			{
+				filePath: '/app/src/pages/index.tsx',
+				rootDir: '/app',
+				outdir: '/app/.eco/.server-modules',
+				bypassCache: undefined,
+				cacheScope: 'request-metadata',
+				transpileErrorMessage: expect.any(Function),
+				noOutputMessage: expect.any(Function),
+			},
+		]);
+	});
+});

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

@@ -0,0 +1,184 @@
+import { invariant } from '../../utils/invariant.ts';
+import type {
+	EcoPageFile,
+	GetMetadata,
+	GetMetadataContext,
+	GetStaticProps,
+	PageMetadataProps,
+	RouteRendererOptions,
+	EcoPageComponent,
+} from '../../types/public-types.ts';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import { getAppModuleLoader } from '../../services/module-loading/app-server-module-transpiler.service.ts';
+import type { AppModuleLoader } from '../../services/module-loading/app-module-loader.service.ts';
+import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.ts';
+
+/**
+ * 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 appModuleLoader: AppModuleLoader;
+	private appConfig: EcoPagesAppConfig;
+	private runtimeOrigin: string;
+
+	/**
+	 * 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.appModuleLoader = getAppModuleLoader(appConfig);
+	}
+
+	/**
+	 * 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, options?: { bypassCache?: boolean; cacheScope?: string }): Promise<EcoPageFile> {
+		try {
+			return await this.appModuleLoader.importModule<EcoPageFile>({
+				filePath: file,
+				rootDir: this.appConfig.rootDir,
+				outdir: `${resolveInternalExecutionDir(this.appConfig)}/.server-modules`,
+				bypassCache: options?.bypassCache,
+				cacheScope: options?.cacheScope,
+				transpileErrorMessage: (details) => `Error transpiling page file: ${details}`,
+				noOutputMessage: (targetFilePath) => `No transpiled output generated for page: ${targetFilePath}`,
+			});
+		} catch (error) {
+			invariant(false, `Error importing page file: ${error}`);
+		}
+	}
+
+	/**
+	 * 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>>;
+		params?: RouteRendererOptions['params'];
+	}): Promise<{
+		props: Record<string, unknown>;
+		metadata?: PageMetadataProps;
+	}> {
+		const { getStaticProps, params } = options;
+		return getStaticProps
+			? await getStaticProps({
+					pathname: { params: params ?? {} },
+					appConfig: this.appConfig,
+					runtimeOrigin: this.runtimeOrigin,
+				})
+					.then((data) => data)
+					.catch((err) => {
+						throw new Error(`Error fetching static props: ${err.message}`);
+					})
+			: {
+					props: {},
+					metadata: undefined,
+				};
+	}
+
+	/**
+	 * 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;
+		context: GetMetadataContext;
+	}): Promise<PageMetadataProps> {
+		const { getMetadata, context } = options;
+		let metadata: PageMetadataProps = this.appConfig.defaultMetadata;
+		if (getMetadata) {
+			const dynamicMetadata = await getMetadata({
+				params: context.params,
+				query: context.query,
+				props: context.props,
+				appConfig: this.appConfig,
+			});
+			metadata = { ...metadata, ...dynamicMetadata };
+		}
+		return metadata;
+	}
+
+	/**
+	 * Loads a page module and normalizes integration-facing exports.
+	 * When both component static methods and module exports exist, component statics win.
+	 */
+	async resolvePageModule(options: {
+		file: string;
+		importPageFileFn?: (file: string) => Promise<EcoPageFile>;
+	}): Promise<{
+		Page: EcoPageFile['default'] | EcoPageComponent<any>;
+		getStaticProps?: GetStaticProps<Record<string, unknown>>;
+		getMetadata?: GetMetadata;
+		integrationSpecificProps: Record<string, unknown>;
+	}> {
+		const module = await (options.importPageFileFn ?? ((file) => this.importPageFile(file)))(options.file);
+		const {
+			default: Page,
+			getStaticProps: moduleGetStaticProps,
+			getMetadata: moduleGetMetadata,
+			...integrationSpecificProps
+		} = module;
+
+		return {
+			Page,
+			getStaticProps: Page.staticProps ?? moduleGetStaticProps,
+			getMetadata: Page.metadata ?? moduleGetMetadata,
+			integrationSpecificProps,
+		};
+	}
+
+	/**
+	 * 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: {
+			getStaticProps?: GetStaticProps<Record<string, unknown>>;
+			getMetadata?: GetMetadata;
+		};
+		routeOptions: RouteRendererOptions;
+	}): Promise<{
+		props: Record<string, unknown>;
+		metadata: PageMetadataProps;
+	}> {
+		const { props } = await this.getStaticPropsForPage({
+			getStaticProps: options.pageModule.getStaticProps,
+			params: options.routeOptions.params,
+		});
+
+		const metadata = await this.getMetadataPropsForPage({
+			getMetadata: options.pageModule.getMetadata,
+			context: {
+				props,
+				params: options.routeOptions.params ?? {},
+				query: options.routeOptions.query ?? {},
+			} as GetMetadataContext,
+		});
+
+		return { props, metadata };
+	}
+}