@sun-asterisk/sunlint 1.2.2 → 1.3.1

package/CONTRIBUTING.md

@@ -49,74 +49,917 @@ When contributing to Sun Lint, please follow these coding rules:
 
 ## 🔧 **Development Workflow**
 
-### **Adding a New Quality Rule**
+### **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**
 
-1. **Create Rule Implementation**
 ```bash
-# Create the rule directory
-mkdir -p rules/quality/c042-new-rule
-cd rules/quality/c042-new-rule
+# Create rule directory
+mkdir -p rules/common/C042_no_hardcoded_config
+
+# 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
+```
+
+#### **Step 3: Implement Main Analyzer (Hybrid Orchestrator)**
+
+```javascript
+// rules/common/C042_no_hardcoded_config/analyzer.js
+const C042SymbolBasedAnalyzer = require('./symbol-based-analyzer.js');
+const C042RegexBasedAnalyzer = require('./regex-based-analyzer.js');
+
+class C042Analyzer {
+  constructor(semanticEngine = null) {
+    this.ruleId = 'C042';
+    this.ruleName = 'No Hardcoded Configuration Values';
+    this.description = 'Avoid hardcoding configuration values in business logic';
+    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);
+  }
+
+  async initialize(semanticEngine = null) {
+    if (semanticEngine) {
+      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;
+      }
+    } catch (error) {
+      if (this.verbose) {
+        console.warn(`⚠️ [C042] Symbol 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 = [];
+    
+    for (const filePath of files) {
+      try {
+        const fileViolations = await this.analyzeFileBasic(filePath, options);
+        violations.push(...fileViolations);
+      } catch (error) {
+        if (this.verbose) {
+          console.warn(`❌ [C042] Analysis failed for ${filePath}:`, error.message);
+        }
+      }
+    }
+    
+    return violations;
+  }
+}
+
+module.exports = C042Analyzer;
+```
+
+#### **Step 4: Implement Symbol-Based Analyzer (Primary)**
+
+```javascript
+// rules/common/C042_no_hardcoded_config/symbol-based-analyzer.js
+class C042SymbolBasedAnalyzer {
+  constructor(semanticEngine = null) {
+    this.ruleId = 'C042';
+    this.ruleName = 'No Hardcoded Configuration Values (Symbol-Based)';
+    this.semanticEngine = semanticEngine;
+    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) {
+    if (semanticEngine) {
+      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);
+      if (!sourceFile) {
+        return violations;
+      }
+
+      // Analyze variable declarations
+      const variableDeclarations = sourceFile.getVariableDeclarations();
+      for (const declaration of variableDeclarations) {
+        const violation = this.analyzeVariableDeclaration(declaration, filePath);
+        if (violation) {
+          violations.push(violation);
+        }
+      }
+
+      return violations;
+    } catch (error) {
+      if (this.verbose) {
+        console.warn(`⚠️ [C042 Symbol-Based] Analysis failed for ${filePath}:`, 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;
 ```
 
-2. **Implement the Rule**
+#### **Step 5: Implement Regex-Based Analyzer (Fallback)**
+
 ```javascript
-// rules/quality/c042-new-rule/analyzer.js
-class C042NewRuleAnalyzer {
-  analyze(code, filePath) {
-    // Implementation following Rule C005 (single responsibility)
-    return this.findViolations(code, filePath);
+// 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`);
+    }
   }
 
-  findViolations(code, filePath) {
-    // Rule C031: Keep validation logic separate
+  async analyzeFileBasic(filePath, options = {}) {
+    const fs = require('fs');
     const violations = [];
-    // Analysis logic here
+    
+    if (!fs.existsSync(filePath)) {
+      return violations;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+    
+    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;
+        
+        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'
+          });
+        }
+      }
+    }
+    
+    return violations;
+  }
+
+  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;
   }
 }
 
-module.exports = C042NewRuleAnalyzer;
+module.exports = C042RegexBasedAnalyzer;
 ```
 
-3. **Add Configuration**
+#### **Step 6: Create Rule Configuration**
+
 ```json
-// rules/quality/c042-new-rule/config.json
+// rules/common/C042_no_hardcoded_config/config.json
 {
-  "id": "C042",
-  "name": "New Rule Name",
-  "category": "quality",
-  "severity": "error",
-  "description": "Description following Rule C015 (domain language)",
-  "languages": ["typescript", "dart", "kotlin"],
-  "tags": ["maintainability", "readability"]
+  "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();"
+    ]
+  }
 }
 ```
 
-4. **Update Registry**
+#### **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)**
+
+Based on the successful C035 implementation, here's the **current recommended approach** for adding new rules:
+
+### **Critical Success Patterns**
+
+#### **✅ 1. Constructor Pattern (REQUIRED)**
 ```javascript
-// Add to config/rules/rules-registry.json
+// ✅ CORRECT - Works with semantic engine injection
+class C042Analyzer {
+  constructor(options = {}) {
+    this.semanticEngine = options.semanticEngine || null;
+    this.verbose = options.verbose || false;
+    // ...
+  }
+}
+
+// ❌ WRONG - Causes semantic engine injection failure
+class C042Analyzer {
+  constructor(semanticEngine = null) {
+    this.semanticEngine = semanticEngine;
+    // ...
+  }
+}
+```
+
+#### **✅ 2. Registry Configuration (REQUIRED)**
+
+**Enhanced Rules Registry** (`config/rules/enhanced-rules-registry.json`):
+```json
 {
   "C042": {
-    "id": "C042",
-    "name": "New Rule Name",
-    "category": "quality",
-    "path": "./rules/quality/c042-new-rule",
-    "analyzer": "analyzer.js",
-    "config": "config.json"
+    "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"]
+    }
+  }
+}
+```
+
+**Rule Analysis Strategies** (`config/rule-analysis-strategies.js`):
+```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 }
+    }
   }
 }
 ```
 
-5. **Add Tests**
+#### **✅ 3. Hybrid Architecture Template**
+
+**Main Analyzer** (`analyzer.js`):
 ```javascript
-// test/fixtures/c042/valid.ts
-// test/fixtures/c042/invalid.ts
-// test/unit/rules/c042.test.js
+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 [];
+  }
+}
+
+module.exports = C042Analyzer;
+```
+
+#### **✅ 4. Testing & Validation**
+
+**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"]
+    }
+  }
+}
+```
+
+#### **Step 9: Add to Enhanced Rules Registry**
+
+```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 }
+    }
+  }
+};
+```
+
+**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');
+
+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;'
+    ]
+  });
+});
+```
+
+#### **Step 5: Test Your Rule**
+
+```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');
+  }
+
+  analyze(node, context) {
+    // Your analysis logic
+    // Return violation or null
+  }
+}
+```
+
+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 but in `rules/security/` directory with `security` category.
+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**
 
@@ -125,25 +968,50 @@ Same process but in `rules/security/` directory with `security` category.
 npm test
 ```
 
-### **Run Specific Tests**
+### **Test Rule Registry System**
 ```bash
-# Test specific rule
-npm run test:c019
+# Validate unified rule registry
+node validate-system.js
+
+# Check rule loading for each engine
+npm run test:engines
+```
 
-# Test multiple rules  
-npm run test:multi
+### **Test Specific Rules**
+```bash
+# Test specific rule with all engines
+node cli.js --rule=C042 --input=test/fixtures
 
-# Test all quality rules
-npm run test:quality
+# 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 all security rules
-npm run test:security
+# Test multiple rules
+node cli.js --rule=C006,C019,C042 --input=test/fixtures
 ```
 
-### **Test Your Changes**
+### **Test Rule Development**
 ```bash
-# Test your new rule
-node cli.js --rule=C042 --input=test/fixtures --format=eslint
+# 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**
@@ -158,13 +1026,16 @@ node cli.js --rule=C042 --input=test/fixtures --format=eslint
 
 2. **Submit Pull Request**
    - Clear title and description
-   - Reference related issues
+   - 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!)
-   - Test coverage
+   - 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
@@ -174,32 +1045,88 @@ node cli.js --rule=C042 --input=test/fixtures --format=eslint
 ### **Update Documentation**
 When adding features:
 - Update `README.md`
-- Add rule documentation
+- 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**
-```markdown
-## Rule C042: New Rule Name
 
-**Category**: Quality  
-**Severity**: Error  
-**Languages**: TypeScript, Dart, Kotlin
+All rule documentation is now centralized in `enhanced-rules-registry.json`:
 
-### Description
-Following Rule C015 (domain language), use clear business terms...
+```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"]
+  }
+}
+```
 
-### Examples
+### **Engine-Specific Documentation**
 
-**❌ Bad:**
-```typescript
-// Code that violates the rule
+#### **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"
+  }
+}
 ```
 
-**✅ Good:**
-```typescript  
-// Code that follows the rule
+#### **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**
@@ -210,6 +1137,49 @@ When reporting bugs:
 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**
 
@@ -220,6 +1190,624 @@ For new features:
 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)