0xray 4.0.13 → 4.0.14

package/dist/enforcement/core/rule-executor.js

@@ -0,0 +1,364 @@
+/**
+ * Rule Executor - Orchestrate validation execution
+ *
+ * This class orchestrates the execution of validation rules, handling
+ * single rule execution, batch execution, parallel vs serial execution,
+ * dependency ordering, timeouts, and error handling.
+ *
+ * Phase 5 refactoring: Extracted from RuleEnforcer.
+ *
+ * @module enforcement/core
+ *
+ * @example
+ * ```typescript
+ * const executor = new RuleExecutor(registry, hierarchy, validatorRegistry);
+ *
+ * // Execute all applicable rules for an operation
+ * const report = await executor.execute('write', context);
+ *
+ * // Execute a specific rule
+ * const result = await executor.executeSingle('no-duplicate-code', context);
+ *
+ * // Execute multiple rules in batch
+ * const results = await executor.executeBatch(['rule1', 'rule2'], context);
+ * ```
+ */
+import { frameworkLogger } from '../../core/framework-logger.js';
+import { isRuleValidationResult, } from '../types.js';
+/**
+ * RuleExecutor orchestrates the execution of validation rules.
+ *
+ * Key responsibilities:
+ * - Execute single rules
+ * - Execute rules in batch (parallel or serial)
+ * - Sort rules by dependency order
+ * - Handle timeouts and errors
+ * - Generate validation reports
+ */
+export class RuleExecutor {
+    registry;
+    hierarchy;
+    validatorRegistry;
+    /** Default timeout for rule validation in milliseconds */
+    DEFAULT_TIMEOUT_MS = 30000;
+    constructor(registry, hierarchy, validatorRegistry) {
+        this.registry = registry;
+        this.hierarchy = hierarchy;
+        this.validatorRegistry = validatorRegistry;
+    }
+    /**
+     * Execute validation for an operation against all applicable rules.
+     *
+     * This method:
+     * 1. Gets all applicable rules for the operation
+     * 2. Sorts them by dependency order
+     * 3. Executes each rule
+     * 4. Collects results and generates a validation report
+     *
+     * @param operation - The operation being performed (e.g., 'write', 'create')
+     * @param context - Validation context with code and operation info
+     * @param options - Optional execution options
+     * @returns Promise resolving to validation report
+     *
+     * @example
+     * ```typescript
+     * const report = await executor.execute('write', {
+     *   operation: 'write',
+     *   files: ['src/index.ts'],
+     *   newCode: 'console.log("hello");'
+     * });
+     *
+     * console.log(report.passed); // false if any rule failed
+     * console.log(report.errors); // Array of error messages
+     * ```
+     */
+    async execute(operation, context, options) {
+        const applicableRules = this.getApplicableRules(operation, context);
+        await frameworkLogger.log('rule-executor', 'execute-start', 'info', {
+            operation,
+            ruleCount: applicableRules.length,
+            rules: applicableRules.map(r => r.id),
+        });
+        const results = [];
+        const errors = [];
+        const warnings = [];
+        // Always sort rules by dependency order for execute()
+        const sortedRules = this.sortByDependencyOrder(applicableRules);
+        // Execute rules
+        if (options?.parallel) {
+            // Execute in parallel
+            const batchResults = await this.executeParallel(sortedRules, context, options);
+            this.processResults(batchResults, sortedRules, results, errors, warnings);
+        }
+        else {
+            // Execute serially
+            const executedRules = new Set();
+            for (const rule of sortedRules) {
+                // Check if dependencies are satisfied
+                if (!this.hierarchy.isDependencySatisfied(rule.id, executedRules)) {
+                    const deps = this.hierarchy.getDependencies(rule.id);
+                    warnings.push(`${rule.id}: dependencies not satisfied (requires: ${deps.join(', ')})`);
+                    executedRules.add(rule.id);
+                    continue;
+                }
+                try {
+                    const result = await this.executeRuleWithTimeout(rule, context, options?.timeoutMs || this.DEFAULT_TIMEOUT_MS);
+                    this.processResult(result, rule, results, errors, warnings);
+                    executedRules.add(rule.id);
+                    // Stop on first error if requested
+                    if (options?.stopOnError && errors.length > 0) {
+                        break;
+                    }
+                }
+                catch (error) {
+                    const errorMessage = `Rule ${rule.name} failed: ${error instanceof Error ? error.message : String(error)}`;
+                    errors.push(errorMessage);
+                    executedRules.add(rule.id);
+                    await frameworkLogger.log('rule-executor', 'rule-execution-error', 'error', {
+                        ruleId: rule.id,
+                        operation,
+                        error: errorMessage,
+                    });
+                    // Stop on first error if requested
+                    if (options?.stopOnError) {
+                        break;
+                    }
+                }
+            }
+        }
+        const report = {
+            operation,
+            passed: errors.length === 0,
+            errors,
+            warnings,
+            results,
+            timestamp: new Date(),
+        };
+        await frameworkLogger.log('rule-executor', 'execute-complete', report.passed ? 'success' : 'error', {
+            operation,
+            passed: report.passed,
+            errorCount: errors.length,
+            warningCount: warnings.length,
+        });
+        return report;
+    }
+    /**
+     * Execute a single rule by ID.
+     *
+     * @param ruleId - The ID of the rule to execute
+     * @param context - Validation context
+     * @returns Promise resolving to validation result
+     * @throws Error if rule not found or not enabled
+     *
+     * @example
+     * ```typescript
+     * const result = await executor.executeSingle('no-duplicate-code', context);
+     * console.log(result.passed); // true or false
+     * ```
+     */
+    async executeSingle(ruleId, context) {
+        const rule = this.registry.getRule(ruleId);
+        if (!rule) {
+            throw new Error(`Rule with ID "${ruleId}" not found`);
+        }
+        if (!rule.enabled) {
+            throw new Error(`Rule "${ruleId}" is disabled`);
+        }
+        return this.executeRuleWithTimeout(rule, context, this.DEFAULT_TIMEOUT_MS);
+    }
+    /**
+     * Execute multiple rules in batch.
+     *
+     * Supports parallel or serial execution based on options.
+     * Optionally sorts rules by dependency order before execution.
+     *
+     * @param ruleIds - Array of rule IDs to execute
+     * @param context - Validation context
+     * @param options - Optional batch execution options
+     * @returns Promise resolving to array of validation results
+     *
+     * @example
+     * ```typescript
+     * const results = await executor.executeBatch(
+     *   ['no-duplicate-code', 'tests-required'],
+     *   context,
+     *   { parallel: true, sortByDependencies: true }
+     * );
+     * ```
+     */
+    async executeBatch(ruleIds, context, options) {
+        // Get rule definitions
+        const rules = [];
+        for (const id of ruleIds) {
+            const rule = this.registry.getRule(id);
+            if (rule && rule.enabled) {
+                rules.push(rule);
+            }
+        }
+        // Sort by dependencies if requested
+        const sortedRules = options?.sortByDependencies !== false
+            ? this.sortByDependencyOrder(rules)
+            : rules;
+        if (options?.parallel) {
+            return this.executeParallel(sortedRules, context, options);
+        }
+        else {
+            const results = [];
+            for (const rule of sortedRules) {
+                const result = await this.executeRuleWithTimeout(rule, context, options?.timeoutMs || this.DEFAULT_TIMEOUT_MS);
+                results.push(result);
+                if (options?.stopOnError && !result.passed) {
+                    break;
+                }
+            }
+            return results;
+        }
+    }
+    /**
+     * Execute a rule with timeout protection.
+     *
+     * @param rule - The rule definition to execute
+     * @param context - Validation context
+     * @param timeoutMs - Timeout in milliseconds
+     * @returns Promise resolving to validation result
+     */
+    async executeRuleWithTimeout(rule, context, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new Error(`Rule ${rule.id} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            rule.validator(context)
+                .then(result => {
+                clearTimeout(timeoutId);
+                resolve(result);
+            })
+                .catch(error => {
+                clearTimeout(timeoutId);
+                reject(error);
+            });
+        });
+    }
+    /**
+     * Execute rules in parallel.
+     *
+     * @param rules - Array of rules to execute
+     * @param context - Validation context
+     * @param options - Execution options
+     * @returns Promise resolving to array of results
+     */
+    async executeParallel(rules, context, options) {
+        const concurrency = options?.concurrency || rules.length;
+        const results = [];
+        // Process in chunks based on concurrency limit
+        for (let i = 0; i < rules.length; i += concurrency) {
+            const chunk = rules.slice(i, i + concurrency);
+            const chunkPromises = chunk.map(rule => this.executeRuleWithTimeout(rule, context, options?.timeoutMs || this.DEFAULT_TIMEOUT_MS).catch(error => ({
+                passed: false,
+                message: `Rule ${rule.id} failed: ${error instanceof Error ? error.message : String(error)}`,
+            })));
+            const chunkResults = await Promise.all(chunkPromises);
+            results.push(...chunkResults);
+            // Stop on first error if requested
+            if (options?.stopOnError && chunkResults.some(r => !r.passed)) {
+                break;
+            }
+        }
+        return results;
+    }
+    /**
+     * Sort rules by dependency order using the hierarchy.
+     *
+     * @param rules - Array of rules to sort
+     * @returns Sorted array of rules
+     */
+    sortByDependencyOrder(rules) {
+        const ruleIds = rules.map(r => r.id);
+        const orderedIds = this.hierarchy.getExecutionOrder(ruleIds);
+        // Map ordered IDs back to rule definitions
+        const ruleMap = new Map(rules.map(r => [r.id, r]));
+        return orderedIds
+            .map(id => ruleMap.get(id))
+            .filter((r) => r !== undefined);
+    }
+    /**
+     * Process a single result and categorize errors/warnings.
+     */
+    processResult(result, rule, results, errors, warnings) {
+        if (isRuleValidationResult(result) && result.passed === false) {
+            results.push(result);
+            if (rule.severity === 'error' || rule.severity === 'blocking' || rule.severity === 'high') {
+                errors.push(`${rule.name}: ${result.message}`);
+            }
+            else if (rule.severity === 'warning') {
+                warnings.push(`${rule.name}: ${result.message}`);
+            }
+        }
+    }
+    /**
+     * Process multiple results and categorize errors/warnings.
+     */
+    processResults(batchResults, rules, results, errors, warnings) {
+        batchResults.forEach((result, index) => {
+            const rule = rules[index];
+            if (rule && isRuleValidationResult(result) && result.passed === false) {
+                results.push(result);
+                if (rule.severity === 'error' || rule.severity === 'blocking' || rule.severity === 'high') {
+                    errors.push(`${rule.name}: ${result.message}`);
+                }
+                else if (rule.severity === 'warning') {
+                    warnings.push(`${rule.name}: ${result.message}`);
+                }
+            }
+        });
+    }
+    /**
+     * Get applicable rules for an operation and context.
+     *
+     * @param operation - The operation being performed
+     * @param context - Validation context
+     * @returns Array of applicable rule definitions
+     */
+    getApplicableRules(operation, context) {
+        return this.registry.getRules().filter(rule => this.isRuleApplicable(rule, operation, context));
+    }
+    /**
+     * Check if a rule is applicable to the current operation.
+     *
+     * @param rule - The rule definition
+     * @param operation - The operation being performed
+     * @param context - Validation context
+     * @returns true if the rule is applicable
+     */
+    isRuleApplicable(rule, operation, context) {
+        if (!rule.enabled)
+            return false;
+        // Check operation type for specific rules
+        switch (rule.id) {
+            case 'tests-required':
+                return operation === 'write' || operation === 'create';
+            case 'no-duplicate-code':
+                return operation === 'write' && !!context.newCode;
+            case 'no-over-engineering':
+                return operation === 'write' && !!context.newCode;
+            case 'resolve-all-errors':
+                return operation === 'write' && !!context.newCode;
+            case 'prevent-infinite-loops':
+                return operation === 'write' && !!context.newCode;
+            case 'state-management-patterns':
+                return operation === 'write' && !!context.newCode;
+            case 'import-consistency':
+                return operation === 'write' && !!context.newCode;
+            case 'documentation-required':
+                return operation === 'write' || operation === 'modify';
+            case 'clean-debug-logs':
+                return operation === 'write' && !!context.newCode;
+            case 'console-log-usage':
+                return operation === 'write' && !!context.newCode;
+            case 'src-dist-integrity':
+                return ((operation === 'write' || operation === 'copy' || operation === 'modify') &&
+                    !!context.files);
+            default:
+                return true;
+        }
+    }
+}

package/dist/enforcement/core/rule-hierarchy.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Rule Hierarchy - Manage rule dependencies and execution order
+ *
+ * This class manages rule dependencies and calculates execution order.
+ * It uses topological sorting to ensure dependencies are validated before dependents.
+ *
+ * Phase 5 refactoring: Extracted from RuleEnforcer.
+ *
+ * @module enforcement/core
+ *
+ * @example
+ * ```typescript
+ * const hierarchy = new RuleHierarchy();
+ * hierarchy.addDependency('tests-required', ['no-duplicate-code']);
+ * hierarchy.addDependency('memory-optimization', ['context-analysis-integration']);
+ *
+ * const order = hierarchy.getExecutionOrder(['tests-required', 'memory-optimization']);
+ * // Result: ['no-duplicate-code', 'tests-required', 'context-analysis-integration', 'memory-optimization']
+ * ```
+ */
+import { IRuleHierarchy } from '../types.js';
+/**
+ * RuleHierarchy manages rule dependency relationships and execution ordering.
+ *
+ * Key responsibilities:
+ * - Track rule dependencies (A depends on B)
+ * - Calculate execution order via topological sort
+ * - Detect circular dependencies
+ * - Check dependency satisfaction
+ */
+export declare class RuleHierarchy implements IRuleHierarchy {
+    /** Map of rule IDs to their dependencies */
+    private dependencies;
+    /** Map of rule IDs to rules that depend on them */
+    private dependents;
+    /**
+     * Add a dependency relationship.
+     * The rule will be executed after all its dependencies.
+     *
+     * @param ruleId - The rule that depends on others
+     * @param dependsOn - Array of rule IDs that must be executed first
+     *
+     * @example
+     * ```typescript
+     * hierarchy.addDependency('tests-required', ['no-duplicate-code']);
+     * // tests-required will be validated after no-duplicate-code
+     * ```
+     */
+    addDependency(ruleId: string, dependsOn: string[]): void;
+    /**
+     * Get all dependencies for a rule.
+     *
+     * @param ruleId - The rule to get dependencies for
+     * @returns Array of rule IDs that the rule depends on
+     *
+     * @example
+     * ```typescript
+     * const deps = hierarchy.getDependencies('tests-required');
+     * console.log(deps); // ['no-duplicate-code']
+     * ```
+     */
+    getDependencies(ruleId: string): string[];
+    /**
+     * Get all rules that depend on the given rule.
+     *
+     * @param ruleId - The rule to get dependents for
+     * @returns Array of rule IDs that depend on this rule
+     *
+     * @example
+     * ```typescript
+     * const dependents = hierarchy.getDependents('no-duplicate-code');
+     * console.log(dependents); // ['tests-required']
+     * ```
+     */
+    getDependents(ruleId: string): string[];
+    /**
+     * Get the execution order for a set of rules using topological sort.
+     * Rules are returned in order such that dependencies come before dependents.
+     *
+     * Uses Kahn's algorithm for topological sorting.
+     *
+     * @param ruleIds - Array of rule IDs to order
+     * @returns Sorted array of rule IDs in dependency order
+     *
+     * @example
+     * ```typescript
+     * const order = hierarchy.getExecutionOrder(['tests-required', 'no-duplicate-code']);
+     * // Result: ['no-duplicate-code', 'tests-required']
+     * ```
+     */
+    getExecutionOrder(ruleIds: string[]): string[];
+    /**
+     * Check if any circular dependencies exist in the hierarchy.
+     *
+     * @returns true if circular dependencies exist, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (hierarchy.hasCircularDependencies()) {
+     *   console.error('Circular dependencies detected!');
+     * }
+     * ```
+     */
+    hasCircularDependencies(): boolean;
+    /**
+     * Find all circular dependency cycles.
+     * Uses DFS to detect cycles in the dependency graph.
+     *
+     * @returns Array of cycles, where each cycle is an array of rule IDs
+     *
+     * @example
+     * ```typescript
+     * const cycles = hierarchy.findCircularDependencies();
+     * // cycles might be [['rule-a', 'rule-b', 'rule-c']]
+     * ```
+     */
+    findCircularDependencies(): string[][];
+    /**
+     * Check if all dependencies for a rule have been executed.
+     *
+     * @param ruleId - The rule to check
+     * @param executedRules - Set of rule IDs that have already been executed
+     * @returns true if all dependencies are satisfied, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const executed = new Set(['no-duplicate-code']);
+     * if (hierarchy.isDependencySatisfied('tests-required', executed)) {
+     *   // Safe to execute tests-required
+     * }
+     * ```
+     */
+    isDependencySatisfied(ruleId: string, executedRules: Set<string>): boolean;
+    /**
+     * Clear all dependency relationships.
+     * Useful for testing or reinitializing.
+     */
+    clear(): void;
+    /**
+     * Get all rules that have dependencies registered.
+     *
+     * @returns Array of rule IDs with dependencies
+     */
+    getAllRules(): string[];
+}