@sun-asterisk/sunlint 1.3.1 → 1.3.2

package/CONTRIBUTING.md

@@ -1,113 +1,78 @@
-# Contributing to Sun Lint
+# Contributing to SunLint - Rule Development Guide
 
-Thank you for your interest in contributing to Sun Lint! 🌟
+## 🎯 Quick Start for Rule Development
 
-## 🚀 **Getting Started**
+This guide focuses on developing new rules for SunLint. Based on practical experience from refactoring rules like C013, C035, we recommend a **symbol-based only** approach for maximum accuracy.
 
-### **Prerequisites**
-- Node.js 16+ 
-- npm 8+
-- Git
+## 📋 Rule Development Steps
 
-### **Setup Development Environment**
+### Step 1: Register Rule in Registry
 
-```bash
-# Clone the repository
-git clone https://github.com/sun-engineering/sunlint.git
-cd sunlint
-
-# Install dependencies
-npm install
-
-# Run tests
-npm test
+Add your rule to `config/rules/enhanced-rules-registry.json`:
 
-# Try the CLI locally
-node cli.js --help
+```json
+{
+  "rules": {
+    "C010": {
+      "name": "Limit Block Nesting",
+      "description": "Limit nested blocks (if/for/while/switch) to maximum 3 levels for readability",
+      "category": "complexity",
+      "severity": "warning",
+      "languages": ["typescript", "javascript", "dart", "kotlin"],
+      "analyzer": "./rules/common/C010_limit_block_nesting/analyzer.js",
+      "config": "./rules/common/C010_limit_block_nesting/config.json",
+      "version": "1.0.0",
+      "status": "stable",
+      "tags": ["complexity", "readability", "nesting", "maintainability"],
+      "strategy": {
+        "preferred": "ast",
+        "fallbacks": ["ast"],
+        "accuracy": {
+          "ast": 95
+        }
+      },
+      "engineMappings": {
+        "eslint": ["complexity", "max-depth"]
+      }
+    }
+  }
+}
 ```
 
-## 📋 **Coding Standards**
+**Key Registry Fields:**
+- `analyzer`: Path to main analyzer file
+- `strategy.preferred`: Use "ast" for symbol-based analysis
+- `strategy.fallbacks`: Recommend ["ast"] only for accuracy
+- `strategy.accuracy`: Expected accuracy percentage
 
-When contributing to Sun Lint, please follow these coding rules:
-
-### **Code Quality Rules**
-- **Rule C005** – Each function should do one thing only
-- **Rule C006** – Function names must be verb/verb-noun
-- **Rule C007** – Avoid comments that just describe the code
-- **Rule C012** – Separate Command and Query operations (CQS principle)
-- **Rule C014** – Use Dependency Injection instead of direct instantiation
-- **Rule C015** – Use domain language in class/function names
-- **Rule C019** – Don't use `error` log level for non-critical errors
-- **Rule C031** – Keep validation logic separate
-- **Rule C032** – Don't call external APIs in constructors or static blocks
-- **Rule C033** – Separate processing logic and data queries in service layer
-- **Rule C034** – Limit direct access to global state in domain logic
-- **Rule C035** – When handling errors, log complete relevant information
-- **Rule C037** – API handlers should return standard response objects (not raw strings)
-- **Rule C038** – Avoid logic depending on file/module loading order
-- **Rule C040** – Don't scatter validation logic across multiple classes
-
-## 🔧 **Development Workflow**
-
-### **SunLint Architecture Overview**
-
-SunLint uses a **multi-engine architecture** with rule mapping system:
-
-- **Heuristic Engine**: Pattern-based analysis using AST (Abstract Syntax Tree)
-- **ESLint Engine**: JavaScript/TypeScript linting using ESLint rules  
-- **OpenAI Engine**: AI-powered code analysis
-
-**Rule Configuration Files:**
-- `rules/` - Unified rule registry (auto-generated from origin-rules)
-- `config/eslint-rule-mapping.json` - ESLint engine rule mappings
-- `origin-rules/` - Original rule definitions (markdown format)
-
-### **Adding a New Rule (Modern Approach - 2025)**
-
-#### **Step 1: Choose Rule Implementation Strategy**
-
-**Modern Approach: Hybrid Symbol + Regex Analysis (Recommended)**
-Following the successful C035 pattern, implement rules with both symbol-based and regex-based analyzers for maximum accuracy and fallback coverage.
-
-#### **Step 2: Create Rule Directory Structure**
+### Step 2: Create Rule Directory Structure
 
 ```bash
-# Create rule directory
-mkdir -p rules/common/C042_no_hardcoded_config
+mkdir -p rules/common/C010_limit_block_nesting
+cd rules/common/C010_limit_block_nesting
 
-# Create required files
-touch rules/common/C042_no_hardcoded_config/analyzer.js
-touch rules/common/C042_no_hardcoded_config/symbol-based-analyzer.js
-touch rules/common/C042_no_hardcoded_config/regex-based-analyzer.js
-touch rules/common/C042_no_hardcoded_config/config.json
-touch rules/common/C042_no_hardcoded_config/STRATEGY.md
+# Required files
+touch analyzer.js           # Main orchestrator
+touch symbol-based-analyzer.js  # Core analysis logic
+touch config.json          # Rule configuration
 ```
 
-#### **Step 3: Implement Main Analyzer (Hybrid Orchestrator)**
+### Step 3: Implement Main Analyzer (analyzer.js)
 
 ```javascript
-// rules/common/C042_no_hardcoded_config/analyzer.js
-const C042SymbolBasedAnalyzer = require('./symbol-based-analyzer.js');
-const C042RegexBasedAnalyzer = require('./regex-based-analyzer.js');
+// rules/common/C010_limit_block_nesting/analyzer.js
+const C010SymbolBasedAnalyzer = require('./symbol-based-analyzer.js');
 
-class C042Analyzer {
+class C010Analyzer {
   constructor(semanticEngine = null) {
-    this.ruleId = 'C042';
-    this.ruleName = 'No Hardcoded Configuration Values';
-    this.description = 'Avoid hardcoding configuration values in business logic';
+    this.ruleId = 'C010';
+    this.ruleName = 'Limit Block Nesting';
+    this.description = 'Limit nested blocks to maximum 3 levels';
     this.semanticEngine = semanticEngine;
     this.verbose = false;
     
-    // Configuration
-    this.config = {
-      useSymbolBased: true,      // Primary approach
-      fallbackToRegex: true,     // Only when symbol fails completely
-      symbolBasedOnly: false     // Can be set to true for pure mode
-    };
-    
-    // Initialize both analyzers
-    this.symbolAnalyzer = new C042SymbolBasedAnalyzer(semanticEngine);
-    this.regexAnalyzer = new C042RegexBasedAnalyzer(semanticEngine);
+    // Use symbol-based only for accuracy
+    this.symbolAnalyzer = new C010SymbolBasedAnalyzer(semanticEngine);
   }
 
   async initialize(semanticEngine = null) {
@@ -115,82 +80,63 @@ class C042Analyzer {
       this.semanticEngine = semanticEngine;
     }
     this.verbose = semanticEngine?.verbose || false;
-    
-    // Initialize both analyzers
     await this.symbolAnalyzer.initialize(semanticEngine);
-    await this.regexAnalyzer.initialize(semanticEngine);
-    
-    if (this.verbose) {
-      console.log(`🔧 [C042 Hybrid] Analyzer initialized`);
-    }
   }
 
   async analyzeFileBasic(filePath, options = {}) {
     try {
-      // Try symbol-based analysis first
-      if (this.semanticEngine?.isSymbolEngineReady?.() && 
-          this.semanticEngine.project) {
-        
-        if (this.verbose) {
-          console.log(`🔍 [C042] Using symbol-based analysis for ${filePath}`);
-        }
-        
-        const violations = await this.symbolAnalyzer.analyzeFileBasic(filePath, options);
-        return violations;
+      // Check if symbol engine is ready
+      if (!this.semanticEngine?.isSymbolEngineReady?.() || !this.semanticEngine.project) {
+        throw new Error('Symbol engine not available');
+      }
+
+      if (this.verbose) {
+        console.log(`[DEBUG] 🎯 C010: Using symbol-based analysis for ${filePath.split('/').pop()}`);
+      }
+
+      const violations = await this.symbolAnalyzer.analyzeFileBasic(filePath, options);
+      
+      if (this.verbose) {
+        console.log(`[DEBUG] 🎯 C010: Symbol-based analysis found ${violations.length} violations`);
       }
+
+      return violations;
     } catch (error) {
       if (this.verbose) {
-        console.warn(`⚠️ [C042] Symbol analysis failed: ${error.message}`);
+        console.error(`[DEBUG] ❌ C010: Analysis failed: ${error.message}`);
       }
+      throw new Error(`C010 analysis failed: ${error.message}`);
     }
-    
-    // Fallback to regex-based analysis
-    if (this.verbose) {
-      console.log(`🔄 [C042] Using regex-based analysis (fallback) for ${filePath}`);
-    }
-    
-    return await this.regexAnalyzer.analyzeFileBasic(filePath, options);
   }
 
-  async analyze(files, language, options = {}) {
-    const violations = [];
-    
+  async analyzeFiles(files, options = {}) {
+    const allViolations = [];
     for (const filePath of files) {
       try {
-        const fileViolations = await this.analyzeFileBasic(filePath, options);
-        violations.push(...fileViolations);
+        const violations = await this.analyzeFileBasic(filePath, options);
+        allViolations.push(...violations);
       } catch (error) {
-        if (this.verbose) {
-          console.warn(`❌ [C042] Analysis failed for ${filePath}:`, error.message);
-        }
+        console.warn(`C010: Skipping ${filePath}: ${error.message}`);
       }
     }
-    
-    return violations;
+    return allViolations;
   }
 }
 
-module.exports = C042Analyzer;
+module.exports = C010Analyzer;
 ```
 
-#### **Step 4: Implement Symbol-Based Analyzer (Primary)**
+### Step 4: Implement Symbol-Based Analyzer
 
 ```javascript
-// rules/common/C042_no_hardcoded_config/symbol-based-analyzer.js
-class C042SymbolBasedAnalyzer {
+// rules/common/C010_limit_block_nesting/symbol-based-analyzer.js
+const { SyntaxKind } = require('ts-morph');
+
+class C010SymbolBasedAnalyzer {
   constructor(semanticEngine = null) {
-    this.ruleId = 'C042';
-    this.ruleName = 'No Hardcoded Configuration Values (Symbol-Based)';
     this.semanticEngine = semanticEngine;
+    this.maxNestingLevel = 3;
     this.verbose = false;
-    
-    // Configuration patterns to detect
-    this.configPatterns = [
-      /^API_/i, /^DATABASE_/i, /^DB_/i,
-      /^MAX_/i, /^MIN_/i, /^LIMIT_/i,
-      /^TIMEOUT/i, /^PORT$/i, /^HOST$/i,
-      /^SECRET/i, /^KEY$/i, /^TOKEN/i
-    ];
   }
 
   async initialize(semanticEngine = null) {
@@ -198,1626 +144,199 @@ class C042SymbolBasedAnalyzer {
       this.semanticEngine = semanticEngine;
     }
     this.verbose = semanticEngine?.verbose || false;
-    
-    if (this.verbose) {
-      console.log(`🔧 [C042 Symbol-Based] Analyzer initialized`);
-    }
   }
 
   async analyzeFileBasic(filePath, options = {}) {
     const violations = [];
     
-    if (!this.semanticEngine?.project) {
-      return violations;
-    }
-
     try {
-      const sourceFile = this.semanticEngine.project.getSourceFileByFilePath(filePath);
+      const sourceFile = this.semanticEngine.project.getSourceFile(filePath);
       if (!sourceFile) {
-        return violations;
+        throw new Error(`Source file not found: ${filePath}`);
+      }
+
+      if (this.verbose) {
+        console.log(`[DEBUG] 🔍 C010: Analyzing nesting in ${filePath.split('/').pop()}`);
       }
 
-      // Analyze variable declarations
-      const variableDeclarations = sourceFile.getVariableDeclarations();
-      for (const declaration of variableDeclarations) {
-        const violation = this.analyzeVariableDeclaration(declaration, filePath);
-        if (violation) {
-          violations.push(violation);
+      // Find nested blocks
+      const nestedBlocks = this.findNestedBlocks(sourceFile);
+      
+      for (const block of nestedBlocks) {
+        if (block.nestingLevel > this.maxNestingLevel) {
+          violations.push({
+            ruleId: 'C010',
+            message: `Nested block exceeds maximum depth of ${this.maxNestingLevel} (current: ${block.nestingLevel}). Consider extracting to separate functions.`,
+            filePath: filePath,
+            line: block.line,
+            column: block.column,
+            severity: 'warning',
+            category: 'complexity'
+          });
         }
       }
 
+      if (this.verbose) {
+        console.log(`[DEBUG] 🔍 C010: Found ${violations.length} nesting violations`);
+      }
+
       return violations;
     } catch (error) {
       if (this.verbose) {
-        console.warn(`⚠️ [C042 Symbol-Based] Analysis failed for ${filePath}:`, error.message);
+        console.error(`[DEBUG] ❌ C010: Symbol analysis error: ${error.message}`);
       }
-      return violations;
-    }
-  }
-
-  analyzeVariableDeclaration(declaration, filePath) {
-    const name = declaration.getName();
-    const initializer = declaration.getInitializer();
-    
-    // Check if variable name suggests configuration
-    if (!this.isConfigVariable(name)) {
-      return null;
-    }
-    
-    // Check if value is hardcoded
-    if (this.isHardcodedValue(initializer)) {
-      const startLineNumber = declaration.getStartLineNumber();
-      
-      return {
-        ruleId: this.ruleId,
-        severity: 'warning',
-        message: `Configuration variable '${name}' should not be hardcoded`,
-        source: this.ruleId,
-        file: filePath,
-        line: startLineNumber,
-        column: declaration.getStart() - declaration.getStartLinePos() + 1,
-        description: `Symbol-based analysis detected hardcoded configuration value. Use environment variables or config files.`,
-        suggestion: `Use process.env.${name} or load from configuration file`,
-        category: 'maintainability'
-      };
-    }
-    
-    return null;
-  }
-
-  isConfigVariable(name) {
-    return this.configPatterns.some(pattern => pattern.test(name));
-  }
-
-  isHardcodedValue(initializer) {
-    if (!initializer) return false;
-    
-    // Check for literal values (strings, numbers)
-    if (initializer.getKind() === ts.SyntaxKind.StringLiteral ||
-        initializer.getKind() === ts.SyntaxKind.NumericLiteral) {
-      return true;
-    }
-    
-    // Check for property access to process.env
-    if (initializer.getText().includes('process.env')) {
-      return false;
-    }
-    
-    return false;
-  }
-}
-
-module.exports = C042SymbolBasedAnalyzer;
-```
-
-#### **Step 5: Implement Regex-Based Analyzer (Fallback)**
-
-```javascript
-// rules/common/C042_no_hardcoded_config/regex-based-analyzer.js
-class C042RegexBasedAnalyzer {
-  constructor(semanticEngine = null) {
-    this.ruleId = 'C042';
-    this.ruleName = 'No Hardcoded Configuration Values (Regex-Based)';
-    this.semanticEngine = semanticEngine;
-    this.verbose = false;
-    
-    // Patterns for hardcoded config detection
-    this.hardcodedPatterns = [
-      /const\s+(API_\w+|DATABASE_\w+|DB_\w+)\s*=\s*["'][^"']+["']/gi,
-      /const\s+(MAX_\w+|MIN_\w+|LIMIT_\w+)\s*=\s*\d+/gi,
-      /const\s+(TIMEOUT|PORT|HOST)\s*=\s*["']\w+["']|\d+/gi
-    ];
-  }
-
-  async initialize(semanticEngine = null) {
-    if (semanticEngine) {
-      this.semanticEngine = semanticEngine;
-    }
-    this.verbose = semanticEngine?.verbose || false;
-    
-    if (this.verbose) {
-      console.log(`🔧 [C042 Regex-Based] Analyzer initialized`);
+      throw error;
     }
   }
 
-  async analyzeFileBasic(filePath, options = {}) {
-    const fs = require('fs');
-    const violations = [];
-    
-    if (!fs.existsSync(filePath)) {
-      return violations;
-    }
-
-    const content = fs.readFileSync(filePath, 'utf8');
-    const lines = content.split('\n');
+  findNestedBlocks(sourceFile) {
+    const blocks = [];
     
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      
-      for (const pattern of this.hardcodedPatterns) {
-        pattern.lastIndex = 0; // Reset regex
-        let match;
+    function traverse(node, currentDepth = 0) {
+      // Check for block statements that increase nesting
+      if (this.isNestingNode(node)) {
+        currentDepth++;
         
-        while ((match = pattern.exec(line)) !== null) {
-          // Skip if using process.env
-          if (line.includes('process.env')) {
-            continue;
-          }
-          
-          violations.push({
-            ruleId: this.ruleId,
-            severity: 'warning',
-            message: `Configuration variable '${match[1]}' should not be hardcoded`,
-            source: this.ruleId,
-            file: filePath,
-            line: i + 1,
-            column: match.index + 1,
-            description: `[REGEX-FALLBACK] Hardcoded configuration detected. Use environment variables or config files.`,
-            suggestion: `Use process.env.${match[1]} or load from configuration file`,
-            category: 'maintainability'
-          });
-        }
+        const position = sourceFile.getLineAndColumnAtPos(node.getStart());
+        blocks.push({
+          node: node,
+          nestingLevel: currentDepth,
+          line: position.line,
+          column: position.column
+        });
       }
+
+      // Traverse children
+      node.forEachChild(child => traverse.call(this, child, currentDepth));
     }
-    
-    return violations;
+
+    traverse.call(this, sourceFile, 0);
+    return blocks;
   }
 
-  async analyze(files, language, options = {}) {
-    const violations = [];
-    
-    for (const filePath of files) {
-      try {
-        const fileViolations = await this.analyzeFileBasic(filePath, options);
-        violations.push(...fileViolations);
-      } catch (error) {
-        if (this.verbose) {
-          console.warn(`❌ [C042 Regex] Analysis failed for ${filePath}:`, error.message);
-        }
-      }
-    }
-    
-    return violations;
+  isNestingNode(node) {
+    return [
+      SyntaxKind.IfStatement,
+      SyntaxKind.ForStatement,
+      SyntaxKind.ForInStatement,
+      SyntaxKind.ForOfStatement,
+      SyntaxKind.WhileStatement,
+      SyntaxKind.DoStatement,
+      SyntaxKind.SwitchStatement,
+      SyntaxKind.TryStatement,
+      SyntaxKind.CatchClause
+    ].includes(node.getKind());
   }
 }
 
-module.exports = C042RegexBasedAnalyzer;
+module.exports = C010SymbolBasedAnalyzer;
 ```
 
-#### **Step 6: Create Rule Configuration**
+### Step 5: Create Rule Configuration
 
 ```json
-// rules/common/C042_no_hardcoded_config/config.json
+// rules/common/C010_limit_block_nesting/config.json
 {
-  "ruleId": "C042",
-  "name": "No Hardcoded Configuration Values",
-  "description": "Avoid hardcoding configuration values in business logic",
-  "category": "maintainability",
-  "severity": "warning",
-  "languages": ["typescript", "javascript"],
-  "version": "1.0.0",
-  "tags": ["configuration", "maintainability", "environment"],
-  "patterns": {
-    "configVariables": [
-      "API_", "DATABASE_", "DB_", "MAX_", "MIN_", "LIMIT_", 
-      "TIMEOUT", "PORT", "HOST", "SECRET", "KEY", "TOKEN"
-    ],
-    "excludePatterns": [
-      "process.env", "config.", "getConfig(", "loadConfig("
-    ]
-  },
-  "examples": {
-    "bad": [
-      "const API_URL = 'https://api.example.com';",
-      "const MAX_RETRIES = 5;",
-      "const DATABASE_PASSWORD = 'secret123';"
-    ],
-    "good": [
-      "const API_URL = process.env.API_URL;",
-      "const MAX_RETRIES = parseInt(process.env.MAX_RETRIES || '3');",
-      "const config = loadConfigFromFile();"
-    ]
-  }
+  "maxNestingLevel": 3,
+  "excludePatterns": [
+    "**/*.test.js",
+    "**/*.spec.js"
+  ],
+  "includePatterns": [
+    "**/*.js",
+    "**/*.ts",
+    "**/*.jsx",
+    "**/*.tsx"
+  ]
 }
 ```
 
-#### **Step 7: Document Analysis Strategy**
-
-```markdown
-<!-- rules/common/C042_no_hardcoded_config/STRATEGY.md -->
-# C042 Analysis Strategy: No Hardcoded Configuration Values
-
-## Overview
-Hybrid approach using symbol-based analysis as primary with regex fallback.
-
-## Symbol-Based Analysis (Primary)
-- Uses ts-morph AST to analyze variable declarations
-- Detects configuration variable patterns by name
-- Checks initializer values for hardcoded literals
-- Excludes process.env and config function calls
-
-## Regex-Based Analysis (Fallback)
-- Pattern matching for common hardcoded config scenarios
-- Simpler but broader detection
-- Used when symbol analysis unavailable
-
-## Strategy Selection
-1. **Symbol-based**: When ts-morph project available (95% accuracy)
-2. **Regex-fallback**: When symbol analysis fails (80% accuracy)
-
-## Testing Approach
-Test both analyzers independently and verify hybrid orchestration.
-```
-
----
-
-## 🆕 **Modern Rule Implementation Guide (2025)**
+## 🚨 Common Pitfalls & Solutions
 
-Based on the successful C035 implementation, here's the **current recommended approach** for adding new rules:
-
-### **Critical Success Patterns**
-
-#### **✅ 1. Constructor Pattern (REQUIRED)**
+### 1. Symbol Engine Not Ready
 ```javascript
-// ✅ CORRECT - Works with semantic engine injection
-class C042Analyzer {
-  constructor(options = {}) {
-    this.semanticEngine = options.semanticEngine || null;
-    this.verbose = options.verbose || false;
-    // ...
-  }
-}
+// ❌ Wrong - Will fail if symbol engine not ready
+const violations = await this.symbolAnalyzer.analyzeFileBasic(filePath);
 
-// ❌ WRONG - Causes semantic engine injection failure
-class C042Analyzer {
-  constructor(semanticEngine = null) {
-    this.semanticEngine = semanticEngine;
-    // ...
-  }
+// ✅ Correct - Check engine availability
+if (!this.semanticEngine?.isSymbolEngineReady?.() || !this.semanticEngine.project) {
+  throw new Error('Symbol engine not available');
 }
 ```
 
-#### **✅ 2. Registry Configuration (REQUIRED)**
+### 2. Missing Source File Check
+```javascript
+// ❌ Wrong - Will crash if file not found
+const sourceFile = this.semanticEngine.project.getSourceFile(filePath);
 
-**Enhanced Rules Registry** (`config/rules/enhanced-rules-registry.json`):
-```json
-{
-  "C042": {
-    "name": "No Hardcoded Configuration Values",
-    "description": "Avoid hardcoding configuration values in business logic",
-    "category": "maintainability",
-    "severity": "warning",
-    "languages": ["typescript", "javascript", "dart", "kotlin"],
-    "analyzer": "./rules/common/C042_no_hardcoded_config/analyzer.js",
-    "config": "./rules/common/C042_no_hardcoded_config/config.json",
-    "version": "1.0.0",
-    "status": "stable",
-    "tags": ["configuration", "hardcoding", "maintainability"],
-    "engineMappings": {
-      "eslint": ["no-magic-numbers", "@typescript-eslint/no-magic-numbers"]
-    }
-  }
+// ✅ Correct - Always check source file existence
+const sourceFile = this.semanticEngine.project.getSourceFile(filePath);
+if (!sourceFile) {
+  throw new Error(`Source file not found: ${filePath}`);
 }
 ```
 
-**Rule Analysis Strategies** (`config/rule-analysis-strategies.js`):
+### 3. Improper Error Handling
 ```javascript
-module.exports = {
-  hybridOptimal: {
-    'C042': {
-      reason: 'Configuration detection requires symbol resolution + pattern matching',
-      methods: ['semantic', 'regex'],
-      strategy: 'semantic-primary-regex-fallback',
-      accuracy: { semantic: 90, regex: 75, combined: 95 }
-    }
-  }
+// ❌ Wrong - Silent failures
+try {
+  const violations = await this.analyzeFile(filePath);
+} catch (error) {
+  return [];
 }
-```
-
-#### **✅ 3. Hybrid Architecture Template**
-
-**Main Analyzer** (`analyzer.js`):
-```javascript
-const C042SymbolBasedAnalyzer = require('./symbol-based-analyzer.js');
-const C042RegexBasedAnalyzer = require('./regex-based-analyzer.js');
-
-class C042Analyzer {
-  constructor(options = {}) {
-    if (process.env.SUNLINT_DEBUG) {
-      console.log(`🔧 [C042] Constructor called with options:`, !!options);
-    }
-    
-    this.ruleId = 'C042';
-    this.semanticEngine = options.semanticEngine || null;
-    this.verbose = options.verbose || false;
-    
-    // Initialize analyzers with THIS.semanticEngine
-    this.symbolAnalyzer = new C042SymbolBasedAnalyzer(this.semanticEngine);
-    this.regexAnalyzer = new C042RegexBasedAnalyzer(this.semanticEngine);
-    
-    this.config = {
-      useSymbolBased: true,
-      fallbackToRegex: true,
-      symbolBasedOnly: false
-    };
-  }
-
-  async analyze(files, language = 'javascript', options = {}) {
-    const allViolations = [];
-    
-    for (const filePath of files) {
-      const violations = await this.analyzeFile(filePath, options);
-      allViolations.push(...violations);
-    }
-    
-    return allViolations;
-  }
 
-  async analyzeFile(filePath, options = {}) {
-    // 1. Try Symbol-based analysis first (primary)
-    if (this.config.useSymbolBased && 
-        this.semanticEngine?.project && 
-        this.semanticEngine?.initialized) {
-      try {
-        const sourceFile = this.semanticEngine.project.getSourceFile(filePath);
-        if (sourceFile) {
-          const violations = await this.symbolAnalyzer.analyzeFileWithSymbols(filePath, options);
-          violations.forEach(v => v.analysisStrategy = 'symbol-based');
-          return violations;
-        }
-      } catch (error) {
-        console.warn(`⚠️ [C042] Symbol analysis failed: ${error.message}`);
-      }
-    }
-    
-    // 2. Fallback to regex-based analysis
-    if (this.config.fallbackToRegex) {
-      const violations = await this.regexAnalyzer.analyzeFileBasic(filePath, options);
-      violations.forEach(v => v.analysisStrategy = 'regex-based');
-      return violations;
-    }
-    
-    return [];
+// ✅ Correct - Proper error propagation
+try {
+  const violations = await this.analyzeFile(filePath);
+  return violations;
+} catch (error) {
+  if (this.verbose) {
+    console.error(`Analysis failed: ${error.message}`);
   }
+  throw error;
 }
-
-module.exports = C042Analyzer;
 ```
 
-#### **✅ 4. Testing & Validation**
+## 🧪 Testing Your Rule
 
-**Debug Output Verification**:
 ```bash
-SUNLINT_DEBUG=true node cli.js --input test-files/c042-test.js --rules C042 --engine=heuristic --debug
-```
-
-**Expected Output**:
-```
-🔧 [HeuristicEngine] Rule C042: semantic (approach: hybrid-combined)
-🔧 [C042] Constructor called with options: true
-🔧 [C042] Options type: object [ 'verbose', 'semanticEngine' ]
-🔧 [C042] Trying symbol-based analysis...
-✅ [C042] Symbol-based analysis: X violations
-```
-
-#### **✅ 5. Common Pitfalls & Solutions**
-
-| ❌ Problem | ✅ Solution |
-|------------|-------------|
-| `constructor(semanticEngine)` | `constructor(options = {})` |
-| Missing from `rule-analysis-strategies.js` | Add to `hybridOptimal` section |
-| `ast (approach: ast-primary)` output | Ensure rule in strategies config |
-| `this.semanticEngine?.project: false` | Check engine injection & initialization |
-| No debug output from constructor | Verify constructor signature |
-
-#### **✅ 6. Validation Checklist**
-
-Before submitting a new rule:
-
-- [ ] Constructor uses `options = {}` pattern
-- [ ] Rule registered in `enhanced-rules-registry.json`  
-- [ ] Strategy defined in `rule-analysis-strategies.js` `hybridOptimal`
-- [ ] Symbol-based analyzer implemented with ts-morph
-- [ ] Regex-based analyzer implemented with pattern matching
-- [ ] Debug output shows `semantic (approach: hybrid-combined)`
-- [ ] Test cases detect expected violations accurately
-- [ ] No modifications to engine core files (registry-driven only)
-- [ ] Performance acceptable for large codebases
-
----
-
-## 📚 **Legacy Implementation Examples**
-
-The following examples show older patterns for reference, but **use the Modern Guide above** for new rules:
-
-#### **Step 7: Document Analysis Strategy**
-
-```markdown
-<!-- rules/common/C042_no_hardcoded_config/STRATEGY.md -->
-# C042 Analysis Strategy: No Hardcoded Configuration Values
-
-## Overview
-Hybrid approach using symbol-based analysis as primary with regex fallback.
-
-## Symbol-Based Analysis (Primary)
-- Uses ts-morph AST to analyze variable declarations
-- Detects configuration variable patterns by name
-- Checks initializer values for hardcoded literals
-- Excludes process.env and config function calls
-
-## Regex-Based Analysis (Fallback)
-- Pattern matching for common hardcoded config scenarios
-- Simpler but broader detection
-- Used when symbol analysis unavailable
-
-## Strategy Selection
-1. **Symbol-based**: When ts-morph project available (95% accuracy)
-2. **Regex-fallback**: When symbol analysis fails (80% accuracy)
-
-## Testing Approach
-Test both analyzers independently and verify hybrid orchestration.
-```
-
-#### **Step 8: Register Rule in Rules Registry**
-
-```json
-// config/rules/rules-registry.json
-{
-  "rules": {
-    "C042": {
-      "name": "No Hardcoded Configuration Values",
-      "description": "Avoid hardcoding configuration values in business logic",
-      "category": "maintainability",
-      "severity": "warning",
-      "languages": ["typescript", "javascript"],
-      "analyzer": "./rules/common/C042_no_hardcoded_config/analyzer.js",
-      "config": "./rules/common/C042_no_hardcoded_config/config.json",
-      "version": "1.0.0",
-      "status": "experimental",
-      "tags": ["configuration", "maintainability", "environment"]
-    }
-  }
-}
-```
+# Test single file
+node cli.js --input=test-file.js --rule=C010 --engine=heuristic --verbose
 
-#### **Step 9: Add to Enhanced Rules Registry**
+# Test project
+node cli.js --input=src/ --rule=C010 --engine=heuristic --max-semantic-files=-1
 
-```javascript
-// core/enhanced-rules-registry.js
-loadEnginePreferences(options = {}) {
-  const preferences = {
-    // ... existing rules ...
-    'C042': ['heuristic', 'openai'], // Symbol + regex hybrid
-    // ... rest of rules ...
-  };
-}
-```
-
-#### **Step 10: Add to Analysis Strategies**
-
-```javascript
-// config/rule-analysis-strategies.js
-module.exports = {
-  astPreferred: {
-    // ... existing rules ...
-    'C042': {
-      reason: 'Configuration detection requires precise symbol analysis for variable declarations',
-      methods: ['ast', 'regex'],
-      accuracy: { ast: 95, regex: 80 }
-    }
-  }
-};
+# Performance test
+time node cli.js --input=large-project/ --rule=C010 --engine=heuristic
 ```
 
-**Description**: Avoid hardcoding configuration values in business logic
-
-**Examples**:
-❌ Bad:
-```javascript
-const API_URL = "https://api.example.com";
-const MAX_RETRIES = 5;
-```
-
-✅ Good:
-```javascript
-const API_URL = process.env.API_URL;
-const MAX_RETRIES = parseInt(process.env.MAX_RETRIES || '3');
-```
-
-#### **Step 4: Add Tests**
-
-```javascript
-// test/rules/c042.test.js
-const { testRule } = require('../test-utils');
+## 📝 Best Practices
 
-describe('Rule C042: No Hardcoded Configuration Values', () => {
-  testRule('C042', {
-    valid: [
-      'const apiUrl = process.env.API_URL;',
-      'const config = loadConfig();'
-    ],
-    invalid: [
-      'const API_URL = "https://api.example.com";',
-      'const MAX_RETRIES = 5;'
-    ]
-  });
-});
-```
+1. **Use Symbol-Based Only**: More accurate than regex patterns
+2. **Always Check Engine State**: Verify semantic engine is ready
+3. **Handle Errors Gracefully**: Don't silently ignore failures  
+4. **Add Debug Logging**: Use `this.verbose` for troubleshooting
+5. **Test on Real Projects**: Validate with large codebases
+6. **Document Accuracy**: Update strategy.accuracy in registry
 
-#### **Step 5: Test Your Rule**
+## 🔧 Development Environment
 
 ```bash
-# Test with specific engine
-node cli.js --rule=C042 --engine=eslint --input=test/fixtures
-node cli.js --rule=C042 --engine=heuristic --input=test/fixtures
-
-# Test rule behavior
-node cli.js --rule=C042 --input=test/fixtures --verbose
-```
-
-### **Engine-Specific Development**
-
-#### **Heuristic Engine Rules**
-
-For custom pattern-based analysis:
-
-1. **Create Rule Class**:
-```javascript
-// rules/custom/your-rule.js
-const HeuristicRuleBase = require('../../core/heuristic-rule-base');
-
-class YourCustomRule extends HeuristicRuleBase {
-  constructor() {
-    super('CXXX', 'Your Rule Name');
-  }
+# Setup
+npm install
+npm test
 
-  analyze(node, context) {
-    // Your analysis logic
-    // Return violation or null
-  }
-}
+# Development workflow
+node cli.js --input=examples/ --rule=YOUR_RULE --engine=heuristic --verbose
 ```
 
-2. **Add to Registry**:
-```json
-{
-  "CXXX": {
-    "engineMappings": {
-      "heuristic": {
-        "implementation": "custom/your-rule",
-        "supportedLanguages": ["typescript", "javascript"]
-      }
-    }
-  }
-}
-```
-
-#### **ESLint Engine Rules**
-
-For JavaScript/TypeScript linting:
-
-1. **Use Existing ESLint Rules**:
-```json
-{
-  "CXXX": {
-    "engineMappings": {
-      "eslint": {
-        "rules": ["no-console", "prefer-const"],
-        "config": {
-          "no-console": ["error"],
-          "prefer-const": ["warn"]
-        }
-      }
-    }
-  }
-}
-```
-
-2. **Create Custom ESLint Rule** (advanced):
-```javascript
-// eslint-custom-rules/your-rule.js
-module.exports = {
-  meta: {
-    type: 'problem',
-    docs: { description: 'Your rule description' }
-  },
-  create(context) {
-    return {
-      FunctionDeclaration(node) {
-        // Your ESLint rule logic
-      }
-    };
-  }
-};
-```
-
-#### **OpenAI Engine Rules**
-
-For AI-powered analysis:
-
-```json
-{
-  "CXXX": {
-    "engineMappings": {
-      "openai": {
-        "prompt": "Analyze code for specific pattern or anti-pattern",
-        "examples": [
-          "// Bad example",
-          "// Good example"
-        ],
-        "temperature": 0.1,
-        "maxTokens": 500
-      }
-    }
-  }
-}
-```
-
-### **Adding a New Security Rule**
-
-Same process as above, just use `"category": "security"` in the rule definition.
-
-### **Testing Your New Rule**
-
-```bash
-# Test all engines with your new rule
-node cli.js --rule=C042 --input=test/fixtures --format=json
-
-# Test specific engine
-node cli.js --rule=C042 --engine=heuristic --input=test/fixtures
-node cli.js --rule=C042 --engine=eslint --input=test/fixtures  
-node cli.js --rule=C042 --engine=openai --input=test/fixtures
-
-# Validate rule registry
-node validate-system.js
-```
-
-### **Rule Definition Schema**
-
-Complete schema for rule definitions:
-
-```json
-{
-  "CXXX": {
-    "id": "CXXX",                          // Required: Rule ID
-    "title": "Rule Title",                 // Required: Human-readable title
-    "description": "Detailed description", // Required: Rule description
-    "severity": "error|warning|info",      // Required: Severity level
-    "category": "quality|security|performance|maintainability", // Required
-    "tags": ["tag1", "tag2"],             // Optional: Tags for filtering
-    "languages": ["typescript", "javascript"], // Optional: Supported languages
-    "engineMappings": {                    // Required: Engine configurations
-      "heuristic": {
-        "implementation": "custom/rule-name",
-        "supportedLanguages": ["typescript"],
-        "astTargets": ["FunctionDeclaration"]
-      },
-      "eslint": {
-        "rules": ["eslint-rule-name"],
-        "config": { "rule-option": true }
-      },
-      "openai": {
-        "prompt": "AI analysis prompt",
-        "examples": ["code example"],
-        "temperature": 0.1
-      }
-    },
-    "analysisStrategy": {                  // Optional: Analysis metadata
-      "type": "ast|regex|semantic",
-      "patterns": ["pattern1"],
-      "astTargets": ["NodeType"],
-      "heuristics": ["detection-method"]
-    },
-    "metadata": {                         // Optional: Additional metadata
-      "author": "Developer Name",
-      "created": "2025-08-07",
-      "updated": "2025-08-07",
-      "version": "1.0.0"
-    }
-  }
-}
-```
-
-### **Architecture Deep Dive**
-
-#### **Unified Rule Registry**
-- **Location**: `rules/` (auto-generated from origin-rules)
-- **Source**: `origin-rules/` (markdown files)
-- **ESLint Mappings**: `config/eslint-rule-mapping.json`
-- **Loader**: `core/unified-rule-registry.js`
-
-#### **Engine Architecture**
-```
-┌─────────────────────────────────────────┐
-│           SunLint CLI                   │
-├─────────────────────────────────────────┤
-│        Analysis Orchestrator            │
-│     (Strict Engine Mode Support)       │
-├─────────────────────────────────────────┤
-│  ┌─────────────┬─────────────┬─────────┐ │
-│  │  Heuristic  │   ESLint    │ OpenAI  │ │
-│  │   Engine    │   Engine    │ Engine  │ │
-│  │ (244 rules) │ (57 rules)  │(256 all)│ │
-│  └─────────────┴─────────────┴─────────┘ │
-├─────────────────────────────────────────┤
-│        Rule Configuration               │
-│ ┌─────────────┬─────────────────────────┐ │
-│ │   ESLint    │    Unified Registry     │ │
-│ │  Mappings   │   (Generated Rules)     │ │
-│ │ (.json)     │    (origin-rules)       │ │
-│ └─────────────┴─────────────────────────┘ │
-└─────────────────────────────────────────┘
-```
-
-#### **How Engines Load Rules**
-1. **Initialization**: Each engine calls `getInstance()` from unified registry
-2. **Rule Loading**: Registry loads rules from auto-generated `rules/` directory
-3. **ESLint Mapping**: ESLint engine loads rule mappings from `config/eslint-rule-mapping.json`
-4. **Engine Filtering**: Each engine filters rules based on their capabilities
-5. **Analysis**: Engines analyze code using their specific rule implementations
-
-**Key Features:**
-- ✅ **Strict Engine Mode**: `--engine=eslint` only runs ESLint, skips unsupported rules
-- ✅ **Fallback Mode**: Auto-engine selection with fallback (ESLint → Heuristic → OpenAI)
-- ✅ **Rule Skipping**: Graceful handling of unsupported rules by specific engines
-
-## 🧪 **Testing**
-
-### **Run All Tests**
-```bash
-npm test
-```
-
-### **Test Rule Registry System**
-```bash
-# Validate unified rule registry
-node validate-system.js
-
-# Check rule loading for each engine
-npm run test:engines
-```
-
-### **Test Specific Rules**
-```bash
-# Test specific rule with all engines
-node cli.js --rule=C042 --input=test/fixtures
-
-# Test with specific engine
-node cli.js --rule=C042 --engine=heuristic --input=test/fixtures
-node cli.js --rule=C042 --engine=eslint --input=test/fixtures
-node cli.js --rule=C042 --engine=openai --input=test/fixtures
-
-# Test multiple rules
-node cli.js --rule=C006,C019,C042 --input=test/fixtures
-```
-
-### **Test Rule Development**
-```bash
-# Create test fixtures
-mkdir -p test/fixtures/c042
-echo 'const API_URL = "https://api.example.com";' > test/fixtures/c042/invalid.ts
-echo 'const apiUrl = process.env.API_URL;' > test/fixtures/c042/valid.ts
-
-# Test your rule
-node cli.js --rule=C042 --input=test/fixtures/c042 --format=json
-```
-
-### **Integration Testing**
-```bash
-# Test all engines work together
-npm run test:integration
-
-# Test rule registry loading
-npm run test:registry
-
-# Performance testing
-npm run test:performance
-```
-
-## 📊 **Code Review Process**
-
-1. **Self-Review Checklist**
-   - [ ] Follows all Sun Lint coding rules (C005, C006, etc.)
-   - [ ] Rule C035: Error handling includes complete logging
-   - [ ] Rule C037: API responses use standard format
-   - [ ] Rule C040: Validation logic is centralized
-   - [ ] Tests pass and cover edge cases
-   - [ ] Documentation updated
-
-2. **Submit Pull Request**
-   - Clear title and description
-   - Reference related issues  
-   - Include test results
-   - Follow template
-   - **NEW**: Validate rule registry with `node validate-system.js`
-
-3. **Review Criteria**
-   - Code quality (follows our own rules!)
-   - Rule properly defined in `enhanced-rules-registry.json`
-   - All engines can load the rule correctly
-   - Test coverage for all supported engines
-   - Documentation completeness
-   - Performance impact
-   - Backward compatibility
-
-## 📝 **Documentation**
-
-### **Update Documentation**
-When adding features:
-- Update `README.md`
-- Add rule to `enhanced-rules-registry.json` (this is your main documentation!)
-- Update configuration examples
-- Add usage examples
-- Update `RULE_MIGRATION_SUMMARY.md` if changing rule system
-
-### **Rule Documentation Template**
-
-All rule documentation is now centralized in `enhanced-rules-registry.json`:
-
-```json
-{
-  "C042": {
-    "title": "Clear, descriptive rule title",
-    "description": "Detailed explanation of what the rule checks, why it matters, and how to fix violations. Follow Rule C015 (domain language) - use clear business terms.",
-    "examples": {
-      "invalid": [
-        "// Bad example that violates the rule",
-        "const API_URL = 'https://hardcoded-url.com';"
-      ],
-      "valid": [
-        "// Good example that follows the rule", 
-        "const apiUrl = process.env.API_URL;"
-      ]
-    },
-    "fixSuggestions": [
-      "Move configuration to environment variables",
-      "Use a configuration management system",
-      "Extract constants to a separate config file"
-    ],
-    "relatedRules": ["C031", "C034"]
-  }
-}
-```
-
-### **Engine-Specific Documentation**
-
-#### **Heuristic Engine Rules**
-Document custom analysis patterns:
-```json
-{
-  "analysisStrategy": {
-    "type": "ast",
-    "description": "Analyzes AST nodes for hardcoded configuration patterns",
-    "astTargets": ["VariableDeclaration", "PropertyAssignment"],
-    "patterns": ["literal-values-in-config-context"],
-    "complexity": "O(n) where n is number of variable declarations"
-  }
-}
-```
-
-#### **ESLint Engine Rules**  
-Document ESLint rule mappings:
-```json
-{
-  "engineMappings": {
-    "eslint": {
-      "rules": ["no-magic-numbers"],
-      "rationale": "ESLint's no-magic-numbers rule catches hardcoded values",
-      "limitations": "May have false positives for legitimate constants",
-      "customConfig": {
-        "no-magic-numbers": ["error", { "ignore": [0, 1, -1] }]
-      }
-    }
-  }
-}
-```
-
-#### **OpenAI Engine Rules**
-Document AI prompts and examples:
-```json
-{
-  "engineMappings": {
-    "openai": {
-      "prompt": "Identify hardcoded configuration values that should be externalized to environment variables or config files",
-      "context": "Look for URLs, timeouts, limits, and other configuration that might change between environments",
-      "examples": [
-        "❌ const API_URL = 'https://api.example.com';",
-        "✅ const API_URL = process.env.API_URL || 'https://default-api.com';"
-      ]
-    }
-  }
-}
-```
-
-## 🐛 **Bug Reports**
-
-When reporting bugs:
-1. Use clear, descriptive title
-2. Include reproduction steps
-3. Provide sample code
-4. Include environment details
-5. Include sunlint output
-6. **NEW**: Run `node validate-system.js` and include output
-
-## 🔧 **Troubleshooting**
-
-### **Common Issues**
-
-#### **Rule Not Loading**
-```bash
-# Check if rule exists in registry
-node -e "const registry = require('./core/unified-rule-registry'); registry.getInstance().initialize().then(() => console.log('Rule C042:', registry.getInstance().rules.has('C042')))"
-
-# Validate registry syntax
-node validate-system.js
-```
-
-#### **Engine Not Finding Rule**
-```bash
-# Check engine-specific mapping
-node -e "const registry = require('./core/unified-rule-registry'); registry.getInstance().initialize().then(r => { const rule = r.rules.get('C042'); console.log('ESLint mapping:', rule?.engineMappings?.eslint); })"
-```
-
-#### **Rule Registry Errors**
-```bash
-# Common issues:
-# 1. JSON syntax errors in enhanced-rules-registry.json
-# 2. Missing required fields (id, title, description, severity, category)
-# 3. Invalid engine mapping structure
-
-# Validate JSON syntax
-node -c config/enhanced-rules-registry.json
-
-# Check required fields
-node validate-system.js
-```
-
-### **Performance Issues**
-```bash
-# Profile rule loading
-node --prof cli.js --rule=C042 --input=large-project/
-
-# Check memory usage
-node --inspect cli.js --rule=C042 --input=test/fixtures/
-```
-
-## 💡 **Feature Requests**
-
-For new features:
-1. Check existing issues first
-2. Describe the use case
-3. Provide examples
-4. Consider implementation complexity
-5. Think about backward compatibility
-
-## 📋 **Quick Reference**
-
-### **Essential Commands**
-```bash
-# Add ESLint engine rule mapping
-vim config/eslint-rule-mapping.json
-
-# Create custom heuristic rule
-vim custom-rules/c042-rule-name.js
-
-# Add rule documentation
-vim origin-rules/common-en.md
-
-# Test new rule with specific engine
-node cli.js --rule=CXXX --engine=eslint --input=test/fixtures
-node cli.js --rule=CXXX --engine=heuristic --input=test/fixtures
-
-# Test strict engine mode (no fallback)
-node cli.js --rule=CXXX --engine=eslint --input=test/fixtures
-
-# Test fallback mode (auto engine selection)
-node cli.js --rule=CXXX --input=test/fixtures
-```
-
-### **Key Files**
-- `config/eslint-rule-mapping.json` - **ESLint engine rule mappings**
-- `origin-rules/` - **Original rule definitions** (markdown format)
-- `rules/` - **Generated rule registry** (auto-generated)
-- `core/unified-rule-registry.js` - Rule registry loader
-- `engines/heuristic-engine.js` - Custom pattern analysis
-- `engines/eslint-engine.js` - JavaScript/TypeScript linting  
-- `engines/openai-engine.js` - AI-powered analysis
-- `integrations/eslint/plugin/` - Custom ESLint rules
-- `custom-rules/` - Heuristic engine custom rules
-
-### **Rule Development Checklist**
-- [ ] Choose appropriate engine (ESLint for JS/TS, Heuristic for universal)
-- [ ] Add ESLint mapping to `config/eslint-rule-mapping.json` (if using ESLint engine)
-- [ ] Create custom rule implementation (if needed)
-- [ ] Add rule definition to `origin-rules/` (markdown format)
-- [ ] Add test cases and examples
-- [ ] Test with `node cli.js --rule=CXXX --input=test/fixtures`
-- [ ] Test engine-specific behavior (`--engine=eslint`, `--engine=heuristic`)
-- [ ] Update documentation if needed
-
----
-
-**🚀 Ready to contribute? Start by choosing your engine and editing the appropriate mapping file!**
-
-**For ESLint rules**: Edit `config/eslint-rule-mapping.json`  
-**For Heuristic rules**: Create files in `custom-rules/`  
-**For documentation**: Add to `origin-rules/` markdown files
-
----
-
-## 🔬 **Modern Rule Development Guide (2024)**
-
-*This section provides a comprehensive, step-by-step guide for implementing new rules using the modern hybrid architecture pattern (symbol-based + regex fallback), based on the successful C035 implementation.*
-
-### **Quick Start: Creating a New Rule**
-
-#### **Step 1: Create Rule Directory Structure**
-
-```bash
-# Example: Creating C042 (No Hardcoded Configuration Values)
-mkdir -p rules/common/C042_no_hardcoded_config
-cd rules/common/C042_no_hardcoded_config
-```
-
-#### **Step 2: Implement Main Analyzer (Hybrid Orchestrator)**
-
-```javascript
-// analyzer.js - Main hybrid orchestrator
-const SymbolBasedAnalyzer = require('./symbol-based-analyzer');
-const RegexBasedAnalyzer = require('./regex-based-analyzer');
-
-class C042NoHardcodedConfigAnalyzer {
-  constructor(verbose = false) {
-    this.verbose = verbose;
-    this.symbolAnalyzer = new SymbolBasedAnalyzer(verbose);
-    this.regexAnalyzer = new RegexBasedAnalyzer(verbose);
-  }
-
-  async analyzeFileBasic(filePath, options = {}) {
-    if (this.verbose) {
-      console.log(`🔍 [C042] Analyzing file: ${filePath}`);
-    }
-
-    try {
-      // Primary: Symbol-based analysis
-      const violations = await this.symbolAnalyzer.analyzeFileBasic(filePath, options);
-      
-      if (this.verbose) {
-        console.log(`✅ [C042] Symbol-based analysis completed. Found ${violations.length} violations.`);
-      }
-      
-      return violations;
-    } catch (error) {
-      if (this.verbose) {
-        console.warn(`⚠️ [C042] Symbol analysis failed: ${error.message}`);
-        console.log(`🔄 [C042] Falling back to regex analysis...`);
-      }
-      
-      // Fallback: Regex-based analysis
-      try {
-        const violations = await this.regexAnalyzer.analyzeFileBasic(filePath, options);
-        
-        if (this.verbose) {
-          console.log(`✅ [C042] Regex-fallback analysis completed. Found ${violations.length} violations.`);
-        }
-        
-        return violations;
-      } catch (fallbackError) {
-        if (this.verbose) {
-          console.error(`❌ [C042] Both symbol and regex analysis failed: ${fallbackError.message}`);
-        }
-        return [];
-      }
-    }
-  }
-}
-
-module.exports = C042NoHardcodedConfigAnalyzer;
-```
-
-#### **Step 3: Implement Symbol-Based Analyzer (Primary)**
-
-```javascript
-// symbol-based-analyzer.js - High-accuracy AST analysis
-const { Project } = require('ts-morph');
-
-class C042SymbolBasedAnalyzer {
-  constructor(verbose = false) {
-    this.verbose = verbose;
-    this.project = new Project({
-      useInMemoryFileSystem: true,
-      compilerOptions: {
-        allowJs: true,
-        checkJs: false,
-      },
-    });
-  }
-
-  async analyzeFileBasic(filePath, options = {}) {
-    const violations = [];
-    
-    try {
-      const sourceFile = this.project.addSourceFileAtPath(filePath);
-      
-      // Analyze variable declarations
-      sourceFile.getVariableDeclarations().forEach(declaration => {
-        const initializer = declaration.getInitializer();
-        if (initializer && this.isHardcodedConfig(initializer, declaration.getName())) {
-          violations.push({
-            line: declaration.getStartLineNumber(),
-            column: declaration.getStart() - declaration.getStartLinePos() + 1,
-            message: `Hardcoded configuration value detected in variable '${declaration.getName()}'`,
-            severity: 'warning',
-            rule: 'C042'
-          });
-        }
-      });
-
-      // Analyze property assignments
-      sourceFile.getDescendantsOfKind(ts.SyntaxKind.PropertyAssignment).forEach(prop => {
-        const value = prop.getInitializer();
-        if (value && this.isHardcodedConfig(value, prop.getName())) {
-          violations.push({
-            line: prop.getStartLineNumber(),
-            column: prop.getStart() - prop.getStartLinePos() + 1,
-            message: `Hardcoded configuration value in property '${prop.getName()}'`,
-            severity: 'warning',
-            rule: 'C042'
-          });
-        }
-      });
-
-      this.project.removeSourceFile(sourceFile);
-      return violations;
-    } catch (error) {
-      throw new Error(`Symbol analysis failed: ${error.message}`);
-    }
-  }
-
-  isHardcodedConfig(node, name) {
-    // Check if the value looks like configuration
-    const configPatterns = [
-      /url/i, /host/i, /port/i, /timeout/i, /secret/i, 
-      /api[_-]?key/i, /password/i, /connection/i, /endpoint/i
-    ];
-    
-    const nameMatches = configPatterns.some(pattern => pattern.test(name));
-    
-    if (!nameMatches) return false;
-    
-    // Check if value is hardcoded (string/number literal)
-    return node.getKind() === ts.SyntaxKind.StringLiteral ||
-           node.getKind() === ts.SyntaxKind.NumericLiteral;
-  }
-}
-
-module.exports = C042SymbolBasedAnalyzer;
-```
-
-#### **Step 4: Implement Regex-Based Analyzer (Fallback)**
-
-```javascript
-// regex-based-analyzer.js - Broad coverage pattern matching
-const fs = require('fs');
-
-class C042RegexBasedAnalyzer {
-  constructor(verbose = false) {
-    this.verbose = verbose;
-    
-    // Configuration-related patterns
-    this.configPatterns = [
-      /(?:const|let|var)\s+(\w*(?:url|host|port|timeout|secret|key|password|connection|endpoint)\w*)\s*=\s*['"`]([^'"`]+)['"`]/gi,
-      /(\w*(?:url|host|port|timeout|secret|key|password|connection|endpoint)\w*)\s*:\s*['"`]([^'"`]+)['"`]/gi,
-      /(\w*(?:url|host|port|timeout|secret|key|password|connection|endpoint)\w*)\s*=\s*(\d+)/gi
-    ];
-  }
-
-  async analyzeFileBasic(filePath, options = {}) {
-    const violations = [];
-    
-    try {
-      const content = fs.readFileSync(filePath, 'utf8');
-      const lines = content.split('\n');
-      
-      this.configPatterns.forEach(pattern => {
-        lines.forEach((line, index) => {
-          let match;
-          while ((match = pattern.exec(line)) !== null) {
-            const variableName = match[1];
-            const value = match[2];
-            
-            if (this.isLikelyHardcodedConfig(variableName, value)) {
-              violations.push({
-                line: index + 1,
-                column: match.index + 1,
-                message: `Potential hardcoded configuration: '${variableName}' = '${value}'`,
-                severity: 'warning',
-                rule: 'C042'
-              });
-            }
-          }
-          pattern.lastIndex = 0; // Reset regex
-        });
-      });
-
-      return violations;
-    } catch (error) {
-      throw new Error(`Regex analysis failed: ${error.message}`);
-    }
-  }
-
-  isLikelyHardcodedConfig(name, value) {
-    // Skip obvious non-config values
-    const skipPatterns = [
-      /^(true|false|null|undefined)$/i,
-      /^process\.env\./i,
-      /^require\(/i,
-      /^\w+\(/i // Function calls
-    ];
-    
-    return !skipPatterns.some(pattern => pattern.test(value));
-  }
-}
-
-module.exports = C042RegexBasedAnalyzer;
-```
-
-#### **Step 5: Create Rule Configuration**
-
-```json
-// config.json - Rule metadata and examples
-{
-  "id": "C042",
-  "name": "No Hardcoded Configuration Values",
-  "category": "Maintainability",
-  "severity": "warning",
-  "description": "Detects hardcoded configuration values that should use environment variables or config files",
-  "rationale": "Hardcoded configuration makes applications less flexible and harder to deploy across different environments",
-  "examples": {
-    "bad": [
-      "const API_URL = 'https://api.example.com';",
-      "const DB_HOST = 'localhost';",
-      "const MAX_CONNECTIONS = 100;",
-      "config: { port: 3000, host: 'localhost' }"
-    ],
-    "good": [
-      "const API_URL = process.env.API_URL;",
-      "const DB_HOST = process.env.DB_HOST || 'localhost';",
-      "const config = loadConfigFromFile();",
-      "const PORT = parseInt(process.env.PORT || '3000');"
-    ]
-  },
-  "tags": ["configuration", "deployment", "security", "maintainability"],
-  "accuracy": {
-    "symbol_based": "high",
-    "regex_based": "medium"
-  },
-  "performance": {
-    "symbol_based": "medium",
-    "regex_based": "fast"
-  }
-}
-```
-
-#### **Step 6: Document Analysis Strategy**
-
-```markdown
-<!-- STRATEGY.md - Analysis approach documentation -->
-# C042: No Hardcoded Configuration Values - Analysis Strategy
-
-## Overview
-This rule detects hardcoded configuration values using a hybrid approach combining symbol-based AST analysis with regex-based pattern matching.
-
-## Analysis Approaches
-
-### Symbol-Based Analysis (Primary)
-- **Tool**: ts-morph AST parser
-- **Accuracy**: High (95%+)
-- **Coverage**: Variable declarations, property assignments
-- **Strengths**: 
-  - Understands code context
-  - Low false positives
-  - Handles complex expressions
-- **Limitations**: 
-  - Requires valid syntax
-  - Slower performance
-
-### Regex-Based Analysis (Fallback)
-- **Tool**: Regular expressions
-- **Accuracy**: Medium (80%+)
-- **Coverage**: String/number patterns in config-like names
-- **Strengths**: 
-  - Fast execution
-  - Works with any file
-  - Broad pattern coverage
-- **Limitations**: 
-  - Higher false positives
-  - Limited context understanding
-
-## Detection Patterns
-
-### Configuration Indicators
-- Variable/property names containing: url, host, port, timeout, secret, key, password, connection, endpoint
-- Literal string/number values
-- Assignment patterns
-
-### Exclusions
-- Environment variable references (process.env.*)
-- Function calls
-- Boolean/null literals
-- Computed values
-
-## Testing Strategy
-- Unit tests for each analyzer
-- Integration tests for hybrid orchestration
-- Real-world project validation
-- Performance benchmarking
-```
-
-#### **Step 7: Add to Rules Registry**
-
-```json
-// config/rules/rules-registry.json - Add rule definition
-{
-  "C042": {
-    "id": "C042",
-    "name": "No Hardcoded Configuration Values",
-    "category": "Maintainability",
-    "severity": "warning",
-    "description": "Detects hardcoded configuration values that should use environment variables or config files",
-    "engine": "heuristic",
-    "analyzerPath": "rules/common/C042_no_hardcoded_config/analyzer.js",
-    "configPath": "rules/common/C042_no_hardcoded_config/config.json",
-    "enabled": true,
-    "languages": ["javascript", "typescript"],
-    "tags": ["configuration", "deployment", "security"]
-  }
-}
-```
-
-#### **Step 8: Register with Enhanced Rules Registry**
-
-```javascript
-// core/enhanced-rules-registry.js - Add engine preferences
-const enginePreferences = {
-  // ... existing rules
-  'C042': ['heuristic'], // Add your rule here
-};
-```
-
-#### **Step 9: Add to Analysis Strategies**
-
-```javascript
-// config/rule-analysis-strategies.js - Add to AST preferred rules
-const strategies = {
-  astPreferred: [
-    // ... existing rules
-    'C042', // Add your rule here
-  ],
-  regexOnly: [
-    // Rules that only use regex
-  ],
-  hybridOnly: [
-    // Rules requiring both approaches
-  ]
-};
-```
-
-#### **Step 10: Create Test Script for Direct Testing**
-
-```javascript
-// test-c042-direct.js - Direct analyzer testing
-const C042Analyzer = require('./rules/common/C042_no_hardcoded_config/analyzer');
-
-async function testC042() {
-  const analyzer = new C042Analyzer(true); // Enable verbose mode
-  
-  try {
-    const violations = await analyzer.analyzeFileBasic('test-files/c042-test.js');
-    console.log(`\n📊 C042 Analysis Results:`);
-    console.log(`   Found ${violations.length} violations`);
-    
-    violations.forEach((violation, index) => {
-      console.log(`   ${index + 1}. Line ${violation.line}: ${violation.message}`);
-    });
-  } catch (error) {
-    console.error('❌ C042 test failed:', error.message);
-  }
-}
-
-testC042();
-```
-
-#### **Step 11: Create Test File**
-
-```javascript
-// test-files/c042-test.js
-/**
- * Test file for C042 No Hardcoded Configuration Values rule
- * Contains various configuration patterns to validate analyzer
- */
-
-// Good Examples: Using environment variables
-const API_URL = process.env.API_URL;
-const MAX_RETRIES = parseInt(process.env.MAX_RETRIES || '3');
-const config = loadConfigFromFile();
-
-// Bad Examples: Hardcoded values (should trigger violations)
-const DATABASE_URL = 'mongodb://localhost:27017/myapp';
-const API_SECRET = 'sk-1234567890abcdef';
-const MAX_CONNECTIONS = 100;
-const TIMEOUT_MS = 5000;
-
-// Edge Cases
-const DEBUG_MODE = true; // Should not trigger (not config pattern)
-const DEFAULT_CONFIG = { // Should trigger for nested hardcoded values
-  port: 3000,
-  host: 'localhost'
-};
-
-module.exports = {
-  goodConfig,
-  badConfig
-};
-```
-
-#### **Step 12: Test Your Rule**
-
-```bash
-# Test the new rule
-node cli.js --rule=C042 --input=test-files/c042-test.js --verbose --engine=heuristic
-
-# Expected output: Should detect 4-5 violations for hardcoded config values
-
-# Test rule in real projects
-node cli.js --rule=C042 --input=src --engine=heuristic
-
-# Test with different engines
-node cli.js --rule=C042 --input=test-files/c042-test.js --engine=openai
-```
-
-#### **Step 13: Validate Integration**
-
-```bash
-# Check rule is loaded
-node cli.js --rule=C042 --input=test-files/c042-test.js --verbose | grep "Loaded.*rule: C042"
-
-# Verify both analyzers work
-node cli.js --rule=C042 --input=test-files/c042-test.js --verbose | grep -E "(Symbol-based|Regex-fallback)"
-
-# Check for violations
-node cli.js --rule=C042 --input=test-files/c042-test.js --format=json | jq '.results[].violations | length'
-```
-
-### **Modern Rule Development Best Practices**
-
-#### **Architecture Patterns**
-
-1. **Hybrid Symbol + Regex Approach** (Recommended)
-   - Primary: Symbol-based analysis (high accuracy)
-   - Fallback: Regex-based analysis (broad coverage)
-   - Example: C035, C033
-
-2. **Symbol-Only Approach**
-   - For complex AST analysis requiring deep context
-   - Higher accuracy but limited fallback
-   - Example: Advanced OOP rules
-
-3. **Regex-Only Approach**
-   - For simple pattern matching
-   - Fast but lower accuracy
-   - Example: Basic naming conventions
-
-#### **Code Quality Standards for Rules**
-
-- **Rule C005**: Each analyzer should have single responsibility
-- **Rule C006**: Method names should be verb-noun (e.g., `analyzeVariableDeclaration`)
-- **Rule C031**: Keep validation logic separate from detection logic
-- **Rule C035**: Log detailed information for debugging (verbose mode)
-
-#### **File Structure Standards**
-
-```
-rules/common/C042_rule_name/
-├── analyzer.js                 # Main hybrid orchestrator
-├── symbol-based-analyzer.js    # Primary AST analysis
-├── regex-based-analyzer.js     # Fallback pattern matching
-├── config.json                 # Rule configuration
-├── STRATEGY.md                 # Analysis approach documentation
-└── README.md                   # Rule documentation (optional)
-```
-
-#### **Error Handling Standards**
-
-```javascript
-// Always include proper error handling
-try {
-  const violations = await this.symbolAnalyzer.analyzeFileBasic(filePath, options);
-  return violations;
-} catch (error) {
-  if (this.verbose) {
-    console.warn(`⚠️ [C042] Symbol analysis failed: ${error.message}`);
-  }
-  // Graceful fallback to regex analysis
-}
-```
-
-#### **Testing Standards**
-
-1. **Unit Tests**: Test each analyzer independently
-2. **Integration Tests**: Test hybrid orchestration
-3. **Real Project Tests**: Validate on actual codebases
-4. **Performance Tests**: Ensure reasonable execution time
-
-#### **Documentation Standards**
-
-- **STRATEGY.md**: Document analysis approach and accuracy
-- **config.json**: Include examples of good/bad patterns
-- **CONTRIBUTING.md**: Update with new patterns learned
-- **Inline comments**: Explain complex detection logic
-
-### **Rule Development Checklist**
-
-- [ ] Created rule directory structure
-- [ ] Implemented main analyzer (hybrid orchestrator)
-- [ ] Implemented symbol-based analyzer (primary)
-- [ ] Implemented regex-based analyzer (fallback)
-- [ ] Created rule configuration (config.json)
-- [ ] Documented analysis strategy (STRATEGY.md)
-- [ ] Added to rules registry
-- [ ] Added to enhanced rules registry
-- [ ] Added to analysis strategies
-- [ ] Created test file
-- [ ] Tested rule individually
-- [ ] Tested rule integration
-- [ ] Validated on real projects
-- [ ] Updated documentation
-
-### **Common Issues and Solutions**
-
-#### **Issue: Rule not loaded**
-```bash
-# Check if rule exists in registry
-node cli.js --rule=C042 --input=test-files --verbose | grep "No compatible analyzer found for C042"
-
-# Solution: Add rule to config/rules/rules-registry.json
-```
-
-#### **Issue: Symbol analysis fails**
-```bash
-# Check semantic engine availability
-node cli.js --rule=C042 --input=test-files --verbose | grep "Symbol analysis failed"
-
-# Solution: Ensure proper error handling and regex fallback
-```
-
-#### **Issue: No violations detected**
-```bash
-# Test analyzers independently
-node test-c042-direct.js
-
-# Check file patterns match expectations
-```
-
-#### **Issue: Too many false positives**
-```bash
-# Refine detection patterns
-# Add exclusion rules
-# Test on diverse codebases
-```
-
----
-
-## 🤝 **Community**
-
-- **Discord**: [Sun Engineering Discord](https://discord.gg/sun-engineering)
-- **Issues**: [GitHub Issues](https://github.com/sun-engineering/sunlint/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/sun-engineering/sunlint/discussions)
-
-## 📄 **License**
+## 📚 Advanced Topics
 
-By contributing, you agree that your contributions will be licensed under the MIT License.
+- **AST Navigation**: Use ts-morph documentation for node traversal
+- **Performance**: Symbol-based analysis is ~15s for 2000+ files
+- **Multi-language**: Extend analyzers for Dart, Kotlin support
+- **Custom Patterns**: Leverage SyntaxKind for specific constructs
 
 ---
 
-**Thank you for making Sun Lint better! ☀️**
+This guide is based on real experience refactoring C013 and other rules. Focus on accuracy over speed - symbol-based analysis provides much better results than regex patterns.