timonel 3.0.0 → 3.1.0

package/dist/lib/policy/pluginRegistry.js

@@ -0,0 +1,69 @@
+import { PluginRegistrationError } from './errors.js';
+export class PluginRegistry {
+    constructor() {
+        this.plugins = new Map();
+        this.pluginConfigs = new Map();
+    }
+    register(plugin, config) {
+        this.validatePlugin(plugin);
+        if (this.plugins.has(plugin.name)) {
+            throw new PluginRegistrationError(`Plugin with name '${plugin.name}' is already registered`, plugin.name);
+        }
+        this.plugins.set(plugin.name, plugin);
+        if (config !== undefined) {
+            this.pluginConfigs.set(plugin.name, config);
+        }
+    }
+    getPlugin(name) {
+        return this.plugins.get(name);
+    }
+    getAllPlugins() {
+        return Array.from(this.plugins.values());
+    }
+    getPluginConfig(pluginName) {
+        return this.pluginConfigs.get(pluginName);
+    }
+    hasPlugin(name) {
+        return this.plugins.has(name);
+    }
+    getPluginCount() {
+        return this.plugins.size;
+    }
+    unregister(name) {
+        const removed = this.plugins.delete(name);
+        if (removed) {
+            this.pluginConfigs.delete(name);
+        }
+        return removed;
+    }
+    clear() {
+        this.plugins.clear();
+        this.pluginConfigs.clear();
+    }
+    validatePlugin(plugin) {
+        if (!plugin) {
+            throw new PluginRegistrationError('Plugin cannot be null or undefined');
+        }
+        if (typeof plugin !== 'object') {
+            throw new PluginRegistrationError('Plugin must be an object');
+        }
+        if (!plugin.name || typeof plugin.name !== 'string') {
+            throw new PluginRegistrationError('Plugin must have a non-empty string name');
+        }
+        if (!plugin.version || typeof plugin.version !== 'string') {
+            throw new PluginRegistrationError('Plugin must have a non-empty string version', plugin.name);
+        }
+        if (typeof plugin.validate !== 'function') {
+            throw new PluginRegistrationError('Plugin must implement validate method', plugin.name);
+        }
+        if (plugin.description !== undefined && typeof plugin.description !== 'string') {
+            throw new PluginRegistrationError('Plugin description must be a string', plugin.name);
+        }
+        if (plugin.configSchema !== undefined && typeof plugin.configSchema !== 'object') {
+            throw new PluginRegistrationError('Plugin configSchema must be an object', plugin.name);
+        }
+        if (plugin.metadata !== undefined && typeof plugin.metadata !== 'object') {
+            throw new PluginRegistrationError('Plugin metadata must be an object', plugin.name);
+        }
+    }
+}

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

@@ -0,0 +1,39 @@
+import type { ChartMetadata } from '../rutter.js';
+import type { PolicyEngine as IPolicyEngine, PolicyPlugin, PolicyEngineOptions, PolicyResult, PolicyViolation, PolicyWarning, ValidationContext } from './types.js';
+export declare class PolicyEngine implements IPolicyEngine {
+    private readonly registry;
+    private options;
+    private readonly logger;
+    private readonly errorContextGenerator;
+    private readonly inputValidator;
+    private _configurationLoader?;
+    private _cache?;
+    private _parallelExecutor?;
+    constructor(options?: PolicyEngineOptions);
+    private get configurationLoader();
+    private get cache();
+    private get parallelExecutor();
+    use(plugin: PolicyPlugin): Promise<PolicyEngine>;
+    validate(manifests: unknown[], chartMetadata: ChartMetadata): Promise<PolicyResult>;
+    configure(options: PolicyEngineOptions): PolicyEngine;
+    formatResult(result: PolicyResult): string;
+    generateErrorContext(violation: PolicyViolation | PolicyWarning, validationContext?: ValidationContext, allViolations?: (PolicyViolation | PolicyWarning)[], executionTime?: number): import("./errorContextGenerator.js").ErrorContext;
+    generateErrorReport(violation: PolicyViolation | PolicyWarning, validationContext?: ValidationContext, allViolations?: (PolicyViolation | PolicyWarning)[], executionTime?: number): string;
+    getCacheStats(): import("./validationCache.js").CacheStats;
+    invalidateCache(criteria: {
+        manifestHash?: string;
+        pluginHash?: string;
+        olderThan?: number;
+        all?: boolean;
+    }): number;
+    clearCacheStats(): void;
+    private executeSequential;
+    private executeParallelOptimized;
+    private executePlugin;
+    private executePluginAttempt;
+    private shouldRetryError;
+    private sleep;
+    private createTimeoutPromise;
+    private handlePluginError;
+    private generateErrorSuggestion;
+}

package/dist/lib/policy/policyEngine.js

@@ -0,0 +1,495 @@
+import { createLogger } from '../utils/logger.js';
+import { InputValidator } from '../validation/inputValidator.js';
+import { PluginRegistry } from './pluginRegistry.js';
+import { PolicyEngineError, ValidationTimeoutError, PluginError, PluginRetryExhaustedError, PolicyValidationError, } from './errors.js';
+import { generateResultSummary } from './resultAggregator.js';
+import { DefaultResultFormatter } from './resultFormatter.js';
+import { ErrorContextGenerator } from './errorContextGenerator.js';
+import { ConfigurationLoader } from './configurationLoader.js';
+import { ValidationCache, generateManifestHash, generatePluginHash } from './validationCache.js';
+import { ParallelExecutor, calculateOptimalConcurrency, } from './parallelExecutor.js';
+const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+const DEFAULT_OPTIONS = {
+    timeout: 5000,
+    parallel: false,
+    failFast: false,
+    gracefulDegradation: true,
+};
+const DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 3,
+    baseDelay: 1000,
+    backoffMultiplier: 2,
+    maxDelay: 10000,
+    retryOnTimeout: true,
+    retryOnPluginError: false,
+};
+const OPERATIONS = {
+    PLUGIN_REGISTRATION: 'plugin_registration',
+    VALIDATION_START: 'validation_start',
+    VALIDATION_COMPLETE: 'validation_complete',
+    PLUGIN_EXECUTION_ERROR: 'plugin_execution_error_isolated',
+    PLUGIN_EXECUTION_RETRY: 'plugin_execution_retry',
+};
+export class PolicyEngine {
+    constructor(options = {}) {
+        this.registry = new PluginRegistry();
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+        this.logger = createLogger('policy-engine');
+        this.errorContextGenerator = new ErrorContextGenerator();
+        this.inputValidator = new InputValidator(options.validationOptions);
+        this.logger.debug('PolicyEngine initialized with lazy loading', {
+            options: this.options,
+            cacheEnabled: !!options.cacheOptions,
+            parallelEnabled: !!options.parallel,
+            operation: 'policy_engine_init',
+        });
+    }
+    get configurationLoader() {
+        if (!this._configurationLoader) {
+            this._configurationLoader = new ConfigurationLoader(this.options.configurationLoader);
+            this.logger.debug('ConfigurationLoader initialized lazily', {
+                operation: 'lazy_init_config_loader',
+            });
+        }
+        return this._configurationLoader;
+    }
+    get cache() {
+        if (!this._cache) {
+            this._cache = new ValidationCache(this.options.cacheOptions);
+            this.logger.debug('ValidationCache initialized lazily', {
+                cacheEnabled: !!this.options.cacheOptions,
+                operation: 'lazy_init_cache',
+            });
+        }
+        return this._cache;
+    }
+    get parallelExecutor() {
+        if (!this._parallelExecutor) {
+            const parallelOptions = {
+                maxConcurrency: this.options.parallelOptions?.maxConcurrency || calculateOptimalConcurrency(10),
+                pluginTimeout: this.options.timeout || DEFAULT_OPTIONS.timeout,
+                failFast: this.options.failFast || DEFAULT_OPTIONS.failFast,
+                ...this.options.parallelOptions,
+            };
+            this._parallelExecutor = new ParallelExecutor(parallelOptions);
+            this.logger.debug('ParallelExecutor initialized lazily', {
+                maxConcurrency: parallelOptions.maxConcurrency,
+                operation: 'lazy_init_parallel_executor',
+            });
+        }
+        return this._parallelExecutor;
+    }
+    async use(plugin) {
+        try {
+            if (!plugin || typeof plugin !== 'object') {
+                throw new PolicyValidationError('Plugin must be a non-null object');
+            }
+            if (!plugin.name || typeof plugin.name !== 'string') {
+                throw new PolicyValidationError('Plugin name must be a non-empty string');
+            }
+            if (!plugin.version || typeof plugin.version !== 'string') {
+                throw new PolicyValidationError('Plugin version must be a non-empty string');
+            }
+            if (typeof plugin.validate !== 'function') {
+                throw new PolicyValidationError('Plugin must have a validate method');
+            }
+            if (plugin.name.length > 100) {
+                throw new PolicyValidationError('Plugin name exceeds maximum length (100 characters)');
+            }
+            const sanitizedName = plugin.name
+                .replace(/[<>"'&]/g, '')
+                .trim();
+            if (sanitizedName !== plugin.name) {
+                this.logger.warn('Plugin name was sanitized', {
+                    original: plugin.name,
+                    sanitized: sanitizedName,
+                    operation: 'plugin_name_sanitization',
+                });
+            }
+            const pluginConfiguration = await this.configurationLoader.loadPluginConfiguration(plugin, this.options.environment, this.options.pluginConfig?.[plugin.name]);
+            this.registry.register(plugin, pluginConfiguration.config);
+            this.logger.info('Plugin registered successfully', {
+                pluginName: plugin.name,
+                pluginVersion: plugin.version,
+                hasConfig: Object.keys(pluginConfiguration.config).length > 0,
+                configValidated: pluginConfiguration.validated,
+                configSources: pluginConfiguration.entries.map((e) => e.source),
+                operation: OPERATIONS.PLUGIN_REGISTRATION,
+            });
+            if (pluginConfiguration.validationErrors) {
+                this.logger.warn('Plugin configuration validation warnings', {
+                    pluginName: plugin.name,
+                    errors: pluginConfiguration.validationErrors,
+                    operation: 'plugin_config_validation_warnings',
+                });
+            }
+            return this;
+        }
+        catch (error) {
+            this.logger.error('Plugin registration failed', {
+                pluginName: plugin?.name || 'unknown',
+                error: error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE,
+                operation: 'plugin_registration_error',
+            });
+            throw error;
+        }
+    }
+    async validate(manifests, chartMetadata) {
+        const startTime = Date.now();
+        if (!Array.isArray(manifests)) {
+            throw new PolicyValidationError('Manifests must be an array');
+        }
+        if (manifests.length > 1000) {
+            throw new PolicyValidationError('Too many manifests provided (maximum: 1000)');
+        }
+        manifests.forEach((manifest, index) => {
+            if (manifest === null || manifest === undefined) {
+                throw new PolicyValidationError(`Manifest at index ${index} cannot be null or undefined`);
+            }
+            const manifestStr = JSON.stringify(manifest);
+            if (manifestStr.length > 100000) {
+                throw new PolicyValidationError(`Manifest at index ${index} exceeds size limit (100KB)`);
+            }
+        });
+        if (!chartMetadata || typeof chartMetadata !== 'object') {
+            throw new PolicyValidationError('Chart metadata must be a non-null object');
+        }
+        const plugins = this.registry.getAllPlugins();
+        this.logger.info('Starting policy validation', {
+            manifestCount: manifests.length,
+            pluginCount: plugins.length,
+            operation: OPERATIONS.VALIDATION_START,
+        });
+        if (plugins.length === 0) {
+            const metadata = {
+                executionTime: Date.now() - startTime,
+                pluginCount: 0,
+                manifestCount: manifests.length,
+                startTime,
+            };
+            this.logger.debug('No plugins registered, validation successful', {
+                metadata,
+                operation: 'validation_no_plugins',
+            });
+            return {
+                valid: true,
+                violations: [],
+                warnings: [],
+                metadata,
+                summary: {
+                    violationsBySeverity: { error: 0, warning: 0, info: 0 },
+                    violationsByPlugin: {},
+                    topViolationTypes: [],
+                },
+            };
+        }
+        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);
+        const cachedResult = this.cache.get(manifestHash, pluginHash);
+        if (cachedResult) {
+            this.logger.info('Returning cached validation result', {
+                manifestCount: manifests.length,
+                pluginCount: plugins.length,
+                cacheAge: Date.now() - (cachedResult.metadata.startTime || 0),
+                operation: 'validation_cache_hit',
+            });
+            return cachedResult;
+        }
+        const violations = [];
+        const warnings = [];
+        try {
+            if (this.options.parallel) {
+                await this.executeParallelOptimized(plugins, manifests, violations, warnings, chartMetadata);
+            }
+            else {
+                await this.executeSequential(plugins, manifests, violations, warnings, chartMetadata);
+            }
+        }
+        catch (error) {
+            const executionTime = Date.now() - startTime;
+            this.logger.error('Policy validation failed', {
+                error: error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE,
+                executionTime,
+                operation: 'validation_error',
+            });
+            throw new PolicyEngineError(`Validation failed: ${error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE}`);
+        }
+        const executionTime = Date.now() - startTime;
+        const metadata = {
+            executionTime,
+            pluginCount: plugins.length,
+            manifestCount: manifests.length,
+            startTime,
+        };
+        const result = {
+            valid: violations.length === 0,
+            violations,
+            warnings,
+            metadata,
+            summary: generateResultSummary(violations, warnings, plugins.map((p) => p.name)),
+        };
+        this.cache.set(manifestHash, pluginHash, result);
+        this.logger.info('Policy validation completed', {
+            valid: result.valid,
+            violationCount: violations.length,
+            warningCount: warnings.length,
+            executionTime,
+            cached: true,
+            operation: 'validation_complete',
+        });
+        return result;
+    }
+    configure(options) {
+        this.options = { ...this.options, ...options };
+        this.logger.debug('PolicyEngine configuration updated', {
+            options: this.options,
+            operation: 'policy_engine_configure',
+        });
+        return this;
+    }
+    formatResult(result) {
+        const formatter = this.options.formatter || new DefaultResultFormatter();
+        return formatter.format(result);
+    }
+    generateErrorContext(violation, validationContext, allViolations, executionTime) {
+        return this.errorContextGenerator.generateContext(violation, validationContext, allViolations, executionTime);
+    }
+    generateErrorReport(violation, validationContext, allViolations, executionTime) {
+        return this.errorContextGenerator.generateErrorReport(violation, validationContext, allViolations, executionTime);
+    }
+    getCacheStats() {
+        return this.cache.getStats();
+    }
+    invalidateCache(criteria) {
+        return this.cache.invalidate(criteria);
+    }
+    clearCacheStats() {
+        this.cache.clearStats();
+    }
+    async executeSequential(plugins, manifests, violations, warnings, chartMetadata) {
+        for (const plugin of plugins) {
+            try {
+                const pluginViolations = await this.executePlugin(plugin, manifests, chartMetadata);
+                for (const violation of pluginViolations) {
+                    if (violation.severity === 'error') {
+                        violations.push(violation);
+                    }
+                    else {
+                        warnings.push(violation);
+                    }
+                }
+                if (this.options.failFast && violations.length > 0) {
+                    this.logger.debug('Fail fast enabled, stopping validation', {
+                        pluginName: plugin.name,
+                        violationCount: violations.length,
+                        operation: 'validation_fail_fast',
+                    });
+                    break;
+                }
+            }
+            catch (error) {
+                if (this.options.gracefulDegradation) {
+                    this.handlePluginError(plugin, error, violations);
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+    }
+    async executeParallelOptimized(plugins, manifests, violations, warnings, chartMetadata) {
+        const validationContext = {
+            chart: chartMetadata,
+            environment: this.options.environment || 'development',
+            logger: this.logger,
+        };
+        const { results, stats } = await this.parallelExecutor.executePlugins(plugins, manifests, validationContext);
+        this.logger.info('Parallel execution completed with statistics', {
+            pluginCount: plugins.length,
+            totalExecutionTime: stats.totalExecutionTime,
+            averagePluginTime: stats.averagePluginTime,
+            concurrencyUtilization: stats.concurrencyUtilization,
+            peakConcurrentPlugins: stats.resourceUsage.peakConcurrentPlugins,
+            totalMemoryMB: stats.resourceUsage.totalMemoryMB,
+            operation: 'parallel_execution_stats',
+        });
+        for (const result of results) {
+            if (result.error) {
+                if (this.options.gracefulDegradation) {
+                    this.handlePluginError(result.plugin, result.error, violations);
+                }
+                else {
+                    throw result.error;
+                }
+            }
+            else {
+                for (const violation of result.violations) {
+                    if (violation.severity === 'error') {
+                        violations.push(violation);
+                    }
+                    else {
+                        warnings.push(violation);
+                    }
+                }
+            }
+            if (this.options.failFast && violations.length > 0) {
+                this.logger.debug('Fail fast enabled, stopping validation', {
+                    pluginName: result.plugin.name,
+                    violationCount: violations.length,
+                    operation: 'validation_fail_fast',
+                });
+                break;
+            }
+        }
+    }
+    async executePlugin(plugin, manifests, chartMetadata) {
+        const retryConfig = { ...DEFAULT_RETRY_CONFIG, ...this.options.retryConfig };
+        let lastError = null;
+        for (let attempt = 1; attempt <= retryConfig.maxAttempts; attempt++) {
+            try {
+                return await this.executePluginAttempt(plugin, manifests, attempt, chartMetadata);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                this.logger.warn('Plugin execution attempt failed', {
+                    pluginName: plugin.name,
+                    attempt,
+                    maxAttempts: retryConfig.maxAttempts,
+                    error: lastError.message,
+                    operation: 'plugin_execution_retry',
+                });
+                const shouldRetry = this.shouldRetryError(lastError, retryConfig);
+                if (!shouldRetry || attempt === retryConfig.maxAttempts) {
+                    break;
+                }
+                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,
+                    attempt: attempt + 1,
+                    delay,
+                    operation: 'plugin_execution_retry_delay',
+                });
+                await this.sleep(delay);
+            }
+        }
+        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);
+    }
+    async executePluginAttempt(plugin, manifests, attempt, chartMetadata) {
+        const timeout = this.options.timeout || DEFAULT_OPTIONS.timeout;
+        this.logger.debug('Executing plugin attempt', {
+            pluginName: plugin.name,
+            attempt,
+            timeout,
+            operation: 'plugin_execution_attempt_start',
+        });
+        const validationContext = {
+            chart: chartMetadata,
+            config: this.registry.getPluginConfig(plugin.name),
+            environment: this.options.environment || 'development',
+            logger: this.logger,
+        };
+        const timeoutPromise = this.createTimeoutPromise(timeout, plugin.name);
+        const validationPromise = plugin.validate(manifests, validationContext);
+        try {
+            const result = await Promise.race([validationPromise, timeoutPromise]);
+            this.logger.debug('Plugin execution attempt completed', {
+                pluginName: plugin.name,
+                attempt,
+                violationCount: result.length,
+                operation: 'plugin_execution_attempt_complete',
+            });
+            return result;
+        }
+        catch (error) {
+            if (error instanceof ValidationTimeoutError) {
+                this.logger.warn('Plugin execution attempt timed out', {
+                    pluginName: plugin.name,
+                    attempt,
+                    timeout,
+                    operation: 'plugin_execution_attempt_timeout',
+                });
+            }
+            else {
+                this.logger.warn('Plugin execution attempt failed', {
+                    pluginName: plugin.name,
+                    attempt,
+                    error: error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE,
+                    operation: 'plugin_execution_attempt_error',
+                });
+            }
+            throw error;
+        }
+    }
+    shouldRetryError(error, retryConfig) {
+        if (error instanceof ValidationTimeoutError) {
+            return retryConfig.retryOnTimeout;
+        }
+        if (error instanceof PluginError) {
+            return retryConfig.retryOnPluginError;
+        }
+        return retryConfig.retryOnPluginError;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => globalThis.setTimeout(resolve, ms));
+    }
+    createTimeoutPromise(timeout, pluginName) {
+        return new Promise((_, reject) => {
+            globalThis.setTimeout(() => {
+                reject(new ValidationTimeoutError(pluginName, timeout));
+            }, timeout);
+        });
+    }
+    handlePluginError(plugin, error, violations) {
+        const errorMessage = error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE;
+        const errorStack = error instanceof Error ? error.stack : String(error);
+        this.logger.warn('Plugin execution failed with error isolation', {
+            pluginName: plugin.name,
+            pluginVersion: plugin.version,
+            error: errorMessage,
+            errorType: error instanceof Error ? error.constructor.name : typeof error,
+            operation: 'plugin_execution_error_isolated',
+        });
+        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,
+        };
+        const errorViolation = {
+            plugin: plugin.name,
+            severity: 'error',
+            message: `Plugin execution failed: ${errorMessage}`,
+            resourcePath: 'plugin-execution',
+            field: 'validate',
+            suggestion: this.generateErrorSuggestion(error, plugin),
+            context: errorContext,
+        };
+        violations.push(errorViolation);
+        this.logger.debug('Plugin error context generated', {
+            pluginName: plugin.name,
+            errorContext,
+            operation: 'plugin_error_context',
+        });
+    }
+    generateErrorSuggestion(error, plugin) {
+        if (error instanceof ValidationTimeoutError) {
+            return `Consider increasing the timeout value or optimizing the plugin '${plugin.name}' for better performance.`;
+        }
+        if (error instanceof PluginRetryExhaustedError) {
+            return `Plugin '${plugin.name}' failed after multiple retry attempts. Check plugin configuration and dependencies.`;
+        }
+        if (error instanceof TypeError) {
+            return `Plugin '${plugin.name}' encountered a type error. Verify the plugin implementation and input validation.`;
+        }
+        if (error instanceof ReferenceError) {
+            return `Plugin '${plugin.name}' referenced an undefined variable or function. Check plugin dependencies and imports.`;
+        }
+        return `Review plugin '${plugin.name}' implementation and ensure it handles all edge cases properly.`;
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { PolicyResult, PolicyViolation, PolicyWarning, ResultSummary } from './types.js';
+export declare function aggregateResults(results: PolicyResult[]): PolicyResult;
+export declare function generateResultSummary(violations: PolicyViolation[], warnings: PolicyWarning[], allPlugins?: string[]): ResultSummary;
+export declare function filterViolationsBySeverity(violations: PolicyViolation[], severity: 'error' | 'warning' | 'info'): PolicyViolation[];
+export declare function groupViolationsByPlugin(violations: PolicyViolation[]): Record<string, PolicyViolation[]>;
+export declare function sortViolationsBySeverity(violations: PolicyViolation[]): PolicyViolation[];
+export declare function createEmptyResult(): PolicyResult;
+export declare function mergeViolationContexts(contexts: Array<Record<string, unknown> | undefined>): Record<string, unknown>;