@ecopages/core 0.2.0-alpha.23 → 0.2.0-alpha.25

package/src/plugins/processor.ts

@@ -0,0 +1,240 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import type { EcoBuildPlugin } from '../build/build-types.ts';
+import type { EcoPagesAppConfig, IClientBridge } from '../types/internal-types.ts';
+import type { AssetDefinition } from '../services/assets/asset-processing-service/assets.types.ts';
+import { DEFAULT_ECOPAGES_WORK_DIR } from '../config/constants.ts';
+import { GENERATED_BASE_PATHS } from '../config/constants.ts';
+import type { RuntimeCapabilityDeclaration } from './runtime-capability.ts';
+
+export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.ts';
+
+export const PROCESSOR_ERRORS = {
+	CACHE_DIRECTORY_NOT_SET: 'Cache directory not set in context',
+} as const;
+
+function resolveGeneratedPath(
+	type: keyof typeof GENERATED_BASE_PATHS,
+	options: { root: string; module: string; subPath?: string },
+): string {
+	const { root, module, subPath } = options;
+	const parts = [root, GENERATED_BASE_PATHS[type], module, subPath].filter(Boolean);
+	return path.join(...(parts as string[]));
+}
+
+export interface ProcessorWatchContext {
+	path: string;
+	bridge: IClientBridge;
+}
+
+export interface ProcessorWatchConfig {
+	paths: string[];
+	extensions?: string[];
+	onCreate?: (ctx: ProcessorWatchContext) => Promise<void>;
+	onChange?: (ctx: ProcessorWatchContext) => Promise<void>;
+	onDelete?: (ctx: ProcessorWatchContext) => Promise<void>;
+	onError?: (error: Error) => void;
+}
+
+export type ProcessorAssetKind = 'script' | 'stylesheet' | 'image';
+export type ProcessorExtensionPattern = string;
+
+export interface ProcessorAssetCapability {
+	kind: ProcessorAssetKind;
+	/**
+	 * Supported patterns:
+	 * - `*` (all extensions)
+	 * - `.css` or `css`
+	 * - `*.css`
+	 * - `*.{css,scss,sass}`
+	 *
+	 * Pattern matching is case-insensitive and trims surrounding spaces,
+	 * including grouped values (e.g. `*.{ CSS, ScSs }`).
+	 */
+	extensions?: ProcessorExtensionPattern[];
+}
+
+export interface ProcessorConfig<TOptions = Record<string, unknown>> {
+	name: string;
+	description?: string;
+	options?: TOptions;
+	watch?: ProcessorWatchConfig;
+	capabilities?: ProcessorAssetCapability[];
+	runtimeCapability?: RuntimeCapabilityDeclaration;
+}
+export interface ProcessorContext {
+	config: EcoPagesAppConfig;
+	rootDir: string;
+	srcDir: string;
+	distDir: string;
+	cache?: string;
+}
+
+/**
+ * Interface for processor build plugins
+ * This is used to pass plugins to the build process directly from the processor
+ * For instance it can become very handy when dealing with virtual modules that needs to be recognized by the bundler
+ * i.e. @ecopages/image-processor
+ */
+export abstract class Processor<TOptions = Record<string, unknown>> {
+	readonly name: string;
+	protected dependencies: AssetDefinition[] = [];
+	protected context?: ProcessorContext;
+	protected options?: TOptions;
+	protected watchConfig?: ProcessorWatchConfig;
+	protected capabilities: ProcessorAssetCapability[] = [];
+	readonly runtimeCapability?: RuntimeCapabilityDeclaration;
+
+	/** Plugins that are only used during the build process */
+	abstract buildPlugins?: EcoBuildPlugin[];
+
+	/** Plugins that are used during runtime for file processing */
+	abstract plugins?: EcoBuildPlugin[];
+
+	constructor(config: ProcessorConfig<TOptions>) {
+		this.name = config.name;
+		this.options = config.options;
+		this.watchConfig = config.watch;
+		this.capabilities = config.capabilities ?? [];
+		this.runtimeCapability = config.runtimeCapability;
+	}
+
+	setContext(appConfig: EcoPagesAppConfig): void {
+		const workDir =
+			appConfig.absolutePaths.workDir ??
+			path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
+		const cachePath = resolveGeneratedPath('cache', {
+			root: workDir,
+			module: this.name,
+		});
+
+		fileSystem.ensureDir(cachePath);
+
+		this.context = {
+			config: appConfig,
+			rootDir: appConfig.rootDir,
+			srcDir: appConfig.absolutePaths.srcDir,
+			distDir: appConfig.absolutePaths.distDir,
+			cache: cachePath,
+		};
+	}
+
+	/**
+	 * Prepares build-facing processor contributions before config finalization.
+	 *
+	 * @remarks
+	 * Override this when a processor must compute runtime/build plugins or other
+	 * manifest-owned state before startup. Runtime-only work such as cache
+	 * warming or watcher registration should stay in `setup()`.
+	 */
+	async prepareBuildContributions(): Promise<void> {}
+
+	abstract setup(): Promise<void>;
+	abstract teardown(): Promise<void>;
+	abstract process(input: unknown, filePath?: string): Promise<unknown>;
+
+	protected getCachePath(key: string): string {
+		return `${this.context?.cache}/${key}`;
+	}
+
+	protected async readCache<T>(key: string): Promise<T | null> {
+		const cachePath = this.getCachePath(key);
+		try {
+			const data = await fileSystem.readFile(cachePath);
+			return JSON.parse(data) as T;
+		} catch {
+			return null;
+		}
+	}
+
+	protected async writeCache<T>(key: string, data: T): Promise<void> {
+		if (!this.context?.cache) {
+			throw new Error(PROCESSOR_ERRORS.CACHE_DIRECTORY_NOT_SET);
+		}
+
+		const cachePath = this.getCachePath(key);
+		fileSystem.write(cachePath, JSON.stringify(data, null, 2));
+	}
+
+	getWatchConfig(): ProcessorWatchConfig | undefined {
+		return this.watchConfig;
+	}
+
+	getDependencies(): AssetDefinition[] {
+		return this.dependencies;
+	}
+
+	getName(): string {
+		return this.name;
+	}
+
+	getAssetCapabilities(): ProcessorAssetCapability[] {
+		return this.capabilities;
+	}
+
+	matchesFileFilter(_filepath: string): boolean {
+		return true;
+	}
+
+	canProcessAsset(kind: ProcessorAssetKind, filepath?: string): boolean {
+		const capabilities = this.getAssetCapabilities();
+		if (capabilities.length === 0) {
+			return false;
+		}
+
+		const matchingKind = capabilities.filter((capability) => capability.kind === kind);
+		if (matchingKind.length === 0) {
+			return false;
+		}
+
+		if (!filepath) {
+			return true;
+		}
+
+		return matchingKind.some((capability) => this.matchesCapabilityExtensions(filepath, capability.extensions));
+	}
+
+	private matchesCapabilityExtensions(filepath: string, extensions?: ProcessorExtensionPattern[]): boolean {
+		if (!extensions || extensions.length === 0) {
+			return true;
+		}
+
+		const normalizedExt = path.extname(filepath).toLowerCase();
+
+		return extensions.some((rawPattern) => {
+			const pattern = this.normalizeExtensionPattern(rawPattern);
+			if (!pattern) {
+				return false;
+			}
+
+			if (pattern === '*') {
+				return true;
+			}
+
+			const groupedMatch = pattern.match(/^\*\.\{(.+)\}$/);
+			if (groupedMatch) {
+				const groupItems = groupedMatch[1]
+					.split(',')
+					.map((item) => this.normalizeExtensionPattern(item))
+					.filter(Boolean);
+
+				return groupItems.some((item) => normalizedExt === item || normalizedExt === `.${item}`);
+			}
+
+			if (pattern.startsWith('*')) {
+				const suffix = pattern.slice(1);
+				return normalizedExt.endsWith(suffix);
+			}
+
+			if (pattern.startsWith('.')) {
+				return normalizedExt === pattern;
+			}
+
+			return normalizedExt === `.${pattern}`;
+		});
+	}
+
+	private normalizeExtensionPattern(rawPattern: string): string {
+		return rawPattern.trim().toLowerCase();
+	}
+}

package/src/plugins/{runtime-capability.d.ts → runtime-capability.ts}

@@ -1,9 +1,14 @@
-export type RuntimeCapabilityTag = 'bun-only' | 'node-compatible' | 'requires-native-bun-api' | 'requires-node-builtins';
+export type RuntimeCapabilityTag =
+	| 'bun-only'
+	| 'node-compatible'
+	| 'requires-native-bun-api'
+	| 'requires-node-builtins';
+
 /**
  * Declares the runtime assumptions a plugin makes so config finalization can
  * reject incompatible startup environments before bootstrapping the app.
  */
 export interface RuntimeCapabilityDeclaration {
-    tags: RuntimeCapabilityTag[];
-    minRuntimeVersion?: string;
+	tags: RuntimeCapabilityTag[];
+	minRuntimeVersion?: string;
 }

package/src/plugins/source-transform.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fileSystem } from '@ecopages/file-system';
+import {
+	applySourceTransform,
+	createVitePluginsFromAppSourceTransforms,
+	createEcoBuildPluginFromSourceTransform,
+	getAppSourceTransforms,
+	createVitePluginFromSourceTransform,
+	normalizeTransformId,
+	type EcoSourceTransform,
+} from './source-transform.ts';
+import type { EcoPagesAppConfig } from '../types/internal-types.ts';
+
+describe('source-transform', () => {
+	const transform: EcoSourceTransform = {
+		name: 'test-transform',
+		filter: /main\.tsx$/,
+		transform(code) {
+			return {
+				code: `/* injected */\n${code}`,
+			};
+		},
+	};
+
+	it('normalizes ids by stripping query and hash suffixes', () => {
+		expect(normalizeTransformId('/src/main.tsx?import')).toBe('/src/main.tsx');
+		expect(normalizeTransformId('/src/main.tsx#hash')).toBe('/src/main.tsx');
+	});
+
+	it('applies transforms against normalized ids', () => {
+		const result = applySourceTransform(transform, 'export const value = 1;', '/src/main.tsx?import');
+
+		expect(result).toEqual({
+			code: '/* injected */\nexport const value = 1;',
+		});
+	});
+
+	it('creates a Vite-compatible transform plugin', () => {
+		const vitePlugin = createVitePluginFromSourceTransform(transform);
+		const result = vitePlugin.transform('export const value = 1;', '/src/main.tsx?import');
+
+		expect(vitePlugin.name).toBe('test-transform');
+		expect(result).toEqual({
+			code: '/* injected */\nexport const value = 1;',
+		});
+	});
+
+	it('creates an Ecopages build plugin wrapper', async () => {
+		const buildPlugin = createEcoBuildPluginFromSourceTransform(transform);
+		let onLoadCallback: ((args: { path: string }) => unknown) | undefined;
+
+		buildPlugin.setup({
+			onLoad(_options: unknown, callback: unknown) {
+				onLoadCallback = callback as typeof onLoadCallback;
+			},
+		} as never);
+
+		const readSpy = vi.spyOn(fileSystem, 'readFileSync').mockReturnValue('export const value = 1;');
+
+		try {
+			const result = await onLoadCallback?.({ path: '/src/main.tsx?import' });
+
+			expect(result).toEqual({
+				contents: '/* injected */\nexport const value = 1;',
+				loader: 'tsx',
+				resolveDir: '/src',
+			});
+		} finally {
+			readSpy.mockRestore();
+		}
+	});
+
+	it('collects app-owned source transforms and adapts them to Vite plugins', () => {
+		const appConfig = {
+			sourceTransforms: new Map([[transform.name, transform]]),
+		} as EcoPagesAppConfig;
+
+		expect(getAppSourceTransforms(appConfig)).toEqual([transform]);
+		expect(createVitePluginsFromAppSourceTransforms(appConfig)).toHaveLength(1);
+		expect(createVitePluginsFromAppSourceTransforms(appConfig)[0].name).toBe('test-transform');
+	});
+});

package/src/plugins/source-transform.ts

@@ -0,0 +1,123 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import type { EcoBuildPlugin } from '../build/build-types.ts';
+import type { EcoPagesAppConfig } from '../types/internal-types.ts';
+
+export interface EcoSourceTransformResult {
+	code: string;
+	map?: unknown;
+}
+
+export interface EcoSourceTransform {
+	name: string;
+	filter: RegExp;
+	enforce?: 'pre' | 'post';
+	transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
+}
+
+export interface EcoViteCompatiblePlugin {
+	name: string;
+	enforce?: 'pre' | 'post';
+	transform(code: string, id: string): EcoSourceTransformResult | string | undefined;
+}
+
+/**
+ * Normalizes bundler module ids so one transform can serve Ecopages loaders,
+ * Vite, and future bundler adapters.
+ */
+export function normalizeTransformId(id: string): string {
+	const queryIndex = id.indexOf('?');
+	const hashIndex = id.indexOf('#');
+	const endIndex = [queryIndex, hashIndex].filter((index) => index >= 0).sort((left, right) => left - right)[0];
+
+	return endIndex === undefined ? id : id.slice(0, endIndex);
+}
+
+/**
+ * Applies one source transform if the normalized id matches its filter.
+ */
+export function applySourceTransform(
+	transform: EcoSourceTransform,
+	code: string,
+	id: string,
+): EcoSourceTransformResult | string | undefined {
+	const normalizedId = normalizeTransformId(id);
+
+	if (!transform.filter.test(normalizedId)) {
+		return undefined;
+	}
+
+	return transform.transform(code, normalizedId);
+}
+
+function inferLoaderFromPath(filePath: string): 'ts' | 'tsx' | 'js' | 'jsx' {
+	const extension = path.extname(filePath).toLowerCase();
+
+	switch (extension) {
+		case '.ts':
+			return 'ts';
+		case '.tsx':
+			return 'tsx';
+		case '.jsx':
+			return 'jsx';
+		default:
+			return 'js';
+	}
+}
+
+/**
+ * Adapts a source transform into the existing Ecopages build-plugin contract.
+ */
+export function createEcoBuildPluginFromSourceTransform(transform: EcoSourceTransform): EcoBuildPlugin {
+	return {
+		name: transform.name,
+		setup(build) {
+			build.onLoad({ filter: transform.filter }, (args) => {
+				const filePath = normalizeTransformId(args.path);
+				const code = fileSystem.readFileSync(filePath);
+				const result = applySourceTransform(transform, code, filePath);
+
+				if (!result) {
+					return undefined;
+				}
+
+				return {
+					contents: typeof result === 'string' ? result : result.code,
+					loader: inferLoaderFromPath(filePath),
+					resolveDir: path.dirname(filePath),
+				};
+			});
+		},
+	};
+}
+
+/**
+ * Adapts a source transform into a Vite-compatible plugin object.
+ *
+ * @remarks
+ * This intentionally returns a plain object shape so core does not need a hard
+ * dependency on `vite` just to author transform primitives.
+ */
+export function createVitePluginFromSourceTransform(transform: EcoSourceTransform): EcoViteCompatiblePlugin {
+	return {
+		name: transform.name,
+		enforce: transform.enforce,
+		transform(code, id) {
+			return applySourceTransform(transform, code, id);
+		},
+	};
+}
+
+/**
+ * Returns the app-owned source transforms in stable registration order.
+ */
+export function getAppSourceTransforms(appConfig: EcoPagesAppConfig): EcoSourceTransform[] {
+	return Array.from(appConfig.sourceTransforms.values());
+}
+
+/**
+ * Adapts the app-owned source transforms into Vite-compatible plugin objects.
+ */
+export function createVitePluginsFromAppSourceTransforms(appConfig: EcoPagesAppConfig): EcoViteCompatiblePlugin[] {
+	return getAppSourceTransforms(appConfig).map((transform) => createVitePluginFromSourceTransform(transform));
+}

package/src/route-renderer/orchestration/boundary-planning.service.ts

@@ -0,0 +1,146 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type {
+	BoundaryPlan,
+	BoundaryPlanNode,
+	BoundaryPlanNodeSource,
+	BoundaryValidationError,
+	EcoComponent,
+} from '../../types/public-types.ts';
+
+type BoundaryPlanBuildInput = {
+	routeFile: string;
+	currentIntegrationName: string;
+	HtmlTemplate: EcoComponent;
+	Layout?: EcoComponent;
+	Page: EcoComponent;
+};
+
+type BoundaryPlanBuildEntry = {
+	component: EcoComponent;
+	source: Extract<BoundaryPlanNodeSource, 'page' | 'layout' | 'html-template'>;
+};
+
+/**
+ * Builds a declared ownership plan from the component dependency graph.
+ *
+ * The plan is intentionally conservative: it reflects declared component
+ * dependencies available during render preparation and records diagnostics for
+ * foreign ownership edges that cannot be validated against registered
+ * integrations or stable component metadata.
+ */
+export class BoundaryPlanningService {
+	private readonly appConfig: EcoPagesAppConfig;
+	private nextSyntheticId = 0;
+
+	constructor(appConfig: EcoPagesAppConfig) {
+		this.appConfig = appConfig;
+	}
+
+	buildPlan(input: BoundaryPlanBuildInput): BoundaryPlan {
+		this.nextSyntheticId = 0;
+
+		const validationErrors: BoundaryValidationError[] = [];
+		const rendererNames = new Set<string>([input.currentIntegrationName]);
+		let foreignEdgeCount = 0;
+
+		const buildNode = (
+			component: EcoComponent,
+			source: Exclude<BoundaryPlanNodeSource, 'route'>,
+			parentIntegrationName: string,
+			lineage: Set<object>,
+		): BoundaryPlanNode => {
+			const integrationName =
+				component.config?.integration ?? component.config?.__eco?.integration ?? parentIntegrationName;
+			const componentMeta = component.config?.__eco;
+			const isForeignToParent = integrationName !== parentIntegrationName;
+			const componentId = componentMeta?.id ?? componentMeta?.file ?? `${source}:${(this.nextSyntheticId += 1)}`;
+
+			rendererNames.add(integrationName);
+
+			if (isForeignToParent) {
+				foreignEdgeCount += 1;
+
+				if (!componentMeta) {
+					validationErrors.push({
+						code: 'MISSING_COMPONENT_METADATA',
+						message: `[ecopages] Foreign boundary "${componentId}" must provide stable __eco metadata so ownership diagnostics stay actionable. Declared dependencies must include all possible foreign children.`,
+						componentId,
+						integrationName,
+					});
+				}
+
+				if (!this.isRegisteredIntegration(integrationName, input.currentIntegrationName)) {
+					validationErrors.push({
+						code: 'UNKNOWN_INTEGRATION_OWNER',
+						message: `[ecopages] Foreign boundary "${componentId}" references unknown integration owner "${integrationName}". Declared dependencies must include all possible foreign children and those integrations must be registered.`,
+						componentId,
+						componentFile: componentMeta?.file,
+						integrationName,
+					});
+				}
+			}
+
+			const nextLineage = new Set(lineage);
+			nextLineage.add(component);
+			const children = (component.config?.dependencies?.components ?? []).flatMap((child) => {
+				if (!child || nextLineage.has(child)) {
+					return [];
+				}
+
+				return [buildNode(child, 'dependency', integrationName, nextLineage)];
+			});
+
+			return {
+				id: componentId,
+				source,
+				ownership: {
+					integrationName,
+					componentId,
+					componentFile: componentMeta?.file,
+					isPageEntry: source === 'page',
+					isForeignToParent,
+				},
+				children,
+				declaredDependenciesValid: true,
+			};
+		};
+
+		const roots: BoundaryPlanBuildEntry[] = [
+			{ component: input.HtmlTemplate, source: 'html-template' },
+			...(input.Layout ? [{ component: input.Layout, source: 'layout' as const }] : []),
+			{ component: input.Page, source: 'page' },
+		];
+
+		const root: BoundaryPlanNode = {
+			id: `route:${input.routeFile}`,
+			source: 'route',
+			ownership: {
+				integrationName: input.currentIntegrationName,
+				componentId: `route:${input.routeFile}`,
+				componentFile: input.routeFile,
+				isPageEntry: false,
+				isForeignToParent: false,
+			},
+			children: roots.map(({ component, source }) =>
+				buildNode(component, source, input.currentIntegrationName, new Set()),
+			),
+			declaredDependenciesValid: validationErrors.length === 0,
+		};
+
+		return {
+			root,
+			rendererNames: Array.from(rendererNames),
+			foreignEdgeCount,
+			hasValidationErrors: validationErrors.length > 0,
+			validationErrors,
+		};
+	}
+
+	private isRegisteredIntegration(integrationName: string, currentIntegrationName: string): boolean {
+		if (integrationName === currentIntegrationName) {
+			return true;
+		}
+
+		return this.appConfig.integrations.some((integration) => integration.name === integrationName);
+	}
+}