@mondaydotcomorg/atp-compiler 0.17.16 → 0.18.4-rc.0

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/array-transformer-utils.ts

@@ -1,11 +1,10 @@
 import * as t from '@babel/types';
+import { isArrayMethod } from './utils.js';
 
 /**
- * Find LLM call expression in callback body
+ * Find LLM call expression in AST node
  */
-export function findLLMCallExpression(
-	body: t.BlockStatement | t.Expression
-): t.CallExpression | null {
+export function findLLMCallExpression(body: t.Node): t.CallExpression | null {
 	let found: t.CallExpression | null = null;
 
 	const visit = (node: t.Node) => {
@@ -42,9 +41,6 @@ export function findLLMCallExpression(
  */
 export function getArrayMethodName(node: t.CallExpression): string | null {
 	const arrayMethods = ['map', 'forEach', 'filter', 'reduce', 'find', 'some', 'every', 'flatMap'];
-
-	const { isArrayMethod } = require('./utils.js');
-
 	for (const method of arrayMethods) {
 		if (isArrayMethod(node, method)) {
 			return method;

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/transformer/loop-transformer.ts

@@ -1,8 +1,9 @@
 import * as t from '@babel/types';
 import { generateUniqueId } from '../runtime/context.js';
-import { containsAwait } from './utils.js';
+import { containsAwait, extractForOfParamName } from './utils.js';
 import { BatchOptimizer } from './batch-optimizer.js';
 import { BatchParallelDetector } from './batch-detector.js';
+import { findLLMCallExpression } from './array-transformer-utils.js';
 
 export class LoopTransformer {
 	private transformCount = 0;
@@ -46,27 +47,10 @@ export class LoopTransformer {
 	 */
 	private transformForOfToBatch(path: any, node: t.ForOfStatement): boolean {
 		const loopId = generateUniqueId('for_of_batch');
-		const left = node.left;
 		const right = node.right;
+		const paramName = extractForOfParamName(node.left);
 
-		let paramName: string;
-		if (t.isVariableDeclaration(left)) {
-			const id = left.declarations[0]?.id;
-			paramName = t.isIdentifier(id) ? id.name : 'item';
-		} else if (t.isIdentifier(left)) {
-			paramName = left.name;
-		} else {
-			paramName = 'item';
-		}
-
-		const bodyStatements = t.isBlockStatement(node.body) ? node.body.body : [node.body];
-		const callback = t.arrowFunctionExpression(
-			[t.identifier(paramName)],
-			t.blockStatement(bodyStatements),
-			true
-		);
-
-		const llmCall = this.findLLMCallInBody(node.body);
+		const llmCall = findLLMCallExpression(node.body);
 		if (!llmCall) {
 			return this.transformForOfToSequential(path, node);
 		}
@@ -109,18 +93,8 @@ export class LoopTransformer {
 	 */
 	private transformForOfToSequential(path: any, node: t.ForOfStatement): boolean {
 		const loopId = generateUniqueId('for_of');
-		const left = node.left;
 		const right = node.right;
-
-		let paramName: string;
-		if (t.isVariableDeclaration(left)) {
-			const id = left.declarations[0]?.id;
-			paramName = t.isIdentifier(id) ? id.name : 'item';
-		} else if (t.isIdentifier(left)) {
-			paramName = left.name;
-		} else {
-			paramName = 'item';
-		}
+		const paramName = extractForOfParamName(node.left);
 
 		const bodyStatements = t.isBlockStatement(node.body) ? node.body.body : [node.body];
 
@@ -142,41 +116,6 @@ export class LoopTransformer {
 		return true;
 	}
 
-	/**
-	 * Find LLM call in loop body
-	 */
-	private findLLMCallInBody(body: t.Statement | t.BlockStatement): t.CallExpression | null {
-		let found: t.CallExpression | null = null;
-
-		const visit = (node: t.Node) => {
-			if (found) return;
-
-			if (t.isAwaitExpression(node) && t.isCallExpression(node.argument)) {
-				const call = node.argument;
-				if (t.isMemberExpression(call.callee)) {
-					found = call;
-					return;
-				}
-			}
-
-			Object.keys(node).forEach((key) => {
-				const value = (node as any)[key];
-				if (Array.isArray(value)) {
-					value.forEach((item) => {
-						if (item && typeof item === 'object' && item.type) {
-							visit(item);
-						}
-					});
-				} else if (value && typeof value === 'object' && value.type) {
-					visit(value);
-				}
-			});
-		};
-
-		visit(body);
-		return found;
-	}
-
 	transformWhileLoop(path: any): boolean {
 		const node = path.node as t.WhileStatement;
 

package/src/transformer/utils.ts

@@ -145,3 +145,17 @@ export function isArrayMethod(node: t.Node, methodName: string): boolean {
 
 	return t.isIdentifier(callee.property) && callee.property.name === methodName;
 }
+
+/**
+ * Extract parameter name from ForOfStatement left side
+ */
+export function extractForOfParamName(left: t.VariableDeclaration | t.LVal): string {
+	if (t.isVariableDeclaration(left)) {
+		const id = left.declarations[0]?.id;
+		return t.isIdentifier(id) ? id.name : 'item';
+	} else if (t.isIdentifier(left)) {
+		return left.name;
+	} else {
+		return 'item';
+	}
+}

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'
+	);
+}
+