@devilsdev/rag-pipeline-utils 2.2.1 → 2.3.0

package/src/core/plugin-registry.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const Ajv = require('ajv');
 const {
   createPluginVerifier,
 } = require('../security/plugin-signature-verifier.js');
@@ -18,6 +19,40 @@ class PluginRegistry {
       'evaluator',
     ]);
     this._contracts = new Map();
+    this._contractWarningsShown = new Set(); // Track warnings to show only once per type
+    this._disableContractWarnings = options.disableContractWarnings || false;
+    this._validateContractSchema =
+      options.validateContractSchema !== undefined
+        ? options.validateContractSchema
+        : true; // Enable schema validation by default
+
+    // Initialize Ajv for contract schema validation
+    this._ajv = new Ajv({
+      allErrors: true,
+      verbose: true,
+      strict: false,
+    });
+
+    // Load contract schema
+    this._contractSchema = this._loadContractSchema();
+
+    // Compile schema validator once
+    this._contractSchemaValidator = null;
+    if (this._contractSchema) {
+      try {
+        this._contractSchemaValidator = this._ajv.compile(this._contractSchema);
+      } catch (error) {
+        if (
+          process.env.NODE_ENV !== 'production' &&
+          !this._disableContractWarnings
+        ) {
+          console.warn(
+            `[PLUGIN_REGISTRY] Warning: Failed to compile contract schema: ${error.message}`,
+          ); // eslint-disable-line no-console
+        }
+        this._contractSchema = null;
+      }
+    }
 
     // Environment-aware signature verification defaults
     const isDevelopment = process.env.NODE_ENV === 'development';
@@ -35,9 +70,192 @@ class PluginRegistry {
     this._loadContracts();
   }
 
+  /**
+   * Load contract schema for validation
+   *
+   * @private
+   * @returns {Object|null} Contract schema or null if not found
+   *
+   * @since 2.2.4
+   */
+  _loadContractSchema() {
+    try {
+      const schemaPath = path.join(
+        __dirname,
+        '../../contracts/contract-schema.json',
+      );
+      if (fs.existsSync(schemaPath)) {
+        const schemaContent = fs.readFileSync(schemaPath, 'utf8');
+        return JSON.parse(schemaContent);
+      }
+    } catch (error) {
+      if (
+        process.env.NODE_ENV !== 'production' &&
+        !this._disableContractWarnings
+      ) {
+        console.warn(
+          `[PLUGIN_REGISTRY] Warning: Failed to load contract schema: ${error.message}`,
+        ); // eslint-disable-line no-console
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Validate contract against schema
+   *
+   * @private
+   * @param {Object} contract - Contract to validate
+   * @param {string} type - Contract type
+   * @returns {Object} Validation result { valid: boolean, errors: Array }
+   *
+   * @since 2.2.4
+   */
+  _validateContractAgainstSchema(contract, type) {
+    if (!this._validateContractSchema || !this._contractSchemaValidator) {
+      return { valid: true, errors: [] };
+    }
+
+    try {
+      const valid = this._contractSchemaValidator(contract);
+
+      if (!valid) {
+        return {
+          valid: false,
+          errors: this._contractSchemaValidator.errors || [],
+        };
+      }
+
+      return { valid: true, errors: [] };
+    } catch (error) {
+      return {
+        valid: false,
+        errors: [
+          {
+            message: `Schema validation error: ${error.message}`,
+          },
+        ],
+      };
+    }
+  }
+
+  /**
+   * Format schema validation errors for display
+   *
+   * @private
+   * @param {Array} errors - Ajv validation errors
+   * @returns {string} Formatted error message
+   *
+   * @since 2.2.4
+   */
+  _formatSchemaErrors(errors) {
+    if (!errors || errors.length === 0) {
+      return 'Unknown schema validation error';
+    }
+
+    const messages = errors.map((err) => {
+      const path = err.instancePath || err.dataPath || '/';
+      const message = err.message || 'validation failed';
+
+      if (err.params) {
+        const params = Object.entries(err.params)
+          .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+          .join(', ');
+        return `  - ${path}: ${message} (${params})`;
+      }
+
+      return `  - ${path}: ${message}`;
+    });
+
+    return messages.join('\n');
+  }
+
+  /**
+   * Check if a contract exists for the given plugin type
+   *
+   * @param {string} type - Plugin type (loader, embedder, etc.)
+   * @returns {boolean} True if contract exists, false otherwise
+   *
+   * @example
+   * const hasContract = registry.checkContractExists('loader');
+   * if (!hasContract) {
+   *   console.warn('No contract for loader plugins');
+   * }
+   *
+   * @since 2.2.4
+   */
+  checkContractExists(type) {
+    return this._contracts.has(type);
+  }
+
+  /**
+   * Log one-time warning for missing contract
+   *
+   * Logs a helpful warning message about the benefits of contracts
+   * and how to add them. Only logs once per contract type and only
+   * in non-production environments.
+   *
+   * @private
+   * @param {string} type - Plugin type
+   * @param {string} context - Context where warning is generated (e.g., 'load', 'register')
+   *
+   * @since 2.2.4
+   */
+  _warnMissingContract(type, context = 'load') {
+    // Skip if warnings disabled or in production
+    if (
+      this._disableContractWarnings ||
+      process.env.NODE_ENV === 'production'
+    ) {
+      return;
+    }
+
+    // Only warn once per type
+    const warningKey = `${type}:${context}`;
+    if (this._contractWarningsShown.has(warningKey)) {
+      return;
+    }
+
+    this._contractWarningsShown.add(warningKey);
+
+    console.warn(
+      `
+╔════════════════════════════════════════════════════════════════════════════╗
+║ [PLUGIN_REGISTRY] Missing Contract for '${type}' plugins                       ║
+╠════════════════════════════════════════════════════════════════════════════╣
+║ A contract specification was not found for the '${type}' plugin type.         ║
+║                                                                            ║
+║ Benefits of using contracts:                                              ║
+║  • Ensures plugin compatibility across versions                           ║
+║  • Validates required methods and properties                              ║
+║  • Provides clear interface documentation                                 ║
+║  • Catches errors early in development                                    ║
+║  • Enables automated testing and validation                               ║
+║                                                                            ║
+║ To add a contract:                                                        ║
+║  1. Create contracts/${type}-contract.json                                   ║
+║  2. Define required methods and their signatures                          ║
+║  3. Run contract validation tests                                         ║
+║                                                                            ║
+║ Example contract structure:                                               ║
+║  {                                                                         ║
+║    "type": "${type}",                                                         ║
+║    "version": "1.0.0",                                                     ║
+║    "required": ["methodName"],                                            ║
+║    "properties": { /* method definitions */ }                             ║
+║  }                                                                         ║
+║                                                                            ║
+║ See: docs/error-context-guide.md and __tests__/contracts/README.md        ║
+║                                                                            ║
+║ To disable these warnings:                                                ║
+║  new PluginRegistry({ disableContractWarnings: true })                    ║
+╚════════════════════════════════════════════════════════════════════════════╝
+    `.trim(),
+    ); // eslint-disable-line no-console
+  }
+
   _loadContracts() {
     const contractsDir = path.join(__dirname, '../../contracts');
-    const isDevelopment = process.env.NODE_ENV === 'development';
 
     try {
       const contractFiles = {
@@ -54,19 +272,46 @@ class PluginRegistry {
           if (fs.existsSync(contractPath)) {
             const contractContent = fs.readFileSync(contractPath, 'utf8');
             const contract = JSON.parse(contractContent);
+
+            // Validate contract against schema
+            const validation = this._validateContractAgainstSchema(
+              contract,
+              type,
+            );
+
+            if (!validation.valid) {
+              const errorMessage = this._formatSchemaErrors(validation.errors);
+              const error = new Error(
+                `Contract schema validation failed for '${type}':\n${errorMessage}`,
+              );
+              error.validationErrors = validation.errors;
+              error.contractType = type;
+
+              if (process.env.NODE_ENV === 'production') {
+                // In production, log error but continue (fail open)
+                console.error(`[PLUGIN_REGISTRY] ERROR: ${error.message}`); // eslint-disable-line no-console
+              } else {
+                // In development, throw to fail fast
+                throw error;
+              }
+            }
+
             this._contracts.set(type, contract);
-          } else if (isDevelopment) {
-            // Dev mode warning: flag missing contract files
-            console.warn(
-              `[PLUGIN_REGISTRY] Warning: Contract file missing for '${type}' plugin type: ${contractPath}`,
-            ); // eslint-disable-line no-console
-            console.warn(
-              `[PLUGIN_REGISTRY] This may indicate test-only drift. Contract validation will be skipped for '${type}' plugins.`,
-            ); // eslint-disable-line no-console
+          } else {
+            // Use new warning method for missing contracts
+            this._warnMissingContract(type, 'load');
           }
         } catch (error) {
+          // Re-throw validation errors in development mode
+          if (error.validationErrors && process.env.NODE_ENV !== 'production') {
+            throw error;
+          }
+
           // Contract loading is optional - don't fail if missing
-          if (isDevelopment) {
+          if (
+            process.env.NODE_ENV !== 'production' &&
+            !this._disableContractWarnings
+          ) {
             console.warn(
               `[PLUGIN_REGISTRY] Warning: Failed to load contract for '${type}': ${error.message}`,
             ); // eslint-disable-line no-console
@@ -74,8 +319,16 @@ class PluginRegistry {
         }
       }
     } catch (error) {
+      // Re-throw validation errors in development mode
+      if (error.validationErrors && process.env.NODE_ENV !== 'production') {
+        throw error;
+      }
+
       // Contracts directory may not exist in all environments
-      if (isDevelopment) {
+      if (
+        process.env.NODE_ENV !== 'production' &&
+        !this._disableContractWarnings
+      ) {
         console.warn(
           `[PLUGIN_REGISTRY] Warning: Contracts directory not accessible: ${error.message}`,
         ); // eslint-disable-line no-console
@@ -86,15 +339,8 @@ class PluginRegistry {
   _validatePluginContract(category, impl) {
     const contract = this._contracts.get(category);
     if (!contract) {
-      // Warn in dev mode when registering a plugin without a contract
-      if (process.env.NODE_ENV === 'development') {
-        console.warn(
-          `[PLUGIN_REGISTRY] Warning: No contract available for plugin category '${category}'. Skipping contract validation.`,
-        ); // eslint-disable-line no-console
-        console.warn(
-          `[PLUGIN_REGISTRY] This may indicate test-only drift. Ensure contracts/${category}-contract.json exists.`,
-        ); // eslint-disable-line no-console
-      }
+      // Use new warning method when registering a plugin without a contract
+      this._warnMissingContract(category, 'register');
       return; // No contract to validate against
     }