timonel 3.1.1 → 3.1.2

package/dist/lib/policy/policyEngine.d.ts

@@ -1,5 +1,17 @@
+/**
+ * Policy Engine Implementation
+ *
+ * This module provides the main PolicyEngine class that orchestrates policy validation
+ * through registered plugins. It implements the core policy engine interface with
+ * plugin management, validation orchestration, and result aggregation.
+ *
+ * @since 3.0.0
+ */
 import type { ChartMetadata } from '../rutter.js';
 import type { PolicyEngine as IPolicyEngine, PolicyPlugin, PolicyEngineOptions, PolicyResult, PolicyViolation, PolicyWarning, ValidationContext } from './types.js';
+/**
+ * Main policy engine implementation
+ */
 export declare class PolicyEngine implements IPolicyEngine {
     private readonly registry;
     private options;
@@ -10,30 +22,155 @@ export declare class PolicyEngine implements IPolicyEngine {
     private _cache?;
     private _parallelExecutor?;
     constructor(options?: PolicyEngineOptions);
+    /**
+     * Lazy getter for configuration loader
+     * @private
+     */
     private get configurationLoader();
+    /**
+     * Lazy getter for validation cache
+     * @private
+     */
     private get cache();
+    /**
+     * Lazy getter for parallel executor
+     * @private
+     */
     private get parallelExecutor();
+    /**
+     * Registers a policy plugin for validation
+     * @param plugin - The policy plugin to register
+     * @returns The engine instance for method chaining
+     */
     use(plugin: PolicyPlugin): Promise<PolicyEngine>;
+    /**
+     * Validates Kubernetes manifests against registered policies
+     * @param manifests - Array of Kubernetes manifest objects
+     * @param chartMetadata - Chart metadata for validation context
+     * @returns Promise resolving to validation results
+     */
     validate(manifests: unknown[], chartMetadata: ChartMetadata): Promise<PolicyResult>;
+    /**
+     * Configures engine-wide settings
+     * @param options - Configuration options
+     */
     configure(options: PolicyEngineOptions): PolicyEngine;
+    /**
+     * Formats validation results using the configured formatter
+     * @param result - Validation result to format
+     * @returns Formatted string representation
+     */
     formatResult(result: PolicyResult): string;
+    /**
+     * Generates detailed error context for a violation
+     * @param violation - Policy violation
+     * @param validationContext - Validation context
+     * @param allViolations - All violations for finding related issues
+     * @param executionTime - Plugin execution time
+     * @returns Detailed error context
+     */
     generateErrorContext(violation: PolicyViolation | PolicyWarning, validationContext?: ValidationContext, allViolations?: (PolicyViolation | PolicyWarning)[], executionTime?: number): import("./errorContextGenerator.js").ErrorContext;
+    /**
+     * Generates a detailed error report for a violation
+     * @param violation - Policy violation
+     * @param validationContext - Validation context
+     * @param allViolations - All violations for finding related issues
+     * @param executionTime - Plugin execution time
+     * @returns Formatted error report string
+     */
     generateErrorReport(violation: PolicyViolation | PolicyWarning, validationContext?: ValidationContext, allViolations?: (PolicyViolation | PolicyWarning)[], executionTime?: number): string;
+    /**
+     * Gets cache statistics for monitoring
+     * @returns Cache statistics
+     */
     getCacheStats(): import("./validationCache.js").CacheStats;
+    /**
+     * Invalidates cache entries based on criteria
+     * @param criteria - Invalidation criteria
+     * @returns Number of invalidated entries
+     */
     invalidateCache(criteria: {
         manifestHash?: string;
         pluginHash?: string;
         olderThan?: number;
         all?: boolean;
     }): number;
+    /**
+     * Clears all cache statistics
+     */
     clearCacheStats(): void;
+    /**
+     * Executes plugins sequentially
+     * @param plugins - Array of plugins to execute
+     * @param manifests - Manifests to validate
+     * @param violations - Array to collect violations
+     * @param warnings - Array to collect warnings
+     * @private
+     */
     private executeSequential;
+    /**
+     * Executes plugins in parallel using the optimized parallel executor
+     * @param plugins - Array of plugins to execute
+     * @param manifests - Manifests to validate
+     * @param violations - Array to collect violations
+     * @param warnings - Array to collect warnings
+     * @private
+     */
     private executeParallelOptimized;
+    /**
+     * Executes a single plugin with timeout and retry handling
+     * @param plugin - Plugin to execute
+     * @param manifests - Manifests to validate
+     * @returns Promise resolving to plugin violations
+     * @private
+     */
     private executePlugin;
+    /**
+     * Executes a single plugin attempt with timeout handling
+     * @param plugin - Plugin to execute
+     * @param manifests - Manifests to validate
+     * @param attempt - Current attempt number
+     * @returns Promise resolving to plugin violations
+     * @private
+     */
     private executePluginAttempt;
+    /**
+     * Determines if an error should trigger a retry
+     * @param error - Error that occurred
+     * @param retryConfig - Retry configuration
+     * @returns True if the error should be retried
+     * @private
+     */
     private shouldRetryError;
+    /**
+     * Sleep for the specified number of milliseconds
+     * @param ms - Milliseconds to sleep
+     * @returns Promise that resolves after the delay
+     * @private
+     */
     private sleep;
+    /**
+     * Creates a timeout promise that rejects after the specified time
+     * @param timeout - Timeout in milliseconds
+     * @param pluginName - Name of the plugin for error reporting
+     * @returns Promise that rejects with timeout error
+     * @private
+     */
     private createTimeoutPromise;
+    /**
+     * Handles plugin execution errors with enhanced isolation and context
+     * @param plugin - Plugin that failed
+     * @param error - Error that occurred
+     * @param violations - Array to add error violation to
+     * @private
+     */
     private handlePluginError;
+    /**
+     * Generates helpful suggestions based on the error type
+     * @param error - Error that occurred
+     * @param plugin - Plugin that failed
+     * @returns Suggestion string
+     * @private
+     */
     private generateErrorSuggestion;
 }

package/dist/lib/policy/policyEngine.js

@@ -1,3 +1,12 @@
+/**
+ * Policy Engine Implementation
+ *
+ * This module provides the main PolicyEngine class that orchestrates policy validation
+ * through registered plugins. It implements the core policy engine interface with
+ * plugin management, validation orchestration, and result aggregation.
+ *
+ * @since 3.0.0
+ */
 import { createLogger } from '../utils/logger.js';
 import { InputValidator } from '../validation/inputValidator.js';
 import { PluginRegistry } from './pluginRegistry.js';
@@ -8,13 +17,22 @@ import { ErrorContextGenerator } from './errorContextGenerator.js';
 import { ConfigurationLoader } from './configurationLoader.js';
 import { ValidationCache, generateManifestHash, generatePluginHash } from './validationCache.js';
 import { ParallelExecutor, calculateOptimalConcurrency, } from './parallelExecutor.js';
+/**
+ * Constants for error messages
+ */
 const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+/**
+ * Default policy engine configuration
+ */
 const DEFAULT_OPTIONS = {
     timeout: 5000,
     parallel: false,
     failFast: false,
     gracefulDegradation: true,
 };
+/**
+ * Default retry configuration
+ */
 const DEFAULT_RETRY_CONFIG = {
     maxAttempts: 3,
     baseDelay: 1000,
@@ -23,6 +41,9 @@ const DEFAULT_RETRY_CONFIG = {
     retryOnTimeout: true,
     retryOnPluginError: false,
 };
+/**
+ * Common operation names for logging
+ */
 const OPERATIONS = {
     PLUGIN_REGISTRATION: 'plugin_registration',
     VALIDATION_START: 'validation_start',
@@ -30,6 +51,9 @@ const OPERATIONS = {
     PLUGIN_EXECUTION_ERROR: 'plugin_execution_error_isolated',
     PLUGIN_EXECUTION_RETRY: 'plugin_execution_retry',
 };
+/**
+ * Main policy engine implementation
+ */
 export class PolicyEngine {
     constructor(options = {}) {
         this.registry = new PluginRegistry();
@@ -44,6 +68,10 @@ export class PolicyEngine {
             operation: 'policy_engine_init',
         });
     }
+    /**
+     * Lazy getter for configuration loader
+     * @private
+     */
     get configurationLoader() {
         if (!this._configurationLoader) {
             this._configurationLoader = new ConfigurationLoader(this.options.configurationLoader);
@@ -53,6 +81,10 @@ export class PolicyEngine {
         }
         return this._configurationLoader;
     }
+    /**
+     * Lazy getter for validation cache
+     * @private
+     */
     get cache() {
         if (!this._cache) {
             this._cache = new ValidationCache(this.options.cacheOptions);
@@ -63,10 +95,14 @@ export class PolicyEngine {
         }
         return this._cache;
     }
+    /**
+     * Lazy getter for parallel executor
+     * @private
+     */
     get parallelExecutor() {
         if (!this._parallelExecutor) {
             const parallelOptions = {
-                maxConcurrency: this.options.parallelOptions?.maxConcurrency || calculateOptimalConcurrency(10),
+                maxConcurrency: this.options.parallelOptions?.maxConcurrency || calculateOptimalConcurrency(10), // Default estimate
                 pluginTimeout: this.options.timeout || DEFAULT_OPTIONS.timeout,
                 failFast: this.options.failFast || DEFAULT_OPTIONS.failFast,
                 ...this.options.parallelOptions,
@@ -79,8 +115,14 @@ export class PolicyEngine {
         }
         return this._parallelExecutor;
     }
+    /**
+     * Registers a policy plugin for validation
+     * @param plugin - The policy plugin to register
+     * @returns The engine instance for method chaining
+     */
     async use(plugin) {
         try {
+            // Input validation for plugin
             if (!plugin || typeof plugin !== 'object') {
                 throw new PolicyValidationError('Plugin must be a non-null object');
             }
@@ -93,11 +135,13 @@ export class PolicyEngine {
             if (typeof plugin.validate !== 'function') {
                 throw new PolicyValidationError('Plugin must have a validate method');
             }
+            // Validate plugin name length and content
             if (plugin.name.length > 100) {
                 throw new PolicyValidationError('Plugin name exceeds maximum length (100 characters)');
             }
+            // Sanitize plugin name to prevent injection
             const sanitizedName = plugin.name
-                .replace(/[<>"'&]/g, '')
+                .replace(/[<>"'&]/g, '') // Remove potentially dangerous characters
                 .trim();
             if (sanitizedName !== plugin.name) {
                 this.logger.warn('Plugin name was sanitized', {
@@ -106,7 +150,9 @@ export class PolicyEngine {
                     operation: 'plugin_name_sanitization',
                 });
             }
+            // Load configuration using the configuration loader
             const pluginConfiguration = await this.configurationLoader.loadPluginConfiguration(plugin, this.options.environment, this.options.pluginConfig?.[plugin.name]);
+            // Register plugin with loaded configuration
             this.registry.register(plugin, pluginConfiguration.config);
             this.logger.info('Plugin registered successfully', {
                 pluginName: plugin.name,
@@ -116,6 +162,7 @@ export class PolicyEngine {
                 configSources: pluginConfiguration.entries.map((e) => e.source),
                 operation: OPERATIONS.PLUGIN_REGISTRATION,
             });
+            // Log configuration validation warnings if any
             if (pluginConfiguration.validationErrors) {
                 this.logger.warn('Plugin configuration validation warnings', {
                     pluginName: plugin.name,
@@ -134,23 +181,36 @@ export class PolicyEngine {
             throw error;
         }
     }
+    /**
+     * Validates Kubernetes manifests against registered policies
+     * @param manifests - Array of Kubernetes manifest objects
+     * @param chartMetadata - Chart metadata for validation context
+     * @returns Promise resolving to validation results
+     */
     async validate(manifests, chartMetadata) {
         const startTime = Date.now();
+        // Input validation - validate manifests array
         if (!Array.isArray(manifests)) {
             throw new PolicyValidationError('Manifests must be an array');
         }
+        // Validate array length
         if (manifests.length > 1000) {
+            // Reasonable limit for manifests
             throw new PolicyValidationError('Too many manifests provided (maximum: 1000)');
         }
+        // Validate each manifest
         manifests.forEach((manifest, index) => {
             if (manifest === null || manifest === undefined) {
                 throw new PolicyValidationError(`Manifest at index ${index} cannot be null or undefined`);
             }
+            // Validate manifest size to prevent memory exhaustion
             const manifestStr = JSON.stringify(manifest);
             if (manifestStr.length > 100000) {
+                // 100KB limit per manifest
                 throw new PolicyValidationError(`Manifest at index ${index} exceeds size limit (100KB)`);
             }
         });
+        // Validate chartMetadata
         if (!chartMetadata || typeof chartMetadata !== 'object') {
             throw new PolicyValidationError('Chart metadata must be a non-null object');
         }
@@ -160,6 +220,7 @@ export class PolicyEngine {
             pluginCount: plugins.length,
             operation: OPERATIONS.VALIDATION_START,
         });
+        // Return successful result if no plugins are registered
         if (plugins.length === 0) {
             const metadata = {
                 executionTime: Date.now() - startTime,
@@ -183,10 +244,12 @@ export class PolicyEngine {
                 },
             };
         }
+        // Generate cache keys
         const manifestHash = generateManifestHash(manifests);
         const pluginNames = plugins.map((p) => p.name);
         const pluginConfigs = Object.fromEntries(pluginNames.map((name) => [name, this.registry.getPluginConfig(name)]));
         const pluginHash = generatePluginHash(pluginNames, pluginConfigs);
+        // Check cache first
         const cachedResult = this.cache.get(manifestHash, pluginHash);
         if (cachedResult) {
             this.logger.info('Returning cached validation result', {
@@ -230,6 +293,7 @@ export class PolicyEngine {
             metadata,
             summary: generateResultSummary(violations, warnings, plugins.map((p) => p.name)),
         };
+        // Cache the result
         this.cache.set(manifestHash, pluginHash, result);
         this.logger.info('Policy validation completed', {
             valid: result.valid,
@@ -241,6 +305,10 @@ export class PolicyEngine {
         });
         return result;
     }
+    /**
+     * Configures engine-wide settings
+     * @param options - Configuration options
+     */
     configure(options) {
         this.options = { ...this.options, ...options };
         this.logger.debug('PolicyEngine configuration updated', {
@@ -249,29 +317,72 @@ export class PolicyEngine {
         });
         return this;
     }
+    /**
+     * Formats validation results using the configured formatter
+     * @param result - Validation result to format
+     * @returns Formatted string representation
+     */
     formatResult(result) {
         const formatter = this.options.formatter || new DefaultResultFormatter();
         return formatter.format(result);
     }
+    /**
+     * Generates detailed error context for a violation
+     * @param violation - Policy violation
+     * @param validationContext - Validation context
+     * @param allViolations - All violations for finding related issues
+     * @param executionTime - Plugin execution time
+     * @returns Detailed error context
+     */
     generateErrorContext(violation, validationContext, allViolations, executionTime) {
         return this.errorContextGenerator.generateContext(violation, validationContext, allViolations, executionTime);
     }
+    /**
+     * Generates a detailed error report for a violation
+     * @param violation - Policy violation
+     * @param validationContext - Validation context
+     * @param allViolations - All violations for finding related issues
+     * @param executionTime - Plugin execution time
+     * @returns Formatted error report string
+     */
     generateErrorReport(violation, validationContext, allViolations, executionTime) {
         return this.errorContextGenerator.generateErrorReport(violation, validationContext, allViolations, executionTime);
     }
+    /**
+     * Gets cache statistics for monitoring
+     * @returns Cache statistics
+     */
     getCacheStats() {
         return this.cache.getStats();
     }
+    /**
+     * Invalidates cache entries based on criteria
+     * @param criteria - Invalidation criteria
+     * @returns Number of invalidated entries
+     */
     invalidateCache(criteria) {
         return this.cache.invalidate(criteria);
     }
+    /**
+     * Clears all cache statistics
+     */
     clearCacheStats() {
         this.cache.clearStats();
     }
+    /**
+     * Executes plugins sequentially
+     * @param plugins - Array of plugins to execute
+     * @param manifests - Manifests to validate
+     * @param violations - Array to collect violations
+     * @param warnings - Array to collect warnings
+     * @private
+     */
+    // eslint-disable-next-line sonarjs/cognitive-complexity
     async executeSequential(plugins, manifests, violations, warnings, chartMetadata) {
         for (const plugin of plugins) {
             try {
                 const pluginViolations = await this.executePlugin(plugin, manifests, chartMetadata);
+                // Separate violations by severity
                 for (const violation of pluginViolations) {
                     if (violation.severity === 'error') {
                         violations.push(violation);
@@ -280,6 +391,7 @@ export class PolicyEngine {
                         warnings.push(violation);
                     }
                 }
+                // Fail fast if enabled and we have errors
                 if (this.options.failFast && violations.length > 0) {
                     this.logger.debug('Fail fast enabled, stopping validation', {
                         pluginName: plugin.name,
@@ -290,18 +402,30 @@ export class PolicyEngine {
                 }
             }
             catch (error) {
+                // Handle plugin execution errors
                 if (this.options.gracefulDegradation) {
+                    // With graceful degradation, convert error to violation
                     this.handlePluginError(plugin, error, violations);
                 }
                 else {
+                    // Without graceful degradation, re-throw the error
                     throw error;
                 }
             }
         }
     }
+    /**
+     * Executes plugins in parallel using the optimized parallel executor
+     * @param plugins - Array of plugins to execute
+     * @param manifests - Manifests to validate
+     * @param violations - Array to collect violations
+     * @param warnings - Array to collect warnings
+     * @private
+     */
+    // eslint-disable-next-line sonarjs/cognitive-complexity
     async executeParallelOptimized(plugins, manifests, violations, warnings, chartMetadata) {
         const validationContext = {
-            chart: chartMetadata,
+            chart: chartMetadata, // Use actual chart metadata instead of hardcoded values
             environment: this.options.environment || 'development',
             logger: this.logger,
         };
@@ -315,16 +439,20 @@ export class PolicyEngine {
             totalMemoryMB: stats.resourceUsage.totalMemoryMB,
             operation: 'parallel_execution_stats',
         });
+        // Process results
         for (const result of results) {
             if (result.error) {
                 if (this.options.gracefulDegradation) {
+                    // With graceful degradation, convert error to violation
                     this.handlePluginError(result.plugin, result.error, violations);
                 }
                 else {
+                    // Without graceful degradation, throw the error
                     throw result.error;
                 }
             }
             else {
+                // Separate violations by severity
                 for (const violation of result.violations) {
                     if (violation.severity === 'error') {
                         violations.push(violation);
@@ -334,6 +462,7 @@ export class PolicyEngine {
                     }
                 }
             }
+            // Fail fast if enabled and we have errors
             if (this.options.failFast && violations.length > 0) {
                 this.logger.debug('Fail fast enabled, stopping validation', {
                     pluginName: result.plugin.name,
@@ -344,6 +473,13 @@ export class PolicyEngine {
             }
         }
     }
+    /**
+     * Executes a single plugin with timeout and retry handling
+     * @param plugin - Plugin to execute
+     * @param manifests - Manifests to validate
+     * @returns Promise resolving to plugin violations
+     * @private
+     */
     async executePlugin(plugin, manifests, chartMetadata) {
         const retryConfig = { ...DEFAULT_RETRY_CONFIG, ...this.options.retryConfig };
         let lastError = null;
@@ -360,10 +496,12 @@ export class PolicyEngine {
                     error: lastError.message,
                     operation: 'plugin_execution_retry',
                 });
+                // Check if we should retry this error type
                 const shouldRetry = this.shouldRetryError(lastError, retryConfig);
                 if (!shouldRetry || attempt === retryConfig.maxAttempts) {
                     break;
                 }
+                // Calculate delay with exponential backoff
                 const delay = Math.min(retryConfig.baseDelay * Math.pow(retryConfig.backoffMultiplier, attempt - 1), retryConfig.maxDelay);
                 this.logger.debug('Retrying plugin execution after delay', {
                     pluginName: plugin.name,
@@ -374,10 +512,20 @@ export class PolicyEngine {
                 await this.sleep(delay);
             }
         }
+        // All retry attempts exhausted - always throw error
+        // Let the calling method decide how to handle it based on gracefulDegradation setting
         const finalError = lastError ||
             new Error(`Plugin '${plugin.name}' failed with unknown error after ${retryConfig.maxAttempts} attempts`);
         throw new PluginRetryExhaustedError(`Plugin '${plugin.name}' failed after ${retryConfig.maxAttempts} attempts`, plugin.name, retryConfig.maxAttempts, finalError);
     }
+    /**
+     * Executes a single plugin attempt with timeout handling
+     * @param plugin - Plugin to execute
+     * @param manifests - Manifests to validate
+     * @param attempt - Current attempt number
+     * @returns Promise resolving to plugin violations
+     * @private
+     */
     async executePluginAttempt(plugin, manifests, attempt, chartMetadata) {
         const timeout = this.options.timeout || DEFAULT_OPTIONS.timeout;
         this.logger.debug('Executing plugin attempt', {
@@ -387,7 +535,7 @@ export class PolicyEngine {
             operation: 'plugin_execution_attempt_start',
         });
         const validationContext = {
-            chart: chartMetadata,
+            chart: chartMetadata, // Use actual chart metadata instead of hardcoded values
             config: this.registry.getPluginConfig(plugin.name),
             environment: this.options.environment || 'development',
             logger: this.logger,
@@ -424,6 +572,13 @@ export class PolicyEngine {
             throw error;
         }
     }
+    /**
+     * Determines if an error should trigger a retry
+     * @param error - Error that occurred
+     * @param retryConfig - Retry configuration
+     * @returns True if the error should be retried
+     * @private
+     */
     shouldRetryError(error, retryConfig) {
         if (error instanceof ValidationTimeoutError) {
             return retryConfig.retryOnTimeout;
@@ -431,11 +586,25 @@ export class PolicyEngine {
         if (error instanceof PluginError) {
             return retryConfig.retryOnPluginError;
         }
+        // Retry on generic errors if plugin error retry is enabled
         return retryConfig.retryOnPluginError;
     }
+    /**
+     * Sleep for the specified number of milliseconds
+     * @param ms - Milliseconds to sleep
+     * @returns Promise that resolves after the delay
+     * @private
+     */
     sleep(ms) {
         return new Promise((resolve) => globalThis.setTimeout(resolve, ms));
     }
+    /**
+     * Creates a timeout promise that rejects after the specified time
+     * @param timeout - Timeout in milliseconds
+     * @param pluginName - Name of the plugin for error reporting
+     * @returns Promise that rejects with timeout error
+     * @private
+     */
     createTimeoutPromise(timeout, pluginName) {
         return new Promise((_, reject) => {
             globalThis.setTimeout(() => {
@@ -443,6 +612,13 @@ export class PolicyEngine {
             }, timeout);
         });
     }
+    /**
+     * Handles plugin execution errors with enhanced isolation and context
+     * @param plugin - Plugin that failed
+     * @param error - Error that occurred
+     * @param violations - Array to add error violation to
+     * @private
+     */
     handlePluginError(plugin, error, violations) {
         const errorMessage = error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE;
         const errorStack = error instanceof Error ? error.stack : String(error);
@@ -453,14 +629,16 @@ export class PolicyEngine {
             errorType: error instanceof Error ? error.constructor.name : typeof error,
             operation: 'plugin_execution_error_isolated',
         });
+        // Create detailed error context for debugging
         const errorContext = {
             error: errorStack,
             pluginVersion: plugin.version,
             pluginMetadata: plugin.metadata,
             timestamp: new Date().toISOString(),
             errorType: error instanceof Error ? error.constructor.name : typeof error,
-            isolated: true,
+            isolated: true, // Mark as isolated error
         };
+        // Add plugin error as a violation with enhanced context
         const errorViolation = {
             plugin: plugin.name,
             severity: 'error',
@@ -471,12 +649,20 @@ export class PolicyEngine {
             context: errorContext,
         };
         violations.push(errorViolation);
+        // Log additional context for debugging
         this.logger.debug('Plugin error context generated', {
             pluginName: plugin.name,
             errorContext,
             operation: 'plugin_error_context',
         });
     }
+    /**
+     * Generates helpful suggestions based on the error type
+     * @param error - Error that occurred
+     * @param plugin - Plugin that failed
+     * @returns Suggestion string
+     * @private
+     */
     generateErrorSuggestion(error, plugin) {
         if (error instanceof ValidationTimeoutError) {
             return `Consider increasing the timeout value or optimizing the plugin '${plugin.name}' for better performance.`;