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

package/src/static-site-generator/static-site-generator.ts

@@ -1,11 +1,14 @@
 import path from 'node:path';
+import { DEFAULT_ECOPAGES_WORK_DIR } from '../constants.ts';
 import { appLogger } from '../global/app-logger.ts';
 import type { EcoPagesAppConfig } from '../internal-types.ts';
 import type { EcoPageComponent, StaticRoute } from '../public-types.ts';
 import type { RouteRendererFactory } from '../route-renderer/route-renderer.ts';
-import type { FSRouter } from '../router/fs-router.ts';
+import type { FSRouter } from '../router/server/fs-router.js';
 import { fileSystem } from '@ecopages/file-system';
 import { PathUtils } from '../utils/path-utils.module.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';
 
 export const STATIC_SITE_GENERATOR_ERRORS = {
 	ROUTE_RENDERER_FACTORY_REQUIRED: 'RouteRendererFactory is required for render strategy',
@@ -17,13 +20,89 @@ export const STATIC_SITE_GENERATOR_ERRORS = {
 		`Dynamic route ${routePath} requires staticPaths to be defined on the view.`,
 } as const;
 
+/**
+ * Generates static output files from the finalized app config and route graph.
+ *
+ * @remarks
+ * This class intentionally reuses the same routing, renderer, and server-module
+ * loading seams used by runtime rendering. Static generation should be a build
+ * loop over the normal app model, not a parallel rendering stack with different
+ * semantics.
+ */
 export class StaticSiteGenerator {
 	appConfig: EcoPagesAppConfig;
+	private serverModuleTranspiler: ServerModuleTranspiler;
 
+	/**
+	 * Creates the static-site generator for one app config.
+	 */
 	constructor({ appConfig }: { appConfig: EcoPagesAppConfig }) {
 		this.appConfig = appConfig;
+		this.serverModuleTranspiler = getAppServerModuleTranspiler(appConfig);
+	}
+
+	/**
+	 * Returns the transpiler output directory used for static page-module probes.
+	 */
+	private getStaticPageModuleOutdir(): string {
+		const workDir =
+			this.appConfig.absolutePaths?.workDir ??
+			path.join(this.appConfig.rootDir, this.appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
+		return path.join(workDir, '.server-static-page-modules');
+	}
+
+	private getExportDir(): string {
+		return this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
+	}
+
+	/**
+	 * Logs the standardized warning emitted when a dynamic-cache page is skipped.
+	 */
+	private warnDynamicPageSkipped(filePath: string): void {
+		appLogger.warn(
+			"Pages with cache: 'dynamic' are not supported in static generation or preview, so they will be skipped\n",
+			`➤ ${filePath}`,
+		);
+	}
+
+	/**
+	 * Determines whether one filesystem-discovered page should be excluded from
+	 * static generation.
+	 */
+	private async shouldSkipStaticPageFile(filePath: string): Promise<boolean> {
+		const module = (await this.serverModuleTranspiler.importModule({
+			filePath,
+			outdir: this.getStaticPageModuleOutdir(),
+			externalPackages: false,
+			transpileErrorMessage: (details) => `Error transpiling static page module: ${details}`,
+			noOutputMessage: (targetFilePath) =>
+				`No transpiled output generated for static page module: ${targetFilePath}`,
+		})) as { default?: EcoPageComponent<any> };
+
+		if (module.default?.cache !== 'dynamic') {
+			return false;
+		}
+
+		this.warnDynamicPageSkipped(filePath);
+		return true;
 	}
 
+	/**
+	 * Determines whether one explicit static route view should be excluded from
+	 * static generation.
+	 */
+	private shouldSkipStaticView(routePath: string, view: EcoPageComponent<any>): boolean {
+		if (view.cache !== 'dynamic') {
+			return false;
+		}
+
+		this.warnDynamicPageSkipped(routePath);
+		return true;
+	}
+
+	/**
+	 * Writes the robots.txt file declared by the app config.
+	 */
 	generateRobotsTxt(): void {
 		let data = '';
 		const preferences = this.appConfig.robotsTxt.preferences;
@@ -36,15 +115,21 @@ export class StaticSiteGenerator {
 			data += '\n';
 		}
 
-		fileSystem.ensureDir(this.appConfig.distDir);
-		fileSystem.write(`${this.appConfig.distDir}/robots.txt`, data);
+		fileSystem.ensureDir(this.getExportDir());
+		fileSystem.write(path.join(this.getExportDir(), 'robots.txt'), data);
 	}
 
+	/**
+	 * Returns whether the input path points at the root directory.
+	 */
 	isRootDir(path: string) {
 		const slashes = path.match(/\//g);
 		return slashes && slashes.length === 1;
 	}
 
+	/**
+	 * Collects parent directories that must exist for the generated route set.
+	 */
 	getDirectories(routes: string[]) {
 		const directories = new Set<string>();
 
@@ -84,6 +169,14 @@ export class StaticSiteGenerator {
 		return params;
 	}
 
+	/**
+	 * Generates static output for all filesystem-discovered routes.
+	 *
+	 * @remarks
+	 * Routes whose integrations opt into fetch-based static builds are rendered by
+	 * issuing a request against the running server origin. Render-strategy routes
+	 * go through the normal route renderer directly.
+	 */
 	async generateStaticPages(router: FSRouter, baseUrl: string, routeRendererFactory?: RouteRendererFactory) {
 		const routes = Object.keys(router.routes).filter((route) => !route.includes('['));
 
@@ -92,12 +185,16 @@ export class StaticSiteGenerator {
 		const directories = this.getDirectories(routes);
 
 		for (const directory of directories) {
-			fileSystem.ensureDir(path.join(this.appConfig.rootDir, this.appConfig.distDir, directory));
+			fileSystem.ensureDir(path.join(this.getExportDir(), directory));
 		}
 
 		for (const route of routes) {
 			try {
 				const { filePath, pathname: routePathname } = router.routes[route];
+				if (await this.shouldSkipStaticPageFile(filePath)) {
+					continue;
+				}
+
 				const ext = PathUtils.getEcoTemplateExtension(filePath);
 				const integration = this.appConfig.integrations.find((plugin) => plugin.extensions.includes(ext));
 				const strategy = integration?.staticBuildStep || 'render';
@@ -163,7 +260,7 @@ export class StaticSiteGenerator {
 					pathname += '.html';
 				}
 
-				const outputPath = path.join(this.appConfig.rootDir, this.appConfig.distDir, pathname);
+				const outputPath = path.join(this.getExportDir(), pathname);
 				fileSystem.write(outputPath, contents);
 			} catch (error) {
 				appLogger.error(
@@ -174,6 +271,9 @@ export class StaticSiteGenerator {
 		}
 	}
 
+	/**
+	 * Executes the full static-generation workflow for one app run.
+	 */
 	async run({
 		router,
 		baseUrl,
@@ -210,6 +310,9 @@ export class StaticSiteGenerator {
 			try {
 				const mod = await route.loader();
 				const view = mod.default;
+				if (this.shouldSkipStaticView(route.path, view)) {
+					continue;
+				}
 
 				const isDynamic = route.path.includes(':') || route.path.includes('[');
 
@@ -347,7 +450,7 @@ export class StaticSiteGenerator {
 			outputName = `${routePath}.html`;
 		}
 
-		return path.join(this.appConfig.rootDir, this.appConfig.distDir, outputName);
+		return path.join(this.getExportDir(), outputName);
 	}
 }
 

package/src/utils/deep-merge.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import { deepMerge } from './deep-merge.ts';
+
+describe('deepMerge', () => {
+	it('should merge two objects with nested properties', () => {
+		const target = { a: 1, b: { c: 2 } };
+		const source = { b: { d: 3 }, e: 4 };
+		const expected = { a: 1, b: { c: 2, d: 3 }, e: 4 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should merge two objects with overlapping properties', () => {
+		const target = { a: 1, b: 2 };
+		const source = { b: 3, c: 4 };
+		const expected = { a: 1, b: 3, c: 4 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should merge two objects with arrays', () => {
+		const target = { a: [1, 2], b: { c: [3, 4] } };
+		const source = { a: [5, 6], b: { c: [7, 8] } };
+		const expected = { a: [1, 2, 5, 6], b: { c: [3, 4, 7, 8] } };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should merge two objects with nested objects', () => {
+		const target = { a: { b: 1, c: 2 }, d: 3 };
+		const source = { a: { c: 3, d: 4 }, e: 5 };
+		const expected = { a: { b: 1, c: 3, d: 4 }, d: 3, e: 5 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should overwrite non-object properties in the target', () => {
+		const target = { a: 1, b: 2 };
+		const source = { a: 3, c: 4 };
+		const expected = { a: 3, b: 2, c: 4 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should add properties from the source that are not in the target', () => {
+		const target = { a: 1 };
+		const source = { b: 2 };
+		const expected = { a: 1, b: 2 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should return an empty object when both inputs are empty', () => {
+		const target = {};
+		const source = {};
+		const expected = {};
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should ignore properties in the source that are undefined', () => {
+		const target = { a: 1, b: 2 };
+		const source = { a: undefined, c: 3 } as Partial<typeof target>;
+		const expected = { a: 1, b: 2, c: 3 };
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+
+	it('should merge dependencies', () => {
+		const depsA = {
+			stylesheets: ['/components/radiant-counter/radiant-counter.css'],
+			scripts: ['/components/radiant-counter/radiant-counter.script.ts'],
+		};
+
+		const depsB = {
+			stylesheets: [
+				'/layouts/docs-layout/docs-layout.css',
+				'/layouts/base-layout/base-layout.css',
+				'/components/header/header.css',
+				'/components/navigation/navigation.css',
+				'/components/logo/logo.css',
+				'/components/code-block/code-block.css',
+			],
+			scripts: ['/layouts/base-layout/base-layout.script.ts'],
+		};
+
+		const expected = {
+			stylesheets: [
+				'/components/radiant-counter/radiant-counter.css',
+				'/layouts/docs-layout/docs-layout.css',
+				'/layouts/base-layout/base-layout.css',
+				'/components/header/header.css',
+				'/components/navigation/navigation.css',
+				'/components/logo/logo.css',
+				'/components/code-block/code-block.css',
+			],
+			scripts: [
+				'/components/radiant-counter/radiant-counter.script.ts',
+				'/layouts/base-layout/base-layout.script.ts',
+			],
+		};
+
+		const result = deepMerge(depsA, depsB);
+		expect(result).toEqual(expected);
+	});
+
+	it('should merge two arrays', () => {
+		const target = [1, 2, 3];
+		const source = [4, 5, 6];
+		const expected = [1, 2, 3, 4, 5, 6];
+		const result = deepMerge(target, source);
+		expect(result).toEqual(expected);
+	});
+});

package/src/utils/invariant.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from 'vitest';
+import { invariant } from './invariant.ts';
+
+describe('invariant', () => {
+	test('should not throw an error when the condition is true', () => {
+		expect(() => {
+			invariant(true);
+		}).not.toThrow();
+	});
+
+	test('should throw an error with the default message when the condition is false', () => {
+		expect(() => {
+			invariant(false);
+		}).toThrowError('[ecopages] An error occurred');
+	});
+
+	test('should throw an error with the provided message when the condition is false', () => {
+		expect(() => {
+			invariant(false, 'Custom error message');
+		}).toThrowError('[ecopages] Custom error message');
+	});
+});

package/src/utils/path-utils.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from 'vitest';
+import { PathUtils } from './path-utils.module.ts';
+
+describe('PathUtils', () => {
+	test.each([
+		['packages/core/src/utils/file-name-analyzer.ts', '.ts'],
+		['packages/playground/src/pages/blog/author/%5Bid%5D.kita.tsx', '.kita.tsx'],
+		['packages/core/src/component-utils/deps-manager.ts', '.ts'],
+		['/packages/core/src/plugins/build-html-pages/build-html-pages.plugin.ts', '.plugin.ts'],
+		['packages/core/src/ecopages.fake.descriptor.ts', '.descriptor.ts'],
+	])('getEcoTemplateExtension: %p should return %p', (filePath, expected) => {
+		const result = PathUtils.getEcoTemplateExtension(filePath);
+		expect(result).toBe(expected);
+	});
+});

package/src/utils/resolve-work-dir.ts

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { DEFAULT_ECOPAGES_WORK_DIR } from '../constants.ts';
+
+type InternalPathConfig = {
+	rootDir?: string;
+	workDir?: string;
+	absolutePaths?: {
+		workDir?: string;
+		distDir?: string;
+	};
+};
+
+function isInsideNodeModules(directory: string): boolean {
+	return path.normalize(directory).split(path.sep).includes('node_modules');
+}
+
+export function resolveInternalWorkDir(appConfig: InternalPathConfig): string {
+	if (appConfig.absolutePaths?.workDir) {
+		return appConfig.absolutePaths.workDir;
+	}
+
+	if (appConfig.rootDir) {
+		return path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
+	}
+
+	if (appConfig.workDir) {
+		return appConfig.workDir;
+	}
+
+	return DEFAULT_ECOPAGES_WORK_DIR;
+}
+
+export function resolveInternalExecutionDir(appConfig: InternalPathConfig): string {
+	const workDir = resolveInternalWorkDir(appConfig);
+
+	if (!isInsideNodeModules(workDir)) {
+		return workDir;
+	}
+
+	if (appConfig.rootDir) {
+		return path.join(appConfig.rootDir, DEFAULT_ECOPAGES_WORK_DIR);
+	}
+
+	return DEFAULT_ECOPAGES_WORK_DIR;
+}

package/src/utils/server-utils.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'vitest';
+import { FIXTURE_APP_PROJECT_DIR } from '../../__fixtures__/constants.js';
+import { ConfigBuilder } from '../config/config-builder.ts';
+import { ServerUtils } from './server-utils.module.ts';
+
+await new ConfigBuilder().setRootDir(FIXTURE_APP_PROJECT_DIR).build();
+
+describe('ServerUtils', () => {
+	test.each([
+		['/my-file.controller.js', 'text/javascript'],
+		['/my-file.css', 'text/css'],
+		['/my-file.html', 'text/html'],
+		['/my-file.json', 'application/json'],
+		['/my-file.png', 'image/png'],
+		['/my-file.jpg', 'image/jpeg'],
+		['/my-file.jpeg', 'image/jpeg'],
+		['/my-file.svg', 'image/svg+xml'],
+		['/my-file.gif', 'image/gif'],
+		['/my-file.ico', 'image/x-icon'],
+		['/my-file', 'text/plain'],
+	])('getContentType(%p) should return %p', (filePath, expected) => {
+		expect(ServerUtils.getContentType(filePath)).toBe(expected);
+	});
+
+	test.each([
+		['/file.css', true],
+		['/file.js', true],
+		['/file.html', true],
+		['/file.txt', true],
+		['/file.png', true],
+		['/page', false],
+		['/page.', false],
+		['/page.xyz', false],
+		['/page.dd', false],
+	])('hasKnownExtension(%p) should return %p', (filePath, expected) => {
+		expect(ServerUtils.hasKnownExtension(filePath)).toBe(expected);
+	});
+});