@sun-asterisk/sunlint 1.3.0 → 1.3.1

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,118 @@ class SemanticEngine {
         // Performance settings for large codebases
         resolutionHost: undefined,          // Disable resolution host
         libFolderPath: undefined,           // Don't load TypeScript libs
-      });
+      };
+      
+      // Only use tsconfig when auto-discovering files (no targetFiles)
+      if (!targetFiles && tsConfigPath) {
+        projectOptions.tsConfigFilePath = tsConfigPath;
+      }
+      
+      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(', ')}`);
+        }
+      }
       
-      // 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));
+      // 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 {
-        this.project.addSourceFilesAtPaths(sourceFiles);
+        // 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}%`);
+      }
+      
+      // 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 {
+        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 +297,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 +307,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 +322,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 +330,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 +351,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 +360,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),

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

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.