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

package/src/plugins/integration-plugin.test.ts

@@ -0,0 +1,156 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { IntegrationPlugin, type IntegrationPluginConfig } from './integration-plugin.ts';
+import type { IHmrManager } from '../types/public-types.ts';
+import type { AssetDefinition } from '../services/assets/asset-processing-service';
+import type { IntegrationRendererRenderOptions, RouteRendererBody } from '../types/public-types.ts';
+import {
+	IntegrationRenderer,
+	type RenderToResponseContext,
+} from '../route-renderer/orchestration/integration-renderer.ts';
+import type { EcoPagesAppConfig } from '../types/internal-types.ts';
+
+class NamelessRenderer extends IntegrationRenderer {
+	declare name: string;
+
+	async render(_options: IntegrationRendererRenderOptions): Promise<RouteRendererBody> {
+		return '<div>ok</div>';
+	}
+
+	async renderToResponse(_view: never, _props: never, _ctx: RenderToResponseContext): Promise<Response> {
+		return new Response('<div>ok</div>');
+	}
+}
+
+class TestIntegrationPlugin extends IntegrationPlugin {
+	renderer = vi.fn() as any;
+	override setup(): Promise<void> {
+		return Promise.resolve();
+	}
+
+	override teardown(): Promise<void> {
+		return Promise.resolve();
+	}
+}
+
+class OverrideInitializeRendererPlugin extends TestIntegrationPlugin {
+	override initializeRenderer() {
+		const renderer = new NamelessRenderer({
+			appConfig: this.appConfig as EcoPagesAppConfig,
+			assetProcessingService: {} as never,
+			resolvedIntegrationDependencies: [],
+			runtimeOrigin: this.runtimeOrigin,
+		});
+
+		return this.attachRendererRuntimeServices(renderer);
+	}
+}
+
+describe('IntegrationPlugin', () => {
+	let plugin: TestIntegrationPlugin;
+	const config: IntegrationPluginConfig = {
+		name: 'test-plugin',
+		extensions: ['.test'],
+		integrationDependencies: [],
+	};
+
+	beforeEach(() => {
+		plugin = new TestIntegrationPlugin(config);
+	});
+
+	it('should initialize with correct config values', () => {
+		expect(plugin.name).toBe(config.name);
+		expect(plugin.extensions).toEqual(config.extensions);
+		expect(plugin.runtimeCapability).toBeUndefined();
+		expect(plugin.getResolvedIntegrationDependencies()).toEqual(
+			config.integrationDependencies as AssetDefinition[],
+		);
+	});
+
+	it('should retain runtime capability declarations', () => {
+		const pluginWithRuntimeCapability = new TestIntegrationPlugin({
+			name: 'runtime-capable',
+			extensions: ['.test'],
+			runtimeCapability: {
+				tags: ['bun-only'],
+				minRuntimeVersion: '1.0.0',
+			},
+		});
+
+		expect(pluginWithRuntimeCapability.runtimeCapability).toEqual({
+			tags: ['bun-only'],
+			minRuntimeVersion: '1.0.0',
+		});
+	});
+
+	it('should initialize with empty dependencies if not provided', () => {
+		const pluginWithoutDeps = new TestIntegrationPlugin({
+			name: 'test',
+			extensions: [],
+		});
+		expect(pluginWithoutDeps.getResolvedIntegrationDependencies()).toEqual([]);
+	});
+
+	it('should implement setup and teardown methods', async () => {
+		await expect(plugin.setup()).resolves.toBeUndefined();
+		await expect(plugin.teardown()).resolves.toBeUndefined();
+	});
+
+	it('should register runtime specifier maps through the base HMR setup', () => {
+		const registerSpecifierMap = vi.fn();
+		const hmrManager = {
+			registerSpecifierMap,
+			registerStrategy: vi.fn(),
+			registerEntrypoint: vi.fn(),
+			registerScriptEntrypoint: vi.fn(),
+			setPlugins: vi.fn(),
+			setEnabled: vi.fn(),
+			isEnabled: vi.fn(() => true),
+			broadcast: vi.fn(),
+			getOutputUrl: vi.fn(),
+			getWatchedFiles: vi.fn(() => new Map()),
+			getSpecifierMap: vi.fn(() => new Map()),
+			getDistDir: vi.fn(() => ''),
+			getPlugins: vi.fn(() => []),
+			getDefaultContext: vi.fn(),
+			handleFileChange: vi.fn(),
+		} satisfies IHmrManager;
+
+		const pluginWithRuntimeSpecifiers = new (class extends TestIntegrationPlugin {
+			override getRuntimeSpecifierMap(): Record<string, string> {
+				return {
+					'test-runtime': '/assets/vendors/test-runtime.js',
+				};
+			}
+		})(config);
+
+		pluginWithRuntimeSpecifiers.setHmrManager(hmrManager);
+
+		expect(registerSpecifierMap).toHaveBeenCalledWith({
+			'test-runtime': '/assets/vendors/test-runtime.js',
+		});
+	});
+
+	it('should stamp the plugin integration name onto initialized renderers', () => {
+		const pluginWithRenderer = new (class extends TestIntegrationPlugin {
+			override renderer = NamelessRenderer as TestIntegrationPlugin['renderer'];
+		})(config);
+
+		(pluginWithRenderer as TestIntegrationPlugin & { appConfig?: object; runtimeOrigin: string }).appConfig =
+			{} as EcoPagesAppConfig;
+		pluginWithRenderer.runtimeOrigin = 'http://localhost:3000';
+
+		const renderer = pluginWithRenderer.initializeRenderer();
+		expect(renderer.name).toBe('test-plugin');
+	});
+
+	it('should stamp the plugin integration name when overrides use shared renderer runtime services', () => {
+		const pluginWithOverride = new OverrideInitializeRendererPlugin(config);
+
+		(pluginWithOverride as TestIntegrationPlugin & { appConfig?: object; runtimeOrigin: string }).appConfig =
+			{} as EcoPagesAppConfig;
+		pluginWithOverride.runtimeOrigin = 'http://localhost:3000';
+
+		const renderer = pluginWithOverride.initializeRenderer();
+		expect(renderer.name).toBe('test-plugin');
+	});
+});

package/src/plugins/integration-plugin.ts

@@ -0,0 +1,311 @@
+import type { EcoBuildPlugin } from '../build/build-types.ts';
+import type { EcoPagesAppConfig, IHmrManager } from '../types/internal-types.ts';
+import type { HmrStrategy } from '../hmr/hmr-strategy.ts';
+import type { EcoPagesElement } from '../types/public-types.ts';
+import type { IntegrationRenderer } from '../route-renderer/orchestration/integration-renderer.ts';
+import { AssetProcessingService } from '../services/assets/asset-processing-service/asset-processing.service.ts';
+import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.ts';
+import type { RuntimeCapabilityDeclaration } from './runtime-capability.ts';
+
+export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.ts';
+
+export const INTEGRATION_PLUGIN_ERRORS = {
+	NOT_INITIALIZED_WITH_APP_CONFIG: 'Plugin not initialized with app config',
+	NOT_INITIALIZED_WITH_ASSET_SERVICE: 'Plugin not initialized with asset dependency service',
+} as const;
+
+/**
+ * Base configuration shared by all integration plugins.
+ *
+ * @remarks
+ * Integrations declare their file ownership, optional runtime requirements, and
+ * any global assets or build-time contributions here. Runtime-only side effects
+ * belong in `setup()` rather than the constructor.
+ */
+export interface IntegrationPluginConfig {
+	/**
+	 * The name of the integration plugin.
+	 */
+	name: string;
+	/**
+	 * The extensions that this plugin supports (e.g., ['.kita.js', '.kita.tsx']).
+	 */
+	extensions: string[];
+	/**
+	 * The dependencies that this plugin requires on a global level.
+	 * These dependencies will be resolved during the setup process and injected into the global scope of the application.
+	 * They are not specific to any particular page or component.
+	 */
+	integrationDependencies?: AssetDefinition[];
+	/**
+	 * The strategy to use for static building.
+	 * - 'render': Execute component function directly (faster, efficient).
+	 * - 'fetch': Start server and fetch URL (slower, needed for some SSR like Lit).
+	 * @default 'render'
+	 */
+	staticBuildStep?: 'render' | 'fetch';
+	/**
+	 * Declares runtime-specific requirements that must be satisfied before the
+	 * app can start with this integration enabled.
+	 */
+	runtimeCapability?: RuntimeCapabilityDeclaration;
+	/**
+	 * JSX import source owned by this integration.
+	 *
+	 * @remarks
+	 * This is primarily used by mixed-JSX flows where host-owned browser bundles
+	 * need to preserve the correct JSX runtime for files claimed by the
+	 * integration.
+	 */
+	jsxImportSource?: string;
+}
+
+type RendererClass<C> = new (options: {
+	appConfig: EcoPagesAppConfig;
+	assetProcessingService: AssetProcessingService;
+	resolvedIntegrationDependencies: ProcessedAsset[];
+	rendererModules?: unknown;
+	runtimeOrigin: string;
+}) => IntegrationRenderer<C>;
+
+/**
+ * Base class for framework integrations.
+ *
+ * @remarks
+ * An integration owns three main concerns:
+ * - which file extensions it claims
+ * - which renderer class turns those files into HTML
+ * - which build-time or runtime contributions must be registered for that framework
+ *
+ * Core owns lifecycle ordering. Integrations declare contributions through the
+ * hooks on this class, while `ConfigBuilder.build()` and app startup decide when
+ * those hooks run.
+ */
+export abstract class IntegrationPlugin<C = EcoPagesElement> {
+	readonly name: string;
+	readonly extensions: string[];
+	abstract renderer: RendererClass<C>;
+	readonly staticBuildStep: 'render' | 'fetch';
+	readonly runtimeCapability?: RuntimeCapabilityDeclaration;
+	readonly jsxImportSource?: string;
+
+	protected integrationDependencies: AssetDefinition[];
+	protected resolvedIntegrationDependencies: ProcessedAsset[] = [];
+	protected options?: Record<string, unknown>;
+	protected appConfig?: EcoPagesAppConfig;
+	protected assetProcessingService?: AssetProcessingService;
+	protected hmrManager?: IHmrManager;
+	declare runtimeOrigin: string;
+
+	get plugins(): EcoBuildPlugin[] {
+		return [];
+	}
+
+	/**
+	 * Returns build plugins that should only apply to browser-oriented bundles.
+	 *
+	 * @remarks
+	 * Browser-only transforms such as runtime import aliasing belong here so they
+	 * do not affect server bundles or static-page module generation.
+	 */
+	get browserBuildPlugins(): EcoBuildPlugin[] {
+		return [];
+	}
+
+	/**
+	 * Creates the integration with static declaration-only configuration.
+	 *
+	 * @remarks
+	 * Constructors are expected to stay side-effect free. Build-manifest
+	 * contributions belong in `prepareBuildContributions()` and runtime-only setup
+	 * belongs in `setup()`.
+	 */
+	constructor(config: IntegrationPluginConfig) {
+		this.name = config.name;
+		this.extensions = config.extensions;
+		this.integrationDependencies = config.integrationDependencies || [];
+		this.staticBuildStep = config.staticBuildStep || 'render';
+		this.runtimeCapability = config.runtimeCapability;
+		this.jsxImportSource = config.jsxImportSource;
+	}
+
+	/**
+	 * Attaches the finalized app config to the integration.
+	 *
+	 * Core calls this during config finalization before runtime setup so the
+	 * integration can resolve asset paths and other app-owned services later.
+	 */
+	setConfig(appConfig: EcoPagesAppConfig): void {
+		this.appConfig = appConfig;
+		this.initializeAssetDefinitionService();
+	}
+
+	/**
+	 * Records the runtime origin used for page-module loading and renderer setup.
+	 */
+	setRuntimeOrigin(runtimeOrigin: string) {
+		this.runtimeOrigin = runtimeOrigin;
+	}
+
+	/**
+	 * Returns an HMR strategy for this integration, if applicable.
+	 * The strategy will be registered with the HmrManager during initialization.
+	 *
+	 * @returns HmrStrategy instance or undefined if no custom HMR handling needed
+	 *
+	 * @example
+	 * ```typescript
+	 * getHmrStrategy(): HmrStrategy {
+	 *   const context = this.hmrManager!.getDefaultContext();
+	 *   return new ReactHmrStrategy(context);
+	 * }
+	 * ```
+	 */
+	getHmrStrategy?(): HmrStrategy | undefined;
+
+	/**
+	 * Returns bare-specifier mappings that should be registered in the active
+	 * runtime specifier registry.
+	 *
+	 * @remarks
+	 * Integrations that own browser runtime bundles can override this to expose
+	 * stable bare specifiers for client-side imports.
+	 *
+	 * Today these mappings are consumed by the development runtime and browser
+	 * bundle aliasing path. They are intentionally generic enough to grow into a
+	 * broader import-map-style facility later without moving framework-specific
+	 * map contents into core.
+	 */
+	getRuntimeSpecifierMap(): Record<string, string> {
+		return {};
+	}
+
+	/**
+	 * Attaches the shared HMR manager and registers integration-owned development hooks.
+	 *
+	 * @remarks
+	 * The default implementation registers both runtime bare-specifier mappings and
+	 * the optional integration HMR strategy. Integrations should override this only
+	 * when they need to extend that shared behavior rather than replace it.
+	 */
+	setHmrManager(hmrManager: IHmrManager) {
+		this.hmrManager = hmrManager;
+		hmrManager.registerSpecifierMap(this.getRuntimeSpecifierMap());
+
+		const strategy = this.getHmrStrategy?.();
+		if (strategy) {
+			hmrManager.registerStrategy(strategy);
+		}
+
+		if (this.assetProcessingService) {
+			this.assetProcessingService.setHmrManager(hmrManager);
+		}
+	}
+
+	/**
+	 * Creates the asset-processing service used for global integration dependencies.
+	 */
+	initializeAssetDefinitionService(): void {
+		if (!this.appConfig) throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
+
+		this.assetProcessingService = AssetProcessingService.createWithDefaultProcessors(this.appConfig);
+		if (this.hmrManager) {
+			this.assetProcessingService.setHmrManager(this.hmrManager);
+		}
+	}
+
+	/**
+	 * Returns processed global assets resolved during `setup()`.
+	 */
+	getResolvedIntegrationDependencies(): ProcessedAsset[] {
+		return this.resolvedIntegrationDependencies;
+	}
+
+	/**
+	 * Creates the shared renderer options owned by core lifecycle setup.
+	 */
+	protected createRendererOptions(options?: { rendererModules?: unknown }) {
+		if (!this.appConfig) {
+			throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_APP_CONFIG);
+		}
+
+		const assetProcessingService = AssetProcessingService.createWithDefaultProcessors(this.appConfig);
+		if (this.hmrManager) {
+			assetProcessingService.setHmrManager(this.hmrManager);
+		}
+
+		return {
+			appConfig: this.appConfig,
+			assetProcessingService,
+			resolvedIntegrationDependencies: this.resolvedIntegrationDependencies,
+			rendererModules: options?.rendererModules,
+			runtimeOrigin: this.runtimeOrigin,
+		};
+	}
+
+	/**
+	 * Attaches runtime-only services after a renderer instance has been created.
+	 */
+	protected attachRendererRuntimeServices<T extends IntegrationRenderer<C>>(renderer: T): T {
+		if (typeof renderer.name !== 'string' || renderer.name.length === 0) {
+			renderer.name = this.name;
+		}
+
+		if (this.hmrManager) {
+			renderer.setHmrManager(this.hmrManager);
+		}
+
+		return renderer;
+	}
+
+	/**
+	 * Instantiates the integration renderer with app-owned services.
+	 *
+	 * @remarks
+	 * Renderers are cheap runtime objects. They receive the finalized app config,
+	 * a fresh asset-processing service, integration-global processed assets, and
+	 * any renderer module context supplied by the active runtime.
+			renderer.name ||= this.name;
+	 */
+	initializeRenderer(options?: { rendererModules?: unknown }): IntegrationRenderer<C> {
+		const renderer = new this.renderer(this.createRendererOptions(options));
+		renderer.name ||= this.name;
+		return this.attachRendererRuntimeServices(renderer);
+	}
+
+	/**
+	 * Prepares build-facing contributions before the app build manifest is sealed.
+	 *
+	 * @remarks
+	 * Integrations can override this when runtime or build plugin declarations must
+	 * be materialized ahead of runtime startup. Runtime-only side effects stay in
+	 * `setup()`.
+	 */
+	async prepareBuildContributions(): Promise<void> {}
+
+	/**
+	 * Performs runtime-only integration setup after config build has already
+	 * sealed manifest contributions.
+	 */
+	async setup(): Promise<void> {
+		if (this.integrationDependencies.length === 0) return;
+		if (!this.assetProcessingService) throw new Error(INTEGRATION_PLUGIN_ERRORS.NOT_INITIALIZED_WITH_ASSET_SERVICE);
+
+		this.resolvedIntegrationDependencies = await this.assetProcessingService.processDependencies(
+			this.integrationDependencies,
+			this.name,
+		);
+
+		this.initializeRenderer();
+	}
+
+	/**
+	 * Releases runtime resources owned by the integration.
+	 *
+	 * @remarks
+	 * Most integrations do not need custom teardown. Override this only for
+	 * explicit cleanup such as watchers, compiler handles, or runtime registries
+	 * that outlive individual requests.
+	 */
+	async teardown(): Promise<void> {}
+}

package/src/plugins/processor.test.ts

@@ -0,0 +1,148 @@
+import { afterAll, beforeEach, describe, expect, test } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { EcoBuildPlugin } from '../build/build-types.ts';
+import type { EcoPagesAppConfig } from '../types/internal-types';
+import { Processor, type ProcessorConfig } from './processor.ts';
+
+class TestProcessor extends Processor {
+	override buildPlugins?: EcoBuildPlugin[] = [];
+	override plugins?: EcoBuildPlugin[] = [];
+
+	override async setup(): Promise<void> {}
+
+	override async process(input: unknown, _filePath?: string): Promise<unknown> {
+		return input;
+	}
+
+	override async teardown(): Promise<void> {}
+}
+
+describe('Processor', () => {
+	let processor: TestProcessor;
+	let config: ProcessorConfig;
+	let appConfig: EcoPagesAppConfig;
+
+	beforeEach(() => {
+		config = {
+			name: 'test-processor',
+			options: { test: true },
+			watch: {
+				paths: ['/test'],
+			},
+		};
+
+		const testRoot = path.join(process.cwd(), '.test-tmp', 'processor-test');
+
+		if (fs.existsSync(testRoot)) {
+			fs.rmSync(testRoot, { recursive: true, force: true });
+		}
+
+		appConfig = {
+			rootDir: testRoot,
+			absolutePaths: {
+				srcDir: path.join(testRoot, 'src'),
+				distDir: path.join(testRoot, 'dist'),
+			},
+		} as EcoPagesAppConfig;
+
+		processor = new TestProcessor(config);
+		processor.setContext(appConfig);
+	});
+
+	afterAll(() => {
+		fs.rmSync(path.join(process.cwd(), '.test-tmp'), { recursive: true, force: true });
+	});
+
+	test('should initialize with correct name', () => {
+		expect(processor.getName()).toBe('test-processor');
+	});
+
+	test('should retain runtime capability declarations', () => {
+		const runtimeProcessor = new TestProcessor({
+			name: 'runtime-processor',
+			runtimeCapability: {
+				tags: ['requires-node-builtins'],
+				minRuntimeVersion: '18.0.0',
+			},
+		});
+
+		expect(runtimeProcessor.runtimeCapability).toEqual({
+			tags: ['requires-node-builtins'],
+			minRuntimeVersion: '18.0.0',
+		});
+	});
+
+	test('should return watch config', () => {
+		expect(processor.getWatchConfig()).toEqual({
+			paths: ['/test'],
+		});
+	});
+});
+
+describe('Processor capability matching', () => {
+	test('matches all extensions with * pattern', () => {
+		const processor = new TestProcessor({
+			name: 'wildcard-all',
+			capabilities: [{ kind: 'stylesheet', extensions: ['*'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.scss')).toBe(true);
+	});
+
+	test('matches explicit *.ext patterns', () => {
+		const processor = new TestProcessor({
+			name: 'wildcard-explicit',
+			capabilities: [{ kind: 'stylesheet', extensions: ['*.css'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.scss')).toBe(false);
+	});
+
+	test('matches grouped extension patterns', () => {
+		const processor = new TestProcessor({
+			name: 'wildcard-group',
+			capabilities: [{ kind: 'stylesheet', extensions: ['*.{css,scss,sass}'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.scss')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.sass')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.less')).toBe(false);
+	});
+
+	test('matches grouped patterns with mixed case and spacing', () => {
+		const processor = new TestProcessor({
+			name: 'wildcard-group-normalized',
+			capabilities: [{ kind: 'stylesheet', extensions: ['*.{ CSS, ScSs , .SASS }'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.scss')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.sass')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.less')).toBe(false);
+	});
+
+	test('matches plain extension and dotted extension forms', () => {
+		const processor = new TestProcessor({
+			name: 'plain-ext',
+			capabilities: [{ kind: 'stylesheet', extensions: ['css', '.scss'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.scss')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.sass')).toBe(false);
+	});
+
+	test('respects capability kind filtering', () => {
+		const processor = new TestProcessor({
+			name: 'kind-filter',
+			capabilities: [{ kind: 'image', extensions: ['*.png'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(false);
+		expect(processor.canProcessAsset('image', '/src/assets/logo.png')).toBe(true);
+	});
+});