@mondaydotcomorg/atp-compiler 0.18.2 → 0.18.4-rc.1

package/src/plugin-system/plugin-api.ts

@@ -0,0 +1,330 @@
+/**
+ * ATP Compiler Plugin API
+ * 
+ * Extensible plugin system for custom transformations and detections
+ */
+
+import type { NodePath } from '@babel/traverse';
+import type * as t from '@babel/types';
+import type { CompilerConfig, DetectionResult, TransformMetadata, AsyncPattern } from '../types.js';
+
+/**
+ * Base plugin interface
+ */
+export interface CompilerPlugin {
+	/**
+	 * Unique plugin name
+	 */
+	name: string;
+
+	/**
+	 * Plugin version (semver)
+	 */
+	version: string;
+
+	/**
+	 * Plugin priority (higher = runs first)
+	 * Built-in plugins: 100
+	 * User plugins: 50 (default)
+	 * Low priority: 10
+	 */
+	priority?: number;
+
+	/**
+	 * Plugin initialization (optional)
+	 * Called once when plugin is registered
+	 */
+	initialize?(config: CompilerConfig): void | Promise<void>;
+
+	/**
+	 * Plugin cleanup (optional)
+	 * Called when compiler is disposed
+	 */
+	dispose?(): void | Promise<void>;
+}
+
+/**
+ * Detection plugin - detects patterns that need transformation
+ */
+export interface DetectionPlugin extends CompilerPlugin {
+	/**
+	 * Detect patterns in code
+	 */
+	detect(code: string, ast: t.File): DetectionResult | Promise<DetectionResult>;
+
+	/**
+	 * Custom async patterns this plugin can detect
+	 */
+	patterns: AsyncPattern[];
+}
+
+/**
+ * Transformation plugin - transforms AST nodes
+ */
+export interface TransformationPlugin extends CompilerPlugin {
+	/**
+	 * Visitor pattern for AST traversal
+	 * Return visitor object compatible with @babel/traverse
+	 */
+	getVisitor(config: CompilerConfig): BabelVisitor;
+
+	/**
+	 * Get transformation metadata after transform
+	 */
+	getMetadata(): Partial<TransformMetadata>;
+
+	/**
+	 * Reset plugin state (called before each transform)
+	 */
+	reset(): void;
+}
+
+/**
+ * Optimizer plugin - optimizes transformed code
+ */
+export interface OptimizerPlugin extends CompilerPlugin {
+	/**
+	 * Optimize AST after all transformations
+	 */
+	optimize(ast: t.File, config: CompilerConfig): t.File | Promise<t.File>;
+}
+
+/**
+ * Validator plugin - validates code before/after transformation
+ */
+export interface ValidatorPlugin extends CompilerPlugin {
+	/**
+	 * Validate code (throw error if invalid)
+	 */
+	validate(code: string, ast: t.File, phase: 'pre' | 'post'): void | Promise<void>;
+}
+
+/**
+ * Babel visitor type (simplified)
+ */
+export interface BabelVisitor {
+	[key: string]: (path: NodePath<any>) => void;
+}
+
+/**
+ * Plugin context - shared state during transformation
+ */
+export interface PluginContext {
+	config: CompilerConfig;
+	executionId?: string;
+	metadata: TransformMetadata;
+	patterns: Set<AsyncPattern>;
+}
+
+/**
+ * Plugin registry for managing plugins
+ */
+export class PluginRegistry {
+	private detectors: DetectionPlugin[] = [];
+	private transformers: TransformationPlugin[] = [];
+	private optimizers: OptimizerPlugin[] = [];
+	private validators: ValidatorPlugin[] = [];
+
+	/**
+	 * Register a plugin
+	 */
+	register(plugin: CompilerPlugin): void {
+		// Check for name conflicts
+		if (this.findPlugin(plugin.name)) {
+			throw new Error(
+				`Plugin "${plugin.name}" is already registered. ` +
+					`Please use a unique name or unregister the existing plugin first.`
+			);
+		}
+
+		// Type guards to determine plugin type
+		if (this.isDetectionPlugin(plugin)) {
+			this.detectors.push(plugin);
+			this.detectors.sort((a, b) => (b.priority || 50) - (a.priority || 50));
+		}
+
+		if (this.isTransformationPlugin(plugin)) {
+			this.transformers.push(plugin);
+			this.transformers.sort((a, b) => (b.priority || 50) - (a.priority || 50));
+		}
+
+		if (this.isOptimizerPlugin(plugin)) {
+			this.optimizers.push(plugin);
+			this.optimizers.sort((a, b) => (b.priority || 50) - (a.priority || 50));
+		}
+
+		if (this.isValidatorPlugin(plugin)) {
+			this.validators.push(plugin);
+			this.validators.sort((a, b) => (b.priority || 50) - (a.priority || 50));
+		}
+	}
+
+	/**
+	 * Find a plugin by name
+	 */
+	findPlugin(name: string): CompilerPlugin | undefined {
+		const allPlugins = [
+			...this.detectors,
+			...this.transformers,
+			...this.optimizers,
+			...this.validators,
+		];
+		return allPlugins.find((p) => p.name === name);
+	}
+
+	/**
+	 * Unregister a plugin by name
+	 */
+	unregister(name: string): boolean {
+		let removed = false;
+
+		this.detectors = this.detectors.filter((p) => {
+			if (p.name === name) {
+				removed = true;
+				return false;
+			}
+			return true;
+		});
+
+		this.transformers = this.transformers.filter((p) => {
+			if (p.name === name) {
+				removed = true;
+				return false;
+			}
+			return true;
+		});
+
+		this.optimizers = this.optimizers.filter((p) => {
+			if (p.name === name) {
+				removed = true;
+				return false;
+			}
+			return true;
+		});
+
+		this.validators = this.validators.filter((p) => {
+			if (p.name === name) {
+				removed = true;
+				return false;
+			}
+			return true;
+		});
+
+		return removed;
+	}
+
+	/**
+	 * Get all detection plugins
+	 */
+	getDetectors(): DetectionPlugin[] {
+		return this.detectors;
+	}
+
+	/**
+	 * Get all transformation plugins
+	 */
+	getTransformers(): TransformationPlugin[] {
+		return this.transformers;
+	}
+
+	/**
+	 * Get all optimizer plugins
+	 */
+	getOptimizers(): OptimizerPlugin[] {
+		return this.optimizers;
+	}
+
+	/**
+	 * Get all validator plugins
+	 */
+	getValidators(): ValidatorPlugin[] {
+		return this.validators;
+	}
+
+	/**
+	 * Initialize all plugins
+	 */
+	async initializeAll(config: CompilerConfig): Promise<void> {
+		const allPlugins = [
+			...this.detectors,
+			...this.transformers,
+			...this.optimizers,
+			...this.validators,
+		];
+
+		for (const plugin of allPlugins) {
+			if (plugin.initialize) {
+				await plugin.initialize(config);
+			}
+		}
+	}
+
+	/**
+	 * Dispose all plugins
+	 */
+	async disposeAll(): Promise<void> {
+		const allPlugins = [
+			...this.detectors,
+			...this.transformers,
+			...this.optimizers,
+			...this.validators,
+		];
+
+		for (const plugin of allPlugins) {
+			if (plugin.dispose) {
+				await plugin.dispose();
+			}
+		}
+	}
+
+	/**
+	 * Type guards
+	 */
+	private isDetectionPlugin(plugin: CompilerPlugin): plugin is DetectionPlugin {
+		return 'detect' in plugin && 'patterns' in plugin;
+	}
+
+	private isTransformationPlugin(plugin: CompilerPlugin): plugin is TransformationPlugin {
+		return 'getVisitor' in plugin && 'getMetadata' in plugin && 'reset' in plugin;
+	}
+
+	private isOptimizerPlugin(plugin: CompilerPlugin): plugin is OptimizerPlugin {
+		return 'optimize' in plugin;
+	}
+
+	private isValidatorPlugin(plugin: CompilerPlugin): plugin is ValidatorPlugin {
+		return 'validate' in plugin;
+	}
+}
+
+/**
+ * Utility function to create a simple transformation plugin
+ */
+export function createTransformPlugin(config: {
+	name: string;
+	version: string;
+	priority?: number;
+	visitor: BabelVisitor;
+	getMetadata?: () => Partial<TransformMetadata>;
+}): TransformationPlugin {
+	let transformCount = 0;
+
+	return {
+		name: config.name,
+		version: config.version,
+		priority: config.priority || 50,
+
+		getVisitor() {
+			return config.visitor;
+		},
+
+		getMetadata() {
+			return config.getMetadata ? config.getMetadata() : { loopCount: transformCount };
+		},
+
+		reset() {
+			transformCount = 0;
+		},
+	};
+}
+

package/src/transformer/index.ts

@@ -12,8 +12,13 @@ import type { TransformResult, CompilerConfig, TransformMetadata } from '../type
 import { DEFAULT_COMPILER_CONFIG } from '../types.js';
 import { TransformationError } from '../runtime/errors.js';
 import { resetIdCounter } from '../runtime/context.js';
+import type { ICompiler } from '../types/compiler-interface.js';
 
-export class ATPCompiler {
+/**
+ * ATP Compiler - Standard compiler for transforming code to support resumability
+ * Implements ICompiler interface for consistency and dependency injection support
+ */
+export class ATPCompiler implements ICompiler {
 	private config: CompilerConfig;
 	private detector: AsyncIterationDetector;
 	private loopTransformer: LoopTransformer;
@@ -144,6 +149,21 @@ export class ATPCompiler {
 			t.isIdentifier(callee.property, { name: 'allSettled' })
 		);
 	}
+
+	/**
+	 * Get the compiler type identifier (ICompiler interface requirement)
+	 */
+	getType(): string {
+		return 'ATPCompiler';
+	}
+
+	/**
+	 * Get cache statistics (ICompiler interface requirement)
+	 * ATPCompiler doesn't cache ASTs, so returns null
+	 */
+	getCacheStats() {
+		return null;
+	}
 }
 
 export * from './detector.js';

package/src/types/compiler-interface.ts

@@ -0,0 +1,79 @@
+/**
+ * Core compiler interface for ATP
+ * All ATP compilers must implement this interface to ensure consistency
+ */
+
+import type { DetectionResult, TransformResult } from '../types.js';
+
+/**
+ * ICompiler - The core interface that all ATP compilers must implement
+ * 
+ * This interface defines the contract for any compiler in the ATP system,
+ * enabling dependency injection and easy extensibility.
+ * 
+ * @example
+ * ```typescript
+ * class MyCustomCompiler implements ICompiler {
+ *   detect(code: string): DetectionResult {
+ *     // Detection logic
+ *   }
+ *   
+ *   transform(code: string): TransformResult {
+ *     // Transformation logic
+ *   }
+ *   
+ *   getType(): string {
+ *     return 'MyCustomCompiler';
+ *   }
+ * }
+ * ```
+ */
+export interface ICompiler {
+	/**
+	 * Detect if code needs transformation and what patterns it contains
+	 * Can be synchronous or asynchronous
+	 */
+	detect(code: string): DetectionResult | Promise<DetectionResult>;
+
+	/**
+	 * Transform the code based on detected patterns
+	 * Can be synchronous or asynchronous
+	 */
+	transform(code: string): TransformResult | Promise<TransformResult>;
+
+	/**
+	 * Get the compiler type identifier
+	 */
+	getType(): string;
+
+	/**
+	 * Get cache statistics (optional)
+	 * Useful for performance monitoring and debugging
+	 */
+	getCacheStats?(): CacheStats | null;
+}
+
+/**
+ * Cache statistics structure
+ */
+export interface CacheStats {
+	size: number;
+	enabled: boolean;
+}
+
+/**
+ * Type guard to check if an object implements ICompiler
+ */
+export function isCompiler(obj: unknown): obj is ICompiler {
+	return (
+		typeof obj === 'object' &&
+		obj !== null &&
+		'detect' in obj &&
+		'transform' in obj &&
+		'getType' in obj &&
+		typeof (obj as any).detect === 'function' &&
+		typeof (obj as any).transform === 'function' &&
+		typeof (obj as any).getType === 'function'
+	);
+}
+