@sun-asterisk/sunlint 1.3.0 → 1.3.2

package/docs/LARGE-PROJECT-GUIDE.md

@@ -0,0 +1,324 @@
+# 🏗️ Large Project Analysis Guide
+
+> **For projects with 1000+ files**: Complete strategies to optimize SunLint performance while maintaining comprehensive analysis coverage.
+
+## 📊 Overview
+
+SunLint uses **semantic analysis** for advanced rules like `C047` (retry pattern detection). For large projects, you can control the scope of semantic analysis to balance accuracy vs performance.
+
+### 🎯 Key Benefits
+
+- **Configurable file limits**: Control memory usage and analysis time
+- **Smart defaults**: Automatic optimization for different project sizes  
+- **Multiple strategies**: Choose the best approach for your workflow
+- **Full coverage options**: Ensure no violations are missed
+
+## ⚙️ Configuration Options
+
+### CLI Option: `--max-semantic-files`
+
+Controls how many files are loaded for semantic analysis:
+
+```bash
+# Default behavior (auto-detect)
+node cli.js --all --input=.
+
+# Conservative analysis (500 files)
+node cli.js --all --input=. --max-semantic-files=500
+
+# Balanced analysis (1000 files - default)  
+node cli.js --all --input=. --max-semantic-files=1000
+
+# Comprehensive analysis (2000 files)
+node cli.js --all --input=. --max-semantic-files=2000
+
+# Unlimited analysis (all files)
+node cli.js --all --input=. --max-semantic-files=-1
+
+# Disable semantic analysis (heuristic only)
+node cli.js --all --input=. --max-semantic-files=0
+```
+
+### 📋 Recommended Limits by Project Size
+
+| Project Size | Files Count | Recommended Limit | Memory Usage | Analysis Time |
+|-------------|-------------|-------------------|--------------|---------------|
+| **Small** | < 100 files | `0` (all files) | Low | Fast |
+| **Medium** | 100-500 files | `500` | Medium | Medium |
+| **Large** | 500-2000 files | `1000` ⭐ | Medium-High | Medium |
+| **Enterprise** | 2000-5000 files | `1500` | High | Slow |
+| **Massive** | 5000+ files | `500-1000` | Controlled | Reasonable |
+
+⭐ **Default recommended setting**
+
+## 🚀 Analysis Strategies
+
+### Strategy 1: Incremental Development
+
+Perfect for daily development work:
+
+```bash
+# Focus on changed files only (fastest)
+node cli.js --all --changed-files --max-semantic-files=300 --format=summary
+
+# Target specific modules  
+node cli.js --all --input=src/auth --max-semantic-files=1000 --format=summary
+node cli.js --all --input=src/api --max-semantic-files=1000 --format=summary
+
+# Use file patterns to focus on critical code
+node cli.js --all --include="src/**/*.ts" --exclude="**/*.test.*" --max-semantic-files=1500
+```
+
+### Strategy 2: CI/CD Pipeline Optimization
+
+Optimize for different CI stages:
+
+```bash
+# PR checks: Fast semantic analysis
+node cli.js --all --changed-files --max-semantic-files=300 --format=github --no-ai
+
+# Nightly builds: Medium coverage  
+node cli.js --all --input=. --max-semantic-files=1000 --format=json --output=nightly.json
+
+# Weekly reports: Comprehensive analysis
+node cli.js --all --input=. --max-semantic-files=-1 --format=detailed --output=weekly.json
+
+# Release validation: Full coverage with baseline
+node cli.js --all --input=. --max-semantic-files=2000 --baseline=last-release.json
+```
+
+### Strategy 3: Rule-Based Prioritization
+
+Different limits for different rule types:
+
+```bash
+# Phase 1: Critical security (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: Monorepo Management
+
+For large monorepos with multiple packages:
+
+```bash
+# Analyze each package separately
+for package in packages/*/; do
+  node cli.js --all --input="$package" --max-semantic-files=1000 \
+    --format=json --output="${package//\//-}-report.json"
+done
+
+# Focus on core packages first
+node cli.js --all --input=packages/core --max-semantic-files=2000 --format=summary
+node cli.js --all --input=packages/api --max-semantic-files=1500 --format=summary
+node cli.js --all --input=packages/ui --max-semantic-files=1000 --format=summary
+
+# Changed files across the entire monorepo
+node cli.js --all --changed-files --max-semantic-files=500 --format=summary
+```
+
+## 📈 Performance Monitoring
+
+### Memory & Time Tracking
+
+```bash
+# Monitor 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
+
+# Debug file loading behavior
+node cli.js --all --input=. --max-semantic-files=1000 --verbose --debug
+```
+
+### Coverage Analysis
+
+Check what percentage of your project is being analyzed:
+
+```bash
+# Show file loading statistics
+node cli.js --all --input=. --max-semantic-files=1000 --verbose --format=summary
+
+# Compare different limits
+node cli.js --all --input=. --max-semantic-files=500 --verbose --dry-run
+node cli.js --all --input=. --max-semantic-files=1000 --verbose --dry-run
+node cli.js --all --input=. --max-semantic-files=-1 --verbose --dry-run
+```
+
+## 🎛️ Configuration Files
+
+### sunlint.config.json
+
+Create a configuration file for consistent settings:
+
+```json
+{
+  "performance": {
+    "maxSemanticFiles": 1000,
+    "maxConcurrentRules": 5,
+    "timeoutMs": 30000
+  },
+  "input": ["src", "lib"],
+  "exclude": [
+    "**/*.test.*",
+    "**/*.d.ts", 
+    "**/generated/**"
+  ],
+  "output": {
+    "format": "summary"
+  },
+  "engines": {
+    "semantic": {
+      "enabled": true,
+      "fileLimit": 1000
+    }
+  }
+}
+```
+
+### Environment-Specific Configs
+
+Different configs for different environments:
+
+```bash
+# Development (fast feedback)
+cp config/sunlint.dev.json sunlint.config.json
+node cli.js --all --input=.
+
+# CI (balanced coverage)  
+cp config/sunlint.ci.json sunlint.config.json
+node cli.js --all --changed-files
+
+# Release (comprehensive)
+cp config/sunlint.release.json sunlint.config.json  
+node cli.js --all --input=.
+```
+
+## 💡 Best Practices
+
+### 1. Start Conservative, Scale Up
+
+```bash
+# Begin with conservative limits
+node cli.js --all --input=. --max-semantic-files=500 --format=summary
+
+# Gradually increase if performance allows
+node cli.js --all --input=. --max-semantic-files=1000 --format=summary
+node cli.js --all --input=. --max-semantic-files=1500 --format=summary
+```
+
+### 2. Use Different Limits for Different Contexts
+
+```bash
+# Daily development: Focus on changed files
+alias sunlint-dev="node cli.js --all --changed-files --max-semantic-files=300"
+
+# Code review: Medium coverage
+alias sunlint-review="node cli.js --all --changed-files --max-semantic-files=500"
+
+# Release preparation: Full coverage
+alias sunlint-release="node cli.js --all --input=. --max-semantic-files=-1"
+```
+
+### 3. Monitor and Adjust
+
+Track your analysis performance over time:
+
+```bash
+# Create performance baseline
+echo "Project size: $(find . -name '*.ts' -o -name '*.js' | wc -l) files"
+time node cli.js --all --input=. --max-semantic-files=1000 --format=summary
+
+# Adjust based on CI constraints
+if [[ $CI_MEMORY_LIMIT -lt 4096 ]]; then
+  SEMANTIC_LIMIT=500
+else
+  SEMANTIC_LIMIT=1000
+fi
+
+node cli.js --all --input=. --max-semantic-files=$SEMANTIC_LIMIT --format=summary
+```
+
+### 4. Combine with File Targeting
+
+Use semantic limits together with file patterns:
+
+```bash
+# Focus semantic analysis on source files only
+node cli.js --all --include="src/**/*.ts" --exclude="**/*.test.*" --max-semantic-files=1500
+
+# Analyze tests separately with lower limits
+node cli.js --all --include="**/*.test.*" --max-semantic-files=500
+
+# Target critical modules with higher limits
+node cli.js --all --input=src/security --max-semantic-files=2000
+node cli.js --all --input=src/api --max-semantic-files=1500
+```
+
+## 🔍 Troubleshooting
+
+### Memory Issues
+
+If you encounter out-of-memory errors:
+
+```bash
+# Reduce semantic file limit
+node cli.js --all --input=. --max-semantic-files=500
+
+# Disable semantic analysis completely
+node cli.js --all --input=. --max-semantic-files=0
+
+# Reduce concurrent rules
+node cli.js --all --input=. --max-semantic-files=1000 --max-concurrent=2
+```
+
+### Slow Analysis
+
+If analysis takes too long:
+
+```bash
+# Use incremental analysis
+node cli.js --all --changed-files --max-semantic-files=300
+
+# Focus on specific directories
+node cli.js --all --input=src/critical --max-semantic-files=1000
+
+# Use timeout limits
+node cli.js --all --input=. --max-semantic-files=1000 --timeout=60000
+```
+
+### Missed Violations
+
+If you suspect violations are being missed:
+
+```bash
+# Run comprehensive analysis periodically
+node cli.js --all --input=. --max-semantic-files=-1 --format=detailed
+
+# Compare different limits
+node cli.js --all --input=. --max-semantic-files=1000 --output=report-1k.json
+node cli.js --all --input=. --max-semantic-files=-1 --output=report-full.json
+diff report-1k.json report-full.json
+```
+
+## 📚 Related Documentation
+
+- [Command Examples](./COMMAND-EXAMPLES.md) - Complete CLI usage examples
+- [Configuration Guide](./CONFIGURATION.md) - Detailed configuration options
+- [CI/CD Guide](./CI-CD-GUIDE.md) - Integration with CI/CD pipelines
+- [Architecture](./ARCHITECTURE.md) - Technical implementation details
+
+---
+
+**💡 Pro Tip**: For projects with 2000+ files, consider breaking analysis into modules and running them in parallel, rather than analyzing everything at once.

package/engines/heuristic-engine.js

@@ -25,7 +25,8 @@ class HeuristicEngine extends AnalysisEngineInterface {
     this.astRegistry = ASTModuleRegistry;
     
     // ts-morph as core technology for heuristic engine
-    this.semanticEngine = new SemanticEngine();
+    // Note: semantic engine will be initialized in initialize() with proper config
+    this.semanticEngine = null;
     this.semanticRules = new Map();
     this.symbolTableEnabled = false;
     
@@ -55,8 +56,13 @@ class HeuristicEngine extends AnalysisEngineInterface {
       // Initialize rule adapter
       await this.ruleAdapter.initialize();
       
-      // Load available rules from unified registry
-      await this.loadRulesFromRegistry(config);
+      // Load available rules from unified registry (OPTIMIZED: skip for performance)
+      // Rules will be loaded on-demand in analyze() method 
+      if (config.loadAllRules) {
+        await this.loadRulesFromRegistry(config);
+      } else if (this.verbose) {
+        console.log(`⚡ [HeuristicEngine] Skipping bulk rule loading for performance - will load on-demand`);
+      }
       
       this.initialized = true;
       if (this.verbose) {
@@ -74,13 +80,25 @@ class HeuristicEngine extends AnalysisEngineInterface {
 
   /**
    * Initialize ts-morph Symbol Table as core requirement
+   * OPTIMIZED: Use targeted files instead of entire project for better performance
    */
   async initializeSymbolTable(config) {
     const projectPath = config?.projectPath || process.cwd();
     
     try {
-      // ts-morph is now a core dependency
-      const success = await this.semanticEngine.initialize(projectPath);
+      // Initialize semantic engine with config options including maxSemanticFiles
+      const semanticOptions = {
+        maxSemanticFiles: config?.maxSemanticFiles,
+        verbose: this.verbose,
+        ...config?.semanticOptions
+      };
+      
+      this.semanticEngine = new SemanticEngine(semanticOptions);
+      // Pass verbose option to semantic engine
+      this.semanticEngine.verbose = this.verbose;
+      
+      // ts-morph is now a core dependency - but optimized for targeted files
+      const success = await this.semanticEngine.initialize(projectPath, config?.targetFiles);
       
       if (success) {
         this.semanticEnabled = true;
@@ -276,6 +294,43 @@ class HeuristicEngine extends AnalysisEngineInterface {
     }
   }
 
+  /**
+   * Lazy load a single rule on-demand
+   * @param {string} ruleId - Rule ID to load
+   * @param {Object} options - Loading options
+   */
+  async lazyLoadRule(ruleId, options = {}) {
+    try {
+      const ruleDefinition = this.unifiedRegistry.getRuleDefinition(ruleId);
+      
+      if (!ruleDefinition) {
+        if (options.verbose) {
+          console.warn(`⚠️ [HeuristicEngine] Rule definition not found for ${ruleId}`);
+        }
+        return;
+      }
+
+      // Check if rule supports heuristic engine
+      if (!this.unifiedRegistry.isRuleSupported(ruleId, 'heuristic')) {
+        if (options.verbose) {
+          console.warn(`⚠️ [HeuristicEngine] Rule ${ruleId} not supported by heuristic engine`);
+        }
+        return;
+      }
+
+      if (options.verbose) {
+        console.log(`🔄 [HeuristicEngine] Lazy loading rule ${ruleId}...`);
+      }
+
+      await this.loadRuleFromDefinition(ruleDefinition);
+      
+    } catch (error) {
+      if (options.verbose) {
+        console.warn(`⚠️ [HeuristicEngine] Failed to lazy load rule ${ruleId}:`, error.message);
+      }
+    }
+  }
+
   /**
    * Manually load C047 semantic rule (special case)
    */
@@ -407,23 +462,23 @@ class HeuristicEngine extends AnalysisEngineInterface {
   }
 
   /**
-   * Register semantic rule
+   * Register semantic rule (lazy initialization)
    */
   async registerSemanticRule(ruleId, analyzerClass, metadata) {
     try {
-      const instance = new analyzerClass(ruleId);
-      instance.initialize(this.semanticEngine);
-      
+      // Store rule class and metadata for lazy initialization
       this.semanticRules.set(ruleId, {
-        instance,
+        analyzerClass,
         metadata,
-        type: 'semantic'
+        type: 'semantic',
+        initialized: false,
+        instance: null
       });
       
       this.supportedRulesList.push(ruleId);
       
       if (this.verbose) {
-        console.log(`🧠 Registered semantic rule: ${ruleId}`);
+        console.log(`🧠 Registered semantic rule: ${ruleId} (lazy initialization)`);
       }
       
     } catch (error) {
@@ -431,6 +486,34 @@ class HeuristicEngine extends AnalysisEngineInterface {
     }
   }
 
+  /**
+   * Initialize semantic rule on-demand
+   */
+  async initializeSemanticRule(ruleId) {
+    const ruleEntry = this.semanticRules.get(ruleId);
+    if (!ruleEntry || ruleEntry.initialized) {
+      return ruleEntry?.instance;
+    }
+
+    try {
+      const instance = new ruleEntry.analyzerClass(ruleId);
+      instance.initialize(this.semanticEngine, { verbose: this.verbose });
+      
+      // Update entry with initialized instance
+      ruleEntry.instance = instance;
+      ruleEntry.initialized = true;
+      
+      if (this.verbose) {
+        console.log(`🔧 Rule ${ruleId} initialized with semantic analysis`);
+      }
+      
+      return instance;
+    } catch (error) {
+      console.warn(`⚠️ Failed to initialize semantic rule ${ruleId}:`, error.message);
+      return null;
+    }
+  }
+
   /**
    * Register traditional (heuristic/AST/regex) rule
    */
@@ -563,6 +646,14 @@ class HeuristicEngine extends AnalysisEngineInterface {
         await this.manuallyLoadC047();
       }
       
+      // Lazy load rule if not already loaded
+      if (!this.isRuleSupported(rule.id)) {
+        if (options.verbose) {
+          console.log(`🔄 [HeuristicEngine] Lazy loading rule ${rule.id}...`);
+        }
+        await this.lazyLoadRule(rule.id, options);
+      }
+      
       if (!this.isRuleSupported(rule.id)) {
         if (options.verbose) {
           console.warn(`⚠️ Rule ${rule.id} not supported by Heuristic engine, skipping...`);
@@ -629,7 +720,13 @@ class HeuristicEngine extends AnalysisEngineInterface {
     }
 
     try {
-      const ruleInstance = semanticRuleInfo.instance;
+      // Initialize rule on-demand (lazy initialization)
+      const ruleInstance = await this.initializeSemanticRule(rule.id);
+      if (!ruleInstance) {
+        console.warn(`⚠️ Failed to initialize semantic rule ${rule.id}`);
+        return [];
+      }
+
       const allViolations = [];
 
       // Run semantic analysis for each file
@@ -677,6 +774,15 @@ class HeuristicEngine extends AnalysisEngineInterface {
   async analyzeRule(rule, filesByLanguage, options) {
     // Get full rule ID (C029 -> C029_catch_block_logging)
     const fullRuleId = this.getFullRuleId(rule.id);
+    
+    // Lazy load rule if not already loaded
+    if (!this.ruleAnalyzers.has(fullRuleId)) {
+      if (options.verbose) {
+        console.log(`🔄 [HeuristicEngine] Lazy loading rule ${rule.id} for analysis...`);
+      }
+      await this.lazyLoadRule(rule.id, options);
+    }
+    
     const analyzerInfo = this.ruleAnalyzers.get(fullRuleId);
     
     if (!analyzerInfo) {
@@ -691,13 +797,26 @@ class HeuristicEngine extends AnalysisEngineInterface {
         // Create analyzer instance from class
         const AnalyzerClass = analyzerInfo.class;
         try {
-          analyzer = new AnalyzerClass({ verbose: options.verbose });
+          analyzer = new AnalyzerClass({ 
+            verbose: options.verbose,
+            semanticEngine: this.semanticEngine 
+          });
+          
+          // Initialize with semantic engine if method exists
+          if (analyzer.initialize && typeof analyzer.initialize === 'function') {
+            await analyzer.initialize(this.semanticEngine);
+          }
         } catch (constructorError) {
           throw new Error(`Failed to instantiate analyzer class: ${constructorError.message}`);
         }
       } else if (analyzerInfo.type === 'instance') {
         // Use existing analyzer instance
         analyzer = analyzerInfo.instance;
+        
+        // Initialize existing instance with semantic engine if method exists
+        if (analyzer.initialize && typeof analyzer.initialize === 'function') {
+          await analyzer.initialize(this.semanticEngine);
+        }
       } else {
         throw new Error(`Unknown analyzer type: ${analyzerInfo.type}`);
       }
@@ -730,7 +849,7 @@ class HeuristicEngine extends AnalysisEngineInterface {
             rule.id,
             languageFiles, 
             language, 
-            { ...ruleConfig, ...options }
+            { ...ruleConfig, ...options, semanticEngine: this.semanticEngine }
           );
 
           allViolations.push(...languageViolations);
@@ -1303,4 +1422,4 @@ class HeuristicEngine extends AnalysisEngineInterface {
   }
 }
 
-module.exports = HeuristicEngine;
+module.exports = HeuristicEngine;

package/integrations/eslint/plugin/index.js

@@ -22,7 +22,6 @@ const c043 = require("./rules/common/c043-no-console-or-print.js");
 const c047 = require("./rules/common/c047-no-duplicate-retry-logic.js");
 const c072 = require("./rules/common/c072-one-assert-per-test.js");
 const c075 = require("./rules/common/c075-explicit-function-return-types.js");
-const c076 = require("./rules/common/c076-single-behavior-per-test.js");
 
 // 📘 TypeScript Rules (T-series)
 const t002 = require("./rules/typescript/t002-interface-prefix-i.js");
@@ -103,7 +102,6 @@ module.exports = {
     "c047-no-duplicate-retry-logic": c047,
     "c072-one-assert-per-test": c072,
     "c075-explicit-function-return-types": c075,
-    "c076-single-behavior-per-test": c076,
     "t002-interface-prefix-i": t002,
     "t003-ts-ignore-reason": t003,
     "t004-no-empty-type": t004,

package/integrations/eslint/plugin/rules/common/c003-no-vague-abbreviations.js

@@ -92,6 +92,59 @@ const c003Rule = {
       return false;
     }
 
+    function isMathContext(node, name) {
+      // Check for math variable patterns
+      const mathPatterns = [
+        // Coordinate pairs: x1, y1, x2, y2
+        /^[xyz][12]$/i,
+        // Delta notation: dx, dy, dt, dr
+        /^d[xyztr]$/i,
+        // Math constants: a, b, c in equations
+        /^[abc]$/i,
+        // Vector components: vx, vy, vz
+        /^v[xyz]$/i,
+        // Position/point notation: p1, p2
+        /^p\d+$/i
+      ];
+      
+      if (mathPatterns.some(pattern => pattern.test(name))) {
+        return true;
+      }
+      
+      // Check if we're in a math function context
+      let parent = node.parent;
+      while (parent) {
+        if (parent.type === 'FunctionDeclaration' || parent.type === 'FunctionExpression' || parent.type === 'ArrowFunctionExpression') {
+          const functionName = parent.id && parent.id.name;
+          if (functionName && /^(distance|calculate|compute|solve|formula|algorithm|equation|math)/i.test(functionName)) {
+            return true;
+          }
+          break; // Don't check beyond the immediate function
+        }
+        parent = parent.parent;
+      }
+      
+      // Check if we're in a context with Math operations
+      let currentNode = node.parent;
+      while (currentNode) {
+        if (currentNode.type === 'CallExpression') {
+          const callee = currentNode.callee;
+          if (callee && callee.object && callee.object.name === 'Math') {
+            return true;
+          }
+          if (callee && callee.name && /^(sqrt|pow|abs|sin|cos|tan|distance|calculate)$/i.test(callee.name)) {
+            return true;
+          }
+        }
+        if (currentNode.type === 'BinaryExpression' && ['+', '-', '*', '/'].includes(currentNode.operator)) {
+          return true;
+        }
+        currentNode = currentNode.parent;
+      }
+      
+      return false;
+    }
+
     function checkVariableName(node, name) {
       // Safety checks
       if (!node || !name || typeof name !== 'string') {
@@ -112,7 +165,7 @@ const c003Rule = {
 
       // Single character check
       if (name.length === 1) {
-        if (!allowedSingleChar.has(name.toLowerCase()) && !isCounterContext(node)) {
+        if (!allowedSingleChar.has(name.toLowerCase()) && !isCounterContext(node) && !isMathContext(node, name)) {
           context.report({
             node,
             messageId: "singleChar",
@@ -137,6 +190,11 @@ const c003Rule = {
         return;
       }
 
+      // Check for math context before flagging as unclear
+      if (isMathContext(node, name)) {
+        return;
+      }
+
       // Check for unclear/generic names
       if (unclearNames.has(name.toLowerCase())) {
         context.report({