timonel 3.1.1 → 3.1.2

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

@@ -1,41 +1,133 @@
+/**
+ * Plugin Loader
+ *
+ * This module provides plugin discovery and loading capabilities for the policy engine.
+ * It supports loading plugins from npm packages, version compatibility checks, and
+ * conditional loading based on environment.
+ *
+ * @since 3.0.0
+ */
 import type { PolicyPlugin, PluginMetadata } from './types.js';
+/**
+ * Plugin loading options
+ */
 export interface PluginLoaderOptions {
+    /** Base directory for plugin discovery */
     baseDirectory?: string;
+    /** Environment for conditional loading */
     environment?: string;
+    /** Whether to validate plugin compatibility */
     validateCompatibility?: boolean;
+    /** Supported Kubernetes versions for compatibility checks */
     supportedKubernetesVersions?: string[];
+    /** Plugin registry URL for discovery */
     registryUrl?: string;
+    /** Timeout for plugin loading operations */
     loadTimeout?: number;
 }
+/**
+ * Plugin discovery result
+ */
 export interface PluginDiscoveryResult {
+    /** Plugin package name */
     packageName: string;
+    /** Plugin version */
     version: string;
+    /** Plugin metadata */
     metadata?: PluginMetadata;
+    /** Whether plugin is compatible */
     compatible: boolean;
+    /** Compatibility issues if any */
     compatibilityIssues?: string[];
+    /** Plugin source (npm, local, etc.) */
     source: 'npm' | 'local' | 'registry';
 }
+/**
+ * Plugin loading result
+ */
 export interface PluginLoadingResult {
+    /** Loaded plugin instance */
     plugin: PolicyPlugin;
+    /** Plugin package name */
     packageName: string;
+    /** Loading source */
     source: 'npm' | 'local' | 'registry';
+    /** Loading time in milliseconds */
     loadTime: number;
+    /** Whether plugin passed validation */
     validated: boolean;
+    /** Validation warnings if any */
     warnings?: string[];
 }
+/**
+ * Plugin loader for policy engine
+ */
 export declare class PluginLoader {
     private readonly options;
     private readonly logger;
     private readonly loadedPlugins;
     constructor(options?: PluginLoaderOptions);
+    /**
+     * Loads a plugin from an npm package
+     * @param packageName - NPM package name
+     * @param version - Optional version constraint
+     * @returns Plugin loading result
+     */
     loadFromPackage(packageName: string, version?: string): Promise<PluginLoadingResult>;
+    /**
+     * Discovers available plugins in the environment
+     * @param searchPattern - Optional search pattern for plugin names
+     * @returns Array of discovered plugins
+     */
     discoverPlugins(searchPattern?: string): Promise<PluginDiscoveryResult[]>;
+    /**
+     * Loads multiple plugins from a list of package names
+     * @param packages - Array of package names or package@version strings
+     * @returns Array of loading results
+     */
     loadMultiplePlugins(packages: string[]): Promise<PluginLoadingResult[]>;
+    /**
+     * Validates that a plugin implements the required interface
+     * @param plugin - Plugin to validate
+     * @param packageName - Package name for error reporting
+     * @throws {PluginRegistrationError} When plugin is invalid
+     */
     static validatePluginInterface(plugin: unknown, packageName: string): asserts plugin is PolicyPlugin;
+    /**
+     * Gets all loaded plugins
+     * @returns Array of loaded plugin results
+     */
     getLoadedPlugins(): PluginLoadingResult[];
+    /**
+     * Clears the plugin cache
+     */
     clearCache(): void;
+    /**
+     * Loads a module with timeout protection
+     * @param modulePath - Module path to load
+     * @returns Loaded plugin
+     * @private
+     */
     private loadModuleWithTimeout;
+    /**
+     * Validates plugin interface (instance method)
+     * @param plugin - Plugin to validate
+     * @param packageName - Package name for error reporting
+     * @private
+     */
     private validatePluginInterface;
+    /**
+     * Checks plugin compatibility with current environment
+     * @param plugin - Plugin to check
+     * @returns Array of compatibility issues
+     * @private
+     */
     private checkCompatibility;
+    /**
+     * Determines if plugin should be loaded in current environment
+     * @param _plugin - Plugin to check (unused for now)
+     * @returns True if plugin should be loaded
+     * @private
+     */
     private shouldLoadInEnvironment;
 }

package/dist/lib/policy/pluginLoader.js

@@ -1,14 +1,32 @@
+/**
+ * Plugin Loader
+ *
+ * This module provides plugin discovery and loading capabilities for the policy engine.
+ * It supports loading plugins from npm packages, version compatibility checks, and
+ * conditional loading based on environment.
+ *
+ * @since 3.0.0
+ */
 import { createLogger } from '../utils/logger.js';
 import { PluginError, PluginRegistrationError } from './errors.js';
+/**
+ * Constants for error messages
+ */
 const UNKNOWN_ERROR_MESSAGE = 'Unknown error';
+/**
+ * Default plugin loader options
+ */
 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,
+    loadTimeout: 30000, // 30 seconds
 };
+/**
+ * Plugin loader for policy engine
+ */
 export class PluginLoader {
     constructor(options = {}) {
         this.loadedPlugins = new Map();
@@ -19,6 +37,12 @@ export class PluginLoader {
             operation: 'plugin_loader_init',
         });
     }
+    /**
+     * Loads a plugin from an npm package
+     * @param packageName - NPM package name
+     * @param version - Optional version constraint
+     * @returns Plugin loading result
+     */
     async loadFromPackage(packageName, version) {
         const startTime = Date.now();
         this.logger.info('Loading plugin from package', {
@@ -27,6 +51,7 @@ export class PluginLoader {
             operation: 'load_from_package',
         });
         try {
+            // Check if already loaded
             const cacheKey = `${packageName}@${version || 'latest'}`;
             if (this.loadedPlugins.has(cacheKey)) {
                 const cached = this.loadedPlugins.get(cacheKey);
@@ -37,14 +62,19 @@ export class PluginLoader {
                 });
                 return cached;
             }
+            // Construct module path
             const modulePath = version ? `${packageName}@${version}` : packageName;
+            // Load the module with timeout
             const plugin = await this.loadModuleWithTimeout(modulePath);
+            // Validate plugin interface
             this.validatePluginInterface(plugin, packageName);
+            // Check compatibility if enabled
             const warnings = [];
             if (this.options.validateCompatibility) {
                 const compatibilityIssues = this.checkCompatibility(plugin);
                 warnings.push(...compatibilityIssues);
             }
+            // Check environment conditions
             if (!this.shouldLoadInEnvironment(plugin)) {
                 throw new PluginError(`Plugin '${packageName}' is not enabled for environment '${this.options.environment}'`, packageName);
             }
@@ -57,6 +87,7 @@ export class PluginLoader {
                 validated: true,
                 ...(warnings.length > 0 && { warnings }),
             };
+            // Cache the result
             this.loadedPlugins.set(cacheKey, result);
             this.logger.info('Plugin loaded successfully', {
                 packageName,
@@ -80,6 +111,11 @@ export class PluginLoader {
             throw new PluginError(`Failed to load plugin from package '${packageName}': ${error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE}`, packageName, { originalError: error, loadTime });
         }
     }
+    /**
+     * Discovers available plugins in the environment
+     * @param searchPattern - Optional search pattern for plugin names
+     * @returns Array of discovered plugins
+     */
     async discoverPlugins(searchPattern) {
         this.logger.info('Discovering plugins', {
             searchPattern,
@@ -88,6 +124,9 @@ export class PluginLoader {
         });
         const discovered = [];
         try {
+            // For now, return empty array as actual discovery would require
+            // scanning node_modules, package.json, or registry API calls
+            // This is a placeholder for future implementation
             this.logger.info('Plugin discovery completed', {
                 discoveredCount: discovered.length,
                 operation: 'discovery_complete',
@@ -102,6 +141,11 @@ export class PluginLoader {
             throw new PluginError(`Plugin discovery failed: ${error instanceof Error ? error.message : UNKNOWN_ERROR_MESSAGE}`, 'discovery');
         }
     }
+    /**
+     * Loads multiple plugins from a list of package names
+     * @param packages - Array of package names or package@version strings
+     * @returns Array of loading results
+     */
     async loadMultiplePlugins(packages) {
         this.logger.info('Loading multiple plugins', {
             packageCount: packages.length,
@@ -110,6 +154,7 @@ export class PluginLoader {
         });
         const results = [];
         const errors = [];
+        // Load plugins in parallel
         const loadPromises = packages.map(async (pkg) => {
             try {
                 const [packageName, version] = pkg.includes('@') && !pkg.startsWith('@') ? pkg.split('@') : [pkg, undefined];
@@ -124,11 +169,13 @@ export class PluginLoader {
             }
         });
         const loadResults = await Promise.all(loadPromises);
+        // Collect successful results
         for (const result of loadResults) {
             if (result) {
                 results.push(result);
             }
         }
+        // Log errors but don't throw (graceful degradation)
         if (errors.length > 0) {
             this.logger.warn('Some plugins failed to load', {
                 successCount: results.length,
@@ -145,6 +192,12 @@ export class PluginLoader {
         });
         return results;
     }
+    /**
+     * Validates that a plugin implements the required interface
+     * @param plugin - Plugin to validate
+     * @param packageName - Package name for error reporting
+     * @throws {PluginRegistrationError} When plugin is invalid
+     */
     static validatePluginInterface(plugin, packageName) {
         if (!plugin || typeof plugin !== 'object') {
             throw new PluginRegistrationError(`Plugin from package '${packageName}' must be an object`, packageName);
@@ -159,6 +212,7 @@ export class PluginLoader {
         if (typeof p.validate !== 'function') {
             throw new PluginRegistrationError(`Plugin from package '${packageName}' must implement validate method`, packageName);
         }
+        // Validate optional fields if present
         if (p.description !== undefined && typeof p.description !== 'string') {
             throw new PluginRegistrationError(`Plugin from package '${packageName}' description must be a string`, packageName);
         }
@@ -169,23 +223,38 @@ export class PluginLoader {
             throw new PluginRegistrationError(`Plugin from package '${packageName}' metadata must be an object`, packageName);
         }
     }
+    /**
+     * Gets all loaded plugins
+     * @returns Array of loaded plugin results
+     */
     getLoadedPlugins() {
         return Array.from(this.loadedPlugins.values());
     }
+    /**
+     * Clears the plugin cache
+     */
     clearCache() {
         this.loadedPlugins.clear();
         this.logger.debug('Plugin cache cleared', {
             operation: 'cache_cleared',
         });
     }
+    /**
+     * Loads a module with timeout protection
+     * @param modulePath - Module path to load
+     * @returns Loaded plugin
+     * @private
+     */
     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);
+            // Use dynamic import to load the module
             import(modulePath)
                 .then((module) => {
                 globalThis.clearTimeout(timeout);
+                // Handle different export patterns
                 const plugin = module.default || module;
                 if (!plugin) {
                     reject(new Error('Plugin module does not export a plugin'));
@@ -199,11 +268,24 @@ export class PluginLoader {
             });
         });
     }
+    /**
+     * Validates plugin interface (instance method)
+     * @param plugin - Plugin to validate
+     * @param packageName - Package name for error reporting
+     * @private
+     */
     validatePluginInterface(plugin, packageName) {
         PluginLoader.validatePluginInterface(plugin, packageName);
     }
+    /**
+     * Checks plugin compatibility with current environment
+     * @param plugin - Plugin to check
+     * @returns Array of compatibility issues
+     * @private
+     */
     checkCompatibility(plugin) {
         const issues = [];
+        // Check Kubernetes version compatibility
         if (plugin.metadata?.kubernetesVersions) {
             const supportedVersions = new Set(this.options.supportedKubernetesVersions);
             const pluginVersions = plugin.metadata.kubernetesVersions;
@@ -212,9 +294,18 @@ export class PluginLoader {
                 issues.push(`Plugin requires Kubernetes versions [${pluginVersions.join(', ')}] but only [${this.options.supportedKubernetesVersions.join(', ')}] are supported`);
             }
         }
+        // Add more compatibility checks as needed
         return issues;
     }
+    /**
+     * Determines if plugin should be loaded in current environment
+     * @param _plugin - Plugin to check (unused for now)
+     * @returns True if plugin should be loaded
+     * @private
+     */
     shouldLoadInEnvironment(_plugin) {
+        // For now, always return true
+        // This could be extended to check plugin metadata for environment restrictions
         return true;
     }
 }

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

@@ -1,14 +1,68 @@
+/**
+ * Plugin Registry
+ *
+ * This module manages the lifecycle of policy plugins including registration,
+ * validation, and configuration management.
+ *
+ * @since 3.0.0
+ */
 import type { PolicyPlugin } from './types.js';
+/**
+ * Registry for managing policy plugins
+ */
 export declare class PluginRegistry {
     private plugins;
     private pluginConfigs;
+    /**
+     * Registers a policy plugin with optional configuration
+     * @param plugin - The policy plugin to register
+     * @param config - Optional plugin-specific configuration
+     * @throws {PluginRegistrationError} When plugin validation fails
+     */
     register(plugin: PolicyPlugin, config?: unknown): void;
+    /**
+     * Gets a plugin by name
+     * @param name - Plugin name
+     * @returns Plugin instance or undefined if not found
+     */
     getPlugin(name: string): PolicyPlugin | undefined;
+    /**
+     * Gets all registered plugins
+     * @returns Array of all registered plugins
+     */
     getAllPlugins(): PolicyPlugin[];
+    /**
+     * Gets plugin configuration
+     * @param pluginName - Name of the plugin
+     * @returns Plugin configuration or undefined if not set
+     */
     getPluginConfig(pluginName: string): unknown;
+    /**
+     * Checks if a plugin is registered
+     * @param name - Plugin name
+     * @returns True if plugin is registered
+     */
     hasPlugin(name: string): boolean;
+    /**
+     * Gets the number of registered plugins
+     * @returns Number of registered plugins
+     */
     getPluginCount(): number;
+    /**
+     * Unregisters a plugin
+     * @param name - Plugin name to unregister
+     * @returns True if plugin was removed, false if not found
+     */
     unregister(name: string): boolean;
+    /**
+     * Clears all registered plugins
+     */
     clear(): void;
+    /**
+     * Validates that a plugin implements the required interface
+     * @param plugin - Plugin to validate
+     * @throws {PluginRegistrationError} When plugin is invalid
+     * @private
+     */
     private validatePlugin;
 }

package/dist/lib/policy/pluginRegistry.js

@@ -1,11 +1,29 @@
+/**
+ * Plugin Registry
+ *
+ * This module manages the lifecycle of policy plugins including registration,
+ * validation, and configuration management.
+ *
+ * @since 3.0.0
+ */
 import { PluginRegistrationError } from './errors.js';
+/**
+ * Registry for managing policy plugins
+ */
 export class PluginRegistry {
     constructor() {
         this.plugins = new Map();
         this.pluginConfigs = new Map();
     }
+    /**
+     * Registers a policy plugin with optional configuration
+     * @param plugin - The policy plugin to register
+     * @param config - Optional plugin-specific configuration
+     * @throws {PluginRegistrationError} When plugin validation fails
+     */
     register(plugin, config) {
         this.validatePlugin(plugin);
+        // Check for duplicate plugin names
         if (this.plugins.has(plugin.name)) {
             throw new PluginRegistrationError(`Plugin with name '${plugin.name}' is already registered`, plugin.name);
         }
@@ -14,21 +32,49 @@ export class PluginRegistry {
             this.pluginConfigs.set(plugin.name, config);
         }
     }
+    /**
+     * Gets a plugin by name
+     * @param name - Plugin name
+     * @returns Plugin instance or undefined if not found
+     */
     getPlugin(name) {
         return this.plugins.get(name);
     }
+    /**
+     * Gets all registered plugins
+     * @returns Array of all registered plugins
+     */
     getAllPlugins() {
         return Array.from(this.plugins.values());
     }
+    /**
+     * Gets plugin configuration
+     * @param pluginName - Name of the plugin
+     * @returns Plugin configuration or undefined if not set
+     */
     getPluginConfig(pluginName) {
         return this.pluginConfigs.get(pluginName);
     }
+    /**
+     * Checks if a plugin is registered
+     * @param name - Plugin name
+     * @returns True if plugin is registered
+     */
     hasPlugin(name) {
         return this.plugins.has(name);
     }
+    /**
+     * Gets the number of registered plugins
+     * @returns Number of registered plugins
+     */
     getPluginCount() {
         return this.plugins.size;
     }
+    /**
+     * Unregisters a plugin
+     * @param name - Plugin name to unregister
+     * @returns True if plugin was removed, false if not found
+     */
     unregister(name) {
         const removed = this.plugins.delete(name);
         if (removed) {
@@ -36,10 +82,19 @@ export class PluginRegistry {
         }
         return removed;
     }
+    /**
+     * Clears all registered plugins
+     */
     clear() {
         this.plugins.clear();
         this.pluginConfigs.clear();
     }
+    /**
+     * Validates that a plugin implements the required interface
+     * @param plugin - Plugin to validate
+     * @throws {PluginRegistrationError} When plugin is invalid
+     * @private
+     */
     validatePlugin(plugin) {
         if (!plugin) {
             throw new PluginRegistrationError('Plugin cannot be null or undefined');
@@ -56,6 +111,7 @@ export class PluginRegistry {
         if (typeof plugin.validate !== 'function') {
             throw new PluginRegistrationError('Plugin must implement validate method', plugin.name);
         }
+        // Validate optional fields if present
         if (plugin.description !== undefined && typeof plugin.description !== 'string') {
             throw new PluginRegistrationError('Plugin description must be a string', plugin.name);
         }