@devilsdev/rag-pipeline-utils 2.2.0 → 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,6 +70,190 @@ 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');
 
@@ -44,6 +263,7 @@ class PluginRegistry {
         embedder: 'embedder-contract.json',
         retriever: 'retriever-contract.json',
         llm: 'llm-contract.json',
+        reranker: 'reranker-contract.json',
       };
 
       for (const [type, filename] of Object.entries(contractFiles)) {
@@ -52,20 +272,75 @@ 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 {
+            // 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 (
+            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
+          }
         }
       }
     } 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 (
+        process.env.NODE_ENV !== 'production' &&
+        !this._disableContractWarnings
+      ) {
+        console.warn(
+          `[PLUGIN_REGISTRY] Warning: Contracts directory not accessible: ${error.message}`,
+        ); // eslint-disable-line no-console
+      }
     }
   }
 
   _validatePluginContract(category, impl) {
     const contract = this._contracts.get(category);
     if (!contract) {
+      // Use new warning method when registering a plugin without a contract
+      this._warnMissingContract(category, 'register');
       return; // No contract to validate against
     }
 

package/src/dag/core/error-context.js

@@ -0,0 +1,391 @@
+/**
+ * @fileoverview Error Context Management Module
+ *
+ * Provides centralized error handling, context management, and error reporting
+ * for DAG execution. Handles error creation, aggregation, preservation of error
+ * properties, and serialization for debugging and monitoring.
+ *
+ * @module dag/core/error-context
+ * @author Ali Kahwaji
+ * @since 2.2.4
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * ErrorContext class for managing DAG execution errors
+ *
+ * Provides comprehensive error management with:
+ * - Rich error context creation with node metadata
+ * - Error aggregation for multiple failures
+ * - Property preservation across error transformations
+ * - Error serialization for logging and monitoring
+ * - Cycle path tracking and reporting
+ * - Downstream impact analysis
+ *
+ * @class
+ * @since 2.2.4
+ *
+ * @example
+ * const errorContext = new ErrorContext();
+ *
+ * // Create error with context
+ * const nodeError = errorContext.createErrorContext('nodeA', new Error('Failed'), {
+ *   downstream: ['nodeB', 'nodeC'],
+ *   timestamp: Date.now()
+ * });
+ *
+ * // Aggregate multiple errors
+ * const errorsMap = new Map([['nodeA', error1], ['nodeB', error2]]);
+ * const aggregated = errorContext.aggregateErrors(errorsMap);
+ *
+ * // Serialize for logging
+ * console.log(errorContext.serializeError(nodeError));
+ */
+class ErrorContext {
+  /**
+   * Create an ErrorContext instance
+   *
+   * @constructor
+   */
+  constructor() {
+    // Reserved for future state management if needed
+  }
+
+  /**
+   * Create error context with node information and downstream impact
+   *
+   * Creates a new Error object enriched with:
+   * - Node ID for tracing execution path
+   * - Timestamp for temporal analysis
+   * - Original error as cause (for stack trace preservation)
+   * - Downstream node impact message
+   *
+   * @param {string} nodeId - ID of the node that failed
+   * @param {Error} error - Original error that occurred
+   * @param {Object} [options={}] - Additional context options
+   * @param {string[]} [options.downstream=[]] - Array of downstream node IDs affected
+   * @param {number} [options.timestamp=Date.now()] - Error timestamp
+   * @returns {Error} Enhanced error object with context
+   *
+   * @example
+   * const error = errorContext.createErrorContext(
+   *   'processData',
+   *   new Error('Invalid input'),
+   *   {
+   *     downstream: ['saveResults', 'sendNotification'],
+   *     timestamp: Date.now()
+   *   }
+   * );
+   * // Error message: "Node processData execution failed: Invalid input.
+   * //                 This affects downstream nodes: saveResults, sendNotification"
+   * // error.nodeId === 'processData'
+   * // error.cause === original Error object
+   *
+   * @since 2.2.4
+   */
+  createErrorContext(nodeId, error, options = {}) {
+    const { downstream = [], timestamp = Date.now() } = options;
+
+    const suffix = downstream.length
+      ? `. This affects downstream nodes: ${downstream.join(', ')}`
+      : '';
+
+    const nodeErr = new Error(
+      `Node ${nodeId} execution failed: ${error.message}${suffix}`,
+    );
+    nodeErr.nodeId = nodeId;
+    nodeErr.timestamp = timestamp;
+    nodeErr.cause = error;
+
+    return nodeErr;
+  }
+
+  /**
+   * Aggregate multiple errors into a single error object
+   *
+   * Creates a consolidated error when multiple nodes fail during execution.
+   * The aggregated error maintains references to all original errors for
+   * comprehensive debugging.
+   *
+   * @param {Map<string, Error>} errorsMap - Map of node ID to error object
+   * @returns {Error|null} Aggregated error, single error, or null if no errors
+   *
+   * @example
+   * const errors = new Map([
+   *   ['nodeA', new Error('A failed')],
+   *   ['nodeB', new Error('B failed')]
+   * ]);
+   * const aggregated = errorContext.aggregateErrors(errors);
+   * // aggregated.message === 'Multiple execution errors'
+   * // aggregated.errors === [Error('A failed'), Error('B failed')]
+   *
+   * @since 2.2.4
+   */
+  aggregateErrors(errorsMap) {
+    if (errorsMap.size >= 2) {
+      const agg = new Error('Multiple execution errors');
+      agg.errors = [...errorsMap.values()].map((x) => x.cause || x);
+      return agg;
+    }
+    if (errorsMap.size === 1) {
+      return [...errorsMap.values()][0];
+    }
+    return null;
+  }
+
+  /**
+   * Preserve node context when wrapping or transforming errors
+   *
+   * Ensures all error metadata (nodeId, timestamp, cause, cycle, errors)
+   * is preserved when creating wrapped errors. This is critical for
+   * maintaining debugging information through error propagation.
+   *
+   * @param {Error} error - Original error to preserve
+   * @param {Object} [context={}] - Additional context to add
+   * @returns {Error} New error with preserved properties
+   *
+   * @example
+   * const originalError = new Error('Original');
+   * originalError.nodeId = 'nodeA';
+   * originalError.timestamp = Date.now();
+   *
+   * const wrapped = errorContext.preserveNodeContext(originalError, {
+   *   retryCount: 3
+   * });
+   * // wrapped.nodeId === 'nodeA'
+   * // wrapped.timestamp === original timestamp
+   * // wrapped.retryCount === 3
+   *
+   * @since 2.2.4
+   */
+  preserveNodeContext(error, context = {}) {
+    const wrapped = new Error(error.message);
+
+    // Preserve standard error properties
+    if (error.nodeId !== undefined) wrapped.nodeId = error.nodeId;
+    if (error.timestamp !== undefined) wrapped.timestamp = error.timestamp;
+    if (error.cause !== undefined) wrapped.cause = error.cause;
+    if (error.cycle !== undefined) wrapped.cycle = error.cycle;
+    if (error.errors !== undefined) wrapped.errors = error.errors;
+
+    // Add any additional context
+    for (const [key, value] of Object.entries(context)) {
+      if (!(key in wrapped)) {
+        wrapped[key] = value;
+      }
+    }
+
+    return wrapped;
+  }
+
+  /**
+   * Format error report for debugging and monitoring
+   *
+   * Creates a structured representation of an error suitable for logging,
+   * monitoring systems, or debugging tools. Includes all metadata and
+   * nested error information.
+   *
+   * @param {Error} error - Error to format
+   * @returns {Object} Structured error report
+   *
+   * @example
+   * const report = errorContext.formatErrorReport(nodeError);
+   * // {
+   * //   message: "Node A execution failed: ...",
+   * //   nodeId: "A",
+   * //   timestamp: 1234567890,
+   * //   cause: { message: "...", stack: "..." },
+   * //   cycle: null,
+   * //   errors: null
+   * // }
+   *
+   * @since 2.2.4
+   */
+  formatErrorReport(error) {
+    const report = {
+      message: error.message,
+      nodeId: error.nodeId || null,
+      timestamp: error.timestamp || null,
+      cause: error.cause
+        ? {
+            message: error.cause.message,
+            stack: error.cause.stack,
+          }
+        : null,
+      cycle: error.cycle || null,
+      errors: error.errors
+        ? error.errors.map((e) => ({
+            message: e.message,
+            stack: e.stack,
+          }))
+        : null,
+    };
+
+    return report;
+  }
+
+  /**
+   * Serialize error for logging and monitoring systems
+   *
+   * Converts error to JSON string with formatting for readability.
+   * Safe for logging systems that require string representation.
+   *
+   * @param {Error} error - Error to serialize
+   * @param {number} [indent=2] - JSON indentation spaces
+   * @returns {string} JSON string representation of error
+   *
+   * @example
+   * const json = errorContext.serializeError(nodeError);
+   * console.log(json);
+   * // {
+   * //   "message": "Node A execution failed: ...",
+   * //   "nodeId": "A",
+   * //   "timestamp": 1234567890,
+   * //   ...
+   * // }
+   *
+   * @since 2.2.4
+   */
+  serializeError(error, indent = 2) {
+    return JSON.stringify(this.formatErrorReport(error), null, indent);
+  }
+
+  /**
+   * Wrap execution errors with appropriate context
+   *
+   * Implements error wrapping policy:
+   * - Node errors (with nodeId or starting with "Node ") are rethrown unchanged
+   * - Validation/cycle errors are wrapped once with "DAG execution failed"
+   * - Timeout and "no sink nodes" errors are not wrapped
+   * - All other errors are wrapped with "DAG execution failed"
+   *
+   * All error properties are preserved during wrapping.
+   *
+   * @param {Error} error - Error to wrap
+   * @returns {Error} Appropriately wrapped error
+   *
+   * @example
+   * const nodeError = new Error('Node A failed');
+   * nodeError.nodeId = 'A';
+   * const wrapped = errorContext.wrapExecutionError(nodeError);
+   * // Returns same error unchanged (node error policy)
+   *
+   * @example
+   * const validationError = new Error('DAG validation failed: cycle detected');
+   * validationError.cycle = ['A', 'B', 'A'];
+   * const wrapped = errorContext.wrapExecutionError(validationError);
+   * // Returns: Error('DAG execution failed: DAG validation failed: cycle detected')
+   * // with cycle property preserved
+   *
+   * @since 2.2.4
+   */
+  wrapExecutionError(error) {
+    // Node errors - rethrow unchanged
+    if (error.message.startsWith('Node ') || error.nodeId) {
+      return error;
+    }
+
+    // Validation or aggregate errors - wrap once
+    if (
+      error.cycle ||
+      /^DAG validation failed/.test(error.message) ||
+      error.errors
+    ) {
+      const wrappedError = new Error(`DAG execution failed: ${error.message}`);
+      if (error.cycle) wrappedError.cycle = error.cycle;
+      if (error.errors) wrappedError.errors = error.errors;
+      if (error.nodeId) wrappedError.nodeId = error.nodeId;
+      if (error.timestamp) wrappedError.timestamp = error.timestamp;
+      return wrappedError;
+    }
+
+    // Timeout and "no sink nodes" errors - don't wrap
+    if (
+      error.message === 'Execution timeout' ||
+      error.message === 'DAG has no sink nodes - no final output available'
+    ) {
+      return error;
+    }
+
+    // All other errors - wrap with context preservation
+    const wrappedError = new Error(`DAG execution failed: ${error.message}`);
+    if (error.errors) wrappedError.errors = error.errors;
+    if (error.nodeId) wrappedError.nodeId = error.nodeId;
+    if (error.timestamp) wrappedError.timestamp = error.timestamp;
+    if (error.cycle) wrappedError.cycle = error.cycle;
+    return wrappedError;
+  }
+
+  /**
+   * Create cycle error with path information
+   *
+   * Creates a specialized error for cycle detection with the cycle path
+   * embedded for debugging and error reporting.
+   *
+   * @param {string[]} cyclePath - Array of node IDs forming the cycle
+   * @returns {Error} Cycle error with path information
+   *
+   * @example
+   * const cycleError = errorContext.createCycleError(['A', 'B', 'C', 'A']);
+   * // cycleError.message === 'Cycle detected involving node: A -> B -> C -> A'
+   * // cycleError.cycle === ['A', 'B', 'C', 'A']
+   *
+   * @since 2.2.4
+   */
+  createCycleError(cyclePath) {
+    const error = new Error(
+      `Cycle detected involving node: ${cyclePath.join(' -> ')}`,
+    );
+    error.cycle = cyclePath;
+    return error;
+  }
+
+  /**
+   * Check if error should halt execution
+   *
+   * Determines if an error is critical enough to stop DAG execution
+   * based on error type and execution options.
+   *
+   * @param {Error} error - Error to evaluate
+   * @param {Object} options - Execution options
+   * @param {boolean} [options.continueOnError=false] - Continue on non-critical errors
+   * @param {boolean} [options.isNonCritical=false] - Whether node is non-critical
+   * @returns {boolean} True if execution should halt
+   *
+   * @example
+   * const shouldHalt = errorContext.shouldHaltExecution(error, {
+   *   continueOnError: true,
+   *   isNonCritical: true
+   * });
+   * // Returns false - execution continues
+   *
+   * @since 2.2.4
+   */
+  shouldHaltExecution(error, options = {}) {
+    const { continueOnError = false, isNonCritical = false } = options;
+
+    // Always halt on validation/cycle errors
+    if (error.cycle || /^DAG validation failed/.test(error.message)) {
+      return true;
+    }
+
+    // Halt on critical node errors
+    if (error.nodeId && !isNonCritical && !continueOnError) {
+      return true;
+    }
+
+    // Halt on timeout
+    if (error.message === 'Execution timeout') {
+      return true;
+    }
+
+    return false;
+  }
+}
+
+module.exports = ErrorContext;
+
+// Default export for convenience
+module.exports.default = ErrorContext;