timonel 3.1.1 → 3.1.2

package/dist/lib/policy/configurationLoader.js

@@ -1,5 +1,17 @@
+/**
+ * Configuration Loader
+ *
+ * This module provides configuration loading and validation for policy plugins.
+ * It supports environment-specific configuration, schema validation, and
+ * configuration inheritance.
+ *
+ * @since 3.0.0
+ */
 import { createLogger } from '../utils/logger.js';
 import { PluginConfigurationError } from './errors.js';
+/**
+ * Default configuration loader options
+ */
 const DEFAULT_LOADER_OPTIONS = {
     defaultEnvironment: 'development',
     validateSchemas: true,
@@ -7,12 +19,18 @@ const DEFAULT_LOADER_OPTIONS = {
     configurationFiles: [],
     environmentPrefix: 'TIMONEL_POLICY',
 };
+/**
+ * Configuration priority levels
+ */
 const CONFIGURATION_PRIORITIES = {
     default: 0,
     file: 10,
     environment: 20,
     inline: 30,
 };
+/**
+ * Configuration loader for policy plugins
+ */
 export class ConfigurationLoader {
     constructor(options = {}) {
         this.configurations = new Map();
@@ -24,6 +42,13 @@ export class ConfigurationLoader {
             operation: 'config_loader_init',
         });
     }
+    /**
+     * Loads configuration for a plugin
+     * @param plugin - Plugin to load configuration for
+     * @param environment - Target environment
+     * @param inlineConfig - Inline configuration to merge
+     * @returns Plugin configuration
+     */
     async loadPluginConfiguration(plugin, environment, inlineConfig) {
         const targetEnvironment = environment || this.options.defaultEnvironment;
         this.logger.debug('Loading plugin configuration', {
@@ -32,8 +57,11 @@ export class ConfigurationLoader {
             hasInlineConfig: inlineConfig !== undefined,
             operation: 'load_plugin_config',
         });
+        // Collect configuration entries from all sources
         const entries = await this.collectConfigurationEntries(plugin, targetEnvironment, inlineConfig);
+        // Merge configurations by priority
         const mergedConfig = this.mergeConfigurations(entries);
+        // Validate configuration if schema is provided
         const validationResult = this.validatePluginConfiguration(plugin, mergedConfig);
         const result = {
             pluginName: plugin.name,
@@ -54,8 +82,13 @@ export class ConfigurationLoader {
         });
         return result;
     }
+    /**
+     * Collects configuration entries from all sources
+     * @private
+     */
     async collectConfigurationEntries(plugin, targetEnvironment, inlineConfig) {
         const entries = [];
+        // 1. Default configuration (if plugin provides it)
         if (plugin.metadata?.defaultConfig) {
             entries.push({
                 value: plugin.metadata.defaultConfig,
@@ -64,6 +97,7 @@ export class ConfigurationLoader {
                 ...(plugin.configSchema && { schema: plugin.configSchema }),
             });
         }
+        // 2. File-based configuration
         const fileConfig = await this.loadFileConfiguration(plugin.name, targetEnvironment);
         if (fileConfig) {
             entries.push({
@@ -74,6 +108,7 @@ export class ConfigurationLoader {
                 ...(plugin.configSchema && { schema: plugin.configSchema }),
             });
         }
+        // 3. Environment variable configuration
         const envConfig = this.loadEnvironmentVariableConfiguration(plugin.name);
         if (envConfig) {
             entries.push({
@@ -83,6 +118,7 @@ export class ConfigurationLoader {
                 ...(plugin.configSchema && { schema: plugin.configSchema }),
             });
         }
+        // 4. Inline configuration (highest priority)
         if (inlineConfig) {
             entries.push({
                 value: inlineConfig,
@@ -93,6 +129,10 @@ export class ConfigurationLoader {
         }
         return entries;
     }
+    /**
+     * Validates plugin configuration
+     * @private
+     */
     validatePluginConfiguration(plugin, mergedConfig) {
         let validated = false;
         let validationErrors;
@@ -112,6 +152,11 @@ export class ConfigurationLoader {
         }
         return { validated, ...(validationErrors && { validationErrors }) };
     }
+    /**
+     * Loads environment-specific configuration
+     * @param environment - Environment name
+     * @returns Environment configuration
+     */
     async loadEnvironmentConfiguration(environment) {
         if (this.environmentConfigs.has(environment)) {
             return this.environmentConfigs.get(environment);
@@ -120,6 +165,7 @@ export class ConfigurationLoader {
             environment,
             operation: 'load_env_config',
         });
+        // Load from configuration files
         const envConfig = await this.loadEnvironmentFromFiles(environment);
         if (envConfig) {
             this.environmentConfigs.set(environment, envConfig);
@@ -132,6 +178,13 @@ export class ConfigurationLoader {
         }
         return envConfig;
     }
+    /**
+     * Validates configuration against a JSON schema
+     * @param config - Configuration to validate
+     * @param schema - JSON schema to validate against
+     * @param pluginName - Plugin name for error reporting
+     * @throws {PluginConfigurationError} When validation fails
+     */
     validateConfiguration(config, schema, pluginName) {
         try {
             this.validateAgainstSchema(config, schema, []);
@@ -140,12 +193,18 @@ export class ConfigurationLoader {
             throw new PluginConfigurationError(`Configuration validation failed for plugin '${pluginName}': ${error instanceof Error ? error.message : String(error)}`, pluginName, undefined, { config, schema, validationError: error });
         }
     }
+    /**
+     * Adds a configuration entry for a plugin
+     * @param pluginName - Plugin name
+     * @param entry - Configuration entry to add
+     */
     addConfigurationEntry(pluginName, entry) {
         if (!this.configurations.has(pluginName)) {
             this.configurations.set(pluginName, []);
         }
         const entries = this.configurations.get(pluginName);
         entries.push(entry);
+        // Sort by priority (highest first)
         entries.sort((a, b) => b.priority - a.priority);
         this.logger.debug('Configuration entry added', {
             pluginName,
@@ -154,9 +213,17 @@ export class ConfigurationLoader {
             operation: 'config_entry_added',
         });
     }
+    /**
+     * Gets all configuration entries for a plugin
+     * @param pluginName - Plugin name
+     * @returns Array of configuration entries
+     */
     getConfigurationEntries(pluginName) {
         return this.configurations.get(pluginName) || [];
     }
+    /**
+     * Clears all cached configurations
+     */
     clearCache() {
         this.configurations.clear();
         this.environmentConfigs.clear();
@@ -164,9 +231,24 @@ export class ConfigurationLoader {
             operation: 'config_cache_cleared',
         });
     }
+    /**
+     * Loads file-based configuration for a plugin
+     * @param _pluginName - Plugin name (unused)
+     * @param _environment - Target environment (unused)
+     * @returns Configuration object or undefined
+     * @private
+     */
     async loadFileConfiguration(_pluginName, _environment) {
+        // For now, return undefined as file loading is not implemented
+        // This would typically load from JSON/YAML files
         return undefined;
     }
+    /**
+     * Loads environment variable configuration for a plugin
+     * @param pluginName - Plugin name
+     * @returns Configuration object or undefined
+     * @private
+     */
     loadEnvironmentVariableConfiguration(pluginName) {
         if (!pluginName) {
             return undefined;
@@ -174,19 +256,36 @@ export class ConfigurationLoader {
         const prefix = `${this.options.environmentPrefix}_${pluginName.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
         const config = Object.create(null);
         let hasConfig = false;
+        // Scan environment variables with the plugin prefix
         for (const [key, value] of Object.entries(process.env)) {
             if (key.startsWith(prefix + '_')) {
                 const configKey = key.substring(prefix.length + 1).toLowerCase();
+                // eslint-disable-next-line security/detect-object-injection
                 config[configKey] = this.parseEnvironmentValue(value);
                 hasConfig = true;
             }
         }
         return hasConfig ? config : undefined;
     }
+    /**
+     * Loads environment configuration from files
+     * @param _environment - Environment name (unused)
+     * @returns Environment configuration or undefined
+     * @private
+     */
     async loadEnvironmentFromFiles(_environment) {
+        // For now, return undefined as file loading is not implemented
+        // This would typically load from configuration files
         return undefined;
     }
+    /**
+     * Merges configuration entries by priority
+     * @param entries - Configuration entries to merge
+     * @returns Merged configuration
+     * @private
+     */
     mergeConfigurations(entries) {
+        // Sort by priority (lowest first for proper merging)
         const sortedEntries = [...entries].sort((a, b) => a.priority - b.priority);
         let merged = {};
         for (const entry of sortedEntries) {
@@ -196,20 +295,40 @@ export class ConfigurationLoader {
         }
         return merged;
     }
+    /**
+     * Parses environment variable value to appropriate type
+     * @param value - Environment variable value
+     * @returns Parsed value
+     * @private
+     */
     parseEnvironmentValue(value) {
         if (!value)
             return undefined;
+        // Try to parse as JSON first
         try {
             return JSON.parse(value);
         }
         catch {
+            // Return as string if not valid JSON
             return value;
         }
     }
+    /**
+     * Validates a configuration object against a JSON schema
+     * @param config - Configuration to validate
+     * @param schema - JSON schema
+     * @param path - Current path for error reporting
+     * @throws {Error} When validation fails
+     * @private
+     */
     validateAgainstSchema(config, schema, path) {
         this.validateBasicType(config, schema, path);
         this.validateObjectProperties(config, schema, path);
     }
+    /**
+     * Validates basic type constraints
+     * @private
+     */
     validateBasicType(config, schema, path) {
         if (schema.type) {
             const actualType = Array.isArray(config) ? 'array' : typeof config;
@@ -218,6 +337,10 @@ export class ConfigurationLoader {
             }
         }
     }
+    /**
+     * Validates object properties
+     * @private
+     */
     validateObjectProperties(config, schema, path) {
         if (schema.type === 'object' &&
             schema.properties &&
@@ -228,6 +351,10 @@ export class ConfigurationLoader {
             this.validateEachProperty(configObj, schema, path);
         }
     }
+    /**
+     * Validates required properties
+     * @private
+     */
     validateRequiredProperties(configObj, schema, path) {
         if (schema.required) {
             for (const requiredProp of schema.required) {
@@ -237,8 +364,13 @@ export class ConfigurationLoader {
             }
         }
     }
+    /**
+     * Validates each property in the object
+     * @private
+     */
     validateEachProperty(configObj, schema, path) {
         for (const [propName, propValue] of Object.entries(configObj)) {
+            // eslint-disable-next-line security/detect-object-injection
             const propSchema = schema.properties?.[propName];
             if (propSchema) {
                 this.validateAgainstSchema(propValue, propSchema, [...path, propName]);

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

@@ -1,23 +1,40 @@
+/**
+ * Error Context Generator
+ *
+ * This module provides utilities for generating detailed error context
+ * for policy violations, including stack traces, environment information,
+ * and debugging hints.
+ *
+ * @since 3.0.0
+ */
 import type { PolicyViolation, PolicyWarning, ValidationContext } from './types.js';
+/**
+ * Enhanced error context information
+ */
 export interface ErrorContext {
+    /** Error timestamp */
     readonly timestamp: string;
+    /** Environment information */
     readonly environment: {
         readonly nodeVersion: string;
         readonly platform: string;
         readonly arch: string;
         readonly timonelVersion?: string;
     };
+    /** Validation context */
     readonly validationContext: {
         readonly chartName?: string;
         readonly chartVersion?: string;
         readonly kubernetesVersion?: string;
         readonly environment?: string;
     };
+    /** Plugin information */
     readonly plugin: {
         readonly name: string;
         readonly version?: string;
         readonly executionTime?: number;
     };
+    /** Error details */
     readonly error: {
         readonly message: string;
         readonly severity: 'error' | 'warning' | 'info';
@@ -27,15 +44,36 @@ export interface ErrorContext {
         readonly stackTrace?: string;
         readonly originalContext?: Record<string, unknown>;
     };
+    /** Debugging hints */
     readonly debuggingHints: string[];
+    /** Related violations */
     readonly relatedViolations?: Array<{
         readonly plugin: string;
         readonly message: string;
         readonly similarity: number;
     }>;
 }
+/**
+ * Error context generator for policy violations
+ */
 export declare class ErrorContextGenerator {
+    /**
+     * Generates detailed error context for a policy violation
+     * @param violation - Policy violation to generate context for
+     * @param validationContext - Validation context
+     * @param allViolations - All violations for finding related issues
+     * @param executionTime - Plugin execution time
+     * @returns Enhanced error context
+     */
     generateContext(violation: PolicyViolation | PolicyWarning, validationContext?: ValidationContext, allViolations?: (PolicyViolation | PolicyWarning)[], executionTime?: number): ErrorContext;
+    /**
+     * Generates a formatted error report
+     * @param violation - Policy violation
+     * @param validationContext - Validation context
+     * @param allViolations - All violations
+     * @param executionTime - Plugin execution time
+     * @returns Formatted error report string
+     */
     generateErrorReport(violation: PolicyViolation | PolicyWarning, validationContext?: ValidationContext, allViolations?: (PolicyViolation | PolicyWarning)[], executionTime?: number): string;
     private addReportHeader;
     private addBasicInformation;
@@ -46,9 +84,32 @@ export declare class ErrorContextGenerator {
     private addDebuggingHints;
     private addRelatedViolations;
     private addOriginalContext;
+    /**
+     * Gets environment information
+     * @returns Environment information object
+     * @private
+     */
     private getEnvironmentInfo;
+    /**
+     * Gets Timonel version from package.json
+     * @returns Timonel version or undefined
+     * @private
+     */
     private getTimonelVersion;
+    /**
+     * Extracts validation context information
+     * @param validationContext - Validation context
+     * @returns Validation context information
+     * @private
+     */
     private getValidationContextInfo;
+    /**
+     * Generates debugging hints based on the violation
+     * @param violation - Policy violation
+     * @param validationContext - Validation context
+     * @returns Array of debugging hints
+     * @private
+     */
     private generateDebuggingHints;
     private addSeverityHints;
     private addResourcePathHints;
@@ -56,8 +117,36 @@ export declare class ErrorContextGenerator {
     private addPluginHints;
     private addEnvironmentHints;
     private addKubernetesVersionHints;
+    /**
+     * Finds violations related to the current one
+     * @param violation - Current violation
+     * @param allViolations - All violations to search through
+     * @returns Array of related violations with similarity scores
+     * @private
+     */
     private findRelatedViolations;
+    /**
+     * Calculates similarity between two violations
+     * @param violation1 - First violation
+     * @param violation2 - Second violation
+     * @returns Similarity score between 0 and 1
+     * @private
+     */
     private calculateSimilarity;
+    /**
+     * Calculates string similarity using a simple algorithm
+     * @param str1 - First string
+     * @param str2 - Second string
+     * @returns Similarity score between 0 and 1
+     * @private
+     */
     private calculateStringSimilarity;
+    /**
+     * Calculates Levenshtein distance between two strings
+     * @param str1 - First string
+     * @param str2 - Second string
+     * @returns Edit distance
+     * @private
+     */
     private calculateLevenshteinDistance;
 }

package/dist/lib/policy/errorContextGenerator.js

@@ -1,4 +1,24 @@
+/**
+ * Error Context Generator
+ *
+ * This module provides utilities for generating detailed error context
+ * for policy violations, including stack traces, environment information,
+ * and debugging hints.
+ *
+ * @since 3.0.0
+ */
+/**
+ * Error context generator for policy violations
+ */
 export class ErrorContextGenerator {
+    /**
+     * Generates detailed error context for a policy violation
+     * @param violation - Policy violation to generate context for
+     * @param validationContext - Validation context
+     * @param allViolations - All violations for finding related issues
+     * @param executionTime - Plugin execution time
+     * @returns Enhanced error context
+     */
     generateContext(violation, validationContext, allViolations, executionTime) {
         return {
             timestamp: new Date().toISOString(),
@@ -20,6 +40,14 @@ export class ErrorContextGenerator {
             relatedViolations: this.findRelatedViolations(violation, allViolations),
         };
     }
+    /**
+     * Generates a formatted error report
+     * @param violation - Policy violation
+     * @param validationContext - Validation context
+     * @param allViolations - All violations
+     * @param executionTime - Plugin execution time
+     * @returns Formatted error report string
+     */
     generateErrorReport(violation, validationContext, allViolations, executionTime) {
         const context = this.generateContext(violation, validationContext, allViolations, executionTime);
         const lines = [];
@@ -126,6 +154,11 @@ export class ErrorContextGenerator {
             lines.push('');
         }
     }
+    /**
+     * Gets environment information
+     * @returns Environment information object
+     * @private
+     */
     getEnvironmentInfo() {
         const timonelVersion = this.getTimonelVersion();
         return {
@@ -135,9 +168,23 @@ export class ErrorContextGenerator {
             ...(timonelVersion && { timonelVersion }),
         };
     }
+    /**
+     * Gets Timonel version from package.json
+     * @returns Timonel version or undefined
+     * @private
+     */
     getTimonelVersion() {
-        return '3.0.0';
+        // Try to read package.json to get version
+        // This is a simplified approach - in a real implementation,
+        // you might want to read from a constants file or build-time injection
+        return '3.0.0'; // Placeholder
     }
+    /**
+     * Extracts validation context information
+     * @param validationContext - Validation context
+     * @returns Validation context information
+     * @private
+     */
     getValidationContextInfo(validationContext) {
         return {
             ...(validationContext?.chart?.name && { chartName: validationContext.chart.name }),
@@ -148,6 +195,13 @@ export class ErrorContextGenerator {
             ...(validationContext?.environment && { environment: validationContext.environment }),
         };
     }
+    /**
+     * Generates debugging hints based on the violation
+     * @param violation - Policy violation
+     * @param validationContext - Validation context
+     * @returns Array of debugging hints
+     * @private
+     */
     generateDebuggingHints(violation, validationContext) {
         const hints = [];
         this.addSeverityHints(hints, violation);
@@ -220,6 +274,13 @@ export class ErrorContextGenerator {
             }
         }
     }
+    /**
+     * Finds violations related to the current one
+     * @param violation - Current violation
+     * @param allViolations - All violations to search through
+     * @returns Array of related violations with similarity scores
+     * @private
+     */
     findRelatedViolations(violation, allViolations) {
         if (!allViolations || allViolations.length <= 1) {
             return [];
@@ -230,6 +291,7 @@ export class ErrorContextGenerator {
                 continue;
             const similarity = this.calculateSimilarity(violation, other);
             if (similarity > 0.3) {
+                // 30% similarity threshold
                 related.push({
                     plugin: other.plugin,
                     message: other.message,
@@ -237,34 +299,54 @@ export class ErrorContextGenerator {
                 });
             }
         }
+        // Sort by similarity and return top 3
         return related.sort((a, b) => b.similarity - a.similarity).slice(0, 3);
     }
+    /**
+     * Calculates similarity between two violations
+     * @param violation1 - First violation
+     * @param violation2 - Second violation
+     * @returns Similarity score between 0 and 1
+     * @private
+     */
     calculateSimilarity(violation1, violation2) {
         let score = 0;
         let factors = 0;
+        // Same plugin
         if (violation1.plugin === violation2.plugin) {
             score += 0.4;
         }
         factors += 0.4;
+        // Same severity
         if (violation1.severity === violation2.severity) {
             score += 0.2;
         }
         factors += 0.2;
+        // Similar resource path
         if (violation1.resourcePath && violation2.resourcePath) {
             const pathSimilarity = this.calculateStringSimilarity(violation1.resourcePath, violation2.resourcePath);
             score += pathSimilarity * 0.2;
         }
         factors += 0.2;
+        // Similar field
         if (violation1.field && violation2.field) {
             const fieldSimilarity = this.calculateStringSimilarity(violation1.field, violation2.field);
             score += fieldSimilarity * 0.1;
         }
         factors += 0.1;
+        // Similar message
         const messageSimilarity = this.calculateStringSimilarity(violation1.message, violation2.message);
         score += messageSimilarity * 0.1;
         factors += 0.1;
         return factors > 0 ? score / factors : 0;
     }
+    /**
+     * Calculates string similarity using a simple algorithm
+     * @param str1 - First string
+     * @param str2 - Second string
+     * @returns Similarity score between 0 and 1
+     * @private
+     */
     calculateStringSimilarity(str1, str2) {
         if (str1 === str2)
             return 1;
@@ -277,23 +359,38 @@ export class ErrorContextGenerator {
         const editDistance = this.calculateLevenshteinDistance(longer, shorter);
         return (longer.length - editDistance) / longer.length;
     }
+    /**
+     * Calculates Levenshtein distance between two strings
+     * @param str1 - First string
+     * @param str2 - Second string
+     * @returns Edit distance
+     * @private
+     */
     calculateLevenshteinDistance(str1, str2) {
         const matrix = Array(str2.length + 1)
             .fill(null)
             .map(() => Array(str1.length + 1).fill(0));
         for (let i = 0; i <= str2.length; i++) {
+            // eslint-disable-next-line security/detect-object-injection
             matrix[i][0] = i;
         }
         for (let j = 0; j <= str1.length; j++) {
+            // eslint-disable-next-line security/detect-object-injection
             matrix[0][j] = j;
         }
         for (let i = 1; i <= str2.length; i++) {
             for (let j = 1; j <= str1.length; j++) {
                 if (str2.charAt(i - 1) === str1.charAt(j - 1)) {
+                    // eslint-disable-next-line security/detect-object-injection
                     matrix[i][j] = matrix[i - 1][j - 1];
                 }
                 else {
-                    matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+                    // eslint-disable-next-line security/detect-object-injection
+                    matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                    // eslint-disable-next-line security/detect-object-injection
+                    matrix[i][j - 1] + 1, // insertion
+                    // eslint-disable-next-line security/detect-object-injection
+                    matrix[i - 1][j] + 1);
                 }
             }
         }