@sun-asterisk/sunlint 1.3.0 → 1.3.2

package/config/rules/rules-registry-generated.json

@@ -441,7 +441,7 @@
     },
     "C019": {
       "name": "Do not use `error` log level for non-critical issues",
-      "description": "Avoid noisy logs and false alarms; ensure meaningful log levels.",
+      "description": "Prevent noisy logs and false alarms; ensure consistent and meaningful log levels across the system.",
       "category": "Common",
       "severity": "major",
       "languages": [
@@ -914,7 +914,7 @@
     },
     "C039": {
       "name": "Do not store temporary data in global or static mutable fields",
-      "description": "No description available",
+      "description": "Prevent issues related to shared state and race conditions in concurrent environments. Ensure thread-safety and testability. Using global or static mutable fields can introduce hard-to-detect and hard-to-fix bugs.",
       "category": "Common",
       "severity": "major",
       "languages": [
@@ -937,7 +937,7 @@
     },
     "C040": {
       "name": "Do not spread validation logic across multiple classes",
-      "description": "No description available",
+      "description": "Centralize validation logic to simplify maintenance, increase reusability, and ensure consistency. Centralized validation helps reduce bugs and simplifies updating validation rules.",
       "category": "Common",
       "severity": "major",
       "languages": [

package/core/cli-action-handler.js

@@ -109,21 +109,29 @@ class CliActionHandler {
   }
 
   /**
-   * Run analysis with modern orchestrator
-   * Following Rule C006: Verb-noun naming
-   * Following Rule C012: Command Query Separation - analysis is a command
+   * Run analysis using modern orchestrator
    */
   async runModernAnalysis(rulesToRun, files, config) {
     if (this.isModernMode) {
       console.log(chalk.blue('🚀 Using modern engine architecture'));
       
-      // Initialize orchestrator with configuration
+      // Initialize orchestrator with configuration including targetFiles for optimization
       await this.orchestrator.initialize({
         enabledEngines: this.determineEnabledEngines(config),
         aiConfig: config.ai || {},
         eslintConfig: config.eslint || {},
-        heuristicConfig: config.heuristic || {}
+        heuristicConfig: { 
+          ...config.heuristic || {},
+          targetFiles: this.options.targetFiles,  // Pass filtered files for semantic optimization
+          maxSemanticFiles: this.options.maxSemanticFiles !== undefined ? parseInt(this.options.maxSemanticFiles) : 1000,  // Configurable semantic file limit
+          verbose: this.options.verbose  // Pass verbose for debugging
+        }
       });
+      
+      if (this.options.verbose) {
+        console.log(`🔧 Debug: maxSemanticFiles option = ${this.options.maxSemanticFiles}`);
+        console.log(`🔧 Debug: parsed maxSemanticFiles = ${this.options.maxSemanticFiles !== undefined ? parseInt(this.options.maxSemanticFiles) : 1000}`);
+      }
 
       // Run analysis with new orchestrator
       const results = await this.orchestrator.analyze(files, rulesToRun, {
@@ -136,21 +144,7 @@ class CliActionHandler {
           requestedEngine: this.options.engine
         }
       });
-
       return results;
-    } else {
-      console.log(chalk.yellow('🔄 Using legacy orchestrator'));
-      
-      // Ensure verbose/quiet flags are in config
-      const analysisConfig = {
-        ...config,
-        verbose: this.options.verbose,
-        quiet: this.options.quiet,
-        // Pass requested engine to enable strict engine mode (no fallback)
-        requestedEngine: this.options.engine
-      };
-      
-      return await this.orchestrator.runAnalysis(rulesToRun, this.options, analysisConfig);
     }
   }
 
@@ -268,6 +262,17 @@ class CliActionHandler {
    * Following Rule C031: Separate validation logic
    */
   validateInput(config) {
+    // Validate engine option if specified (check this first, always)
+    if (this.options.engine) {
+      const validEngines = ['eslint', 'heuristic', 'openai'];
+      if (!validEngines.includes(this.options.engine)) {
+        throw new Error(
+          chalk.red(`❌ Invalid engine: ${this.options.engine}\n`) +
+          chalk.gray(`Valid engines: ${validEngines.join(', ')}`)
+        );
+      }
+    }
+
     // Priority 1: CLI --input parameter (highest priority)
     if (this.options.input) {
       // Validate CLI input path exists
@@ -302,17 +307,6 @@ class CliActionHandler {
       }
       return;
     }
-
-    // Validate engine option if specified
-    if (this.options.engine) {
-      const validEngines = ['eslint', 'sunlint', 'heuristic'];
-      if (!validEngines.includes(this.options.engine)) {
-        throw new Error(
-          chalk.red(`❌ Invalid engine: ${this.options.engine}\n`) +
-          chalk.gray(`Valid engines: ${validEngines.join(', ')}`)
-        );
-      }
-    }
   }
 
   /**

package/core/cli-program.js

@@ -26,7 +26,7 @@ function createCliProgram() {
   // TypeScript specific options (Phase 1 focus)
   program
     .option('--typescript', 'Enable TypeScript-specific analysis')
-    .option('--typescript-engine <engine>', 'TypeScript analysis engine (eslint,sunlint,hybrid)', 'sunlint')
+    .option('--typescript-engine <engine>', 'TypeScript analysis engine (eslint,heuristic,hybrid)', 'heuristic')
     .option('--ensure-deps', 'Ensure ESLint dependencies are installed');
 
   // Input/Output options (v1.x: explicit --input required)
@@ -58,7 +58,7 @@ function createCliProgram() {
 
   // Advanced options
   program
-    .option('--engine <engine>', 'Force specific analysis engine (eslint,sunlint)', '')
+    .option('--engine <engine>', 'Force specific analysis engine (eslint,heuristic)', '')
     .option('--dry-run', 'Show what would be analyzed without running')
     .option('--verbose', 'Enable verbose logging')
     .option('--quiet', 'Suppress non-error output')
@@ -67,6 +67,7 @@ function createCliProgram() {
     .option('--no-ai', 'Force disable AI analysis (use heuristic only)')
     .option('--legacy', 'Use legacy analysis architecture')
     .option('--modern', 'Use modern plugin-based architecture (default)')
+    .option('--max-semantic-files <number>', 'Control semantic analysis scope: 0=disable, -1=unlimited, >0=limit (default: 1000)', '1000')
     .option('--list-engines', 'List available analysis engines');
 
   // ESLint Integration options
@@ -107,7 +108,7 @@ Version Strategy:
 Engine Configuration:
   $ sunlint --all --input=src                    # Use config engine setting
   $ sunlint --all --input=src --engine=eslint    # Force ESLint engine 
-  $ sunlint --all --input=src --engine=sunlint   # Force SunLint engine
+  $ sunlint --all --input=src --engine=heuristic # Force Heuristic engine
 
 CI/CD Integration:
   $ sunlint --all --changed-files --format=summary --no-ai
@@ -127,6 +128,13 @@ Advanced File Targeting:
   $ sunlint --languages=typescript,dart --include="src/**,packages/**" --input=.
   $ sunlint --all --only-source --exclude-tests --languages=typescript --input=.
 
+Large Project Optimization:
+  $ sunlint --all --input=. --max-semantic-files=500    # Conservative analysis
+  $ sunlint --all --input=. --max-semantic-files=2000   # Comprehensive analysis  
+  $ sunlint --all --input=. --max-semantic-files=-1     # Unlimited (all files)
+  $ sunlint --all --input=. --max-semantic-files=0      # Disable semantic analysis
+  $ sunlint --all --changed-files --max-semantic-files=300  # Fast CI analysis
+
 Sun* Engineering - Coding Standards Made Simple ☀️
 `);
 

package/core/config-merger.js

@@ -209,8 +209,35 @@ class ConfigMerger {
       // Add flexible patterns for input paths
       const expandedInclude = [...currentInclude];
       for (const inputPath of inputPaths) {
-        expandedInclude.push(inputPath + '/**');
-        expandedInclude.push('**/' + inputPath + '/**');
+        // Check if inputPath is a file or directory
+        const fs = require('fs');
+        const path = require('path');
+        
+        try {
+          const resolvedPath = path.resolve(inputPath);
+          if (fs.existsSync(resolvedPath)) {
+            const stat = fs.statSync(resolvedPath);
+            if (stat.isFile()) {
+              // For files, add the exact path
+              expandedInclude.push(inputPath);
+              expandedInclude.push('**/' + inputPath);
+            } else if (stat.isDirectory()) {
+              // For directories, add recursive patterns
+              expandedInclude.push(inputPath + '/**');
+              expandedInclude.push('**/' + inputPath + '/**');
+            }
+          } else {
+            // If path doesn't exist, assume it's a pattern and add both file and directory variants
+            expandedInclude.push(inputPath);
+            expandedInclude.push(inputPath + '/**');
+            expandedInclude.push('**/' + inputPath);
+            expandedInclude.push('**/' + inputPath + '/**');
+          }
+        } catch (error) {
+          // Fallback to original logic if file system check fails
+          expandedInclude.push(inputPath + '/**');
+          expandedInclude.push('**/' + inputPath + '/**');
+        }
       }
       result.include = expandedInclude;
       

package/core/enhanced-rules-registry.js

@@ -100,7 +100,9 @@ class EnhancedRulesRegistry {
       'C006': ['eslint', 'heuristic', 'openai'],
       'C007': ['eslint', 'heuristic', 'openai'],
       'C014': ['eslint', 'heuristic', 'openai'],
-      'C033': ['eslint', 'heuristic'],
+      'C018': ['heuristic', 'eslint'],
+      'C033': ['heuristic', 'eslint'],
+      'C035': ['heuristic', 'eslint'],
       'C040': ['eslint', 'heuristic'],
       
       // AI-enhanced rules (complex logic analysis)
@@ -109,7 +111,6 @@ class EnhancedRulesRegistry {
       'C015': ['openai', 'heuristic'],
       'C032': ['openai', 'heuristic'],
       'C034': ['openai', 'heuristic'],
-      'C035': ['openai', 'heuristic'],
       'C037': ['openai', 'heuristic', 'eslint'],
       'C038': ['openai', 'heuristic']
     };

package/core/semantic-engine.js

@@ -8,6 +8,7 @@
 
 const path = require('path');
 const fs = require('fs').promises;
+const { Project, SyntaxKind } = require('ts-morph');
 
 class SemanticEngine {
   constructor(options = {}) {
@@ -49,8 +50,9 @@ class SemanticEngine {
   /**
    * Initialize ts-morph project with optimized memory configuration
    * Designed for large projects (3000+ files, 800-1000 lines each)
+   * OPTIMIZED: Accept targetFiles parameter to avoid loading unnecessary files
    */
-  async initialize(projectPath) {
+  async initialize(projectPath, targetFiles = null) {
     try {
       // Load ts-morph conditionally
       const { Project } = await import('ts-morph');
@@ -59,8 +61,8 @@ class SemanticEngine {
       const tsConfigPath = await this.findTsConfig(projectPath);
       
       // Initialize project with memory-optimized settings
-      this.project = new Project({
-        tsConfigFilePath: tsConfigPath,
+      // When using targetFiles, skip tsconfig to avoid auto-discovery
+      const projectOptions = {
         compilerOptions: {
           ...this.options.compilerOptions,
           // Memory optimization flags
@@ -78,22 +80,122 @@ class SemanticEngine {
         // Performance settings for large codebases
         resolutionHost: undefined,          // Disable resolution host
         libFolderPath: undefined,           // Don't load TypeScript libs
-      });
+      };
+      
+      // NEVER use project tsconfig.json to avoid file resolution issues
+      // Instead, load files explicitly to ensure they can be found
+      if (this.options.verbose) {
+        console.log(`🔧 SemanticEngine: Skipping project tsconfig.json to avoid file resolution issues`);
+        if (tsConfigPath) {
+          console.log(`   📋 Found tsconfig: ${tsConfigPath} (ignored for better compatibility)`);
+        }
+      }
+      
+      this.project = new Project(projectOptions);
+      
+      // Use provided targetFiles if available, otherwise discover
+      const sourceFiles = targetFiles || await this.discoverTargetFiles(projectPath);
+      
+      // Filter to TypeScript/JavaScript files only for semantic analysis
+      const semanticFiles = sourceFiles.filter(filePath => 
+        /\.(ts|tsx|js|jsx)$/i.test(filePath)
+      );
+      
+      if (targetFiles) {
+        console.log(`🎯 Targeted files received: ${targetFiles.length} total, ${semanticFiles.length} TS/JS files`);
+        if (semanticFiles.length < 10) {
+          console.log(`   Files: ${semanticFiles.map(f => path.basename(f)).join(', ')}`);
+        }
+      }
+      
+      // Adaptive loading strategy based on project size and user preference
+      const userMaxFiles = this.options.maxSemanticFiles;
+      let maxFiles;
+      
+      if (userMaxFiles === -1) {
+        // Unlimited: Load all files
+        maxFiles = semanticFiles.length;
+        console.log(`🔧 Semantic Engine config: UNLIMITED analysis (all ${semanticFiles.length} files)`);
+      } else if (userMaxFiles === 0) {
+        // Disable semantic analysis
+        maxFiles = 0;
+        console.log(`🔧 Semantic Engine config: DISABLED semantic analysis (heuristic only)`);
+      } else if (userMaxFiles > 0) {
+        // User-specified limit
+        maxFiles = Math.min(userMaxFiles, semanticFiles.length);
+        console.log(`🔧 Semantic Engine config: USER limit ${maxFiles} files (requested: ${userMaxFiles})`);
+      } else {
+        // Auto-detect based on project size
+        maxFiles = semanticFiles.length > 1000 ? 1000 : semanticFiles.length;
+        console.log(`🔧 Semantic Engine config: AUTO limit ${maxFiles} files (project has ${semanticFiles.length} files)`);
+      }
+      
+      if (this.options.verbose) {
+        console.log(`🔧 Semantic Engine detailed config:`);
+        console.log(`   📊 maxSemanticFiles option: ${this.options.maxSemanticFiles}`);
+        console.log(`   📈 Total semantic files: ${semanticFiles.length}`);
+        console.log(`   🎯 Files to load: ${maxFiles}`);
+        console.log(`   📉 Coverage: ${maxFiles > 0 ? Math.round(maxFiles/semanticFiles.length*100) : 0}%`);
+      }
       
-      // Only add target files, not entire project
-      const sourceFiles = await this.discoverTargetFiles(projectPath);
-      if (sourceFiles.length > 100) {
-        console.warn(`⚠️  Large project detected (${sourceFiles.length} files) - limited analysis mode`);
-        // For large projects, only add first 50 files to avoid memory issues
-        this.project.addSourceFilesAtPaths(sourceFiles.slice(0, 50));
+      // Skip semantic analysis if disabled
+      if (maxFiles === 0) {
+        console.log(`⚠️  Semantic analysis DISABLED - using heuristic rules only`);
+        console.log(`💡 To enable semantic analysis, use --max-semantic-files=1000 (or higher)`);
+        this.initialized = true;
+        return true;
+      }
+      
+      if (semanticFiles.length > maxFiles && maxFiles !== semanticFiles.length) {
+        console.warn(`⚠️  Large semantic project detected (${semanticFiles.length} files)`);
+        console.warn(`⚠️  Loading ${maxFiles} files for memory optimization (${Math.round(maxFiles/semanticFiles.length*100)}% coverage)`);
+        if (userMaxFiles !== -1) {
+          console.warn(`⚠️  Use --max-semantic-files=-1 to analyze ALL files (unlimited)`);
+          console.warn(`⚠️  Use --max-semantic-files=${semanticFiles.length} to analyze exactly this project`);
+        }
+        
+        const filesToLoad = semanticFiles.slice(0, maxFiles);
+        
+        // Load files one by one to handle any parse errors gracefully
+        let successCount = 0;
+        let errorCount = 0;
+        
+        for (const filePath of filesToLoad) {
+          try {
+            if (require('fs').existsSync(filePath)) {
+              this.project.addSourceFileAtPath(filePath);
+              successCount++;
+            } else {
+              errorCount++;
+            }
+          } catch (error) {
+            if (this.options.verbose) {
+              console.warn(`❌ Failed to load: ${path.basename(filePath)} - ${error.message}`);
+            }
+            errorCount++;
+          }
+        }
+        
+        console.log(`📊 Semantic analysis: ${successCount} files loaded, ${errorCount} skipped`);
+        
       } else {
-        this.project.addSourceFilesAtPaths(sourceFiles);
+        console.log(`📊 Loading all ${semanticFiles.length} files for complete semantic analysis`);
+        // For projects within limits, load all files
+        this.project.addSourceFilesAtPaths(semanticFiles);
+      }
+      
+      // Debug what ts-morph actually loaded
+      const actualFiles = this.project.getSourceFiles();
+      console.log(`📊 ts-morph loaded: ${actualFiles.length} files (expected: ${semanticFiles.length})`);
+      if (actualFiles.length > semanticFiles.length * 2) {
+        console.warn(`⚠️  ts-morph auto-discovered additional files (dependency resolution)`);
       }
       
       console.log(`🔧 Semantic Engine initialized (Memory Optimized):`);
       console.log(`   📁 Project: ${projectPath}`);
       console.log(`   📋 TS Config: ${tsConfigPath || 'default (minimal)'}`);
       console.log(`   📄 Files loaded: ${this.project.getSourceFiles().length}`);
+      console.log(`   🎯 Targeting mode: ${targetFiles ? 'Filtered files' : 'Auto-discovery'}`);
       console.log(`   💾 Memory mode: Optimized for large projects`);
       
       this.initialized = true;
@@ -199,7 +301,7 @@ class SemanticEngine {
       const namedImports = importDecl.getNamedImports().map(namedImport => ({
         name: namedImport.getName(),
         alias: namedImport.getAliasNode()?.getText(),
-        line: namedImport.getStartLineNumber()
+        line: sourceFile.getLineAndColumnAtPos(namedImport.getStart()).line
       }));
       
       // Default import
@@ -209,7 +311,7 @@ class SemanticEngine {
         module: moduleSpecifier,
         defaultImport: defaultImport?.getText(),
         namedImports,
-        line: importDecl.getStartLineNumber(),
+        line: sourceFile.getLineAndColumnAtPos(importDecl.getStart()).line,
         isTypeOnly: importDecl.isTypeOnly(),
         resolvedPath: this.resolveModule(moduleSpecifier, sourceFile)
       });
@@ -224,7 +326,7 @@ class SemanticEngine {
   extractFunctionCalls(sourceFile) {
     const calls = [];
     
-    sourceFile.getDescendantsOfKind(sourceFile.getKindName().CallExpression || 210).forEach(callExpr => {
+    sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression).forEach(callExpr => {
       const expression = callExpr.getExpression();
       
       calls.push({
@@ -232,10 +334,10 @@ class SemanticEngine {
         arguments: callExpr.getArguments().map(arg => ({
           text: arg.getText(),
           type: this.getExpressionType(arg),
-          line: arg.getStartLineNumber()
+          line: sourceFile.getLineAndColumnAtPos(arg.getStart()).line
         })),
-        line: callExpr.getStartLineNumber(),
-        column: callExpr.getStartColumnNumber(),
+        line: sourceFile.getLineAndColumnAtPos(callExpr.getStart()).line,
+        column: sourceFile.getLineAndColumnAtPos(callExpr.getStart()).column,
         
         // Detailed analysis for retry patterns
         isRetryPattern: this.isRetryPattern(callExpr),
@@ -253,7 +355,7 @@ class SemanticEngine {
   extractHooks(sourceFile) {
     const hooks = [];
     
-    sourceFile.getDescendantsOfKind(sourceFile.getKindName().CallExpression || 210).forEach(callExpr => {
+    sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression).forEach(callExpr => {
       const expression = callExpr.getExpression();
       const functionName = expression.getText();
       
@@ -262,7 +364,7 @@ class SemanticEngine {
         hooks.push({
           hookName: functionName,
           arguments: callExpr.getArguments().map(arg => arg.getText()),
-          line: callExpr.getStartLineNumber(),
+          line: sourceFile.getLineAndColumnAtPos(callExpr.getStart()).line,
           
           // Special analysis for useQuery, useMutation, etc.
           isQueryHook: this.isQueryHook(functionName),
@@ -555,6 +657,14 @@ class SemanticEngine {
   getParentContext(callExpr) { return null; }
   isKnownHook(functionName) { return false; }
   findSymbolUsages(sourceFile, namedImports) { return []; }
+
+  /**
+   * Check if symbol engine is ready for symbol-based analysis
+   * @returns {boolean} true if project is initialized and ready
+   */
+  isSymbolEngineReady() {
+    return this.initialized && this.project !== null;
+  }
 }
 
 module.exports = SemanticEngine;

package/core/semantic-rule-base.js

@@ -41,14 +41,16 @@ class SemanticRuleBase {
   /**
    * Initialize rule with SemanticEngine instance
    */
-  initialize(semanticEngine) {
+  initialize(semanticEngine, options = {}) {
     this.semanticEngine = semanticEngine;
     
     if (!this.semanticEngine || !this.semanticEngine.initialized) {
       throw new Error(`${this.ruleId}: SemanticEngine is required and must be initialized`);
     }
     
-    console.log(`🔧 Rule ${this.ruleId} initialized with semantic analysis`);
+    if (options?.verbose) {
+      console.log(`🔧 Rule ${this.ruleId} initialized with semantic analysis`);
+    }
   }
 
   /**

package/core/unified-rule-registry.js

@@ -481,4 +481,4 @@ module.exports = {
     }
     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