@sun-asterisk/sunlint 1.0.7 → 1.1.3

package/engines/heuristic-engine.js

@@ -0,0 +1,860 @@
+/**
+ * Heuristic Analysis Engine Plugin
+ * Following Rule C005: Single responsibility - Pattern-based analysis with AST enhancement
+ * Following Rule C014: Dependency injection - implements interface
+ * Following Rule C015: Use domain language - clear heuristic analysis terms
+ */
+
+const AnalysisEngineInterface = require('../core/interfaces/analysis-engine.interface');
+const ASTModuleRegistry = require('../core/ast-modules/index');
+const fs = require('fs');
+const path = require('path');
+
+class HeuristicEngine extends AnalysisEngineInterface {
+  constructor() {
+    super('heuristic', '2.0', ['typescript', 'javascript', 'dart', 'swift', 'kotlin', 'java', 'python', 'go', 'rust', 'all']);
+    
+    this.ruleAnalyzers = new Map();
+    this.supportedRulesList = [];
+    this.rulesRegistry = {};
+    this.astRegistry = ASTModuleRegistry;
+  }
+
+  /**
+   * Initialize Heuristic engine with configuration
+   * Following Rule C006: Verb-noun naming
+   * @param {Object} config - Engine configuration
+   */
+  async initialize(config) {
+    try {
+      // Store verbosity setting
+      this.verbose = config?.verbose || false;
+      
+      // Load rules registry
+      await this.loadRulesRegistry(config);
+      
+      // Scan for available rule analyzers
+      await this.scanRuleAnalyzers(config);
+      
+      this.initialized = true;
+      if (this.verbose) {
+        console.log(`🔍 Heuristic engine v2.0 initialized with ${this.supportedRulesList.length} rules (AST-enhanced)`);
+      }
+      
+    } catch (error) {
+      console.error('Failed to initialize Heuristic engine:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Load rules registry configuration
+   * Following Rule C006: Verb-noun naming
+   */
+  async loadRulesRegistry(config = {}) {
+    try {
+      const registryPath = path.resolve(__dirname, '../config/rules/rules-registry.json');
+      if (fs.existsSync(registryPath)) {
+        this.rulesRegistry = require(registryPath);
+        if (config.verbose) {
+        if (this.verbose) {
+          console.log('📋 Loaded rules registry');
+        }
+        }
+      } else {
+        console.warn('⚠️ Rules registry not found, using minimal support');
+        this.rulesRegistry = { rules: {} };
+      }
+    } catch (error) {
+      console.warn('⚠️ Failed to load rules registry:', error.message);
+      this.rulesRegistry = { rules: {} };
+    }
+  }
+
+  /**
+   * Scan for available rule analyzers
+   * Following Rule C006: Verb-noun naming
+   */
+  async scanRuleAnalyzers(config = {}) {
+    const rulesDir = path.resolve(__dirname, '../rules');
+    
+    if (!fs.existsSync(rulesDir)) {
+      console.warn('⚠️ Rules directory not found');
+      return;
+    }
+
+    try {
+      // Scan category folders (common, security, typescript, etc.)
+      const categoryFolders = fs.readdirSync(rulesDir, { withFileTypes: true })
+        .filter(dirent => dirent.isDirectory())
+        .filter(dirent => !['tests', 'docs', 'utils', 'migration'].includes(dirent.name))
+        .map(dirent => dirent.name);
+
+      for (const categoryFolder of categoryFolders) {
+        const categoryPath = path.join(rulesDir, categoryFolder);
+        
+        // Scan rule folders within category
+        const ruleFolders = fs.readdirSync(categoryPath, { withFileTypes: true })
+          .filter(dirent => dirent.isDirectory())
+          .map(dirent => dirent.name);
+
+        for (const ruleFolder of ruleFolders) {
+          const ruleId = this.extractRuleIdFromFolder(ruleFolder);
+          const analyzerPath = path.join(categoryPath, ruleFolder, 'analyzer.js');
+          
+          if (fs.existsSync(analyzerPath)) {
+            try {
+              // Load analyzer dynamically - handle both class and instance exports
+              const analyzerModule = require(analyzerPath);
+              const analyzer = analyzerModule.default || analyzerModule;
+              
+              // Check if it's a class constructor, instance, or factory function
+              if (typeof analyzer === 'function') {
+                // It's a class constructor
+                this.ruleAnalyzers.set(ruleId, {
+                  path: analyzerPath,
+                  class: analyzer,
+                  folder: ruleFolder,
+                  category: categoryFolder,
+                  type: 'class'
+                });
+                this.supportedRulesList.push(ruleId);
+              } else if (analyzer && typeof analyzer === 'object' && analyzer.analyze) {
+                // It's an analyzer instance with analyze method
+                this.ruleAnalyzers.set(ruleId, {
+                  path: analyzerPath,
+                  instance: analyzer,
+                  folder: ruleFolder,
+                  category: categoryFolder,
+                  type: 'instance'
+                });
+                this.supportedRulesList.push(ruleId);
+              } else {
+                console.warn(`⚠️ Analyzer for ${ruleId} has unsupported format:`, typeof analyzer);
+              }
+              
+            } catch (error) {
+              console.warn(`⚠️ Failed to load analyzer for ${ruleId}:`, error.message);
+            }
+          }
+        }
+      }
+
+      if (config.verbose) {
+      if (this.verbose) {
+        console.log(`🔍 Found ${this.supportedRulesList.length} heuristic analyzers`);
+        console.log(`🔍 Supported rules: ${this.supportedRulesList.join(', ')}`);
+      }
+      }
+      
+    } catch (error) {
+      console.error('Failed to scan rule analyzers:', error.message);
+    }
+  }
+
+  /**
+   * Extract rule ID from folder name
+   * Following Rule C006: Verb-noun naming
+   * @param {string} folderName - Rule folder name
+   * @returns {string} Rule ID
+   */
+  extractRuleIdFromFolder(folderName) {
+    // Extract rule ID from patterns like "C019_log_level_usage"
+    const match = folderName.match(/^([CST]\d{3})/);
+    return match ? match[1] : folderName;
+  }
+
+  /**
+   * Analyze files using heuristic patterns
+   * Following Rule C006: Verb-noun naming
+   * @param {string[]} files - Files to analyze
+   * @param {Object[]} rules - Rules to apply
+   * @param {Object} options - Analysis options
+   * @returns {Promise<Object>} Analysis results
+   */
+  async analyze(files, rules, options) {
+    if (!this.initialized) {
+      throw new Error('Heuristic engine not initialized');
+    }
+
+    if (options.verbose) {
+      console.log(`🔍 [HeuristicEngine] Analyzing ${files.length} files with ${rules.length} rules`);
+      console.log(`🔍 [HeuristicEngine] Files: ${files.map(f => path.basename(f)).join(', ')}`);
+      console.log(`🔍 [HeuristicEngine] Rules: ${rules.map(r => r.id).join(', ')}`);
+    }
+
+    const results = {
+      results: [],
+      filesAnalyzed: files.length,
+      engine: 'heuristic',
+      metadata: {
+        rulesAnalyzed: rules.map(r => r.id),
+        analyzersUsed: []
+      }
+    };
+
+    // Group files by language for efficient processing
+    const filesByLanguage = this.groupFilesByLanguage(files);
+
+    for (const rule of rules) {
+      if (!this.isRuleSupported(rule.id)) {
+        if (options.verbose) {
+          console.warn(`⚠️ Rule ${rule.id} not supported by Heuristic engine, skipping...`);
+        }
+        continue;
+      }
+
+      try {
+        const ruleViolations = await this.analyzeRule(rule, filesByLanguage, options);
+        
+        if (ruleViolations.length > 0) {
+          // Group violations by file
+          const violationsByFile = this.groupViolationsByFile(ruleViolations);
+          
+          for (const [filePath, violations] of violationsByFile) {
+            // Find or create file result
+            let fileResult = results.results.find(r => r.file === filePath);
+            if (!fileResult) {
+              fileResult = { file: filePath, violations: [] };
+              results.results.push(fileResult);
+            }
+            fileResult.violations.push(...violations);
+          }
+        }
+
+        results.metadata.analyzersUsed.push(rule.id);
+        
+      } catch (error) {
+        console.error(`❌ Failed to analyze rule ${rule.id}:`, error.message);
+        // Continue with other rules
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Analyze a specific rule across files
+   * Following Rule C006: Verb-noun naming
+   * @param {Object} rule - Rule to analyze
+   * @param {Object} filesByLanguage - Files grouped by language
+   * @param {Object} options - Analysis options
+   * @returns {Promise<Object[]>} Rule violations
+   */
+  async analyzeRule(rule, filesByLanguage, options) {
+    const analyzerInfo = this.ruleAnalyzers.get(rule.id);
+    if (!analyzerInfo) {
+      return [];
+    }
+
+    try {
+      // Get analyzer - handle both class and instance types
+      const analyzerInfo = this.ruleAnalyzers.get(rule.id);
+      let analyzer;
+      
+      if (analyzerInfo.type === 'class') {
+        // Create analyzer instance from class
+        const AnalyzerClass = analyzerInfo.class;
+        try {
+          analyzer = new AnalyzerClass();
+        } catch (constructorError) {
+          throw new Error(`Failed to instantiate analyzer class: ${constructorError.message}`);
+        }
+      } else if (analyzerInfo.type === 'instance') {
+        // Use existing analyzer instance
+        analyzer = analyzerInfo.instance;
+      } else {
+        throw new Error(`Unknown analyzer type: ${analyzerInfo.type}`);
+      }
+      
+      // Verify analyzer has required methods
+      if (!analyzer.analyze || typeof analyzer.analyze !== 'function') {
+        console.warn(`⚠️ Analyzer for ${rule.id} missing analyze method`);
+        return [];
+      }
+
+      const allViolations = [];
+
+      // Run analyzer for each supported language
+      const ruleLanguages = this.getRuleLanguages(rule);
+      for (const language of ruleLanguages) {
+        const languageFiles = filesByLanguage[language] || [];
+        if (languageFiles.length === 0) continue;
+
+        try {
+          // Load rule config
+          const ruleConfig = await this.loadRuleConfig(rule.id, analyzerInfo.folder, analyzerInfo.category);
+          
+          // Run analysis with AST enhancement
+          if (options.verbose) {
+            console.log(`🔧 [DEBUG] About to call runEnhancedAnalysis for rule ${rule.id}, language ${language}`);
+          }
+          
+          const languageViolations = await this.runEnhancedAnalysis(
+            analyzer,
+            rule.id,
+            languageFiles, 
+            language, 
+            { ...ruleConfig, ...options }
+          );
+
+          allViolations.push(...languageViolations);
+          
+        } catch (error) {
+          console.error(`❌ Rule ${rule.id} failed for ${language}:`, error.message);
+        }
+      }
+
+      return allViolations;
+      
+    } catch (error) {
+      console.error(`❌ Failed to create analyzer for rule ${rule.id}:`, error.message);
+      return [];
+    }
+  }
+
+  /**
+   * Get supported languages for a rule
+   * Following Rule C006: Verb-noun naming
+   * @param {Object} rule - Rule object
+   * @returns {string[]} Supported languages
+   */
+  getRuleLanguages(rule) {
+    // Get from rules registry
+    const registryRule = this.rulesRegistry.rules?.[rule.id];
+    if (registryRule?.languages) {
+      return registryRule.languages;
+    }
+
+    // Fallback to rule object
+    if (rule.languages) {
+      return rule.languages;
+    }
+
+    // Default to common languages
+    return ['typescript', 'javascript'];
+  }
+
+  /**
+   * Load rule configuration
+   * Following Rule C006: Verb-noun naming
+   * @param {string} ruleId - Rule ID
+   * @param {string} ruleFolder - Rule folder name
+   * @param {string} category - Rule category (common, security, etc)
+   * @returns {Promise<Object>} Rule configuration
+   */
+  async loadRuleConfig(ruleId, ruleFolder, category = 'common') {
+    try {
+      const configPath = path.resolve(__dirname, '../rules', category, ruleFolder, 'config.json');
+      if (fs.existsSync(configPath)) {
+        return require(configPath);
+      }
+    } catch (error) {
+      console.warn(`⚠️ Failed to load config for ${ruleId}:`, error.message);
+    }
+
+    // Return minimal config
+    return {
+      ruleId,
+      name: `Rule ${ruleId}`,
+      description: `Analysis for rule ${ruleId}`,
+      severity: 'warning'
+    };
+  }
+
+  /**
+   * Group files by programming language
+   * Following Rule C006: Verb-noun naming
+   * @param {string[]} files - Files to group
+   * @returns {Object} Files grouped by language
+   */
+  groupFilesByLanguage(files) {
+    const groups = {};
+
+    for (const file of files) {
+      const language = this.detectLanguage(file);
+      if (!groups[language]) {
+        groups[language] = [];
+      }
+      groups[language].push(file);
+    }
+
+    return groups;
+  }
+
+  /**
+   * Detect programming language from file extension
+   * Following Rule C006: Verb-noun naming
+   * @param {string} filePath - File path
+   * @returns {string} Detected language
+   */
+  detectLanguage(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    
+    switch (ext) {
+      case '.ts': case '.tsx': return 'typescript';
+      case '.js': case '.jsx': return 'javascript';
+      case '.dart': return 'dart';
+      case '.swift': return 'swift';
+      case '.kt': case '.kts': return 'kotlin';
+      default: return 'unknown';
+    }
+  }
+
+  /**
+   * Group violations by file path
+   * Following Rule C006: Verb-noun naming
+   * @param {Object[]} violations - Array of violations
+   * @returns {Map} Violations grouped by file
+   */
+  groupViolationsByFile(violations) {
+    const groups = new Map();
+
+    for (const violation of violations) {
+      const filePath = violation.file || violation.filePath;
+      if (!filePath) continue;
+
+      if (!groups.has(filePath)) {
+        groups.set(filePath, []);
+      }
+      groups.get(filePath).push(violation);
+    }
+
+    return groups;
+  }
+
+  /**
+   * Get supported rules
+   * Following Rule C006: Verb-noun naming
+   * @returns {string[]} Supported rule IDs
+   */
+  getSupportedRules() {
+    return this.supportedRulesList;
+  }
+
+  /**
+   * Run enhanced analysis with multiple strategies
+   * Automatically selects optimal analysis method per rule
+   * Following Rule C006: Verb-noun naming
+   */
+  async runEnhancedAnalysis(analyzer, ruleId, files, language, options) {
+    // Create debug config from options
+    const debugConfig = {
+      enabled: options.debug || options.verbose || false,
+      logger: (component, message) => console.log(`🔧 [${component}] ${message}`)
+    };
+    
+    // Debug logging based on debug flag
+    if (debugConfig.enabled) {
+      debugConfig.logger(this.constructor.name, `runEnhancedAnalysis called: rule=${ruleId}, language=${language}, files=${files.length}`);
+    }
+    
+    if (options.verbose) {
+      console.log(`🔧 [DEBUG] runEnhancedAnalysis called: rule=${ruleId}, language=${language}, files=${files.length}`);
+    }
+    
+    // Load rule analysis strategy
+    const strategy = await this.getRuleAnalysisStrategy(ruleId, language);
+    
+    // Debug logging based on debug flag
+    if (debugConfig.enabled) {
+      debugConfig.logger(this.constructor.name, `Rule ${ruleId}: ${strategy.primary} (approach: ${strategy.approach})`);
+    }
+    
+    if (options.verbose) {
+      console.log(`🔧 [Strategy] Rule ${ruleId}: ${strategy.primary} (fallback: ${strategy.fallback || 'none'})`);
+    }
+
+    let violations = [];
+    let analysisResults = {
+      methods: [],
+      totalViolations: 0,
+      accuracy: 'unknown'
+    };
+
+    // Execute analysis based on strategy
+    switch (strategy.approach) {
+      case 'ast-primary':
+        violations = await this.runASTPrimaryAnalysis(analyzer, ruleId, files, language, options, strategy, debugConfig);
+        break;
+      
+      case 'regex-optimal':
+        violations = await this.runRegexOptimalAnalysis(analyzer, ruleId, files, language, options);
+        break;
+      
+      case 'hybrid-combined':
+        violations = await this.runHybridAnalysis(analyzer, ruleId, files, language, options, strategy);
+        break;
+      
+      case 'progressive-enhancement':
+        violations = await this.runProgressiveAnalysis(analyzer, ruleId, files, language, options, strategy);
+        break;
+      
+      default:
+        // Fallback to existing logic
+        violations = await this.runLegacyAnalysis(analyzer, ruleId, files, language, options);
+    }
+
+    if (options.verbose && violations.length > 0) {
+      console.log(`📊 [Analysis] Found ${violations.length} violations using ${strategy.approach}`);
+    }
+
+    return violations;
+  }
+
+  /**
+   * Get optimal analysis strategy for a rule
+   */
+  async getRuleAnalysisStrategy(ruleId, language) {
+    try {
+      const strategies = require('../config/rule-analysis-strategies');
+      
+      // Check AST-preferred rules
+      if (strategies.astPreferred[ruleId]) {
+        const astAvailable = this.astRegistry.isASTSupportAvailable(language);
+        return {
+          approach: 'ast-primary',
+          primary: 'ast',
+          fallback: 'regex',
+          astAvailable,
+          config: strategies.astPreferred[ruleId]
+        };
+      }
+      
+      // Check regex-optimal rules
+      if (strategies.regexOptimal[ruleId]) {
+        return {
+          approach: 'regex-optimal',
+          primary: 'regex',
+          config: strategies.regexOptimal[ruleId]
+        };
+      }
+      
+      // Check hybrid rules
+      if (strategies.hybridOptimal[ruleId]) {
+        return {
+          approach: 'hybrid-combined',
+          primary: strategies.hybridOptimal[ruleId].strategy.split('-')[0],
+          config: strategies.hybridOptimal[ruleId]
+        };
+      }
+      
+      // Check experimental rules
+      if (strategies.experimental[ruleId]) {
+        return {
+          approach: 'progressive-enhancement',
+          primary: 'regex',
+          fallback: 'ast',
+          config: strategies.experimental[ruleId]
+        };
+      }
+      
+      // Default strategy
+      return {
+        approach: 'ast-primary',
+        primary: 'ast',
+        fallback: 'regex',
+        astAvailable: this.astRegistry.isASTSupportAvailable(language)
+      };
+      
+    } catch (error) {
+      // Fallback if strategy config is not available
+      return {
+        approach: 'ast-primary',
+        primary: 'ast',
+        fallback: 'regex',
+        astAvailable: this.astRegistry.isASTSupportAvailable(language)
+      };
+    }
+  }
+
+  /**
+   * AST-primary analysis: Try AST first, fallback to regex
+   */
+  async runASTPrimaryAnalysis(analyzer, ruleId, files, language, options, strategy, debugConfig) {
+    const violations = [];
+    
+    if (debugConfig.enabled) {
+      debugConfig.logger(this.constructor.name, `Starting AST-primary analysis for ${ruleId}, AST available: ${strategy.astAvailable}`);
+    }
+    
+    for (const filePath of files) {
+      try {
+        const code = fs.readFileSync(filePath, 'utf8');
+        let analysisResult = null;
+        
+        // Try AST analysis first if available
+        if (strategy.astAvailable) {
+          if (debugConfig.enabled) {
+            debugConfig.logger(this.constructor.name, `Attempting AST for file: ${filePath}`);
+          }
+          
+          try {
+            const astResult = await this.astRegistry.analyzeRule(ruleId, code, language, filePath);
+            if (astResult && astResult.length > 0) {
+              analysisResult = astResult.map(violation => ({
+                ...violation,
+                filePath,
+                analysisMethod: 'ast',
+                confidence: strategy.config?.accuracy?.ast || 90
+              }));
+              
+              if (debugConfig.enabled) {
+                debugConfig.logger(this.constructor.name, `AST found ${astResult.length} violations in ${filePath}`);
+              }
+            }
+          } catch (astError) {
+            if (debugConfig.enabled) {
+              debugConfig.logger(this.constructor.name, `AST failed for ${filePath}: ${astError.message}`);
+            }
+            
+            if (options.verbose) {
+              console.warn(`⚠️ AST analysis failed for ${filePath}, falling back to regex`);
+            }
+          }
+        } else {
+          if (debugConfig.enabled) {
+            debugConfig.logger(this.constructor.name, `AST not available, skipping to fallback for ${filePath}`);
+          }
+        }
+
+        // Fallback to regex if AST failed or not available
+        if (!analysisResult) {
+          if (debugConfig.enabled) {
+            debugConfig.logger(this.constructor.name, `Using regex fallback for ${filePath}`);
+          }
+          const regexResult = await analyzer.analyze([filePath], language, options);
+          if (regexResult && regexResult.length > 0) {
+            analysisResult = regexResult.map(violation => ({
+              ...violation,
+              analysisMethod: 'regex',
+              confidence: strategy.config?.accuracy?.regex || 75
+            }));
+          }
+        }
+
+        if (analysisResult) {
+          violations.push(...analysisResult);
+        }
+        
+      } catch (error) {
+        if (options.verbose) {
+          console.error(`❌ Analysis failed for ${filePath}:`, error.message);
+        }
+      }
+    }
+
+    return violations;
+  }
+
+  /**
+   * Regex-optimal analysis: Use regex as primary method
+   */
+  async runRegexOptimalAnalysis(analyzer, ruleId, files, language, options) {
+    const violations = [];
+    
+    const regexResult = await analyzer.analyze(files, language, options);
+    if (regexResult && regexResult.length > 0) {
+      violations.push(...regexResult.map(violation => ({
+        ...violation,
+        analysisMethod: 'regex',
+        confidence: 95 // High confidence for regex-optimal rules
+      })));
+    }
+
+    return violations;
+  }
+
+  /**
+   * Hybrid analysis: Combine multiple methods for best results
+   */
+  async runHybridAnalysis(analyzer, ruleId, files, language, options, strategy) {
+    const violations = [];
+    const astViolations = [];
+    const regexViolations = [];
+    
+    for (const filePath of files) {
+      try {
+        const code = fs.readFileSync(filePath, 'utf8');
+        
+        // Run both AST and regex analysis
+        const analysisPromises = [];
+        
+        // AST analysis
+        if (this.astRegistry.isASTSupportAvailable(language)) {
+          analysisPromises.push(
+            this.astRegistry.analyzeRule(ruleId, code, language, filePath)
+              .then(result => ({ type: 'ast', result, filePath }))
+              .catch(() => ({ type: 'ast', result: null, filePath }))
+          );
+        }
+        
+        // Regex analysis
+        analysisPromises.push(
+          analyzer.analyze([filePath], language, options)
+            .then(result => ({ type: 'regex', result, filePath }))
+            .catch(() => ({ type: 'regex', result: null, filePath }))
+        );
+
+        const results = await Promise.all(analysisPromises);
+        
+        // Process results based on strategy
+        for (const { type, result, filePath } of results) {
+          if (result && result.length > 0) {
+            const violations = result.map(violation => ({
+              ...violation,
+              filePath,
+              analysisMethod: type,
+              confidence: strategy.config?.accuracy?.[type] || 85
+            }));
+            
+            if (type === 'ast') {
+              astViolations.push(...violations);
+            } else {
+              regexViolations.push(...violations);
+            }
+          }
+        }
+        
+      } catch (error) {
+        if (options.verbose) {
+          console.error(`❌ Hybrid analysis failed for ${filePath}:`, error.message);
+        }
+      }
+    }
+
+    // Combine results intelligently
+    const combinedViolations = this.combineHybridResults(
+      astViolations, 
+      regexViolations, 
+      strategy.config?.strategy || 'ast-primary-regex-fallback'
+    );
+
+    return combinedViolations;
+  }
+
+  /**
+   * Progressive enhancement: Start simple, enhance with advanced methods
+   */
+  async runProgressiveAnalysis(analyzer, ruleId, files, language, options, strategy) {
+    const violations = [];
+    
+    // Start with basic regex analysis
+    const regexResult = await analyzer.analyze(files, language, options);
+    if (regexResult) {
+      violations.push(...regexResult.map(violation => ({
+        ...violation,
+        analysisMethod: 'regex',
+        confidence: 75
+      })));
+    }
+
+    // Enhance with AST if available and beneficial
+    if (this.astRegistry.isASTSupportAvailable(language) && violations.length > 0) {
+      // TODO: Implement AST enhancement for specific violation types
+      // This could involve re-analyzing files with violations for better precision
+    }
+
+    return violations;
+  }
+
+  /**
+   * Legacy analysis method (for backward compatibility)
+   */
+  async runLegacyAnalysis(analyzer, ruleId, files, language, options) {
+    const regexResult = await analyzer.analyze(files, language, options);
+    return regexResult || [];
+  }
+
+  /**
+   * Intelligently combine AST and regex results
+   */
+  combineHybridResults(astViolations, regexViolations, strategy) {
+    switch (strategy) {
+      case 'ast-primary-regex-fallback':
+        // Use AST results where available, fill gaps with regex
+        return this.mergeViolationsWithPriority(astViolations, regexViolations, 'ast');
+        
+      case 'regex-primary-ast-enhancement':
+        // Use regex as base, enhance with AST insights
+        return this.mergeViolationsWithPriority(regexViolations, astViolations, 'regex');
+        
+      case 'union':
+        // Combine all violations (may have duplicates)
+        return [...astViolations, ...regexViolations];
+        
+      case 'intersection':
+        // Only violations found by both methods
+        return this.findIntersectionViolations(astViolations, regexViolations);
+        
+      default:
+        return astViolations.length > 0 ? astViolations : regexViolations;
+    }
+  }
+
+  /**
+   * Merge violations with priority given to one method
+   */
+  mergeViolationsWithPriority(primary, secondary, primaryType) {
+    const merged = [...primary];
+    const primaryLocations = new Set(
+      primary.map(v => `${v.filePath}:${v.line}:${v.column}`)
+    );
+
+    // Add secondary violations that don't conflict with primary
+    for (const violation of secondary) {
+      const location = `${violation.filePath}:${violation.line}:${violation.column}`;
+      if (!primaryLocations.has(location)) {
+        merged.push({
+          ...violation,
+          isSecondary: true,
+          primaryMethod: primaryType
+        });
+      }
+    }
+
+    return merged;
+  }
+
+  /**
+   * Find violations detected by both methods (high confidence)
+   */
+  findIntersectionViolations(astViolations, regexViolations) {
+    const intersection = [];
+    
+    for (const astViolation of astViolations) {
+      const matching = regexViolations.find(regexViolation => 
+        astViolation.filePath === regexViolation.filePath &&
+        Math.abs(astViolation.line - regexViolation.line) <= 2 // Allow small line differences
+      );
+      
+      if (matching) {
+        intersection.push({
+          ...astViolation,
+          analysisMethod: 'hybrid-intersection',
+          confidence: 98, // Very high confidence
+          confirmedBy: ['ast', 'regex']
+        });
+      }
+    }
+
+    return intersection;
+  }
+
+  /**
+   * Cleanup Heuristic engine resources
+   * Following Rule C006: Verb-noun naming
+   */
+  async cleanup() {
+    // Clear analyzer cache
+    this.ruleAnalyzers.clear();
+    this.supportedRulesList = [];
+    
+    await super.cleanup();
+    if (this.verbose) {
+      console.log('🔍 Heuristic engine cleanup completed');
+    }
+  }
+}
+
+module.exports = HeuristicEngine;