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

package/src/services/invalidation/development-invalidation.service.ts

@@ -0,0 +1,262 @@
+import path from 'node:path';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import { getAppServerInvalidationState } from '../runtime-state/server-invalidation-state.service.ts';
+
+export type DevelopmentInvalidationCategory =
+	| 'public-asset'
+	| 'additional-watch'
+	| 'include-source'
+	| 'route-source'
+	| 'processor-owned-asset'
+	| 'server-source'
+	| 'other';
+
+/**
+ * Framework-owned invalidation plan for one changed file.
+ *
+ * @remarks
+ * This is the explicit invalidation matrix Workstream 4 needs. Watchers and
+ * runtime adapters consume this plan instead of encoding file-category rules in
+ * host-specific control flow.
+ */
+export interface DevelopmentInvalidationPlan {
+	category: DevelopmentInvalidationCategory;
+	invalidateServerModules: boolean;
+	refreshRoutes: boolean;
+	reloadBrowser: boolean;
+	delegateToHmr: boolean;
+	processorHandledAsset: boolean;
+}
+
+/**
+ * Framework-owned development invalidation service.
+ *
+ * @remarks
+ * This service centralizes two responsibilities:
+ * - file-change classification for watcher behavior
+ * - app-owned server-module invalidation versioning backed by the dev graph
+ *
+ * Hosts and watchers should ask this service what a file change means instead
+ * of deciding invalidation semantics inline.
+ */
+export class DevelopmentInvalidationService {
+	private readonly appConfig: EcoPagesAppConfig;
+
+	constructor(appConfig: EcoPagesAppConfig) {
+		this.appConfig = appConfig;
+	}
+
+	/**
+	 * Returns the current app-owned server-module invalidation version.
+	 */
+	getServerModuleInvalidationVersion(): number {
+		return getAppServerInvalidationState(this.appConfig).getServerInvalidationVersion();
+	}
+
+	/**
+	 * Invalidates the app-owned server-module graph.
+	 */
+	invalidateServerModules(changedFiles?: string[]): void {
+		getAppServerInvalidationState(this.appConfig).invalidateServerModules(changedFiles);
+		this.appConfig.runtime?.appModuleLoader?.invalidateDevelopmentGraph();
+	}
+
+	/**
+	 * Resets runtime-owned graph state and invalidates server modules.
+	 */
+	resetRuntimeState(changedFiles?: string[]): void {
+		const serverInvalidationState = getAppServerInvalidationState(this.appConfig);
+		serverInvalidationState.invalidateServerModules(changedFiles);
+		serverInvalidationState.reset();
+	}
+
+	/**
+	 * Classifies one changed file into an explicit framework invalidation plan.
+	 */
+	planFileChange(filePath: string): DevelopmentInvalidationPlan {
+		if (this.isPublicDirFile(filePath)) {
+			return {
+				category: 'public-asset',
+				invalidateServerModules: false,
+				refreshRoutes: false,
+				reloadBrowser: true,
+				delegateToHmr: false,
+				processorHandledAsset: false,
+			};
+		}
+
+		if (this.matchesAdditionalWatchPaths(filePath)) {
+			return {
+				category: 'additional-watch',
+				invalidateServerModules: false,
+				refreshRoutes: false,
+				reloadBrowser: true,
+				delegateToHmr: false,
+				processorHandledAsset: false,
+			};
+		}
+
+		if (this.isIncludeSourceFile(filePath)) {
+			return {
+				category: 'include-source',
+				invalidateServerModules: true,
+				refreshRoutes: false,
+				reloadBrowser: true,
+				delegateToHmr: false,
+				processorHandledAsset: false,
+			};
+		}
+
+		if (this.isRouteSourceFile(filePath)) {
+			return {
+				category: 'route-source',
+				invalidateServerModules: true,
+				refreshRoutes: true,
+				reloadBrowser: false,
+				delegateToHmr: true,
+				processorHandledAsset: false,
+			};
+		}
+
+		if (this.isProcessorOwnedAsset(filePath)) {
+			return {
+				category: 'processor-owned-asset',
+				invalidateServerModules: false,
+				refreshRoutes: false,
+				reloadBrowser: false,
+				delegateToHmr: false,
+				processorHandledAsset: true,
+			};
+		}
+
+		if (this.isServerModuleSourceFile(filePath)) {
+			return {
+				category: 'server-source',
+				invalidateServerModules: true,
+				refreshRoutes: false,
+				reloadBrowser: false,
+				delegateToHmr: true,
+				processorHandledAsset: false,
+			};
+		}
+
+		return {
+			category: 'other',
+			invalidateServerModules: false,
+			refreshRoutes: false,
+			reloadBrowser: false,
+			delegateToHmr: true,
+			processorHandledAsset: false,
+		};
+	}
+
+	/**
+	 * Returns whether the file lives under the public directory.
+	 */
+	isPublicDirFile(filePath: string): boolean {
+		return path.resolve(filePath).startsWith(this.appConfig.absolutePaths.publicDir);
+	}
+
+	/**
+	 * Returns whether the file matches `additionalWatchPaths`.
+	 */
+	matchesAdditionalWatchPaths(filePath: string): boolean {
+		const normalizedPath = path.resolve(filePath);
+		const patterns = this.appConfig.additionalWatchPaths;
+		if (!patterns.length) return false;
+
+		for (const pattern of patterns) {
+			if (pattern.includes('*')) {
+				const ext = pattern.replace(/\*\*?\/\*/, '');
+				if (normalizedPath.endsWith(ext)) return true;
+			} else if (normalizedPath.endsWith(pattern) || normalizedPath === path.resolve(pattern)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Returns whether the file is a route source file.
+	 */
+	isRouteSourceFile(filePath: string): boolean {
+		const resolvedPath = path.resolve(filePath);
+
+		if (!resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir)) {
+			return false;
+		}
+
+		if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+			return true;
+		}
+
+		return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+	}
+
+	/**
+	 * Returns whether the file is an include/template source file.
+	 */
+	isIncludeSourceFile(filePath: string): boolean {
+		const resolvedPath = path.resolve(filePath);
+
+		if (!resolvedPath.startsWith(this.appConfig.absolutePaths.includesDir)) {
+			return false;
+		}
+
+		if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+			return true;
+		}
+
+		return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+	}
+
+	/**
+	 * Returns whether the file is a server-executed source module outside the
+	 * special route/include buckets.
+	 */
+	isServerModuleSourceFile(filePath: string): boolean {
+		const resolvedPath = path.resolve(filePath);
+		if (!resolvedPath.startsWith(this.appConfig.absolutePaths.srcDir)) {
+			return false;
+		}
+
+		if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+			return true;
+		}
+
+		return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+	}
+
+	/**
+	 * Returns whether a processor owns the changed file as an asset input.
+	 */
+	isProcessorOwnedAsset(filePath: string): boolean {
+		for (const processor of this.appConfig.processors.values()) {
+			const capabilities = processor.getAssetCapabilities?.() ?? [];
+			if (capabilities.length > 0) {
+				const matchesConfiguredAsset =
+					typeof processor.matchesFileFilter !== 'function' || processor.matchesFileFilter(filePath);
+
+				if (
+					matchesConfiguredAsset &&
+					capabilities.some((capability) => processor.canProcessAsset?.(capability.kind, filePath))
+				) {
+					return true;
+				}
+
+				continue;
+			}
+
+			const watchConfig = processor.getWatchConfig();
+			if (!watchConfig) continue;
+
+			const { extensions = [] } = watchConfig;
+			if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+}

package/src/services/module-loading/app-module-loader.service.ts

@@ -0,0 +1,9 @@
+import type { PageModuleBuildImportOptions } from './page-module-import.service.ts';
+
+export type AppModuleLoaderOwner = 'app' | 'host';
+
+export interface AppModuleLoader {
+	readonly owner: AppModuleLoaderOwner;
+	importModule<T = unknown>(options: PageModuleBuildImportOptions): Promise<T>;
+	invalidateDevelopmentGraph(): void;
+}

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

@@ -0,0 +1,297 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, it } from 'vitest';
+import { type BuildExecutor, setAppBuildManifest } from '../../build/build-adapter.ts';
+import { RolldownBuildAdapter } from '../../build/rolldown-build-adapter.ts';
+import type { EcoPagesElement } from '../../types/public-types.ts';
+import {
+	createAppServerModuleTranspiler,
+	getAppHostModuleLoader,
+	getAppModuleLoader,
+	setAppHostModuleLoader,
+	shouldAppUseHostModuleLoader,
+} from './app-server-module-transpiler.service.ts';
+
+describe('app server module transpiler runtime state', () => {
+	it('stores and exposes an abstract host module loader on app runtime state', () => {
+		const appConfig = {
+			runtime: {},
+		} as any;
+		const hostModuleLoader = async (id: string) => ({ id });
+
+		setAppHostModuleLoader(appConfig, hostModuleLoader);
+
+		assert.equal(getAppHostModuleLoader(appConfig), hostModuleLoader);
+	});
+
+	it('exposes host ownership when a host module loader is configured', () => {
+		const hostModuleLoader = async (id: string) => ({ id });
+		const appConfig = {
+			rootDir: '/app',
+			runtime: {
+				hostModuleLoader,
+			},
+		} as any;
+
+		const moduleLoader = getAppModuleLoader(appConfig);
+
+		assert.equal(moduleLoader.owner, 'host');
+	});
+
+	it('creates a server transpiler that uses the app module loader', () => {
+		const hostModuleLoader = async (id: string) => ({ id });
+		const appConfig = {
+			rootDir: '/app',
+			runtime: {
+				hostModuleLoader,
+			},
+		} as any;
+
+		const transpiler = createAppServerModuleTranspiler(appConfig);
+
+		assert.ok(transpiler);
+		assert.equal(getAppHostModuleLoader(appConfig), hostModuleLoader);
+	});
+
+	it('keeps Ecopages integration modules on the framework transpiler path', () => {
+		const appConfig = {
+			absolutePaths: {
+				componentsDir: '/app/src/components',
+				includesDir: '/app/src/includes',
+				layoutsDir: '/app/src/layouts',
+				pagesDir: '/app/src/pages',
+			},
+			templatesExt: ['.kita.tsx', '.lit.tsx'],
+		} as any;
+
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/runtime/helpers.ts'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/index.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/includes/html.kita.tsx'), false);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/layouts/base-layout.kita.tsx'), false);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/counter.lit.tsx'), false);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/components/counter.lit.tsx'), false);
+	});
+
+	it('prefers the host module loader for framework-owned modules when a host runtime provides one', () => {
+		const appConfig = {
+			absolutePaths: {
+				componentsDir: '/app/src/components',
+				includesDir: '/app/src/includes',
+				layoutsDir: '/app/src/layouts',
+				pagesDir: '/app/src/pages',
+			},
+			runtime: {
+				hostModuleLoader: async (id: string) => ({ id }),
+			},
+			templatesExt: ['.kita.tsx', '.lit.tsx'],
+		} as any;
+
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/runtime/helpers.ts'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/index.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/includes/html.kita.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/layouts/base-layout.kita.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/counter.lit.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/components/counter.lit.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/docs.md'), false);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/react-content.mdx'), false);
+	});
+
+	it('compiles Bun-owned Kita modules to string render functions during app module imports', async () => {
+		(
+			globalThis as typeof globalThis & {
+				Bun?: { hash(content: string | Buffer<ArrayBufferLike>): number | bigint };
+			}
+		).Bun = {
+			hash: (content) => {
+				const value = String(content);
+				let hash = 0;
+
+				for (let index = 0; index < value.length; index += 1) {
+					hash = (hash * 31 + value.charCodeAt(index)) >>> 0;
+				}
+
+				return hash;
+			},
+		};
+		const tempParentDir = path.join(process.cwd(), 'playground', 'kitchen-sink');
+		const tempRootBase = path.join(tempParentDir, '.tmp-app-module-loader-');
+		fs.mkdirSync(tempParentDir, { recursive: true });
+		const rootDir = fs.mkdtempSync(tempRootBase);
+		const componentsDir = path.join(rootDir, 'src', 'components');
+		const pagesDir = path.join(rootDir, 'src', 'pages');
+		fs.mkdirSync(componentsDir, { recursive: true });
+		fs.mkdirSync(pagesDir, { recursive: true });
+
+		const kitaComponentPath = path.join(componentsDir, 'kita-child.kita.tsx');
+		fs.writeFileSync(
+			kitaComponentPath,
+			[
+				"import { eco } from '@ecopages/core';",
+				"import type { EcoPagesElement } from '@ecopages/core';",
+				'',
+				'export const KitaChild = eco.component<{}, EcoPagesElement>({',
+				"\tintegration: 'kitajs',",
+				'\trender: () => <div data-kita-child="true">Leaf</div>,',
+				'});',
+				'',
+			].join('\n'),
+			'utf8',
+		);
+
+		const appConfig = {
+			rootDir,
+			absolutePaths: {
+				srcDir: path.join(rootDir, 'src'),
+				componentsDir,
+				includesDir: path.join(rootDir, 'src', 'includes'),
+				layoutsDir: path.join(rootDir, 'src', 'layouts'),
+				pagesDir,
+			},
+			integrations: [
+				{
+					name: 'ecopages-jsx',
+					extensions: ['.eco.tsx'],
+					jsxImportSource: '@ecopages/jsx',
+				},
+				{
+					name: 'kitajs',
+					extensions: ['.kita.tsx'],
+					jsxImportSource: '@kitajs/html',
+				},
+			],
+			templatesExt: ['.eco.tsx', '.kita.tsx'],
+			runtime: {},
+		} as any;
+
+		const moduleLoader = getAppModuleLoader(appConfig);
+
+		try {
+			const imported = await moduleLoader.importModule<{
+				KitaChild: (() => EcoPagesElement) & { config?: Record<string, unknown> };
+			}>({
+				filePath: kitaComponentPath,
+				rootDir,
+				outdir: path.join(rootDir, '.eco', '.server-modules'),
+				buildExecutor: new RolldownBuildAdapter(),
+			});
+
+			const rendered = imported.KitaChild();
+			assert.equal(typeof rendered, 'string');
+			assert.match(String(rendered), /data-kita-child/);
+		} finally {
+			delete (globalThis as typeof globalThis & { Bun?: unknown }).Bun;
+			fs.rmSync(rootDir, { recursive: true, force: true });
+		}
+	});
+
+	it('preserves top-level await through the Node app-module loader path', async () => {
+		const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'ecopages-node-app-module-tla-'));
+		const pagesDir = path.join(rootDir, 'src', 'pages');
+		fs.mkdirSync(pagesDir, { recursive: true });
+		fs.writeFileSync(
+			path.join(rootDir, 'package.json'),
+			JSON.stringify({ name: 'test-app', type: 'module' }),
+			'utf8',
+		);
+		const pageFilePath = path.join(pagesDir, 'index.ts');
+		fs.writeFileSync(
+			pageFilePath,
+			['export const value = await Promise.resolve(42);', 'export default { ok: value === 42 };'].join('\n'),
+			'utf8',
+		);
+
+		const appConfig = {
+			rootDir,
+			absolutePaths: {
+				srcDir: path.join(rootDir, 'src'),
+				componentsDir: path.join(rootDir, 'src', 'components'),
+				includesDir: path.join(rootDir, 'src', 'includes'),
+				layoutsDir: path.join(rootDir, 'src', 'layouts'),
+				pagesDir,
+			},
+			integrations: [],
+			templatesExt: ['.ts'],
+			runtime: {},
+		} as any;
+
+		try {
+			const imported = await getAppModuleLoader(appConfig).importModule<{
+				default: { ok: boolean };
+				value: number;
+			}>({
+				filePath: pageFilePath,
+				rootDir,
+				outdir: path.join(rootDir, '.eco', '.server-modules'),
+				buildExecutor: new RolldownBuildAdapter(),
+			});
+
+			assert.deepEqual(imported.default, { ok: true });
+			assert.equal(imported.value, 42);
+		} finally {
+			fs.rmSync(rootDir, { recursive: true, force: true });
+		}
+	});
+
+	it('includes manifest runtime plugins in app module imports', async () => {
+		const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'ecopages-app-module-runtime-plugins-'));
+		const pagesDir = path.join(rootDir, 'src', 'pages');
+		fs.mkdirSync(pagesDir, { recursive: true });
+		const pageFilePath = path.join(pagesDir, 'index.tsx');
+		fs.writeFileSync(pageFilePath, 'export default { ok: true };', 'utf8');
+
+		const observedPlugins: string[][] = [];
+		const buildExecutor: BuildExecutor = {
+			build: async (options: { outdir?: string; naming?: string; plugins?: Array<{ name: string }> }) => {
+				observedPlugins.push((options.plugins ?? []).map((plugin) => plugin.name));
+				const naming = String(options.naming ?? 'index.[ext]');
+				const compiledOutputPath = path.join(String(options.outdir), naming.replace('[ext]', 'mjs'));
+
+				fs.mkdirSync(path.dirname(compiledOutputPath), { recursive: true });
+				fs.writeFileSync(compiledOutputPath, 'export default { ok: true };', 'utf8');
+
+				return {
+					success: true,
+					logs: [],
+					outputs: [{ path: compiledOutputPath }],
+				};
+			},
+		};
+
+		const appConfig = {
+			rootDir,
+			absolutePaths: {
+				srcDir: path.join(rootDir, 'src'),
+				componentsDir: path.join(rootDir, 'src', 'components'),
+				includesDir: path.join(rootDir, 'src', 'includes'),
+				layoutsDir: path.join(rootDir, 'src', 'layouts'),
+				pagesDir,
+			},
+			integrations: [],
+			loaders: new Map(),
+			templatesExt: ['.tsx'],
+			runtime: {},
+		} as any;
+
+		setAppBuildManifest(appConfig, {
+			loaderPlugins: [],
+			runtimePlugins: [{ name: 'react-mdx-loader', setup() {} }],
+			browserBundlePlugins: [],
+			browserRuntimeManifest: { assets: [], bySpecifier: new Map() },
+		});
+
+		try {
+			await getAppModuleLoader(appConfig).importModule({
+				filePath: pageFilePath,
+				rootDir,
+				outdir: path.join(rootDir, '.eco', '.server-modules'),
+				buildExecutor,
+			});
+
+			assert.deepEqual(observedPlugins, [['react-mdx-loader']]);
+		} finally {
+			fs.rmSync(rootDir, { recursive: true, force: true });
+		}
+	});
+});