@devilsdev/rag-pipeline-utils 2.3.1 → 2.4.1

package/src/cli/doctor-command.js

@@ -1,31 +1,41 @@
 /**
  * Doctor Command for RAG Pipeline Diagnostics
  * Scans for common issues and provides actionable solutions
+ *
+ * This module serves as the orchestrator, delegating individual checks
+ * to focused checker modules in the diagnostics/ directory.
  */
 
-const fs = require('fs/promises');
-const path = require('path');
+const fs = require("fs/promises");
+const path = require("path");
+
+const { checkConfiguration } = require("./diagnostics/config-checker.js");
+const { checkPlugins } = require("./diagnostics/plugin-checker.js");
+const { checkDependencies } = require("./diagnostics/dependency-checker.js");
+const { checkPerformance } = require("./diagnostics/performance-checker.js");
+const { checkSecurity } = require("./diagnostics/security-checker.js");
+const { checkEnvironment } = require("./diagnostics/environment-checker.js");
 
 /**
  * Diagnostic categories
  */
 const DIAGNOSTIC_CATEGORIES = {
-  CONFIGURATION: 'configuration',
-  PLUGINS: 'plugins',
-  DEPENDENCIES: 'dependencies',
-  PERFORMANCE: 'performance',
-  SECURITY: 'security',
-  ENVIRONMENT: 'environment',
+  CONFIGURATION: "configuration",
+  PLUGINS: "plugins",
+  DEPENDENCIES: "dependencies",
+  PERFORMANCE: "performance",
+  SECURITY: "security",
+  ENVIRONMENT: "environment",
 };
 
 /**
  * Issue severity levels
  */
 const SEVERITY_LEVELS = {
-  ERROR: 'error',
-  WARNING: 'warning',
-  INFO: 'info',
-  SUCCESS: 'success',
+  ERROR: "error",
+  WARNING: "warning",
+  INFO: "info",
+  SUCCESS: "success",
 };
 
 /**
@@ -34,10 +44,10 @@ const SEVERITY_LEVELS = {
 class PipelineDoctor {
   constructor(_options = {}) {
     this.options = {
-      configPath: _options.configPath || '.ragrc.json',
+      configPath: _options.configPath || ".ragrc.json",
       verbose: _options.verbose || false,
       autoFix: _options.autoFix || false,
-      categories: _options.categories || ['all'],
+      categories: _options.categories || ["all"],
       ..._options,
     };
   }
@@ -47,71 +57,7 @@ class PipelineDoctor {
    * @returns {Promise<Array>} Array of configuration issues
    */
   async checkConfiguration() {
-    const issues = [];
-
-    try {
-      await fs.access(this.options.configPath);
-    } catch (error) {
-      issues.push({
-        category: 'configuration',
-        severity: 'error',
-        code: 'CONFIG_MISSING',
-        message: `Configuration file not found: ${this.options.configPath}`,
-        fix: 'Run "rag-pipeline init" to create a configuration file',
-        autoFixable: false,
-      });
-      return issues;
-    }
-
-    try {
-      const configContent = await fs.readFile(this.options.configPath, 'utf8');
-      const config = JSON.parse(configContent);
-
-      // Check if config is empty
-      if (Object.keys(config).length === 0 || !config.plugins) {
-        issues.push({
-          category: 'configuration',
-          severity: 'warning',
-          code: 'CONFIG_EMPTY',
-          message: 'Configuration file is empty or missing required sections',
-          fix: 'Add plugin configurations and pipeline settings',
-          autoFixable: false,
-        });
-      }
-
-      // Validate schema if available
-      try {
-        const {
-          validateEnhancedRagrcSchema,
-        } = require('../config/enhanced-ragrc-schema.js');
-        const validation = validateEnhancedRagrcSchema(config);
-        if (!validation.valid && validation.errors) {
-          validation.errors.forEach((error) => {
-            issues.push({
-              category: 'configuration',
-              severity: 'error',
-              code: 'CONFIG_SCHEMA_ERROR',
-              message: `Schema validation failed: ${error.instancePath} ${error.message}`,
-              fix: 'Fix configuration schema errors',
-              autoFixable: false,
-            });
-          });
-        }
-      } catch (schemaError) {
-        // Schema validation not available, skip
-      }
-    } catch (parseError) {
-      issues.push({
-        category: 'configuration',
-        severity: 'error',
-        code: 'CONFIG_INVALID_JSON',
-        message: 'Configuration file contains invalid JSON syntax',
-        fix: `Fix JSON syntax errors in ${this.options.configPath}`,
-        autoFixable: false,
-      });
-    }
-
-    return issues;
+    return checkConfiguration(this.options);
   }
 
   /**
@@ -119,95 +65,7 @@ class PipelineDoctor {
    * @returns {Promise<Array>} Array of plugin issues
    */
   async checkPlugins() {
-    const issues = [];
-
-    try {
-      // First check if config file exists (this accounts for the first fs.access call in the test)
-      await fs.access(this.options.configPath);
-
-      const configContent = await fs.readFile(this.options.configPath, 'utf8');
-      const config = JSON.parse(configContent);
-
-      if (config.plugins) {
-        // Process plugins in the order expected by tests: loader first, then embedder
-        const categories = ['loader', 'embedder'];
-        for (const category of categories) {
-          if (config.plugins[category]) {
-            const plugins = config.plugins[category];
-            const sortedPlugins = Object.keys(plugins).sort();
-            for (const pluginName of sortedPlugins) {
-              try {
-                // Check if plugin file exists (simplified check)
-                await fs.access(path.join('node_modules', pluginName));
-              } catch (error) {
-                issues.push({
-                  category: 'plugins',
-                  severity: 'error',
-                  code: 'PLUGIN_MISSING',
-                  message: `Plugin not found: ${pluginName}`,
-                  fix: `Install plugin: npm install ${pluginName}`,
-                  autoFixable: true,
-                });
-              }
-            }
-          }
-        }
-
-        // Check for version conflicts
-        try {
-          const {
-            resolvePluginVersions,
-          } = require('../core/plugin-marketplace/version-resolver.js');
-          const resolution = await resolvePluginVersions(config.plugins);
-          if (resolution.conflicts) {
-            resolution.conflicts.forEach((conflict) => {
-              issues.push({
-                category: 'plugins',
-                severity: 'warning',
-                code: 'PLUGIN_VERSION_CONFLICT',
-                message: `Version conflict: ${conflict.plugin} - ${conflict.conflict}`,
-                fix: 'Update plugin versions to resolve conflicts',
-                autoFixable: false,
-              });
-            });
-          }
-        } catch (resolverError) {
-          // Version resolver not available, skip
-        }
-
-        // Check for outdated plugins
-        try {
-          const registryUrl = 'https://registry.rag-pipeline.dev';
-          const response = await fetch(`${registryUrl}/plugins`);
-          if (response.ok) {
-            const registry = await response.json();
-            for (const [category, plugins] of Object.entries(config.plugins)) {
-              for (const [pluginName, version] of Object.entries(plugins)) {
-                if (registry.plugins && registry.plugins[pluginName]) {
-                  const latest = registry.plugins[pluginName].versions.latest;
-                  if (version !== 'latest' && version !== latest) {
-                    issues.push({
-                      category: 'plugins',
-                      severity: 'info',
-                      code: 'PLUGIN_OUTDATED',
-                      message: `Plugin outdated: ${pluginName}@${version} (latest: ${latest})`,
-                      fix: `Update to latest version: rag-pipeline plugin install ${pluginName}@latest`,
-                      autoFixable: true,
-                    });
-                  }
-                }
-              }
-            }
-          }
-        } catch (fetchError) {
-          // Registry not available, skip
-        }
-      }
-    } catch (configError) {
-      // Config issues handled in checkConfiguration
-    }
-
-    return issues;
+    return checkPlugins(this.options);
   }
 
   /**
@@ -215,58 +73,7 @@ class PipelineDoctor {
    * @returns {Promise<Array>} Array of dependency issues
    */
   async checkDependencies() {
-    const issues = [];
-
-    // Check Node.js version
-    const nodeVersion = process.version;
-    const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0]);
-    if (majorVersion < 18) {
-      issues.push({
-        category: 'dependencies',
-        severity: 'error',
-        code: 'NODE_VERSION_INCOMPATIBLE',
-        message: `Node.js version ${nodeVersion} is not supported (required: >=18.0.0)`,
-        fix: 'Upgrade Node.js to version 18.0.0 or higher',
-        autoFixable: false,
-      });
-    }
-
-    // Check package.json
-    try {
-      await fs.access('package.json');
-      const packageContent = await fs.readFile('package.json', 'utf8');
-      const packageJson = JSON.parse(packageContent);
-
-      if (packageJson.dependencies) {
-        for (const [depName, version] of Object.entries(
-          packageJson.dependencies,
-        )) {
-          try {
-            await fs.access(path.join('node_modules', depName));
-          } catch (error) {
-            issues.push({
-              category: 'dependencies',
-              severity: 'error',
-              code: 'NPM_DEPENDENCY_MISSING',
-              message: `NPM dependency missing: ${depName}`,
-              fix: 'Install missing dependencies: npm install',
-              autoFixable: true,
-            });
-          }
-        }
-      }
-    } catch (error) {
-      issues.push({
-        category: 'dependencies',
-        severity: 'warning',
-        code: 'PACKAGE_JSON_MISSING',
-        message: 'package.json not found in current directory',
-        fix: 'Initialize npm project: npm init',
-        autoFixable: false,
-      });
-    }
-
-    return issues;
+    return checkDependencies(this.options);
   }
 
   /**
@@ -274,41 +81,7 @@ class PipelineDoctor {
    * @returns {Promise<Array>} Array of performance issues
    */
   async checkPerformance() {
-    const issues = [];
-
-    // Check memory usage
-    const memUsage = process.memoryUsage();
-    const heapUsedMB = Math.round(memUsage.heapUsed / 1024 / 1024);
-    if (heapUsedMB > 512) {
-      issues.push({
-        category: 'performance',
-        severity: 'warning',
-        code: 'MEMORY_USAGE_HIGH',
-        message: `High memory usage detected: ${heapUsedMB}MB used`,
-        fix: 'Consider reducing batch sizes or enabling streaming',
-        autoFixable: false,
-      });
-    }
-
-    // Check config file size
-    try {
-      const stats = await fs.stat(this.options.configPath);
-      const sizeMB = stats.size / 1024 / 1024;
-      if (sizeMB > 1) {
-        issues.push({
-          category: 'performance',
-          severity: 'warning',
-          code: 'CONFIG_FILE_LARGE',
-          message: `Configuration file is unusually large: ${sizeMB.toFixed(1)}MB`,
-          fix: 'Consider splitting configuration or removing unused sections',
-          autoFixable: false,
-        });
-      }
-    } catch (error) {
-      // File doesn't exist, handled elsewhere
-    }
-
-    return issues;
+    return checkPerformance(this.options);
   }
 
   /**
@@ -316,51 +89,7 @@ class PipelineDoctor {
    * @returns {Promise<Array>} Array of security issues
    */
   async checkSecurity() {
-    const issues = [];
-
-    // Check for hardcoded API keys in config content
-    try {
-      const configContent = await fs.readFile(this.options.configPath, 'utf8');
-      const config = JSON.parse(configContent);
-
-      const configStr = JSON.stringify(config);
-      if (
-        configStr.includes('sk-') ||
-        configStr.includes('apiKey') ||
-        configStr.includes('api_key')
-      ) {
-        issues.push({
-          category: 'security',
-          severity: 'error',
-          code: 'HARDCODED_API_KEY',
-          message: 'Hardcoded API key detected in configuration',
-          fix: 'Move API keys to environment variables',
-          autoFixable: false,
-        });
-      }
-    } catch (configError) {
-      // Config reading issues handled elsewhere
-    }
-
-    // Check file permissions (independent of config content)
-    try {
-      const stats = await fs.stat(this.options.configPath);
-      const mode = stats.mode & 0o777;
-      if (mode === 0o777) {
-        issues.push({
-          category: 'security',
-          severity: 'warning',
-          code: 'INSECURE_PERMISSIONS',
-          message: 'Configuration file has insecure permissions (777)',
-          fix: `Set secure permissions: chmod 600 ${this.options.configPath}`,
-          autoFixable: true,
-        });
-      }
-    } catch (statError) {
-      // File stat issues handled elsewhere
-    }
-
-    return issues;
+    return checkSecurity(this.options);
   }
 
   /**
@@ -368,35 +97,7 @@ class PipelineDoctor {
    * @returns {Promise<Array>} Array of environment issues
    */
   async checkEnvironment() {
-    const issues = [];
-
-    try {
-      const configContent = await fs.readFile(this.options.configPath, 'utf8');
-      const config = JSON.parse(configContent);
-
-      // Check for missing environment variables
-      const configStr = JSON.stringify(config);
-      const envVarMatches = configStr.match(/\$\{([^}]+)\}/g);
-      if (envVarMatches) {
-        envVarMatches.forEach((match) => {
-          const envVar = match.slice(2, -1);
-          if (!process.env[envVar]) {
-            issues.push({
-              category: 'environment',
-              severity: 'error',
-              code: 'ENV_VAR_MISSING',
-              message: `Required environment variable missing: ${envVar}`,
-              fix: `Set environment variable: export ${envVar}=your_key`,
-              autoFixable: false,
-            });
-          }
-        });
-      }
-    } catch (error) {
-      // Config issues handled elsewhere
-    }
-
-    return issues;
+    return checkEnvironment(this.options);
   }
 
   /**
@@ -407,23 +108,23 @@ class PipelineDoctor {
    * @returns {Promise<object>} Execution result
    */
   async execSafe(command, args = [], options = {}) {
-    const { execFile } = require('child_process');
-    const { promisify } = require('util');
+    const { execFile } = require("child_process");
+    const { promisify } = require("util");
     const execFileAsync = promisify(execFile);
 
     // Validate command is in allowlist
-    const ALLOWED_COMMANDS = ['npm', 'chmod', 'node', 'icacls'];
+    const ALLOWED_COMMANDS = ["npm", "chmod", "node", "icacls"];
     if (!ALLOWED_COMMANDS.includes(command)) {
       throw new Error(`Command not allowed: ${command}`);
     }
 
     // Sanitize arguments
     const sanitizedArgs = args.map((arg) => {
-      if (typeof arg !== 'string') {
-        throw new Error('All arguments must be strings');
+      if (typeof arg !== "string") {
+        throw new Error("All arguments must be strings");
       }
       // Remove shell metacharacters
-      return arg.replace(/[;&|`$(){}[\]<>"'\\]/g, '');
+      return arg.replace(/[;&|`$(){}[\]<>"'\\]/g, "");
     });
 
     const execOptions = {
@@ -445,41 +146,41 @@ class PipelineDoctor {
     if (!issue.autoFixable) {
       return {
         success: false,
-        message: 'Issue is not auto-fixable',
+        message: "Issue is not auto-fixable",
       };
     }
 
     try {
-      if (issue.code === 'NPM_DEPENDENCY_MISSING') {
+      if (issue.code === "NPM_DEPENDENCY_MISSING") {
         // Use execSafe with validated command and args
-        const result = await this.execSafe('npm', [
-          'install',
-          '--no-fund',
-          '--no-audit',
+        const result = await this.execSafe("npm", [
+          "install",
+          "--no-fund",
+          "--no-audit",
         ]);
         return {
           success: true,
-          message: result.stdout || 'Dependencies installed',
+          message: result.stdout || "Dependencies installed",
         };
       }
 
-      if (issue.code === 'INSECURE_PERMISSIONS') {
+      if (issue.code === "INSECURE_PERMISSIONS") {
         // Validate config path is within project directory
         const configPath = path.resolve(this.options.configPath);
-        const projectDir = path.resolve('.');
+        const projectDir = path.resolve(".");
         if (!configPath.startsWith(projectDir)) {
-          throw new Error('Config path outside project directory');
+          throw new Error("Config path outside project directory");
         }
 
         // Check if running on Windows
-        if (process.platform === 'win32') {
+        if (process.platform === "win32") {
           // On Windows, attempt to use icacls or fall back to fs.chmod
           try {
-            await this.execSafe('icacls', [
+            await this.execSafe("icacls", [
               configPath,
-              '/inheritance:r',
-              '/grant',
-              `${require('os').userInfo().username}:F`,
+              "/inheritance:r",
+              "/grant",
+              `${require("os").userInfo().username}:F`,
             ]);
           } catch (icaclsError) {
             // Fall back to fs.chmod if icacls fails
@@ -493,18 +194,18 @@ class PipelineDoctor {
           }
         } else {
           // Use chmod on Unix-like systems
-          await this.execSafe('chmod', ['600', configPath]);
+          await this.execSafe("chmod", ["600", configPath]);
         }
 
         return {
           success: true,
-          message: 'Permissions updated',
+          message: "Permissions updated",
         };
       }
 
       return {
         success: false,
-        message: 'Auto-fix not implemented for this issue type',
+        message: "Auto-fix not implemented for this issue type",
       };
     } catch (error) {
       return {
@@ -522,15 +223,15 @@ class PipelineDoctor {
   generateReport(issues) {
     const summary = {
       totalIssues: issues.length,
-      errors: issues.filter((i) => i.severity === 'error').length,
-      warnings: issues.filter((i) => i.severity === 'warning').length,
-      info: issues.filter((i) => i.severity === 'info').length,
+      errors: issues.filter((i) => i.severity === "error").length,
+      warnings: issues.filter((i) => i.severity === "warning").length,
+      info: issues.filter((i) => i.severity === "info").length,
       healthScore: Math.max(
         0,
         100 -
-          (issues.filter((i) => i.severity === 'error').length * 25 +
-            issues.filter((i) => i.severity === 'warning').length * 10 +
-            issues.filter((i) => i.severity === 'info').length * 2),
+          (issues.filter((i) => i.severity === "error").length * 25 +
+            issues.filter((i) => i.severity === "warning").length * 10 +
+            issues.filter((i) => i.severity === "info").length * 2),
       ),
     };
 
@@ -546,11 +247,11 @@ class PipelineDoctor {
     issues.forEach((issue) => {
       if (categories[issue.category]) {
         categories[issue.category].issues++;
-        if (issue.severity === 'error') {
+        if (issue.severity === "error") {
           categories[issue.category].errors++;
-        } else if (issue.severity === 'warning') {
+        } else if (issue.severity === "warning") {
           categories[issue.category].warnings++;
-        } else if (issue.severity === 'info') {
+        } else if (issue.severity === "info") {
           categories[issue.category].info++;
         }
       }
@@ -571,36 +272,36 @@ class PipelineDoctor {
   async run() {
     const allIssues = [];
 
-    const categoriesToRun = this.options.categories.includes('all')
+    const categoriesToRun = this.options.categories.includes("all")
       ? Object.values(DIAGNOSTIC_CATEGORIES)
       : this.options.categories;
 
-    if (categoriesToRun.includes('configuration')) {
+    if (categoriesToRun.includes("configuration")) {
       const configIssues = await this.checkConfiguration();
       allIssues.push(...configIssues);
     }
 
-    if (categoriesToRun.includes('plugins')) {
+    if (categoriesToRun.includes("plugins")) {
       const pluginIssues = await this.checkPlugins();
       allIssues.push(...pluginIssues);
     }
 
-    if (categoriesToRun.includes('dependencies')) {
+    if (categoriesToRun.includes("dependencies")) {
       const depIssues = await this.checkDependencies();
       allIssues.push(...depIssues);
     }
 
-    if (categoriesToRun.includes('performance')) {
+    if (categoriesToRun.includes("performance")) {
       const perfIssues = await this.checkPerformance();
       allIssues.push(...perfIssues);
     }
 
-    if (categoriesToRun.includes('security')) {
+    if (categoriesToRun.includes("security")) {
       const secIssues = await this.checkSecurity();
       allIssues.push(...secIssues);
     }
 
-    if (categoriesToRun.includes('environment')) {
+    if (categoriesToRun.includes("environment")) {
       const envIssues = await this.checkEnvironment();
       allIssues.push(...envIssues);
     }