timonel 3.1.1 → 3.1.2

package/dist/lib/policy/validationCache.js

@@ -1,12 +1,27 @@
+/**
+ * Validation Result Cache Implementation
+ *
+ * This module provides caching functionality for policy validation results to optimize
+ * performance for repeated manifest validations. It implements cache invalidation
+ * strategies and optimizations for large chart processing.
+ *
+ * @since 3.0.0
+ */
 import { createLogger } from '../utils/logger.js';
+/**
+ * Default cache configuration
+ */
 const DEFAULT_CACHE_OPTIONS = {
     maxEntries: 1000,
-    maxAge: 30 * 60 * 1000,
+    maxAge: 30 * 60 * 1000, // 30 minutes
     enableCompression: false,
     evictionStrategy: 'lru',
     cacheFailures: true,
-    minExecutionTimeToCache: 10,
+    minExecutionTimeToCache: 10, // 10ms
 };
+/**
+ * Validation result cache implementation
+ */
 export class ValidationCache {
     constructor(options = {}) {
         this.cache = new Map();
@@ -24,8 +39,15 @@ export class ValidationCache {
             options: this.options,
             operation: 'cache_init',
         });
+        // Set up periodic cleanup
         this.startPeriodicCleanup();
     }
+    /**
+     * Gets a cached validation result if available
+     * @param manifestHash - Hash of the manifests
+     * @param pluginHash - Hash of the plugin configuration
+     * @returns Cached result or undefined if not found
+     */
     get(manifestHash, pluginHash) {
         const cacheKey = this.generateCacheKey(manifestHash, pluginHash);
         const entry = this.cache.get(cacheKey);
@@ -39,6 +61,7 @@ export class ValidationCache {
             });
             return undefined;
         }
+        // Check if entry has expired
         if (this.isExpired(entry)) {
             this.cache.delete(cacheKey);
             this.stats.misses++;
@@ -51,6 +74,7 @@ export class ValidationCache {
             });
             return undefined;
         }
+        // Update access statistics
         entry.accessCount++;
         entry.lastAccessed = Date.now();
         this.stats.hits++;
@@ -64,7 +88,14 @@ export class ValidationCache {
         });
         return entry.result;
     }
+    /**
+     * Stores a validation result in the cache
+     * @param manifestHash - Hash of the manifests
+     * @param pluginHash - Hash of the plugin configuration
+     * @param result - Validation result to cache
+     */
     set(manifestHash, pluginHash, result) {
+        // Check if we should cache this result
         if (!this.shouldCache(result)) {
             this.logger.debug('Skipping cache storage', {
                 manifestHash: manifestHash.substring(0, 8),
@@ -76,6 +107,7 @@ export class ValidationCache {
             return;
         }
         const cacheKey = this.generateCacheKey(manifestHash, pluginHash);
+        // Check if we need to evict entries
         if (this.cache.size >= this.options.maxEntries) {
             this.evictEntries();
         }
@@ -98,12 +130,21 @@ export class ValidationCache {
             operation: 'cache_store',
         });
     }
+    /**
+     * Invalidates cache entries based on criteria
+     * @param criteria - Invalidation criteria
+     */
     invalidate(criteria) {
         if (criteria.all) {
             return this.invalidateAll();
         }
         return this.invalidateSelective(criteria);
     }
+    /**
+     * Invalidates all cache entries
+     * @returns Number of invalidated entries
+     * @private
+     */
     invalidateAll() {
         const invalidatedCount = this.cache.size;
         this.cache.clear();
@@ -114,6 +155,12 @@ export class ValidationCache {
         this.updateStats();
         return invalidatedCount;
     }
+    /**
+     * Invalidates cache entries based on selective criteria
+     * @param criteria - Invalidation criteria
+     * @returns Number of invalidated entries
+     * @private
+     */
     invalidateSelective(criteria) {
         const keysToDelete = [];
         for (const [key, entry] of this.cache.entries()) {
@@ -132,6 +179,13 @@ export class ValidationCache {
         this.updateStats();
         return keysToDelete.length;
     }
+    /**
+     * Determines if a cache entry should be invalidated
+     * @param entry - Cache entry to check
+     * @param criteria - Invalidation criteria
+     * @returns True if entry should be invalidated
+     * @private
+     */
     shouldInvalidateEntry(entry, criteria) {
         if (criteria.manifestHash && entry.manifestHash === criteria.manifestHash) {
             return true;
@@ -144,9 +198,16 @@ export class ValidationCache {
         }
         return false;
     }
+    /**
+     * Gets current cache statistics
+     * @returns Cache statistics
+     */
     getStats() {
         return { ...this.stats };
     }
+    /**
+     * Clears all cache statistics
+     */
     clearStats() {
         this.stats = {
             hits: 0,
@@ -160,23 +221,48 @@ export class ValidationCache {
             operation: 'cache_stats_clear',
         });
     }
+    /**
+     * Generates a cache key from manifest and plugin hashes
+     * @param manifestHash - Hash of the manifests
+     * @param pluginHash - Hash of the plugin configuration
+     * @returns Cache key string
+     * @private
+     */
     generateCacheKey(manifestHash, pluginHash) {
         return `${manifestHash}:${pluginHash}`;
     }
+    /**
+     * Checks if a cache entry has expired
+     * @param entry - Cache entry to check
+     * @returns True if expired
+     * @private
+     */
     isExpired(entry) {
         return Date.now() - entry.timestamp > this.options.maxAge;
     }
+    /**
+     * Determines if a validation result should be cached
+     * @param result - Validation result
+     * @returns True if should be cached
+     * @private
+     */
     shouldCache(result) {
+        // Don't cache if execution time is too short
         if (result.metadata.executionTime < this.options.minExecutionTimeToCache) {
             return false;
         }
+        // Don't cache failures if disabled
         if (!this.options.cacheFailures && !result.valid) {
             return false;
         }
         return true;
     }
+    /**
+     * Evicts cache entries based on the configured strategy
+     * @private
+     */
     evictEntries() {
-        const entriesToEvict = Math.max(1, Math.floor(this.options.maxEntries * 0.1));
+        const entriesToEvict = Math.max(1, Math.floor(this.options.maxEntries * 0.1)); // Evict 10%
         switch (this.options.evictionStrategy) {
             case 'lru':
                 this.evictLRU(entriesToEvict);
@@ -195,6 +281,11 @@ export class ValidationCache {
             operation: 'cache_evict',
         });
     }
+    /**
+     * Evicts least recently used entries
+     * @param count - Number of entries to evict
+     * @private
+     */
     evictLRU(count) {
         const entries = Array.from(this.cache.entries())
             .sort(([, a], [, b]) => a.lastAccessed - b.lastAccessed)
@@ -203,6 +294,11 @@ export class ValidationCache {
             this.cache.delete(key);
         }
     }
+    /**
+     * Evicts least frequently used entries
+     * @param count - Number of entries to evict
+     * @private
+     */
     evictLFU(count) {
         const entries = Array.from(this.cache.entries())
             .sort(([, a], [, b]) => a.accessCount - b.accessCount)
@@ -211,6 +307,11 @@ export class ValidationCache {
             this.cache.delete(key);
         }
     }
+    /**
+     * Evicts oldest entries (time to live)
+     * @param count - Number of entries to evict
+     * @private
+     */
     evictTTL(count) {
         const entries = Array.from(this.cache.entries())
             .sort(([, a], [, b]) => a.timestamp - b.timestamp)
@@ -219,6 +320,10 @@ export class ValidationCache {
             this.cache.delete(key);
         }
     }
+    /**
+     * Updates cache statistics
+     * @private
+     */
     updateStats() {
         const totalRequests = this.stats.hits + this.stats.misses;
         this.stats.entries = this.cache.size;
@@ -232,22 +337,36 @@ export class ValidationCache {
             this.stats.averageAccessCount = 0;
         }
     }
+    /**
+     * Estimates memory usage of the cache
+     * @returns Estimated memory usage in bytes
+     * @private
+     */
     estimateMemoryUsage() {
         let totalSize = 0;
         for (const entry of this.cache.values()) {
-            totalSize += JSON.stringify(entry.result).length * 2;
+            // Rough estimation of entry size
+            totalSize += JSON.stringify(entry.result).length * 2; // UTF-16 encoding
             totalSize += entry.manifestHash.length * 2;
             totalSize += entry.pluginHash.length * 2;
-            totalSize += 64;
+            totalSize += 64; // Overhead for timestamps and counters
         }
         return totalSize;
     }
+    /**
+     * Starts periodic cleanup of expired entries
+     * @private
+     */
     startPeriodicCleanup() {
-        const cleanupInterval = Math.min(this.options.maxAge / 4, 5 * 60 * 1000);
+        const cleanupInterval = Math.min(this.options.maxAge / 4, 5 * 60 * 1000); // Every 5 minutes or 1/4 of maxAge
         globalThis.setInterval(() => {
             this.cleanupExpiredEntries();
         }, cleanupInterval);
     }
+    /**
+     * Removes expired entries from the cache
+     * @private
+     */
     cleanupExpiredEntries() {
         const keysToDelete = [];
         const now = Date.now();
@@ -269,10 +388,21 @@ export class ValidationCache {
         }
     }
 }
+/**
+ * Utility function to generate a hash from manifests
+ * @param manifests - Array of manifest objects
+ * @returns Hash string
+ */
 export function generateManifestHash(manifests) {
     const manifestString = JSON.stringify(manifests, Object.keys(manifests).sort());
     return hashString(manifestString);
 }
+/**
+ * Utility function to generate a hash from plugin configuration
+ * @param plugins - Array of plugin names
+ * @param pluginConfigs - Plugin configurations
+ * @returns Hash string
+ */
 export function generatePluginHash(plugins, pluginConfigs) {
     const configString = JSON.stringify({
         plugins: plugins.sort(),
@@ -280,6 +410,12 @@ export function generatePluginHash(plugins, pluginConfigs) {
     }, Object.keys({ plugins: plugins.sort(), configs: pluginConfigs }).sort());
     return hashString(configString);
 }
+/**
+ * Simple string hashing function (djb2 algorithm)
+ * @param str - String to hash
+ * @returns Hash string
+ * @private
+ */
 function hashString(str) {
     let hash = 5381;
     for (let i = 0; i < str.length; i++) {

package/dist/lib/resources/baseResourceProvider.d.ts

@@ -1,13 +1,58 @@
 import { ApiObject } from 'cdk8s';
 import type { Chart } from 'cdk8s';
+/**
+ * Base interface for all resource providers
+ * Provides common functionality and ensures consistent patterns across providers
+ *
+ * @since 2.8.0+
+ */
 export interface IResourceProvider {
+    /** Reference to the CDK8s chart */
     readonly chart: Chart;
 }
+/**
+ * Abstract base class for resource providers
+ * Implements common functionality and validation patterns
+ *
+ * @since 2.4.0
+ */
 export declare abstract class BaseResourceProvider implements IResourceProvider {
     readonly chart: Chart;
     constructor(chart: Chart);
+    /**
+     * Validates that a name follows Kubernetes naming conventions
+     * @param name - Resource name to validate
+     * @param resourceType - Type of resource for error messages
+     * @throws Error if name is invalid
+     */
     protected validateKubernetesName(name: string, resourceType: string): void;
+    /**
+     * Validates that labels follow Kubernetes conventions
+     * @param labels - Labels to validate
+     * @param resourceType - Type of resource for error messages
+     */
     protected validateLabels(labels: Record<string, string> | undefined, resourceType: string): void;
+    /**
+     * Creates a standardized ApiObject with common metadata
+     * @param name - Resource name
+     * @param apiVersion - Kubernetes API version
+     * @param kind - Kubernetes resource kind
+     * @param spec - Resource specification
+     * @param labels - Optional labels
+     * @param annotations - Optional annotations
+     * @returns Created ApiObject
+     */
     protected createApiObject(name: string, apiVersion: string, kind: string, spec: Record<string, unknown>, labels?: Record<string, string>, annotations?: Record<string, string>): ApiObject;
+    /**
+     * Creates an ApiObject for resources that don't use spec wrapper (like StorageClass)
+     * @param name - Resource name
+     * @param apiVersion - API version
+     * @param kind - Resource kind
+     * @param fields - Root-level fields for the resource
+     * @param labels - Optional labels
+     * @param annotations - Optional annotations
+     * @returns Created ApiObject
+     * @since 2.8.0+
+     */
     protected createRootLevelApiObject(name: string, apiVersion: string, kind: string, fields: Record<string, unknown>, labels?: Record<string, string>, annotations?: Record<string, string>): ApiObject;
 }

package/dist/lib/resources/baseResourceProvider.js

@@ -1,36 +1,70 @@
 import { ApiObject } from 'cdk8s';
+/**
+ * Abstract base class for resource providers
+ * Implements common functionality and validation patterns
+ *
+ * @since 2.4.0
+ */
 export class BaseResourceProvider {
     constructor(chart) {
         this.chart = chart;
     }
+    /**
+     * Validates that a name follows Kubernetes naming conventions
+     * @param name - Resource name to validate
+     * @param resourceType - Type of resource for error messages
+     * @throws Error if name is invalid
+     */
     validateKubernetesName(name, resourceType) {
         if (!name || typeof name !== 'string') {
             throw new Error(`${resourceType} name must be a non-empty string`);
         }
+        // Kubernetes name validation (RFC 1123 subdomain)
+        // eslint-disable-next-line security/detect-unsafe-regex -- Simple character class regex is safe
         const nameRegex = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/;
         if (!nameRegex.test(name) || name.length > 63) {
             throw new Error(`${resourceType} name '${name}' must be a valid Kubernetes name (lowercase alphanumeric and hyphens, max 63 chars)`);
         }
     }
+    /**
+     * Validates that labels follow Kubernetes conventions
+     * @param labels - Labels to validate
+     * @param resourceType - Type of resource for error messages
+     */
     validateLabels(labels, resourceType) {
         if (!labels)
             return;
         Object.entries(labels).forEach(([key, value]) => {
+            // Validate label key
             if (key.length > 253) {
                 throw new Error(`${resourceType} label key '${key}' exceeds 253 characters`);
             }
+            // Validate label value
             if (value.length > 63) {
                 throw new Error(`${resourceType} label value '${value}' exceeds 63 characters`);
             }
+            // Skip validation for Helm template values
             if (value.includes('{{') && value.includes('}}')) {
                 return;
             }
+            // Basic character validation
+            // eslint-disable-next-line security/detect-unsafe-regex -- Simple character class regex is safe
             const labelRegex = /^[a-zA-Z0-9]([-a-zA-Z0-9_.]*[a-zA-Z0-9])?$/;
             if (!labelRegex.test(value)) {
                 throw new Error(`${resourceType} label value '${value}' contains invalid characters`);
             }
         });
     }
+    /**
+     * Creates a standardized ApiObject with common metadata
+     * @param name - Resource name
+     * @param apiVersion - Kubernetes API version
+     * @param kind - Kubernetes resource kind
+     * @param spec - Resource specification
+     * @param labels - Optional labels
+     * @param annotations - Optional annotations
+     * @returns Created ApiObject
+     */
     createApiObject(name, apiVersion, kind, spec, labels, annotations) {
         this.validateKubernetesName(name, kind);
         this.validateLabels(labels, kind);
@@ -45,9 +79,21 @@ export class BaseResourceProvider {
             spec,
         });
     }
+    /**
+     * Creates an ApiObject for resources that don't use spec wrapper (like StorageClass)
+     * @param name - Resource name
+     * @param apiVersion - API version
+     * @param kind - Resource kind
+     * @param fields - Root-level fields for the resource
+     * @param labels - Optional labels
+     * @param annotations - Optional annotations
+     * @returns Created ApiObject
+     * @since 2.8.0+
+     */
     createRootLevelApiObject(name, apiVersion, kind, fields, labels, annotations) {
         this.validateKubernetesName(name, kind);
         this.validateLabels(labels, kind);
+        // Validate that fields doesn't contain reserved keys
         const reservedKeys = ['apiVersion', 'kind', 'metadata'];
         const conflictingKeys = Object.keys(fields).filter((key) => reservedKeys.includes(key));
         if (conflictingKeys.length > 0) {
@@ -61,7 +107,8 @@ export class BaseResourceProvider {
                 ...(labels && Object.keys(labels).length > 0 ? { labels } : {}),
                 ...(annotations && Object.keys(annotations).length > 0 ? { annotations } : {}),
             },
-            ...fields,
+            // Safe: fields validated above to not contain reserved keys (apiVersion, kind, metadata)
+            ...fields, // Fields go at root level, not under spec
         });
     }
 }