npm - @ecopages/core - Versions diffs - 0.2.0-alpha.5 → 0.2.0-alpha.7 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (418) hide show

package/src/services/html/html-transformer.service.ts ADDED Viewed

@@ -0,0 +1,279 @@
+import type { AssetPosition, ProcessedAsset, ScriptAsset } from '../assets/asset-processing-service/assets.types';
+import {
+	DefaultHtmlRewriterProvider,
+	type HtmlRewriterElement,
+	type HtmlRewriterMode,
+	type HtmlRewriterProvider,
+} from './html-rewriter-provider.service';
+export interface HtmlTransformerServiceOptions {
+	htmlRewriterMode?: HtmlRewriterMode;
+	htmlRewriterProvider?: HtmlRewriterProvider;
+}
+export class HtmlTransformerService {
+	private processedDependencies: ProcessedAsset[] = [];
+	private htmlRewriterProvider: HtmlRewriterProvider;
+	constructor(options: HtmlTransformerServiceOptions = {}) {
+		this.htmlRewriterProvider = options.htmlRewriterProvider ?? new DefaultHtmlRewriterProvider();
+		if (options.htmlRewriterMode) {
+			this.htmlRewriterProvider.setMode(options.htmlRewriterMode);
+		}
+	}
+	/**
+	 * Overrides the HTML rewriter runtime selection.
+	 *
+	 * This is intended for internal/runtime tests that need deterministic
+	 * selection between native, worker-tools, and string fallback behavior.
+	 *
+	 * @param mode Requested runtime selection strategy.
+	 */
+	setHtmlRewriterMode(mode: HtmlRewriterMode) {
+		this.htmlRewriterProvider.setMode(mode);
+	}
+	private formatAttributes(attrs?: Record<string, string>): string {
+		if (!attrs) return '';
+		return ` ${Object.entries(attrs)
+			.map(([key, value]) => `${key}="${value}"`)
+			.join(' ')}`;
+	}
+	private generateScriptTag(dep: ProcessedAsset & { kind: 'script' }): string {
+		return dep.inline
+			? `<script${this.formatAttributes(dep.attributes)}>${dep.content}</script>`
+			: `<script src="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}></script>`;
+	}
+	private generateStylesheetTag(dep: ProcessedAsset): string {
+		return dep.inline
+			? `<style${this.formatAttributes(dep.attributes)}>${dep.content}</style>`
+			: `<link rel="stylesheet" href="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}>`;
+	}
+	private appendDependencies(element: HtmlRewriterElement, dependencies: ProcessedAsset[]) {
+		for (const dep of dependencies) {
+			const tag =
+				dep.kind === 'script' ? this.generateScriptTag(dep as ScriptAsset) : this.generateStylesheetTag(dep);
+			element.append(tag, { html: true });
+		}
+	}
+	private buildDependencyTags(dependencies: ProcessedAsset[]): string {
+		return dependencies
+			.map((dep) =>
+				dep.kind === 'script' ? this.generateScriptTag(dep as ScriptAsset) : this.generateStylesheetTag(dep),
+			)
+			.join('');
+	}
+	/**
+	 * Injects generated markup immediately before the closing HTML tag when it is
+	 * present, or appends/prepends a fallback insertion otherwise.
+	 */
+	private injectBeforeClosingTag(html: string, tag: 'head' | 'body', content: string): string {
+		if (!content) {
+			return html;
+		}
+		const closingTag = `</${tag}>`;
+		const lowerHtml = html.toLowerCase();
+		const closingTagIndex = lowerHtml.lastIndexOf(closingTag);
+		if (closingTagIndex !== -1) {
+			return `${html.slice(0, closingTagIndex)}${content}${html.slice(closingTagIndex)}`;
+		}
+		if (tag === 'head') {
+			return `${content}${html}`;
+		}
+		return `${html}${content}`;
+	}
+	/**
+	 * Replaces the current processed dependency set used during HTML finalization.
+	 */
+	setProcessedDependencies(processedDependencies: ProcessedAsset[]) {
+		this.processedDependencies = processedDependencies;
+	}
+	/**
+	 * Returns the processed dependencies queued for the next transform pass.
+	 */
+	getProcessedDependencies(): ProcessedAsset[] {
+		return this.processedDependencies;
+	}
+	/**
+	 * Applies attributes to the opening `<html>` tag when present.
+	 */
+	applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string {
+		const htmlTagMatch = html.match(/<html\b[^>]*>/i);
+		if (!htmlTagMatch || htmlTagMatch.index === undefined) {
+			return html;
+		}
+		const attrs = this.buildAttributeString(attributes);
+		if (attrs.length === 0) {
+			return html;
+		}
+		const injectionOffset = htmlTagMatch.index + htmlTagMatch[0].length - 1;
+		return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+	}
+	/**
+	 * Applies attributes to the first element nested directly under `<body>`.
+	 */
+	applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string {
+		const bodyMatch = html.match(/<body\b[^>]*>/i);
+		if (!bodyMatch || bodyMatch.index === undefined) {
+			return html;
+		}
+		const bodyOpenEnd = bodyMatch.index + bodyMatch[0].length;
+		const afterBody = html.slice(bodyOpenEnd);
+		const firstTagMatch = afterBody.match(/^(\s*<)([a-zA-Z][a-zA-Z0-9:-]*)(\b[^>]*>)/);
+		if (!firstTagMatch || firstTagMatch.index === undefined) {
+			return html;
+		}
+		const attrs = this.buildAttributeString(attributes);
+		if (attrs.length === 0) {
+			return html;
+		}
+		const injectionOffset = bodyOpenEnd + firstTagMatch[1].length + firstTagMatch[2].length;
+		return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+	}
+	/**
+	 * Applies attributes to the first element in a fragment or full-document HTML
+	 * string.
+	 */
+	applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string {
+		const firstTagMatch = html.match(/^(\s*<)([a-zA-Z][a-zA-Z0-9:-]*)(\b[^>]*>)/);
+		if (!firstTagMatch || firstTagMatch.index === undefined) {
+			return html;
+		}
+		const attrs = this.buildAttributeString(attributes);
+		if (attrs.length === 0) {
+			return html;
+		}
+		const injectionOffset = firstTagMatch[1].length + firstTagMatch[2].length;
+		return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+	}
+	/**
+	 * Removes duplicate processed assets while preserving first-seen order.
+	 *
+	 * @remarks
+	 * Dedupe keys include structural asset fields and HTML attributes so repeated
+	 * orchestration passes can merge assets safely without collapsing distinct tag
+	 * variants.
+	 */
+	dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[] {
+		const unique = new Map<string, ProcessedAsset>();
+		for (const asset of assets) {
+			const key = [
+				asset.kind,
+				asset.position ?? '',
+				asset.srcUrl ?? '',
+				asset.filepath ?? '',
+				asset.content ?? '',
+				asset.inline ? 'inline' : 'external',
+				asset.excludeFromHtml ? 'excluded' : 'included',
+				JSON.stringify(asset.attributes ?? {}),
+			].join('|');
+			if (!unique.has(key)) {
+				unique.set(key, asset);
+			}
+		}
+		return [...unique.values()];
+	}
+	/**
+	 * Injects the currently processed dependencies into an HTML response.
+	 *
+	 * @remarks
+	 * Native or worker-tools HTML rewriter support is preferred when available. A
+	 * string-based fallback remains in place for runtimes that cannot provide one
+	 * of those rewriter implementations.
+	 */
+	async transform(res: Response): Promise<Response> {
+		const { head, body } = this.groupDependenciesByPosition();
+		const htmlRewriter = await this.htmlRewriterProvider.createHtmlRewriter();
+		const html = await res.text();
+		const headers = new Headers(res.headers);
+		if (htmlRewriter) {
+			htmlRewriter
+				.on('head', {
+					element: (element) => this.appendDependencies(element, head),
+				})
+				.on('body', {
+					element: (element) => this.appendDependencies(element, body),
+				});
+			return htmlRewriter.transform(
+				new Response(html, {
+					headers,
+					status: res.status,
+					statusText: res.statusText,
+				}),
+			);
+		}
+		const withHeadDependencies = this.injectBeforeClosingTag(html, 'head', this.buildDependencyTags(head));
+		const transformedHtml = this.injectBeforeClosingTag(
+			withHeadDependencies,
+			'body',
+			this.buildDependencyTags(body),
+		);
+		return new Response(transformedHtml, {
+			headers,
+			status: res.status,
+			statusText: res.statusText,
+		});
+	}
+	/**
+	 * Splits processed assets into head and body injection groups.
+	 */
+	private groupDependenciesByPosition() {
+		return this.processedDependencies.reduce(
+			(acc, dep) => {
+				if (dep.kind === 'script') {
+					if (dep.excludeFromHtml) return acc;
+					const position = dep.position || 'body';
+					acc[position].push(dep);
+				} else if (dep.kind === 'stylesheet') {
+					acc.head.push(dep);
+				}
+				return acc;
+			},
+			{ head: [], body: [] } as Record<AssetPosition, ProcessedAsset[]>,
+		);
+	}
+	/**
+	 * Builds a serialized HTML attribute string from an attribute object.
+	 */
+	private buildAttributeString(attributes: Record<string, string>): string {
+		return Object.entries(attributes)
+			.filter(([key, value]) => key.length > 0 && value.length > 0)
+			.map(([key, value]) => ` ${key}="${value}"`)
+			.join('');
+	}
+}

package/src/services/invalidation/development-invalidation.service.test.ts ADDED Viewed

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import { ConfigBuilder } from '../../config/config-builder.js';
+import { Processor } from '../../plugins/processor.js';
+import { DevelopmentInvalidationService } from './development-invalidation.service.ts';
+import { InMemoryDevGraphService, setAppDevGraphService } from '../runtime-state/dev-graph.service.ts';
+class StylesheetProcessor extends Processor {
+	buildPlugins = [];
+	plugins = [];
+	constructor() {
+		super({
+			name: 'css',
+			watch: {
+				paths: ['/test/project/src'],
+				extensions: ['.css'],
+			},
+			capabilities: [{ kind: 'stylesheet', extensions: ['*.css'] }],
+		});
+	}
+	async setup(): Promise<void> {}
+	async teardown(): Promise<void> {}
+	async process<T>(input: T): Promise<T> {
+		return input;
+	}
+}
+describe('DevelopmentInvalidationService', () => {
+	it('classifies route, include, processor-owned, and additional-watch changes explicitly', async () => {
+		const appConfig = await new ConfigBuilder().setRootDir('/test/project').build();
+		appConfig.additionalWatchPaths = ['**/*.config.ts'];
+		appConfig.processors.set('css', new StylesheetProcessor());
+		const service = new DevelopmentInvalidationService(appConfig);
+		expect(service.planFileChange('/test/project/src/pages/index.tsx')).toMatchObject({
+			category: 'route-source',
+			invalidateServerModules: true,
+			refreshRoutes: true,
+			delegateToHmr: true,
+		});
+		expect(service.planFileChange('/test/project/src/includes/seo.kita.tsx')).toMatchObject({
+			category: 'include-source',
+			invalidateServerModules: true,
+			reloadBrowser: true,
+			delegateToHmr: false,
+		});
+		expect(service.planFileChange('/test/project/src/styles/main.css')).toMatchObject({
+			category: 'processor-owned-asset',
+			invalidateServerModules: false,
+			processorHandledAsset: true,
+		});
+		expect(service.planFileChange('/test/project/tailwind.config.ts')).toMatchObject({
+			category: 'additional-watch',
+			reloadBrowser: true,
+			invalidateServerModules: false,
+		});
+	});
+	it('delegates server invalidation versioning to the app-owned dev graph service', async () => {
+		const appConfig = await new ConfigBuilder().setRootDir('/test/project').build();
+		const devGraphService = new InMemoryDevGraphService();
+		setAppDevGraphService(appConfig, devGraphService);
+		const service = new DevelopmentInvalidationService(appConfig);
+		expect(service.getServerModuleInvalidationVersion()).toBe(0);
+		service.invalidateServerModules(['/test/project/src/components/Button.tsx']);
+		expect(service.getServerModuleInvalidationVersion()).toBe(1);
+		service.resetRuntimeState(['/test/project/src/pages/index.tsx']);
+		expect(service.getServerModuleInvalidationVersion()).toBe(3);
+	});
+});

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

@@ -0,0 +1,261 @@
+import path from 'node:path';
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+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);
+	}
+	/**
+	 * 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-server-module-transpiler.service.ts ADDED Viewed

@@ -0,0 +1,52 @@
+import { getAppBuildExecutor } from '../../build/build-adapter.js';
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+import { createAppNodeBootstrapPlugin } from '../../adapters/node/bootstrap-dependency-resolver.ts';
+import { DevelopmentInvalidationService } from '../invalidation/development-invalidation.service.ts';
+import { ServerModuleTranspiler } from './server-module-transpiler.service.ts';
+/**
+ * Creates the shared app-scoped server-module transpiler for one runtime
+ * instance.
+ */
+export function createAppServerModuleTranspiler(appConfig: EcoPagesAppConfig): ServerModuleTranspiler {
+	const invalidationService = new DevelopmentInvalidationService(appConfig);
+	return new ServerModuleTranspiler({
+		rootDir: appConfig.rootDir,
+		getBuildExecutor: () => getAppBuildExecutor(appConfig),
+		getInvalidationVersion: () => invalidationService.getServerModuleInvalidationVersion(),
+		invalidateModules: (changedFiles) => invalidationService.invalidateServerModules(changedFiles),
+		getDefaultPlugins:
+			typeof Bun === 'undefined' && appConfig.rootDir
+				? () => [createAppNodeBootstrapPlugin(appConfig)]
+				: undefined,
+	});
+}
+/**
+ * Returns the app-owned server-module transpiler, creating it lazily when the
+ * runtime first needs one.
+ */
+export function getAppServerModuleTranspiler(appConfig: EcoPagesAppConfig): ServerModuleTranspiler {
+	const existingTranspiler = appConfig.runtime?.serverModuleTranspiler;
+	if (existingTranspiler) {
+		return existingTranspiler;
+	}
+	const serverModuleTranspiler = createAppServerModuleTranspiler(appConfig);
+	setAppServerModuleTranspiler(appConfig, serverModuleTranspiler);
+	return serverModuleTranspiler;
+}
+/**
+ * Installs the server-module transpiler that should serve one app instance.
+ */
+export function setAppServerModuleTranspiler(
+	appConfig: EcoPagesAppConfig,
+	serverModuleTranspiler: ServerModuleTranspiler,
+): void {
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		serverModuleTranspiler,
+	};
+}