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

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

@@ -1,151 +0,0 @@
-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 HMR strategies through the base HMR setup', () => {
-		const registerStrategy = vi.fn();
-		const hmrManager = {
-			registerStrategy,
-			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()),
-			getDistDir: vi.fn(() => ''),
-			getPlugins: vi.fn(() => []),
-			getDefaultContext: vi.fn(),
-			handleFileChange: vi.fn(),
-		} satisfies IHmrManager;
-
-		const strategy = { matches: vi.fn(() => false), process: vi.fn(), priority: 10, type: 'integration' } as any;
-		const pluginWithStrategy = new (class extends TestIntegrationPlugin {
-			override getHmrStrategy() {
-				return strategy;
-			}
-		})(config);
-
-		pluginWithStrategy.setHmrManager(hmrManager);
-
-		expect(registerStrategy).toHaveBeenCalledWith(strategy);
-	});
-
-	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

@@ -1,344 +0,0 @@
-import type { EcoBuildPlugin } from '../build/build-types.ts';
-import { createBrowserRuntimeManifest, type BrowserRuntimeManifest } from '../build/browser-runtime-manifest.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 { deepMerge } from '../utils/deep-merge.ts';
-import { invariant } from '../utils/invariant.ts';
-import type { RuntimeCapabilityDeclaration } from './runtime-capability.ts';
-
-export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.ts';
-export type {
-	EcoBuildLoader,
-	EcoBuildOnLoadArgs,
-	EcoBuildOnLoadResult,
-	EcoBuildOnResolveArgs,
-	EcoBuildOnResolveResult,
-	EcoBuildPlugin,
-	EcoBuildPluginBuilder,
-} from '../build/build-types.ts';
-export type { PageBrowserGraphContribution, PageBrowserGraphContributionContext } from '../types/public-types.ts';
-export type {
-	HtmlDocumentContribution,
-	HtmlDocumentContributionContext,
-} from '../route-renderer/orchestration/integration-renderer.ts';
-
-/**
- * Type-erased integration plugin stored in app-level registries.
- *
- * Ecopages keeps one heterogeneous integration list, while each plugin and
- * renderer still owns its framework-specific render payload type internally.
- */
-export type AnyIntegrationPlugin = IntegrationPlugin<unknown>;
-
-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;
-
-export function mergeIntegrationOptions<TDefaults, TOverrides>(
-	defaults: TDefaults,
-	overrides: TOverrides,
-): TDefaults & TOverrides {
-	return deepMerge(defaults, overrides);
-}
-
-export function assertIntegrationInvariant(condition: boolean, message?: string): asserts condition {
-	invariant(condition, message);
-}
-
-/**
- * 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. For page-browser and document shaping, integrations should
- * prefer the contribution contracts re-exported from this module:
- * `PageBrowserGraphContribution` / `PageBrowserGraphContributionContext` and
- * `HtmlDocumentContribution` / `HtmlDocumentContributionContext`.
- */
-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 [];
-	}
-
-	/**
-	 * Returns shared browser runtime asset declarations owned by this integration.
-	 *
-	 * @remarks
-	 * Core seals these declarations into the app build manifest so app-owned browser
-	 * bundle paths can rewrite manifest-owned imports even when a specific build
-	 * request does not install an integration-local runtime rewrite plugin.
-	 */
-	get browserRuntimeManifest(): BrowserRuntimeManifest {
-		return createBrowserRuntimeManifest();
-	}
-
-	/**
-	 * 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, pageMetadataCache, runtimeManifest });
-	 * }
-	 * ```
-	 */
-	getHmrStrategy?(): HmrStrategy | undefined;
-
-	/**
-	 * Attaches the shared HMR manager and registers integration-owned development hooks.
-	 *
-	 * @remarks
-	 * The default implementation registers 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;
-
-		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

@@ -1,148 +0,0 @@
-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);
-	});
-});