@sun-asterisk/sunlint 1.2.2 → 1.3.1

package/core/unified-rule-registry.js

@@ -0,0 +1,484 @@
+/**
+ * Unified Rule Registry - Single Source of Truth
+ * Following Rule C005: Single responsibility - centralized rule management
+ * Following Rule C015: Use domain language - clear registry terms
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class UnifiedRuleRegistry {
+  constructor() {
+    this.rules = new Map();
+    this.engineCapabilities = new Map();
+    this.initialized = false;
+    this.verbose = false;
+  }
+
+  /**
+   * Initialize registry with auto-discovery
+   * @param {Object} options - Configuration options
+   */
+  async initialize(options = {}) {
+    if (this.initialized) return;
+    
+    this.verbose = options.verbose || false;
+    
+    try {
+      // 1. Load master rule definitions
+      await this.loadMasterRegistry();
+      
+      // 2. Auto-discover analyzer files  
+      await this.autoDiscoverAnalyzers();
+      
+      // 3. Register engine capabilities
+      this.registerEngineCapabilities();
+      
+      // 4. Validate consistency
+      await this.validateRegistry();
+      
+      this.initialized = true;
+      
+      if (this.verbose) {
+        console.log(`✅ Unified Registry initialized: ${this.rules.size} rules`);
+      }
+      
+    } catch (error) {
+      console.error('❌ Failed to initialize Unified Rule Registry:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Load master rule definitions from primary source
+   */
+  async loadMasterRegistry() {
+    // Try enhanced registry first, fall back to original
+    const registryPaths = [
+      path.resolve(__dirname, '../config/rules/enhanced-rules-registry.json'),
+      path.resolve(__dirname, '../config/rules/rules-registry.json')
+    ];
+    
+    let registryPath = null;
+    for (const tryPath of registryPaths) {
+      if (fs.existsSync(tryPath)) {
+        registryPath = tryPath;
+        break;
+      }
+    }
+    
+    if (!registryPath) {
+      throw new Error('No master registry found in config/rules/');
+    }
+
+    if (this.verbose) {
+      console.log(`📋 Loading enhanced registry from: ${path.basename(registryPath)}`);
+    }
+    
+    try {
+      const registryData = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      const rules = registryData.rules || registryData;
+      
+      for (const [ruleId, ruleConfig] of Object.entries(rules)) {
+        const ruleDefinition = {
+          id: ruleId,
+          name: ruleConfig.name,
+          description: ruleConfig.description,
+          category: ruleConfig.category,
+          severity: ruleConfig.severity || 'warning',
+          languages: ruleConfig.languages || ['javascript', 'typescript'],
+          
+          // Use existing analyzer paths or initialize empty
+          analyzers: ruleConfig.analyzers || {},
+          
+          // Use existing engine mappings or initialize empty
+          engineMappings: ruleConfig.engineMappings || {},
+          
+          // Use existing strategy or initialize default
+          strategy: ruleConfig.strategy || {
+            preferred: 'regex',
+            fallbacks: ['ast'],
+            accuracy: {}
+          },
+          
+          // Metadata
+          version: ruleConfig.version || '1.0.0',
+          status: ruleConfig.status || 'stable',
+          tags: ruleConfig.tags || []
+        };
+        
+        this.rules.set(ruleId, ruleDefinition);
+      }
+      
+      if (this.verbose) {
+        console.log(`📋 Loaded ${this.rules.size} rules from master registry`);
+      }
+      
+    } catch (error) {
+      throw new Error(`Failed to parse master registry: ${error.message}`);
+    }
+  }
+
+  /**
+   * Auto-discover analyzer files for all rules
+   */
+  async autoDiscoverAnalyzers() {
+    const rulesBaseDir = path.resolve(__dirname, '../rules');
+    
+    for (const [ruleId, ruleDefinition] of this.rules.entries()) {
+      const analyzers = await this.discoverAnalyzersForRule(ruleId, rulesBaseDir);
+      ruleDefinition.analyzers = analyzers;
+      
+      // Infer preferred analysis strategy based on available analyzers
+      if (analyzers.semantic) {
+        ruleDefinition.strategy.preferred = 'semantic';
+        ruleDefinition.strategy.fallbacks = ['ast', 'regex'];
+      } else if (analyzers.ast) {
+        ruleDefinition.strategy.preferred = 'ast';
+        ruleDefinition.strategy.fallbacks = ['regex'];
+      } else if (analyzers.regex || analyzers.legacy) {
+        ruleDefinition.strategy.preferred = 'regex';
+        ruleDefinition.strategy.fallbacks = [];
+      }
+    }
+    
+    if (this.verbose) {
+      const rulesWithAnalyzers = Array.from(this.rules.values()).filter(rule => 
+        Object.keys(rule.analyzers).length > 0
+      ).length;
+      console.log(`🔍 Auto-discovered analyzers for ${rulesWithAnalyzers}/${this.rules.size} rules`);
+    }
+  }
+
+  /**
+   * Discover analyzer files for a specific rule
+   * @param {string} ruleId - Rule ID
+   * @param {string} rulesBaseDir - Base rules directory
+   * @returns {Object} Analyzer file paths
+   */
+  async discoverAnalyzersForRule(ruleId, rulesBaseDir) {
+    const analyzers = {};
+    
+    // Direct search in common directory using exact folder names
+    const commonRulesDir = path.join(rulesBaseDir, 'common');
+    
+    if (fs.existsSync(commonRulesDir)) {
+      const ruleFolders = fs.readdirSync(commonRulesDir);
+      
+      // Look for folder that starts with rule ID
+      const matchingFolder = ruleFolders.find(folder => 
+        folder.startsWith(ruleId + '_') || folder === ruleId
+      );
+      
+      if (matchingFolder) {
+        const rulePath = path.join(commonRulesDir, matchingFolder);
+        
+        // Check for different analyzer files
+        const analyzerFiles = {
+          semantic: path.join(rulePath, 'semantic-analyzer.js'),
+          ast: path.join(rulePath, 'ast-analyzer.js'),
+          regex: path.join(rulePath, 'regex-analyzer.js'),
+          legacy: path.join(rulePath, 'analyzer.js')
+        };
+        
+        for (const [type, filePath] of Object.entries(analyzerFiles)) {
+          if (fs.existsSync(filePath)) {
+            analyzers[type] = filePath;
+          }
+        }
+      }
+    }
+    
+    // Also check other category directories (security, typescript, etc.)
+    const otherDirs = ['security', 'typescript', 'react'];
+    for (const categoryDir of otherDirs) {
+      const categoryPath = path.join(rulesBaseDir, categoryDir);
+      
+      if (fs.existsSync(categoryPath)) {
+        const ruleFolders = fs.readdirSync(categoryPath);
+        const matchingFolder = ruleFolders.find(folder => 
+          folder.startsWith(ruleId + '_') || folder === ruleId
+        );
+        
+        if (matchingFolder) {
+          const rulePath = path.join(categoryPath, matchingFolder);
+          
+          const analyzerFiles = {
+            semantic: path.join(rulePath, 'semantic-analyzer.js'),
+            ast: path.join(rulePath, 'ast-analyzer.js'),
+            regex: path.join(rulePath, 'regex-analyzer.js'),
+            legacy: path.join(rulePath, 'analyzer.js')
+          };
+          
+          for (const [type, filePath] of Object.entries(analyzerFiles)) {
+            if (fs.existsSync(filePath)) {
+              analyzers[type] = filePath;
+            }
+          }
+          
+          // If we found analyzers, stop searching
+          if (Object.keys(analyzers).length > 0) {
+            break;
+          }
+        }
+      }
+    }
+    
+    return analyzers;
+  }
+
+  /**
+   * Expand glob-like patterns to actual paths
+   * @param {string} baseDir - Base directory
+   * @param {string} pattern - Pattern with * wildcards
+   * @returns {string[]} Expanded paths
+   */
+  expandPattern(baseDir, pattern) {
+    if (!pattern.includes('*')) {
+      return [path.join(baseDir, pattern)];
+    }
+    
+    const parts = pattern.split('/');
+    let currentPaths = [baseDir];
+    
+    for (const part of parts) {
+      if (part === '') continue;
+      
+      const newPaths = [];
+      for (const currentPath of currentPaths) {
+        if (part.includes('*')) {
+          // Wildcard part - expand
+          if (fs.existsSync(currentPath)) {
+            const entries = fs.readdirSync(currentPath);
+            const regex = new RegExp('^' + part.replace(/\*/g, '.*') + '$');
+            
+            for (const entry of entries) {
+              if (regex.test(entry)) {
+                newPaths.push(path.join(currentPath, entry));
+              }
+            }
+          }
+        } else {
+          // Literal part
+          newPaths.push(path.join(currentPath, part));
+        }
+      }
+      currentPaths = newPaths;
+    }
+    
+    return currentPaths;
+  }
+
+  /**
+   * Register engine capabilities
+   */
+  registerEngineCapabilities() {
+    // Define what each engine can handle
+    this.engineCapabilities.set('heuristic', ['semantic', 'ast', 'regex']);
+    this.engineCapabilities.set('eslint', ['ast', 'regex']);
+    this.engineCapabilities.set('openai', ['semantic']);
+    
+    // Load ESLint mappings
+    this.loadESLintMappings();
+  }
+
+  /**
+   * Load ESLint rule mappings
+   */
+  loadESLintMappings() {
+    const eslintMappingPath = path.resolve(__dirname, '../config/eslint-rule-mapping.json');
+    
+    if (fs.existsSync(eslintMappingPath)) {
+      try {
+        const mappingData = JSON.parse(fs.readFileSync(eslintMappingPath, 'utf8'));
+        const mappings = mappingData.mappings || mappingData;
+        
+        for (const [ruleId, eslintRules] of Object.entries(mappings)) {
+          if (this.rules.has(ruleId)) {
+            this.rules.get(ruleId).engineMappings.eslint = eslintRules;
+          }
+        }
+        
+        if (this.verbose) {
+          console.log(`🔗 Loaded ESLint mappings for ${Object.keys(mappings).length} rules`);
+        }
+        
+      } catch (error) {
+        console.warn(`⚠️ Failed to load ESLint mappings: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Validate registry consistency
+   */
+  async validateRegistry() {
+    const issues = [];
+    
+    for (const [ruleId, ruleDefinition] of this.rules.entries()) {
+      // Check if rule has at least one analyzer
+      if (Object.keys(ruleDefinition.analyzers).length === 0) {
+        issues.push(`${ruleId}: No analyzers found`);
+      }
+      
+      // Check if analyzer files actually exist
+      for (const [type, filePath] of Object.entries(ruleDefinition.analyzers)) {
+        if (!fs.existsSync(filePath)) {
+          issues.push(`${ruleId}: ${type} analyzer not found at ${filePath}`);
+        }
+      }
+    }
+    
+    if (issues.length > 0 && this.verbose) {
+      console.warn(`⚠️ Registry validation found ${issues.length} issues:`);
+      issues.slice(0, 5).forEach(issue => console.warn(`  - ${issue}`));
+      if (issues.length > 5) {
+        console.warn(`  ... and ${issues.length - 5} more`);
+      }
+    }
+  }
+
+  // === PUBLIC API ===
+
+  /**
+   * Get rule definition by ID
+   * @param {string} ruleId - Rule ID
+   * @returns {Object|null} Rule definition
+   */
+  getRuleDefinition(ruleId) {
+    return this.rules.get(ruleId) || null;
+  }
+
+  /**
+   * Get all rules supported by an engine
+   * @param {string} engine - Engine name
+   * @returns {Object[]} Array of rule definitions
+   */
+  getRulesForEngine(engine) {
+    const capabilities = this.engineCapabilities.get(engine) || [];
+    const supportedRules = [];
+    
+    for (const [ruleId, ruleDefinition] of this.rules.entries()) {
+      // Check if engine can handle this rule's preferred strategy
+      if (capabilities.includes(ruleDefinition.strategy.preferred)) {
+        supportedRules.push(ruleDefinition);
+      }
+      // Or if engine can handle any fallback strategy
+      else if (ruleDefinition.strategy.fallbacks.some(fallback => capabilities.includes(fallback))) {
+        supportedRules.push(ruleDefinition);
+      }
+    }
+    
+    return supportedRules;
+  }
+
+  /**
+   * Get all supported rule IDs
+   * @returns {string[]} Array of rule IDs
+   */
+  getSupportedRules() {
+    return Array.from(this.rules.keys());
+  }
+
+  /**
+   * Resolve analyzer path for a rule and engine
+   * @param {string} ruleId - Rule ID
+   * @param {string} engine - Engine name  
+   * @returns {string|null} Analyzer file path
+   */
+  resolveAnalyzerPath(ruleId, engine) {
+    const ruleDefinition = this.rules.get(ruleId);
+    if (!ruleDefinition) return null;
+    
+    const capabilities = this.engineCapabilities.get(engine) || [];
+    const analyzers = ruleDefinition.analyzers;
+    
+    // Try preferred strategy first
+    const preferred = ruleDefinition.strategy.preferred;
+    if (capabilities.includes(preferred) && analyzers[preferred]) {
+      return analyzers[preferred];
+    }
+    
+    // Try fallback strategies
+    for (const fallback of ruleDefinition.strategy.fallbacks) {
+      if (capabilities.includes(fallback) && analyzers[fallback]) {
+        return analyzers[fallback];
+      }
+    }
+    
+    // Fall back to legacy analyzer if available and engine supports regex/ast
+    if (analyzers.legacy && (capabilities.includes('regex') || capabilities.includes('ast'))) {
+      return analyzers.legacy;
+    }
+    
+    return null;
+  }
+
+  /**
+   * Get engine mapping for a rule (ESLint specific)
+   * @param {string} ruleId - Rule ID
+   * @param {string} engine - Engine name
+   * @returns {string[]} Array of engine-specific rule names
+   */
+  getEngineMapping(ruleId, engine) {
+    const ruleDefinition = this.rules.get(ruleId);
+    if (!ruleDefinition) return [];
+    
+    return ruleDefinition.engineMappings[engine] || [];
+  }
+
+  /**
+   * Check if rule is supported by engine
+   * @param {string} ruleId - Rule ID
+   * @param {string} engine - Engine name
+   * @returns {boolean} True if supported
+   */
+  isRuleSupported(ruleId, engine) {
+    const analyzerPath = this.resolveAnalyzerPath(ruleId, engine);
+    return analyzerPath !== null;
+  }
+
+  /**
+   * Get registry statistics
+   * @returns {Object} Registry stats
+   */
+  getStats() {
+    const stats = {
+      totalRules: this.rules.size,
+      rulesByCategory: {},
+      rulesByEngine: {},
+      rulesWithAnalyzers: 0
+    };
+    
+    for (const ruleDefinition of this.rules.values()) {
+      // Count by category
+      const category = ruleDefinition.category;
+      stats.rulesByCategory[category] = (stats.rulesByCategory[category] || 0) + 1;
+      
+      // Count rules with analyzers
+      if (Object.keys(ruleDefinition.analyzers).length > 0) {
+        stats.rulesWithAnalyzers++;
+      }
+    }
+    
+    // Count by engine
+    for (const engine of this.engineCapabilities.keys()) {
+      stats.rulesByEngine[engine] = this.getRulesForEngine(engine).length;
+    }
+    
+    return stats;
+  }
+}
+
+// Singleton instance
+let instance = null;
+
+module.exports = {
+  UnifiedRuleRegistry,
+  getInstance: () => {
+    if (!instance) {
+      instance = new UnifiedRuleRegistry();
+    }
+    return instance;
+  }
+};

package/docs/COMMAND-EXAMPLES.md

@@ -113,6 +113,22 @@ node cli.js --all --input=. --timeout=60000 --format=summary --no-ai
 # Disable caching
 node cli.js --all --input=. --no-cache --format=summary --no-ai
 
+# **Control semantic analysis for large projects**
+# Default limit: 1000 files for performance balance
+node cli.js --all --input=. --max-semantic-files=1000 --format=summary
+
+# For small projects: Analyze all files
+node cli.js --all --input=. --max-semantic-files=0 --format=summary
+
+# For large projects: Conservative analysis
+node cli.js --all --input=. --max-semantic-files=500 --format=summary
+
+# For massive projects: Minimal semantic analysis
+node cli.js --all --input=. --max-semantic-files=100 --format=summary
+
+# Unlimited semantic analysis (use with caution!)
+node cli.js --all --input=. --max-semantic-files=-1 --format=summary
+
 # Verbose logging
 node cli.js --all --input=. --verbose --format=summary --no-ai
 
@@ -203,6 +219,124 @@ node cli.js --all --changed-files --diff-base=origin/main --format=github --no-a
 node cli.js --all --changed-files --ai --format=detailed
 ```
 
+## 🏗️ **Large Project Strategies**
+
+> **⚡ Performance Note**: SunLint uses semantic analysis for advanced rules (like C047). For projects with 1000+ files, you can control semantic analysis scope to balance accuracy vs performance.
+
+### **Strategy 1: Incremental Analysis** 📈
+```bash
+# Start with changed files only (fastest)
+node cli.js --all --changed-files --format=summary --no-ai
+
+# Focus on specific directories
+node cli.js --all --input=src/critical --max-semantic-files=2000 --format=summary
+
+# Target important file patterns only
+node cli.js --all --include="src/**/*.ts" --exclude="**/*.test.*,**/*.d.ts" --input=.
+
+# Use directory-based analysis
+node cli.js --all --input=src/auth --format=summary  # Most critical module first
+node cli.js --all --input=src/api --format=summary   # Then API layer
+node cli.js --all --input=src/utils --format=summary # Finally utilities
+```
+
+### **Strategy 2: Semantic Analysis Tuning** 🔧
+```bash
+# Conservative: 500 files for faster analysis
+node cli.js --all --input=. --max-semantic-files=500 --format=summary
+
+# Balanced: 1000 files (default) for medium projects
+node cli.js --all --input=. --max-semantic-files=1000 --format=summary
+
+# Comprehensive: 2000+ files for complete analysis
+node cli.js --all --input=. --max-semantic-files=2000 --format=summary
+
+# Unlimited: All files (use for final validation)
+node cli.js --all --input=. --max-semantic-files=-1 --format=summary
+
+# Disable semantic analysis completely (heuristic only)
+node cli.js --all --input=. --max-semantic-files=0 --format=summary
+```
+
+### **Strategy 3: Rule-Based Prioritization** 🎯
+```bash
+# Phase 1: Critical security issues (fast heuristic rules)
+node cli.js --security --input=. --max-semantic-files=0 --format=summary
+
+# Phase 2: Code quality basics
+node cli.js --rules=C006,C019,C029 --input=. --max-semantic-files=500 --format=summary
+
+# Phase 3: Advanced semantic rules (targeted)
+node cli.js --rules=C047 --input=src --max-semantic-files=1000 --format=summary
+
+# Phase 4: Full comprehensive scan
+node cli.js --all --input=. --max-semantic-files=-1 --format=detailed
+```
+
+### **Strategy 4: CI/CD Optimization** ⚡
+```bash
+# PR checks: Fast semantic analysis
+node cli.js --all --changed-files --max-semantic-files=300 --format=github --no-ai
+
+# Nightly builds: Medium semantic analysis
+node cli.js --all --input=. --max-semantic-files=1000 --format=json --output=nightly.json
+
+# Weekly reports: Full semantic analysis
+node cli.js --all --input=. --max-semantic-files=-1 --format=detailed --output=weekly.json
+
+# Release validation: Comprehensive with baselines
+node cli.js --all --input=. --max-semantic-files=2000 --baseline=last-release.json
+```
+
+### **Strategy 5: Memory & Performance Monitoring** 📊
+```bash
+# Monitor file loading (debug mode)
+node cli.js --all --input=. --max-semantic-files=1000 --verbose --debug
+
+# Track performance with different limits
+time node cli.js --all --input=. --max-semantic-files=500 --format=summary
+time node cli.js --all --input=. --max-semantic-files=1000 --format=summary
+time node cli.js --all --input=. --max-semantic-files=2000 --format=summary
+
+# Memory-conscious analysis for CI
+node cli.js --all --input=. --max-semantic-files=300 --max-concurrent=2 --format=summary
+```
+
+### **📋 Recommended Limits by Project Size**
+
+| Project Size | Files Count | Recommended Limit | Use Case |
+|-------------|-------------|-------------------|----------|
+| Small | < 100 files | `--max-semantic-files=0` (all) | Complete analysis |
+| Medium | 100-500 files | `--max-semantic-files=500` | Balanced |
+| Large | 500-2000 files | `--max-semantic-files=1000` | Default recommended |
+| Enterprise | 2000-5000 files | `--max-semantic-files=1500` | Conservative |
+| Massive | 5000+ files | `--max-semantic-files=500` | Targeted analysis |
+
+> **💡 Pro Tips for Large Projects:**
+> 1. Use `--changed-files` for daily development
+> 2. Use `--max-semantic-files=500` for CI/CD pipelines  
+> 3. Use `--max-semantic-files=-1` for release validation
+> 4. Combine with `--include` patterns to focus on critical code
+> 5. Monitor analysis time and adjust limits accordingly
+
+### **Example 1: Monorepo with 5000+ Files**
+```bash
+# Daily development: Changed files only
+node cli.js --all --changed-files --max-semantic-files=300 --format=summary
+
+# Module-specific analysis
+node cli.js --all --input=packages/core --max-semantic-files=1000 --format=summary
+node cli.js --all --input=packages/api --max-semantic-files=1000 --format=summary
+
+# CI pipeline: Conservative semantic analysis
+node cli.js --all --changed-files --max-semantic-files=500 --format=github
+
+# Release validation: Full analysis by modules
+for dir in packages/*/; do
+  node cli.js --all --input="$dir" --max-semantic-files=2000 --format=json --output="${dir//\//-}-report.json"
+done
+```
+
 ### **Example 2: Legacy Code Improvement**
 ```bash
 # Step 1: Baseline assessment