timonel 3.0.0-beta.1 → 3.1.0-beta.1

package/dist/lib/policy/parallelExecutor.js

@@ -0,0 +1,215 @@
+import { cpus, totalmem } from 'os';
+import { createLogger } from '../utils/logger.js';
+import { ValidationTimeoutError } from './errors.js';
+const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+const DEFAULT_PARALLEL_OPTIONS = {
+    maxConcurrency: Math.max(2, Math.min(8, cpus().length)),
+    useWorkerThreads: false,
+    pluginTimeout: 5000,
+    failFast: false,
+};
+export class ParallelExecutor {
+    constructor(options = {}) {
+        this.activeExecutions = 0;
+        this.executionQueue = [];
+        this.options = { ...DEFAULT_PARALLEL_OPTIONS, ...options };
+        this.logger = createLogger('parallel-executor');
+        this.logger.debug('ParallelExecutor initialized', {
+            maxConcurrency: this.options.maxConcurrency,
+            useWorkerThreads: this.options.useWorkerThreads,
+            pluginTimeout: this.options.pluginTimeout,
+            operation: 'parallel_executor_init',
+        });
+    }
+    async executePlugins(plugins, manifests, validationContext) {
+        const startTime = Date.now();
+        this.logger.info('Starting parallel plugin execution', {
+            pluginCount: plugins.length,
+            maxConcurrency: this.options.maxConcurrency,
+            manifestCount: manifests.length,
+            operation: 'parallel_execution_start',
+        });
+        const sortedPlugins = this.sortPluginsByPriority(plugins);
+        const executionTasks = sortedPlugins.map((plugin) => () => this.executePlugin(plugin, manifests, validationContext));
+        const results = await this.executeConcurrently(executionTasks);
+        const totalExecutionTime = Date.now() - startTime;
+        const stats = this.calculateStats(results, totalExecutionTime);
+        this.logger.info('Parallel plugin execution completed', {
+            pluginCount: plugins.length,
+            totalExecutionTime,
+            averagePluginTime: stats.averagePluginTime,
+            concurrencyUtilization: stats.concurrencyUtilization,
+            operation: 'parallel_execution_complete',
+        });
+        return { results, stats };
+    }
+    async executePlugin(plugin, manifests, validationContext) {
+        const startTime = Date.now();
+        const startMemory = process.memoryUsage().heapUsed;
+        this.logger.debug('Starting plugin execution', {
+            pluginName: plugin.name,
+            pluginVersion: plugin.version,
+            operation: 'plugin_execution_start',
+        });
+        try {
+            const violations = await this.executeWithTimeout(plugin, manifests, validationContext, this.options.pluginTimeout);
+            const executionTime = Date.now() - startTime;
+            const endMemory = process.memoryUsage().heapUsed;
+            const memoryUsageMB = Math.max(0, endMemory - startMemory) / (1024 * 1024);
+            const result = {
+                plugin,
+                violations,
+                executionTime,
+                resourceUsage: {
+                    memoryUsageMB,
+                    cpuTimeMs: executionTime,
+                },
+            };
+            this.logger.debug('Plugin execution completed successfully', {
+                pluginName: plugin.name,
+                executionTime,
+                violationCount: violations.length,
+                memoryUsageMB: memoryUsageMB.toFixed(2),
+                operation: 'plugin_execution_success',
+            });
+            return result;
+        }
+        catch (error) {
+            const executionTime = Date.now() - startTime;
+            const endMemory = process.memoryUsage().heapUsed;
+            const memoryUsageMB = Math.max(0, endMemory - startMemory) / (1024 * 1024);
+            this.logger.warn('Plugin execution failed', {
+                pluginName: plugin.name,
+                executionTime,
+                error: error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE,
+                memoryUsageMB: memoryUsageMB.toFixed(2),
+                operation: 'plugin_execution_error',
+            });
+            return {
+                plugin,
+                violations: [],
+                executionTime,
+                error: error instanceof Error ? error : new Error(String(error)),
+                resourceUsage: {
+                    memoryUsageMB,
+                    cpuTimeMs: executionTime,
+                },
+            };
+        }
+    }
+    async executeWithTimeout(plugin, manifests, validationContext, timeout) {
+        const timeoutPromise = new Promise((_, reject) => {
+            globalThis.setTimeout(() => {
+                reject(new ValidationTimeoutError(plugin.name, timeout));
+            }, timeout);
+        });
+        const validationPromise = plugin.validate(manifests, validationContext);
+        return Promise.race([validationPromise, timeoutPromise]);
+    }
+    async executeConcurrently(tasks) {
+        const results = [];
+        const executing = [];
+        let taskIndex = 0;
+        let peakConcurrency = 0;
+        const executeNext = async () => {
+            if (taskIndex >= tasks.length) {
+                return;
+            }
+            const currentTaskIndex = taskIndex++;
+            const task = tasks[currentTaskIndex];
+            if (!task) {
+                return;
+            }
+            this.activeExecutions++;
+            peakConcurrency = Math.max(peakConcurrency, this.activeExecutions);
+            try {
+                const result = await task();
+                results[currentTaskIndex] = result;
+                if (this.options.failFast && result.error) {
+                    this.logger.debug('Fail-fast triggered, stopping execution', {
+                        pluginName: result.plugin.name,
+                        error: result.error.message,
+                        operation: 'parallel_execution_fail_fast',
+                    });
+                    return;
+                }
+            }
+            catch (error) {
+                this.logger.error('Unexpected error in parallel execution', {
+                    taskIndex: currentTaskIndex,
+                    error: error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE,
+                    operation: 'parallel_execution_unexpected_error',
+                });
+            }
+            finally {
+                this.activeExecutions--;
+            }
+            if (!this.options.failFast || !results[currentTaskIndex]?.error) {
+                await executeNext();
+            }
+        };
+        const maxConcurrency = this.options.maxConcurrency;
+        for (let i = 0; i < Math.min(maxConcurrency, tasks.length); i++) {
+            executing.push(executeNext());
+        }
+        await Promise.all(executing);
+        this.logger.debug('Concurrent execution completed', {
+            totalTasks: tasks.length,
+            completedTasks: results.filter((r) => r).length,
+            peakConcurrency,
+            operation: 'concurrent_execution_complete',
+        });
+        return results.filter((r) => r);
+    }
+    sortPluginsByPriority(plugins) {
+        if (!this.options.priorityConfig) {
+            return [...plugins];
+        }
+        const { highPriority = [], lowPriority = [] } = this.options.priorityConfig;
+        const highPriorityPlugins = plugins.filter((p) => highPriority.includes(p.name));
+        const normalPriorityPlugins = plugins.filter((p) => !highPriority.includes(p.name) && !lowPriority.includes(p.name));
+        const lowPriorityPlugins = plugins.filter((p) => lowPriority.includes(p.name));
+        const sortedPlugins = [...highPriorityPlugins, ...normalPriorityPlugins, ...lowPriorityPlugins];
+        this.logger.debug('Plugins sorted by priority', {
+            totalPlugins: plugins.length,
+            highPriorityCount: highPriorityPlugins.length,
+            normalPriorityCount: normalPriorityPlugins.length,
+            lowPriorityCount: lowPriorityPlugins.length,
+            operation: 'plugin_priority_sort',
+        });
+        return sortedPlugins;
+    }
+    calculateStats(results, totalExecutionTime) {
+        const executionTimes = results.map((r) => r.executionTime);
+        const averagePluginTime = executionTimes.reduce((sum, time) => sum + time, 0) / results.length;
+        const maxPluginTime = Math.max(...executionTimes);
+        const totalMemoryMB = results.reduce((sum, r) => sum + (r.resourceUsage?.memoryUsageMB || 0), 0);
+        const totalCpuTimeMs = results.reduce((sum, r) => sum + (r.resourceUsage?.cpuTimeMs || 0), 0);
+        const theoreticalMinTime = Math.max(...executionTimes);
+        const concurrencyUtilization = theoreticalMinTime / totalExecutionTime;
+        return {
+            totalExecutionTime,
+            averagePluginTime,
+            maxPluginTime,
+            parallelPluginCount: results.length,
+            concurrencyUtilization: Math.min(1, concurrencyUtilization),
+            resourceUsage: {
+                totalMemoryMB,
+                totalCpuTimeMs,
+                peakConcurrentPlugins: Math.min(this.options.maxConcurrency, results.length),
+            },
+        };
+    }
+}
+export function calculateOptimalConcurrency(pluginCount, systemInfo) {
+    const cpuCount = systemInfo?.cpuCount || cpus().length;
+    const availableMemoryMB = systemInfo?.availableMemoryMB || totalmem() / (1024 * 1024);
+    let optimalConcurrency = Math.max(2, Math.min(cpuCount, pluginCount));
+    const memoryBasedConcurrency = Math.floor(availableMemoryMB / 100);
+    optimalConcurrency = Math.min(optimalConcurrency, memoryBasedConcurrency);
+    if (systemInfo?.isContainerized) {
+        optimalConcurrency = Math.max(1, Math.floor(optimalConcurrency * 0.75));
+    }
+    optimalConcurrency = Math.min(optimalConcurrency, 16);
+    return optimalConcurrency;
+}

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

@@ -0,0 +1,41 @@
+import type { PolicyPlugin, PluginMetadata } from './types.js';
+export interface PluginLoaderOptions {
+    baseDirectory?: string;
+    environment?: string;
+    validateCompatibility?: boolean;
+    supportedKubernetesVersions?: string[];
+    registryUrl?: string;
+    loadTimeout?: number;
+}
+export interface PluginDiscoveryResult {
+    packageName: string;
+    version: string;
+    metadata?: PluginMetadata;
+    compatible: boolean;
+    compatibilityIssues?: string[];
+    source: 'npm' | 'local' | 'registry';
+}
+export interface PluginLoadingResult {
+    plugin: PolicyPlugin;
+    packageName: string;
+    source: 'npm' | 'local' | 'registry';
+    loadTime: number;
+    validated: boolean;
+    warnings?: string[];
+}
+export declare class PluginLoader {
+    private readonly options;
+    private readonly logger;
+    private readonly loadedPlugins;
+    constructor(options?: PluginLoaderOptions);
+    loadFromPackage(packageName: string, version?: string): Promise<PluginLoadingResult>;
+    discoverPlugins(searchPattern?: string): Promise<PluginDiscoveryResult[]>;
+    loadMultiplePlugins(packages: string[]): Promise<PluginLoadingResult[]>;
+    static validatePluginInterface(plugin: unknown, packageName: string): asserts plugin is PolicyPlugin;
+    getLoadedPlugins(): PluginLoadingResult[];
+    clearCache(): void;
+    private loadModuleWithTimeout;
+    private validatePluginInterface;
+    private checkCompatibility;
+    private shouldLoadInEnvironment;
+}

package/dist/lib/policy/pluginLoader.js

@@ -0,0 +1,220 @@
+import { createLogger } from '../utils/logger.js';
+import { PluginError, PluginRegistrationError } from './errors.js';
+const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+const DEFAULT_LOADER_OPTIONS = {
+    baseDirectory: process.cwd(),
+    environment: 'development',
+    validateCompatibility: true,
+    supportedKubernetesVersions: ['1.25', '1.26', '1.27', '1.28', '1.29'],
+    registryUrl: 'https://registry.npmjs.org',
+    loadTimeout: 30000,
+};
+export class PluginLoader {
+    constructor(options = {}) {
+        this.loadedPlugins = new Map();
+        this.options = { ...DEFAULT_LOADER_OPTIONS, ...options };
+        this.logger = createLogger('policy-plugin-loader');
+        this.logger.debug('PluginLoader initialized', {
+            options: this.options,
+            operation: 'plugin_loader_init',
+        });
+    }
+    async loadFromPackage(packageName, version) {
+        const startTime = Date.now();
+        this.logger.info('Loading plugin from package', {
+            packageName,
+            version,
+            operation: 'load_from_package',
+        });
+        try {
+            const cacheKey = `${packageName}@${version || 'latest'}`;
+            if (this.loadedPlugins.has(cacheKey)) {
+                const cached = this.loadedPlugins.get(cacheKey);
+                this.logger.debug('Plugin loaded from cache', {
+                    packageName,
+                    cacheKey,
+                    operation: 'load_from_cache',
+                });
+                return cached;
+            }
+            const modulePath = version ? `${packageName}@${version}` : packageName;
+            const plugin = await this.loadModuleWithTimeout(modulePath);
+            this.validatePluginInterface(plugin, packageName);
+            const warnings = [];
+            if (this.options.validateCompatibility) {
+                const compatibilityIssues = this.checkCompatibility(plugin);
+                warnings.push(...compatibilityIssues);
+            }
+            if (!this.shouldLoadInEnvironment(plugin)) {
+                throw new PluginError(`Plugin '${packageName}' is not enabled for environment '${this.options.environment}'`, packageName);
+            }
+            const loadTime = Date.now() - startTime;
+            const result = {
+                plugin,
+                packageName,
+                source: 'npm',
+                loadTime,
+                validated: true,
+                ...(warnings.length > 0 && { warnings }),
+            };
+            this.loadedPlugins.set(cacheKey, result);
+            this.logger.info('Plugin loaded successfully', {
+                packageName,
+                pluginName: plugin.name,
+                pluginVersion: plugin.version,
+                loadTime,
+                hasWarnings: warnings.length > 0,
+                operation: 'plugin_loaded',
+            });
+            return result;
+        }
+        catch (error) {
+            const loadTime = Date.now() - startTime;
+            this.logger.error('Plugin loading failed', {
+                packageName,
+                version,
+                loadTime,
+                error: error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE,
+                operation: 'plugin_load_failed',
+            });
+            throw new PluginError(`Failed to load plugin from package '${packageName}': ${error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE}`, packageName, { originalError: error, loadTime });
+        }
+    }
+    async discoverPlugins(searchPattern) {
+        this.logger.info('Discovering plugins', {
+            searchPattern,
+            environment: this.options.environment,
+            operation: 'discover_plugins',
+        });
+        const discovered = [];
+        try {
+            this.logger.info('Plugin discovery completed', {
+                discoveredCount: discovered.length,
+                operation: 'discovery_complete',
+            });
+            return discovered;
+        }
+        catch (error) {
+            this.logger.error('Plugin discovery failed', {
+                error: error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE,
+                operation: 'discovery_failed',
+            });
+            throw new PluginError(`Plugin discovery failed: ${error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE}`, 'discovery');
+        }
+    }
+    async loadMultiplePlugins(packages) {
+        this.logger.info('Loading multiple plugins', {
+            packageCount: packages.length,
+            packages,
+            operation: 'load_multiple',
+        });
+        const results = [];
+        const errors = [];
+        const loadPromises = packages.map(async (pkg) => {
+            try {
+                const [packageName, version] = pkg.includes('@') && !pkg.startsWith('@') ? pkg.split('@') : [pkg, undefined];
+                return await this.loadFromPackage(packageName, version);
+            }
+            catch (error) {
+                errors.push({
+                    package: pkg,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+                return null;
+            }
+        });
+        const loadResults = await Promise.all(loadPromises);
+        for (const result of loadResults) {
+            if (result) {
+                results.push(result);
+            }
+        }
+        if (errors.length > 0) {
+            this.logger.warn('Some plugins failed to load', {
+                successCount: results.length,
+                errorCount: errors.length,
+                errors: errors.map((e) => ({ package: e.package, error: e.error.message })),
+                operation: 'load_multiple_partial_failure',
+            });
+        }
+        this.logger.info('Multiple plugin loading completed', {
+            totalPackages: packages.length,
+            successCount: results.length,
+            errorCount: errors.length,
+            operation: 'load_multiple_complete',
+        });
+        return results;
+    }
+    static validatePluginInterface(plugin, packageName) {
+        if (!plugin || typeof plugin !== 'object') {
+            throw new PluginRegistrationError(`Plugin from package '${packageName}' must be an object`, packageName);
+        }
+        const p = plugin;
+        if (!p.name || typeof p.name !== 'string') {
+            throw new PluginRegistrationError(`Plugin from package '${packageName}' must have a non-empty string name`, packageName);
+        }
+        if (!p.version || typeof p.version !== 'string') {
+            throw new PluginRegistrationError(`Plugin from package '${packageName}' must have a non-empty string version`, packageName);
+        }
+        if (typeof p.validate !== 'function') {
+            throw new PluginRegistrationError(`Plugin from package '${packageName}' must implement validate method`, packageName);
+        }
+        if (p.description !== undefined && typeof p.description !== 'string') {
+            throw new PluginRegistrationError(`Plugin from package '${packageName}' description must be a string`, packageName);
+        }
+        if (p.configSchema !== undefined && typeof p.configSchema !== 'object') {
+            throw new PluginRegistrationError(`Plugin from package '${packageName}' configSchema must be an object`, packageName);
+        }
+        if (p.metadata !== undefined && typeof p.metadata !== 'object') {
+            throw new PluginRegistrationError(`Plugin from package '${packageName}' metadata must be an object`, packageName);
+        }
+    }
+    getLoadedPlugins() {
+        return Array.from(this.loadedPlugins.values());
+    }
+    clearCache() {
+        this.loadedPlugins.clear();
+        this.logger.debug('Plugin cache cleared', {
+            operation: 'cache_cleared',
+        });
+    }
+    async loadModuleWithTimeout(modulePath) {
+        return new Promise((resolve, reject) => {
+            const timeout = globalThis.setTimeout(() => {
+                reject(new Error(`Plugin loading timed out after ${this.options.loadTimeout}ms`));
+            }, this.options.loadTimeout);
+            import(modulePath)
+                .then((module) => {
+                globalThis.clearTimeout(timeout);
+                const plugin = module.default || module;
+                if (!plugin) {
+                    reject(new Error('Plugin module does not export a plugin'));
+                    return;
+                }
+                resolve(plugin);
+            })
+                .catch((error) => {
+                globalThis.clearTimeout(timeout);
+                reject(error);
+            });
+        });
+    }
+    validatePluginInterface(plugin, packageName) {
+        PluginLoader.validatePluginInterface(plugin, packageName);
+    }
+    checkCompatibility(plugin) {
+        const issues = [];
+        if (plugin.metadata?.kubernetesVersions) {
+            const supportedVersions = new Set(this.options.supportedKubernetesVersions);
+            const pluginVersions = plugin.metadata.kubernetesVersions;
+            const hasCompatibleVersion = pluginVersions.some((version) => supportedVersions.has(version));
+            if (!hasCompatibleVersion) {
+                issues.push(`Plugin requires Kubernetes versions [${pluginVersions.join(', ')}] but only [${this.options.supportedKubernetesVersions.join(', ')}] are supported`);
+            }
+        }
+        return issues;
+    }
+    shouldLoadInEnvironment(_plugin) {
+        return true;
+    }
+}

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

@@ -0,0 +1,14 @@
+import type { PolicyPlugin } from './types.js';
+export declare class PluginRegistry {
+    private plugins;
+    private pluginConfigs;
+    register(plugin: PolicyPlugin, config?: unknown): void;
+    getPlugin(name: string): PolicyPlugin | undefined;
+    getAllPlugins(): PolicyPlugin[];
+    getPluginConfig(pluginName: string): unknown;
+    hasPlugin(name: string): boolean;
+    getPluginCount(): number;
+    unregister(name: string): boolean;
+    clear(): void;
+    private validatePlugin;
+}

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