@sun-asterisk/sunlint 1.3.0 → 1.3.1

package/CONTRIBUTING.md

@@ -62,92 +62,652 @@ SunLint uses a **multi-engine architecture** with rule mapping system:
 - `config/eslint-rule-mapping.json` - ESLint engine rule mappings
 - `origin-rules/` - Original rule definitions (markdown format)
 
-### **Adding a New Rule (Current Process)**
+### **Adding a New Rule (Modern Approach - 2025)**
 
-#### **Step 1: Choose Rule Implementation Approach**
+#### **Step 1: Choose Rule Implementation Strategy**
 
-**Option A: ESLint Engine Rule (Recommended for JS/TS)**
-For JavaScript/TypeScript rules that can use existing ESLint rules:
+**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.
 
-1. **Add to ESLint mapping**: Edit `config/eslint-rule-mapping.json`
-```json
-{
-  "C042": ["no-magic-numbers", "custom/no-hardcoded-values"]
+#### **Step 2: Create Rule Directory Structure**
+
+```bash
+# 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;
 ```
 
-2. **Create custom ESLint rule** (if needed): `integrations/eslint/plugin/rules/no-hardcoded-values.js`
+#### **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;
+    }
 
-**Option B: Heuristic Engine Rule (Universal)**
-For language-agnostic rules or complex pattern analysis:
+    try {
+      const sourceFile = this.semanticEngine.project.getSourceFileByFilePath(filePath);
+      if (!sourceFile) {
+        return violations;
+      }
 
-1. **Create rule class**: `custom-rules/c042-no-hardcoded-config.js`
+      // Analyze variable declarations
+      const variableDeclarations = sourceFile.getVariableDeclarations();
+      for (const declaration of variableDeclarations) {
+        const violation = this.analyzeVariableDeclaration(declaration, filePath);
+        if (violation) {
+          violations.push(violation);
+        }
+      }
 
-#### **Step 2: Implement Rule Logic**
+      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;
+```
+
+#### **Step 5: Implement Regex-Based Analyzer (Fallback)**
 
-**For ESLint Engine Rules:**
 ```javascript
-// integrations/eslint/plugin/rules/no-hardcoded-values.js
-module.exports = {
-  meta: {
-    type: 'problem',
-    docs: { description: 'Detect hardcoded configuration values' },
-    schema: []
-  },
-  create(context) {
-    return {
-      VariableDeclaration(node) {
-        // Rule C005: Single responsibility - detect hardcoded values
-        if (this.isHardcodedConfig(node)) {
-          context.report({
-            node,
-            message: 'Avoid hardcoded configuration values'
+// 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`);
+    }
+  }
+
+  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');
+    
+    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 = C042RegexBasedAnalyzer;
 ```
 
-**For Heuristic Engine Rules:**
+#### **Step 6: Create Rule Configuration**
+
+```json
+// rules/common/C042_no_hardcoded_config/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();"
+    ]
+  }
+}
+```
+
+#### **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
-// custom-rules/c042-no-hardcoded-config.js
-const SemanticRuleBase = require('../core/semantic-rule-base');
+// ✅ CORRECT - Works with semantic engine injection
+class C042Analyzer {
+  constructor(options = {}) {
+    this.semanticEngine = options.semanticEngine || null;
+    this.verbose = options.verbose || false;
+    // ...
+  }
+}
 
-class NoHardcodedConfigRule extends SemanticRuleBase {
-  constructor() {
-    super('C042', 'No Hardcoded Configuration Values');
+// ❌ WRONG - Causes semantic engine injection failure
+class C042Analyzer {
+  constructor(semanticEngine = null) {
+    this.semanticEngine = semanticEngine;
+    // ...
   }
+}
+```
 
-  analyze(node, context) {
-    // Rule C005: Single responsibility - focus only on hardcoded config detection
-    if (this.isHardcodedConfigValue(node)) {
-      return this.createViolation(node, 'Hardcoded configuration value detected');
+#### **✅ 2. Registry Configuration (REQUIRED)**
+
+**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"]
     }
-    return null;
+  }
+}
+```
+
+**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 }
+    }
+  }
+}
+```
+
+#### **✅ 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
+    };
   }
 
-  isHardcodedConfigValue(node) {
-    // Rule C031: Keep validation logic separate
-    const configPatterns = /^(API_URL|DATABASE_URL|MAX_|MIN_|TIMEOUT|PORT)/;
-    return node.type === 'VariableDeclaration' && 
-           configPatterns.test(node.declarations[0]?.id?.name);
+  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 = NoHardcodedConfigRule;
+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
 ```
 
-#### **Step 3: Update Rule Registry**
+**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**
 
-Add rule definition to origin rules:
 ```markdown
-<!-- origin-rules/common-en.md -->
-## C042: No Hardcoded Configuration Values
+<!-- rules/common/C042_no_hardcoded_config/STRATEGY.md -->
+# C042 Analysis Strategy: No Hardcoded Configuration Values
 
-**Category**: Maintainability  
-**Severity**: Warning
+## 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
 
@@ -683,6 +1243,571 @@ node cli.js --rule=CXXX --input=test/fixtures
 **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)