@sun-asterisk/sunlint 1.3.0 → 1.3.2

package/CONTRIBUTING.md

@@ -1,698 +1,342 @@
-# Contributing to Sun Lint
+# Contributing to SunLint - Rule Development Guide
 
-Thank you for your interest in contributing to Sun Lint! 🌟
+## 🎯 Quick Start for Rule Development
 
-## 🚀 **Getting Started**
+This guide focuses on developing new rules for SunLint. Based on practical experience from refactoring rules like C013, C035, we recommend a **symbol-based only** approach for maximum accuracy.
 
-### **Prerequisites**
-- Node.js 16+ 
-- npm 8+
-- Git
+## 📋 Rule Development Steps
 
-### **Setup Development Environment**
+### Step 1: Register Rule in Registry
 
-```bash
-# Clone the repository
-git clone https://github.com/sun-engineering/sunlint.git
-cd sunlint
-
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Try the CLI locally
-node cli.js --help
-```
-
-## 📋 **Coding Standards**
-
-When contributing to Sun Lint, please follow these coding rules:
-
-### **Code Quality Rules**
-- **Rule C005** – Each function should do one thing only
-- **Rule C006** – Function names must be verb/verb-noun
-- **Rule C007** – Avoid comments that just describe the code
-- **Rule C012** – Separate Command and Query operations (CQS principle)
-- **Rule C014** – Use Dependency Injection instead of direct instantiation
-- **Rule C015** – Use domain language in class/function names
-- **Rule C019** – Don't use `error` log level for non-critical errors
-- **Rule C031** – Keep validation logic separate
-- **Rule C032** – Don't call external APIs in constructors or static blocks
-- **Rule C033** – Separate processing logic and data queries in service layer
-- **Rule C034** – Limit direct access to global state in domain logic
-- **Rule C035** – When handling errors, log complete relevant information
-- **Rule C037** – API handlers should return standard response objects (not raw strings)
-- **Rule C038** – Avoid logic depending on file/module loading order
-- **Rule C040** – Don't scatter validation logic across multiple classes
-
-## 🔧 **Development Workflow**
+Add your rule to `config/rules/enhanced-rules-registry.json`:
 
-### **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 (Current Process)**
-
-#### **Step 1: Choose Rule Implementation Approach**
-
-**Option A: ESLint Engine Rule (Recommended for JS/TS)**
-For JavaScript/TypeScript rules that can use existing ESLint rules:
-
-1. **Add to ESLint mapping**: Edit `config/eslint-rule-mapping.json`
 ```json
 {
-  "C042": ["no-magic-numbers", "custom/no-hardcoded-values"]
-}
-```
-
-2. **Create custom ESLint rule** (if needed): `integrations/eslint/plugin/rules/no-hardcoded-values.js`
-
-**Option B: Heuristic Engine Rule (Universal)**
-For language-agnostic rules or complex pattern analysis:
-
-1. **Create rule class**: `custom-rules/c042-no-hardcoded-config.js`
-
-#### **Step 2: Implement Rule Logic**
-
-**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": {
+    "C010": {
+      "name": "Limit Block Nesting",
+      "description": "Limit nested blocks (if/for/while/switch) to maximum 3 levels for readability",
+      "category": "complexity",
+      "severity": "warning",
+      "languages": ["typescript", "javascript", "dart", "kotlin"],
+      "analyzer": "./rules/common/C010_limit_block_nesting/analyzer.js",
+      "config": "./rules/common/C010_limit_block_nesting/config.json",
+      "version": "1.0.0",
+      "status": "stable",
+      "tags": ["complexity", "readability", "nesting", "maintainability"],
+      "strategy": {
+        "preferred": "ast",
+        "fallbacks": ["ast"],
+        "accuracy": {
+          "ast": 95
         }
+      },
+      "engineMappings": {
+        "eslint": ["complexity", "max-depth"]
       }
-    };
-  }
-};
-```
-
-**For Heuristic Engine Rules:**
-```javascript
-// custom-rules/c042-no-hardcoded-config.js
-const SemanticRuleBase = require('../core/semantic-rule-base');
-
-class NoHardcodedConfigRule extends SemanticRuleBase {
-  constructor() {
-    super('C042', 'No Hardcoded Configuration Values');
-  }
-
-  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');
     }
-    return null;
-  }
-
-  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);
   }
 }
-
-module.exports = NoHardcodedConfigRule;
-```
-
-#### **Step 3: Update Rule Registry**
-
-Add rule definition to origin rules:
-```markdown
-<!-- origin-rules/common-en.md -->
-## C042: No Hardcoded Configuration Values
-
-**Category**: Maintainability  
-**Severity**: Warning
-
-**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');
-```
+**Key Registry Fields:**
+- `analyzer`: Path to main analyzer file
+- `strategy.preferred`: Use "ast" for symbol-based analysis
+- `strategy.fallbacks`: Recommend ["ast"] only for accuracy
+- `strategy.accuracy`: Expected accuracy percentage
 
-#### **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**
+### Step 2: Create Rule Directory Structure
 
 ```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
+mkdir -p rules/common/C010_limit_block_nesting
+cd rules/common/C010_limit_block_nesting
 
-# Test rule behavior
-node cli.js --rule=C042 --input=test/fixtures --verbose
+# Required files
+touch analyzer.js           # Main orchestrator
+touch symbol-based-analyzer.js  # Core analysis logic
+touch config.json          # Rule configuration
 ```
 
-### **Engine-Specific Development**
-
-#### **Heuristic Engine Rules**
+### Step 3: Implement Main Analyzer (analyzer.js)
 
-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');
+// rules/common/C010_limit_block_nesting/analyzer.js
+const C010SymbolBasedAnalyzer = require('./symbol-based-analyzer.js');
+
+class C010Analyzer {
+  constructor(semanticEngine = null) {
+    this.ruleId = 'C010';
+    this.ruleName = 'Limit Block Nesting';
+    this.description = 'Limit nested blocks to maximum 3 levels';
+    this.semanticEngine = semanticEngine;
+    this.verbose = false;
+    
+    // Use symbol-based only for accuracy
+    this.symbolAnalyzer = new C010SymbolBasedAnalyzer(semanticEngine);
   }
 
-  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"]
-      }
+  async initialize(semanticEngine = null) {
+    if (semanticEngine) {
+      this.semanticEngine = semanticEngine;
     }
+    this.verbose = semanticEngine?.verbose || false;
+    await this.symbolAnalyzer.initialize(semanticEngine);
   }
-}
-```
 
-#### **ESLint Engine Rules**
+  async analyzeFileBasic(filePath, options = {}) {
+    try {
+      // Check if symbol engine is ready
+      if (!this.semanticEngine?.isSymbolEngineReady?.() || !this.semanticEngine.project) {
+        throw new Error('Symbol engine not available');
+      }
 
-For JavaScript/TypeScript linting:
+      if (this.verbose) {
+        console.log(`[DEBUG] 🎯 C010: Using symbol-based analysis for ${filePath.split('/').pop()}`);
+      }
 
-1. **Use Existing ESLint Rules**:
-```json
-{
-  "CXXX": {
-    "engineMappings": {
-      "eslint": {
-        "rules": ["no-console", "prefer-const"],
-        "config": {
-          "no-console": ["error"],
-          "prefer-const": ["warn"]
-        }
+      const violations = await this.symbolAnalyzer.analyzeFileBasic(filePath, options);
+      
+      if (this.verbose) {
+        console.log(`[DEBUG] 🎯 C010: Symbol-based analysis found ${violations.length} violations`);
       }
-    }
-  }
-}
-```
 
-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
+      return violations;
+    } catch (error) {
+      if (this.verbose) {
+        console.error(`[DEBUG] ❌ C010: Analysis failed: ${error.message}`);
       }
-    };
+      throw new Error(`C010 analysis failed: ${error.message}`);
+    }
   }
-};
-```
-
-#### **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
+  async analyzeFiles(files, options = {}) {
+    const allViolations = [];
+    for (const filePath of files) {
+      try {
+        const violations = await this.analyzeFileBasic(filePath, options);
+        allViolations.push(...violations);
+      } catch (error) {
+        console.warn(`C010: Skipping ${filePath}: ${error.message}`);
       }
     }
+    return allViolations;
   }
 }
-```
-
-### **Adding a New Security Rule**
-
-Same process as above, just use `"category": "security"` in the rule definition.
-
-### **Testing Your New Rule**
-
-```bash
-# Test all engines with your new rule
-node cli.js --rule=C042 --input=test/fixtures --format=json
-
-# Test specific engine
-node cli.js --rule=C042 --engine=heuristic --input=test/fixtures
-node cli.js --rule=C042 --engine=eslint --input=test/fixtures  
-node cli.js --rule=C042 --engine=openai --input=test/fixtures
 
-# Validate rule registry
-node validate-system.js
+module.exports = C010Analyzer;
 ```
 
-### **Rule Definition Schema**
+### Step 4: Implement Symbol-Based Analyzer
 
-Complete schema for rule definitions:
+```javascript
+// rules/common/C010_limit_block_nesting/symbol-based-analyzer.js
+const { SyntaxKind } = require('ts-morph');
+
+class C010SymbolBasedAnalyzer {
+  constructor(semanticEngine = null) {
+    this.semanticEngine = semanticEngine;
+    this.maxNestingLevel = 3;
+    this.verbose = false;
+  }
 
-```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"
+  async initialize(semanticEngine = null) {
+    if (semanticEngine) {
+      this.semanticEngine = semanticEngine;
     }
+    this.verbose = semanticEngine?.verbose || false;
   }
-}
-```
-
-### **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)       │ │
-│ └─────────────┴─────────────────────────┘ │
-└─────────────────────────────────────────┘
-```
+  async analyzeFileBasic(filePath, options = {}) {
+    const violations = [];
+    
+    try {
+      const sourceFile = this.semanticEngine.project.getSourceFile(filePath);
+      if (!sourceFile) {
+        throw new Error(`Source file not found: ${filePath}`);
+      }
 
-#### **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
+      if (this.verbose) {
+        console.log(`[DEBUG] 🔍 C010: Analyzing nesting in ${filePath.split('/').pop()}`);
+      }
 
-**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
+      // Find nested blocks
+      const nestedBlocks = this.findNestedBlocks(sourceFile);
+      
+      for (const block of nestedBlocks) {
+        if (block.nestingLevel > this.maxNestingLevel) {
+          violations.push({
+            ruleId: 'C010',
+            message: `Nested block exceeds maximum depth of ${this.maxNestingLevel} (current: ${block.nestingLevel}). Consider extracting to separate functions.`,
+            filePath: filePath,
+            line: block.line,
+            column: block.column,
+            severity: 'warning',
+            category: 'complexity'
+          });
+        }
+      }
 
-## 🧪 **Testing**
+      if (this.verbose) {
+        console.log(`[DEBUG] 🔍 C010: Found ${violations.length} nesting violations`);
+      }
 
-### **Run All Tests**
-```bash
-npm test
-```
+      return violations;
+    } catch (error) {
+      if (this.verbose) {
+        console.error(`[DEBUG] ❌ C010: Symbol analysis error: ${error.message}`);
+      }
+      throw error;
+    }
+  }
 
-### **Test Rule Registry System**
-```bash
-# Validate unified rule registry
-node validate-system.js
+  findNestedBlocks(sourceFile) {
+    const blocks = [];
+    
+    function traverse(node, currentDepth = 0) {
+      // Check for block statements that increase nesting
+      if (this.isNestingNode(node)) {
+        currentDepth++;
+        
+        const position = sourceFile.getLineAndColumnAtPos(node.getStart());
+        blocks.push({
+          node: node,
+          nestingLevel: currentDepth,
+          line: position.line,
+          column: position.column
+        });
+      }
 
-# Check rule loading for each engine
-npm run test:engines
-```
+      // Traverse children
+      node.forEachChild(child => traverse.call(this, child, currentDepth));
+    }
 
-### **Test Specific Rules**
-```bash
-# Test specific rule with all engines
-node cli.js --rule=C042 --input=test/fixtures
+    traverse.call(this, sourceFile, 0);
+    return blocks;
+  }
 
-# 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
+  isNestingNode(node) {
+    return [
+      SyntaxKind.IfStatement,
+      SyntaxKind.ForStatement,
+      SyntaxKind.ForInStatement,
+      SyntaxKind.ForOfStatement,
+      SyntaxKind.WhileStatement,
+      SyntaxKind.DoStatement,
+      SyntaxKind.SwitchStatement,
+      SyntaxKind.TryStatement,
+      SyntaxKind.CatchClause
+    ].includes(node.getKind());
+  }
+}
 
-# Test multiple rules
-node cli.js --rule=C006,C019,C042 --input=test/fixtures
+module.exports = C010SymbolBasedAnalyzer;
 ```
 
-### **Test Rule Development**
-```bash
-# Create test fixtures
-mkdir -p test/fixtures/c042
-echo 'const API_URL = "https://api.example.com";' > test/fixtures/c042/invalid.ts
-echo 'const apiUrl = process.env.API_URL;' > test/fixtures/c042/valid.ts
+### Step 5: Create Rule Configuration
 
-# Test your rule
-node cli.js --rule=C042 --input=test/fixtures/c042 --format=json
+```json
+// rules/common/C010_limit_block_nesting/config.json
+{
+  "maxNestingLevel": 3,
+  "excludePatterns": [
+    "**/*.test.js",
+    "**/*.spec.js"
+  ],
+  "includePatterns": [
+    "**/*.js",
+    "**/*.ts",
+    "**/*.jsx",
+    "**/*.tsx"
+  ]
+}
 ```
 
-### **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
-```
+## 🚨 Common Pitfalls & Solutions
 
-## 📊 **Code Review Process**
-
-1. **Self-Review Checklist**
-   - [ ] Follows all Sun Lint coding rules (C005, C006, etc.)
-   - [ ] Rule C035: Error handling includes complete logging
-   - [ ] Rule C037: API responses use standard format
-   - [ ] Rule C040: Validation logic is centralized
-   - [ ] Tests pass and cover edge cases
-   - [ ] Documentation updated
-
-2. **Submit Pull Request**
-   - Clear title and description
-   - Reference related issues  
-   - Include test results
-   - Follow template
-   - **NEW**: Validate rule registry with `node validate-system.js`
-
-3. **Review Criteria**
-   - Code quality (follows our own rules!)
-   - Rule properly defined in `enhanced-rules-registry.json`
-   - All engines can load the rule correctly
-   - Test coverage for all supported engines
-   - Documentation completeness
-   - Performance impact
-   - Backward compatibility
-
-## 📝 **Documentation**
-
-### **Update Documentation**
-When adding features:
-- Update `README.md`
-- Add rule to `enhanced-rules-registry.json` (this is your main documentation!)
-- Update configuration examples
-- Add usage examples
-- Update `RULE_MIGRATION_SUMMARY.md` if changing rule system
-
-### **Rule Documentation Template**
-
-All rule documentation is now centralized in `enhanced-rules-registry.json`:
+### 1. Symbol Engine Not Ready
+```javascript
+// ❌ Wrong - Will fail if symbol engine not ready
+const violations = await this.symbolAnalyzer.analyzeFileBasic(filePath);
 
-```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"]
-  }
+// ✅ Correct - Check engine availability
+if (!this.semanticEngine?.isSymbolEngineReady?.() || !this.semanticEngine.project) {
+  throw new Error('Symbol engine not available');
 }
 ```
 
-### **Engine-Specific Documentation**
+### 2. Missing Source File Check
+```javascript
+// ❌ Wrong - Will crash if file not found
+const sourceFile = this.semanticEngine.project.getSourceFile(filePath);
 
-#### **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"
-  }
+// ✅ Correct - Always check source file existence
+const sourceFile = this.semanticEngine.project.getSourceFile(filePath);
+if (!sourceFile) {
+  throw new Error(`Source file not found: ${filePath}`);
 }
 ```
 
-#### **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] }]
-      }
-    }
-  }
+### 3. Improper Error Handling
+```javascript
+// ❌ Wrong - Silent failures
+try {
+  const violations = await this.analyzeFile(filePath);
+} catch (error) {
+  return [];
 }
-```
 
-#### **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';"
-      ]
-    }
+// ✅ Correct - Proper error propagation
+try {
+  const violations = await this.analyzeFile(filePath);
+  return violations;
+} catch (error) {
+  if (this.verbose) {
+    console.error(`Analysis failed: ${error.message}`);
   }
+  throw error;
 }
 ```
 
-## 🐛 **Bug Reports**
-
-When reporting bugs:
-1. Use clear, descriptive title
-2. Include reproduction steps
-3. Provide sample code
-4. Include environment details
-5. Include sunlint output
-6. **NEW**: Run `node validate-system.js` and include output
+## 🧪 Testing Your Rule
 
-## 🔧 **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')))"
+# Test single file
+node cli.js --input=test-file.js --rule=C010 --engine=heuristic --verbose
 
-# Validate registry syntax
-node validate-system.js
-```
+# Test project
+node cli.js --input=src/ --rule=C010 --engine=heuristic --max-semantic-files=-1
 
-#### **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); })"
+# Performance test
+time node cli.js --input=large-project/ --rule=C010 --engine=heuristic
 ```
 
-#### **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
+## 📝 Best Practices
 
-# Validate JSON syntax
-node -c config/enhanced-rules-registry.json
+1. **Use Symbol-Based Only**: More accurate than regex patterns
+2. **Always Check Engine State**: Verify semantic engine is ready
+3. **Handle Errors Gracefully**: Don't silently ignore failures  
+4. **Add Debug Logging**: Use `this.verbose` for troubleshooting
+5. **Test on Real Projects**: Validate with large codebases
+6. **Document Accuracy**: Update strategy.accuracy in registry
 
-# Check required fields
-node validate-system.js
-```
+## 🔧 Development Environment
 
-### **Performance Issues**
 ```bash
-# Profile rule loading
-node --prof cli.js --rule=C042 --input=large-project/
-
-# Check memory usage
-node --inspect cli.js --rule=C042 --input=test/fixtures/
-```
-
-## 💡 **Feature Requests**
-
-For new features:
-1. Check existing issues first
-2. Describe the use case
-3. Provide examples
-4. Consider implementation complexity
-5. Think about backward compatibility
-
-## 📋 **Quick Reference**
-
-### **Essential Commands**
-```bash
-# Add ESLint engine rule mapping
-vim config/eslint-rule-mapping.json
-
-# Create custom heuristic rule
-vim custom-rules/c042-rule-name.js
-
-# Add rule documentation
-vim origin-rules/common-en.md
-
-# Test new rule with specific engine
-node cli.js --rule=CXXX --engine=eslint --input=test/fixtures
-node cli.js --rule=CXXX --engine=heuristic --input=test/fixtures
-
-# Test strict engine mode (no fallback)
-node cli.js --rule=CXXX --engine=eslint --input=test/fixtures
+# Setup
+npm install
+npm test
 
-# Test fallback mode (auto engine selection)
-node cli.js --rule=CXXX --input=test/fixtures
+# Development workflow
+node cli.js --input=examples/ --rule=YOUR_RULE --engine=heuristic --verbose
 ```
 
-### **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
-
-## 🤝 **Community**
-
-- **Discord**: [Sun Engineering Discord](https://discord.gg/sun-engineering)
-- **Issues**: [GitHub Issues](https://github.com/sun-engineering/sunlint/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/sun-engineering/sunlint/discussions)
-
-## 📄 **License**
+## 📚 Advanced Topics
 
-By contributing, you agree that your contributions will be licensed under the MIT License.
+- **AST Navigation**: Use ts-morph documentation for node traversal
+- **Performance**: Symbol-based analysis is ~15s for 2000+ files
+- **Multi-language**: Extend analyzers for Dart, Kotlin support
+- **Custom Patterns**: Leverage SyntaxKind for specific constructs
 
 ---
 
-**Thank you for making Sun Lint better! ☀️**
+This guide is based on real experience refactoring C013 and other rules. Focus on accuracy over speed - symbol-based analysis provides much better results than regex patterns.