@sun-asterisk/sunlint 1.2.1 → 1.3.0

package/CONTRIBUTING.md

@@ -49,74 +49,357 @@ When contributing to Sun Lint, please follow these coding rules:
 
 ## 🔧 **Development Workflow**
 
-### **Adding a New Quality Rule**
+### **SunLint Architecture Overview**
 
-1. **Create Rule Implementation**
-```bash
-# Create the rule directory
-mkdir -p rules/quality/c042-new-rule
-cd rules/quality/c042-new-rule
+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. **Implement the Rule**
+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
-// rules/quality/c042-new-rule/analyzer.js
-class C042NewRuleAnalyzer {
-  analyze(code, filePath) {
-    // Implementation following Rule C005 (single responsibility)
-    return this.findViolations(code, filePath);
+// 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'
+          });
+        }
+      }
+    };
+  }
+};
+```
+
+**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');
   }
 
-  findViolations(code, filePath) {
+  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 violations = [];
-    // Analysis logic here
-    return violations;
+    const configPatterns = /^(API_URL|DATABASE_URL|MAX_|MIN_|TIMEOUT|PORT)/;
+    return node.type === 'VariableDeclaration' && 
+           configPatterns.test(node.declarations[0]?.id?.name);
   }
 }
 
-module.exports = C042NewRuleAnalyzer;
+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;
 ```
 
-3. **Add Configuration**
+✅ 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
-// rules/quality/c042-new-rule/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"]
+  "CXXX": {
+    "engineMappings": {
+      "heuristic": {
+        "implementation": "custom/your-rule",
+        "supportedLanguages": ["typescript", "javascript"]
+      }
+    }
+  }
 }
 ```
 
-4. **Update Registry**
-```javascript
-// Add to config/rules/rules-registry.json
+#### **ESLint Engine Rules**
+
+For JavaScript/TypeScript linting:
+
+1. **Use Existing ESLint Rules**:
+```json
 {
-  "C042": {
-    "id": "C042",
-    "name": "New Rule Name",
-    "category": "quality",
-    "path": "./rules/quality/c042-new-rule",
-    "analyzer": "analyzer.js",
-    "config": "config.json"
+  "CXXX": {
+    "engineMappings": {
+      "eslint": {
+        "rules": ["no-console", "prefer-const"],
+        "config": {
+          "no-console": ["error"],
+          "prefer-const": ["warn"]
+        }
+      }
+    }
   }
 }
 ```
 
-5. **Add Tests**
+2. **Create Custom ESLint Rule** (advanced):
 ```javascript
-// test/fixtures/c042/valid.ts
-// test/fixtures/c042/invalid.ts
-// test/unit/rules/c042.test.js
+// 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 +408,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
 
-# Test multiple rules  
-npm run test:multi
+# Check rule loading for each engine
+npm run test:engines
+```
 
-# Test all quality rules
-npm run test:quality
+### **Test Specific Rules**
+```bash
+# Test specific rule with all engines
+node cli.js --rule=C042 --input=test/fixtures
 
-# Test all security rules
-npm run test:security
+# Test with specific engine
+node cli.js --rule=C042 --engine=heuristic --input=test/fixtures
+node cli.js --rule=C042 --engine=eslint --input=test/fixtures
+node cli.js --rule=C042 --engine=openai --input=test/fixtures
+
+# Test multiple rules
+node cli.js --rule=C006,C019,C042 --input=test/fixtures
 ```
 
-### **Test 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 +466,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 +485,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 +577,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 +630,59 @@ 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
+
 ## 🤝 **Community**
 
 - **Discord**: [Sun Engineering Discord](https://discord.gg/sun-engineering)