timonel 3.1.1 → 3.1.2

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

@@ -1,39 +1,74 @@
+/**
+ * Policy Engine Error Types
+ *
+ * This module defines custom error types for the Timonel Policy Engine system.
+ * These errors provide structured error handling and debugging capabilities.
+ *
+ * @since 3.0.0
+ */
+/**
+ * Base error class for all policy engine related errors
+ */
 export declare class PolicyEngineError extends Error {
     readonly code?: string | undefined;
     readonly context?: Record<string, unknown> | undefined;
     constructor(message: string, code?: string | undefined, context?: Record<string, unknown> | undefined);
 }
+/**
+ * Error thrown when a plugin fails during execution
+ */
 export declare class PluginError extends PolicyEngineError {
     readonly pluginName: string;
     constructor(message: string, pluginName: string, context?: Record<string, unknown>);
 }
+/**
+ * Error thrown when plugin validation times out
+ */
 export declare class ValidationTimeoutError extends PolicyEngineError {
     constructor(pluginName: string, timeout: number);
 }
+/**
+ * Error thrown when plugin registration fails
+ */
 export declare class PluginRegistrationError extends PolicyEngineError {
     readonly pluginName?: string | undefined;
     constructor(message: string, pluginName?: string | undefined, context?: Record<string, unknown>);
 }
+/**
+ * Error thrown when plugin configuration is invalid
+ */
 export declare class PluginConfigurationError extends PolicyEngineError {
     readonly pluginName: string;
     readonly configPath?: string | undefined;
     constructor(message: string, pluginName: string, configPath?: string | undefined, context?: Record<string, unknown>);
 }
+/**
+ * Error thrown when validation orchestration fails
+ */
 export declare class ValidationOrchestrationError extends PolicyEngineError {
     readonly failedPlugins?: string[] | undefined;
     constructor(message: string, failedPlugins?: string[] | undefined, context?: Record<string, unknown>);
 }
+/**
+ * Error thrown when plugin execution fails after all retry attempts
+ */
 export declare class PluginRetryExhaustedError extends PolicyEngineError {
     readonly pluginName: string;
     readonly attempts: number;
     readonly lastError: Error;
     constructor(message: string, pluginName: string, attempts: number, lastError: Error, context?: Record<string, unknown>);
 }
+/**
+ * Error thrown when graceful degradation is triggered
+ */
 export declare class GracefulDegradationError extends PolicyEngineError {
     readonly degradedPlugins: string[];
     readonly originalErrors: Error[];
     constructor(message: string, degradedPlugins: string[], originalErrors: Error[], context?: Record<string, unknown>);
 }
+/**
+ * Error thrown when input validation fails
+ */
 export declare class PolicyValidationError extends PolicyEngineError {
     readonly field?: string | undefined;
     constructor(message: string, field?: string | undefined, context?: Record<string, unknown>);

package/dist/lib/policy/errors.js

@@ -1,14 +1,29 @@
+/**
+ * Policy Engine Error Types
+ *
+ * This module defines custom error types for the Timonel Policy Engine system.
+ * These errors provide structured error handling and debugging capabilities.
+ *
+ * @since 3.0.0
+ */
+/**
+ * Base error class for all policy engine related errors
+ */
 export class PolicyEngineError extends Error {
     constructor(message, code, context) {
         super(message);
         this.code = code;
         this.context = context;
         this.name = 'PolicyEngineError';
+        // Maintain proper stack trace for where our error was thrown (only available on V8)
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, PolicyEngineError);
         }
     }
 }
+/**
+ * Error thrown when a plugin fails during execution
+ */
 export class PluginError extends PolicyEngineError {
     constructor(message, pluginName, context) {
         super(message, 'PLUGIN_ERROR', { ...context, pluginName });
@@ -19,6 +34,9 @@ export class PluginError extends PolicyEngineError {
         }
     }
 }
+/**
+ * Error thrown when plugin validation times out
+ */
 export class ValidationTimeoutError extends PolicyEngineError {
     constructor(pluginName, timeout) {
         super(`Plugin '${pluginName}' timed out after ${timeout}ms`, 'VALIDATION_TIMEOUT', {
@@ -31,6 +49,9 @@ export class ValidationTimeoutError extends PolicyEngineError {
         }
     }
 }
+/**
+ * Error thrown when plugin registration fails
+ */
 export class PluginRegistrationError extends PolicyEngineError {
     constructor(message, pluginName, context) {
         super(message, 'PLUGIN_REGISTRATION_ERROR', { ...context, pluginName });
@@ -41,6 +62,9 @@ export class PluginRegistrationError extends PolicyEngineError {
         }
     }
 }
+/**
+ * Error thrown when plugin configuration is invalid
+ */
 export class PluginConfigurationError extends PolicyEngineError {
     constructor(message, pluginName, configPath, context) {
         super(message, 'PLUGIN_CONFIGURATION_ERROR', { ...context, pluginName, configPath });
@@ -52,6 +76,9 @@ export class PluginConfigurationError extends PolicyEngineError {
         }
     }
 }
+/**
+ * Error thrown when validation orchestration fails
+ */
 export class ValidationOrchestrationError extends PolicyEngineError {
     constructor(message, failedPlugins, context) {
         super(message, 'VALIDATION_ORCHESTRATION_ERROR', { ...context, failedPlugins });
@@ -62,6 +89,9 @@ export class ValidationOrchestrationError extends PolicyEngineError {
         }
     }
 }
+/**
+ * Error thrown when plugin execution fails after all retry attempts
+ */
 export class PluginRetryExhaustedError extends PolicyEngineError {
     constructor(message, pluginName, attempts, lastError, context) {
         super(message, 'PLUGIN_RETRY_EXHAUSTED', {
@@ -79,6 +109,9 @@ export class PluginRetryExhaustedError extends PolicyEngineError {
         }
     }
 }
+/**
+ * Error thrown when graceful degradation is triggered
+ */
 export class GracefulDegradationError extends PolicyEngineError {
     constructor(message, degradedPlugins, originalErrors, context) {
         super(message, 'GRACEFUL_DEGRADATION', {
@@ -94,6 +127,9 @@ export class GracefulDegradationError extends PolicyEngineError {
         }
     }
 }
+/**
+ * Error thrown when input validation fails
+ */
 export class PolicyValidationError extends PolicyEngineError {
     constructor(message, field, context) {
         super(message, 'POLICY_VALIDATION_ERROR', {

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

@@ -1,3 +1,12 @@
+/**
+ * Policy Engine Module
+ *
+ * This module provides a lightweight, extensible policy validation system for Timonel.
+ * It enables validation of Kubernetes manifests through external plugins following
+ * industry best practices for plugin architecture and extensibility.
+ *
+ * @since 3.0.0
+ */
 export { PolicyEngine } from './policyEngine.js';
 export { PluginRegistry } from './pluginRegistry.js';
 export { ConfigurationLoader } from './configurationLoader.js';

package/dist/lib/policy/index.js

@@ -1,10 +1,26 @@
+/**
+ * Policy Engine Module
+ *
+ * This module provides a lightweight, extensible policy validation system for Timonel.
+ * It enables validation of Kubernetes manifests through external plugins following
+ * industry best practices for plugin architecture and extensibility.
+ *
+ * @since 3.0.0
+ */
+// Core engine
 export { PolicyEngine } from './policyEngine.js';
 export { PluginRegistry } from './pluginRegistry.js';
 export { ConfigurationLoader } from './configurationLoader.js';
 export { PluginLoader } from './pluginLoader.js';
+// Validation cache
 export { ValidationCache, generateManifestHash, generatePluginHash, } from './validationCache.js';
+// Parallel execution
 export { ParallelExecutor, calculateOptimalConcurrency, } from './parallelExecutor.js';
+// Result aggregation utilities
 export { aggregateResults, generateResultSummary, filterViolationsBySeverity, groupViolationsByPlugin, sortViolationsBySeverity, createEmptyResult, mergeViolationContexts, } from './resultAggregator.js';
+// Result formatters
 export { DefaultResultFormatter, JsonResultFormatter, CompactResultFormatter, GitHubActionsResultFormatter, SarifResultFormatter, createFormatter, getAvailableFormatters, } from './resultFormatter.js';
+// Error context generation
 export { ErrorContextGenerator } from './errorContextGenerator.js';
+// Error types
 export { PolicyEngineError, PluginError, ValidationTimeoutError, PluginRegistrationError, PluginConfigurationError, ValidationOrchestrationError, PluginRetryExhaustedError, GracefulDegradationError, } from './errors.js';

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

@@ -1,56 +1,146 @@
+/**
+ * Parallel Execution Manager for Policy Plugins
+ *
+ * This module provides sophisticated parallel execution capabilities for policy plugins,
+ * including resource management, concurrency control, and performance optimization.
+ *
+ * @since 3.0.0
+ */
 import type { PolicyPlugin, PolicyViolation, ValidationContext } from './types.js';
+/**
+ * Parallel execution configuration
+ */
 export interface ParallelExecutionOptions {
+    /** Maximum number of concurrent plugin executions */
     maxConcurrency?: number;
+    /** Whether to use worker threads for CPU-intensive plugins */
     useWorkerThreads?: boolean;
+    /** Timeout for individual plugin execution */
     pluginTimeout?: number;
+    /** Whether to fail fast on first error */
     failFast?: boolean;
+    /** Resource limits for plugin execution */
     resourceLimits?: {
+        /** Maximum memory usage per plugin in MB */
         maxMemoryMB?: number;
+        /** Maximum CPU time per plugin in milliseconds */
         maxCpuTimeMs?: number;
     };
+    /** Plugin execution priority configuration */
     priorityConfig?: {
+        /** High priority plugins (executed first) */
         highPriority?: string[];
+        /** Low priority plugins (executed last) */
         lowPriority?: string[];
     };
 }
+/**
+ * Plugin execution result
+ */
 export interface PluginExecutionResult {
+    /** Plugin that was executed */
     plugin: PolicyPlugin;
+    /** Violations found by the plugin */
     violations: PolicyViolation[];
+    /** Execution time in milliseconds */
     executionTime: number;
+    /** Error if execution failed */
     error?: Error;
+    /** Resource usage statistics */
     resourceUsage?: {
         memoryUsageMB: number;
         cpuTimeMs: number;
     };
 }
+/**
+ * Parallel execution statistics
+ */
 export interface ParallelExecutionStats {
+    /** Total execution time */
     totalExecutionTime: number;
+    /** Average plugin execution time */
     averagePluginTime: number;
+    /** Maximum plugin execution time */
     maxPluginTime: number;
+    /** Number of plugins executed in parallel */
     parallelPluginCount: number;
+    /** Concurrency utilization (0-1) */
     concurrencyUtilization: number;
+    /** Resource usage statistics */
     resourceUsage: {
         totalMemoryMB: number;
         totalCpuTimeMs: number;
         peakConcurrentPlugins: number;
     };
 }
+/**
+ * Parallel execution manager for policy plugins
+ */
 export declare class ParallelExecutor {
     private readonly options;
     private readonly logger;
     private activeExecutions;
     private executionQueue;
     constructor(options?: ParallelExecutionOptions);
+    /**
+     * Executes plugins in parallel with resource management
+     * @param plugins - Array of plugins to execute
+     * @param manifests - Manifests to validate
+     * @param validationContext - Validation context
+     * @returns Promise resolving to execution results
+     */
     executePlugins(plugins: PolicyPlugin[], manifests: unknown[], validationContext: ValidationContext): Promise<{
         results: PluginExecutionResult[];
         stats: ParallelExecutionStats;
     }>;
+    /**
+     * Executes a single plugin with resource monitoring
+     * @param plugin - Plugin to execute
+     * @param manifests - Manifests to validate
+     * @param validationContext - Validation context
+     * @returns Promise resolving to execution result
+     * @private
+     */
     private executePlugin;
+    /**
+     * Executes plugin with timeout handling
+     * @param plugin - Plugin to execute
+     * @param manifests - Manifests to validate
+     * @param validationContext - Validation context
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise resolving to violations
+     * @private
+     */
     private executeWithTimeout;
+    /**
+     * Executes tasks with concurrency control
+     * @param tasks - Array of execution tasks
+     * @returns Promise resolving to results
+     * @private
+     */
     private executeConcurrently;
+    /**
+     * Sorts plugins by priority configuration
+     * @param plugins - Array of plugins to sort
+     * @returns Sorted array of plugins
+     * @private
+     */
     private sortPluginsByPriority;
+    /**
+     * Calculates execution statistics
+     * @param results - Array of execution results
+     * @param totalExecutionTime - Total execution time
+     * @returns Execution statistics
+     * @private
+     */
     private calculateStats;
 }
+/**
+ * Utility function to determine optimal concurrency based on system resources
+ * @param pluginCount - Number of plugins to execute
+ * @param systemInfo - Optional system information
+ * @returns Recommended concurrency level
+ */
 export declare function calculateOptimalConcurrency(pluginCount: number, systemInfo?: {
     cpuCount?: number;
     availableMemoryMB?: number;

package/dist/lib/policy/parallelExecutor.js

@@ -1,13 +1,30 @@
+/**
+ * Parallel Execution Manager for Policy Plugins
+ *
+ * This module provides sophisticated parallel execution capabilities for policy plugins,
+ * including resource management, concurrency control, and performance optimization.
+ *
+ * @since 3.0.0
+ */
 import { cpus, totalmem } from 'os';
 import { createLogger } from '../utils/logger.js';
 import { ValidationTimeoutError } from './errors.js';
+/**
+ * Constants for error messages
+ */
 const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+/**
+ * Default parallel execution options
+ */
 const DEFAULT_PARALLEL_OPTIONS = {
     maxConcurrency: Math.max(2, Math.min(8, cpus().length)),
-    useWorkerThreads: false,
+    useWorkerThreads: false, // Disabled by default for simplicity
     pluginTimeout: 5000,
     failFast: false,
 };
+/**
+ * Parallel execution manager for policy plugins
+ */
 export class ParallelExecutor {
     constructor(options = {}) {
         this.activeExecutions = 0;
@@ -21,6 +38,13 @@ export class ParallelExecutor {
             operation: 'parallel_executor_init',
         });
     }
+    /**
+     * Executes plugins in parallel with resource management
+     * @param plugins - Array of plugins to execute
+     * @param manifests - Manifests to validate
+     * @param validationContext - Validation context
+     * @returns Promise resolving to execution results
+     */
     async executePlugins(plugins, manifests, validationContext) {
         const startTime = Date.now();
         this.logger.info('Starting parallel plugin execution', {
@@ -29,8 +53,11 @@ export class ParallelExecutor {
             manifestCount: manifests.length,
             operation: 'parallel_execution_start',
         });
+        // Sort plugins by priority
         const sortedPlugins = this.sortPluginsByPriority(plugins);
+        // Create execution tasks
         const executionTasks = sortedPlugins.map((plugin) => () => this.executePlugin(plugin, manifests, validationContext));
+        // Execute with concurrency control
         const results = await this.executeConcurrently(executionTasks);
         const totalExecutionTime = Date.now() - startTime;
         const stats = this.calculateStats(results, totalExecutionTime);
@@ -43,6 +70,14 @@ export class ParallelExecutor {
         });
         return { results, stats };
     }
+    /**
+     * Executes a single plugin with resource monitoring
+     * @param plugin - Plugin to execute
+     * @param manifests - Manifests to validate
+     * @param validationContext - Validation context
+     * @returns Promise resolving to execution result
+     * @private
+     */
     async executePlugin(plugin, manifests, validationContext) {
         const startTime = Date.now();
         const startMemory = process.memoryUsage().heapUsed;
@@ -52,6 +87,7 @@ export class ParallelExecutor {
             operation: 'plugin_execution_start',
         });
         try {
+            // Execute plugin with timeout
             const violations = await this.executeWithTimeout(plugin, manifests, validationContext, this.options.pluginTimeout);
             const executionTime = Date.now() - startTime;
             const endMemory = process.memoryUsage().heapUsed;
@@ -62,7 +98,7 @@ export class ParallelExecutor {
                 executionTime,
                 resourceUsage: {
                     memoryUsageMB,
-                    cpuTimeMs: executionTime,
+                    cpuTimeMs: executionTime, // Approximation
                 },
             };
             this.logger.debug('Plugin execution completed successfully', {
@@ -97,6 +133,15 @@ export class ParallelExecutor {
             };
         }
     }
+    /**
+     * Executes plugin with timeout handling
+     * @param plugin - Plugin to execute
+     * @param manifests - Manifests to validate
+     * @param validationContext - Validation context
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise resolving to violations
+     * @private
+     */
     async executeWithTimeout(plugin, manifests, validationContext, timeout) {
         const timeoutPromise = new Promise((_, reject) => {
             globalThis.setTimeout(() => {
@@ -106,6 +151,12 @@ export class ParallelExecutor {
         const validationPromise = plugin.validate(manifests, validationContext);
         return Promise.race([validationPromise, timeoutPromise]);
     }
+    /**
+     * Executes tasks with concurrency control
+     * @param tasks - Array of execution tasks
+     * @returns Promise resolving to results
+     * @private
+     */
     async executeConcurrently(tasks) {
         const results = [];
         const executing = [];
@@ -116,6 +167,7 @@ export class ParallelExecutor {
                 return;
             }
             const currentTaskIndex = taskIndex++;
+            // eslint-disable-next-line security/detect-object-injection
             const task = tasks[currentTaskIndex];
             if (!task) {
                 return;
@@ -124,7 +176,9 @@ export class ParallelExecutor {
             peakConcurrency = Math.max(peakConcurrency, this.activeExecutions);
             try {
                 const result = await task();
+                // eslint-disable-next-line security/detect-object-injection
                 results[currentTaskIndex] = result;
+                // Check for fail-fast condition
                 if (this.options.failFast && result.error) {
                     this.logger.debug('Fail-fast triggered, stopping execution', {
                         pluginName: result.plugin.name,
@@ -135,6 +189,7 @@ export class ParallelExecutor {
                 }
             }
             catch (error) {
+                // This shouldn't happen as executePlugin catches all errors
                 this.logger.error('Unexpected error in parallel execution', {
                     taskIndex: currentTaskIndex,
                     error: error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE,
@@ -144,14 +199,18 @@ export class ParallelExecutor {
             finally {
                 this.activeExecutions--;
             }
+            // Continue with next task if available and not in fail-fast mode
+            // eslint-disable-next-line security/detect-object-injection
             if (!this.options.failFast || !results[currentTaskIndex]?.error) {
                 await executeNext();
             }
         };
+        // Start initial batch of concurrent executions
         const maxConcurrency = this.options.maxConcurrency;
         for (let i = 0; i < Math.min(maxConcurrency, tasks.length); i++) {
             executing.push(executeNext());
         }
+        // Wait for all executions to complete
         await Promise.all(executing);
         this.logger.debug('Concurrent execution completed', {
             totalTasks: tasks.length,
@@ -159,8 +218,14 @@ export class ParallelExecutor {
             peakConcurrency,
             operation: 'concurrent_execution_complete',
         });
-        return results.filter((r) => r);
+        return results.filter((r) => r); // Filter out undefined results
     }
+    /**
+     * Sorts plugins by priority configuration
+     * @param plugins - Array of plugins to sort
+     * @returns Sorted array of plugins
+     * @private
+     */
     sortPluginsByPriority(plugins) {
         if (!this.options.priorityConfig) {
             return [...plugins];
@@ -179,12 +244,20 @@ export class ParallelExecutor {
         });
         return sortedPlugins;
     }
+    /**
+     * Calculates execution statistics
+     * @param results - Array of execution results
+     * @param totalExecutionTime - Total execution time
+     * @returns Execution statistics
+     * @private
+     */
     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);
+        // Calculate concurrency utilization
         const theoreticalMinTime = Math.max(...executionTimes);
         const concurrencyUtilization = theoreticalMinTime / totalExecutionTime;
         return {
@@ -201,15 +274,25 @@ export class ParallelExecutor {
         };
     }
 }
+/**
+ * Utility function to determine optimal concurrency based on system resources
+ * @param pluginCount - Number of plugins to execute
+ * @param systemInfo - Optional system information
+ * @returns Recommended concurrency level
+ */
 export function calculateOptimalConcurrency(pluginCount, systemInfo) {
     const cpuCount = systemInfo?.cpuCount || cpus().length;
     const availableMemoryMB = systemInfo?.availableMemoryMB || totalmem() / (1024 * 1024);
+    // Base concurrency on CPU count
     let optimalConcurrency = Math.max(2, Math.min(cpuCount, pluginCount));
+    // Adjust for memory constraints (assume 100MB per concurrent plugin)
     const memoryBasedConcurrency = Math.floor(availableMemoryMB / 100);
     optimalConcurrency = Math.min(optimalConcurrency, memoryBasedConcurrency);
+    // Reduce concurrency in containerized environments
     if (systemInfo?.isContainerized) {
         optimalConcurrency = Math.max(1, Math.floor(optimalConcurrency * 0.75));
     }
+    // Cap at reasonable maximum
     optimalConcurrency = Math.min(optimalConcurrency, 16);
     return optimalConcurrency;
 }