@sun-asterisk/sunlint 1.1.7 → 1.2.0

package/core/rule-selection-service.js

@@ -1,25 +1,30 @@
 /**
  * Rule Selection Service
  * Following Rule C005: Single responsibility - only handle rule selection
+ * REFACTORED: Now uses SunlintRuleAdapter instead of direct registry access
  */
 
 const chalk = require('chalk');
 const RuleMappingService = require('./rule-mapping-service');
+const SunlintRuleAdapter = require('./adapters/sunlint-rule-adapter');
 
 class RuleSelectionService {
   constructor() {
-    this.rulesRegistry = null;
+    this.ruleAdapter = SunlintRuleAdapter.getInstance();
     this.ruleMappingService = new RuleMappingService();
+    this.initialized = false;
   }
 
-  async selectRules(config, options) {
-    // Load rules registry
-    try {
-      this.rulesRegistry = require('../config/rules/rules-registry.json');
-    } catch (error) {
-      console.log(chalk.yellow('⚠️  Rules registry not found, using minimal rule set'));
-      this.rulesRegistry = this.getMinimalRuleSet();
+  async initialize() {
+    if (!this.initialized) {
+      await this.ruleAdapter.initialize();
+      this.initialized = true;
     }
+  }
+
+  async selectRules(config, options) {
+    // Ensure adapter is initialized
+    await this.initialize();
     
     const allRules = config.rules || {};
     let selectedRules = [];
@@ -30,27 +35,40 @@ class RuleSelectionService {
     } else if (options.rules) {
       selectedRules = options.rules.split(',').map(r => r.trim());
     } else if (options.all) {
-      // For --all, use all supported rules from both registry and ESLint integration
-      const registryRules = Object.keys(this.rulesRegistry.rules || {});
+      // For --all, use all supported rules from adapter
+      const adapterRules = this.ruleAdapter.getAllRuleIds();
       const eslintSupportedRules = this.ruleMappingService.getSupportedSunLintRules();
       
       // Combine and deduplicate
-      selectedRules = [...new Set([...registryRules, ...eslintSupportedRules])];
+      selectedRules = [...new Set([...adapterRules, ...eslintSupportedRules])];
       
       if (options.verbose) {
-        console.log(chalk.blue(`📋 Found ${selectedRules.length} total rules (${registryRules.length} registry + ${eslintSupportedRules.length} ESLint)`));
+        console.log(chalk.blue(`📋 Found ${selectedRules.length} total rules (${adapterRules.length} adapter + ${eslintSupportedRules.length} ESLint)`));
       }
     } else if (options.quality) {
-      // Handle --quality shortcut
-      const categoryRules = this.getRulesByCategory('quality');
-      selectedRules = categoryRules;
+      // Handle --quality shortcut (standardized approach)
+      const categoryRules = this.ruleAdapter.getStandardCategoryRules('quality');
+      selectedRules = categoryRules.map(rule => rule.id);
+      
+      if (options.verbose) {
+        console.log(chalk.blue(`📋 Selected ${selectedRules.length} quality rules from core files`));
+      }
     } else if (options.security) {
-      // Handle --security shortcut
-      const categoryRules = this.getRulesByCategory('security');
-      selectedRules = categoryRules;
+      // Handle --security shortcut (standardized approach)
+      const categoryRules = this.ruleAdapter.getStandardCategoryRules('security');
+      selectedRules = categoryRules.map(rule => rule.id);
+      
+      if (options.verbose) {
+        console.log(chalk.blue(`📋 Selected ${selectedRules.length} security rules from core files`));
+      }
     } else if (options.category) {
-      const categoryRules = this.getRulesByCategory(options.category);
-      selectedRules = categoryRules;
+      // Handle --category shortcut (standardized approach)
+      const categoryRules = this.ruleAdapter.getStandardCategoryRules(options.category);
+      selectedRules = categoryRules.map(rule => rule.id);
+      
+      if (options.verbose) {
+        console.log(chalk.blue(`📋 Selected ${selectedRules.length} ${options.category} rules from core files`));
+      }
     } else {
       // Default: use config rules or minimal set
       selectedRules = Object.keys(allRules).filter(ruleId => 
@@ -63,12 +81,15 @@ class RuleSelectionService {
     }
 
     // Convert to rule objects
-    return selectedRules.map(ruleId => ({
-      id: ruleId,
-      name: this.getRuleName(ruleId),
-      severity: 'warning',
-      ...((this.rulesRegistry.rules && this.rulesRegistry.rules[ruleId]) || {})
-    })).filter(rule => rule.id);
+    return selectedRules.map(ruleId => {
+      const adapterRule = this.ruleAdapter.getRuleById(ruleId);
+      return {
+        id: ruleId,
+        name: this.getRuleName(ruleId),
+        severity: 'warning',
+        ...(adapterRule || {})
+      };
+    }).filter(rule => rule.id);
   }
 
   getMinimalRuleSet() {
@@ -91,38 +112,14 @@ class RuleSelectionService {
   }
 
   getRulesByCategory(category) {
-    // Get rules from registry if available
-    if (this.rulesRegistry && this.rulesRegistry.categories && this.rulesRegistry.categories[category]) {
-      return this.rulesRegistry.categories[category].rules;
-    }
-    
-    // Fallback to hardcoded mapping
-    const categoryMap = {
-      'quality': [
-        'C002', 'C003', 'C006', 'C010', 'C013', 'C014', 'C017', 'C018', 'C019', 
-        'C023', 'C027', 'C029', 'C030', 'C031', 'C034', 'C035', 'C041', 'C042', 
-        'C043', 'C047', 'C048', 'C076', 'T002', 'T003', 'T004', 'T007', 'T011', 
-        'T019', 'T025', 'T026'
-      ],
-      'security': ['S001', 'S002', 'S003', 'S005', 'S006', 'S007', 'S008', 'S009', 'S010', 'S011', 'S012', 'S013', 'S014', 'S015', 'S016', 'S017', 'S018', 'S019', 'S020', 'S022', 'S023', 'S025', 'S026', 'S027', 'S029', 'S030', 'S033', 'S034', 'S035', 'S036', 'S037', 'S038', 'S039', 'S041', 'S042', 'S043', 'S044', 'S045', 'S046', 'S047', 'S048', 'S050', 'S052', 'S054', 'S055', 'S057', 'S058'],
-      'naming': ['C006'],
-      'logging': ['C019', 'S057'],
-      'validation': ['C031', 'S018', 'S025', 'S026']
-    };
-    
-    return categoryMap[category] || [];
+    // Use adapter to get rules by category
+    return this.ruleAdapter.getRulesByCategory(category).map(rule => rule.id);
   }
 
   getRuleName(ruleId) {
-    const ruleNames = {
-      'C006': 'Function Naming Convention',
-      'C019': 'Log Level Usage',
-      'C002': 'No Duplicate Code',
-      'C003': 'No Vague Abbreviations',
-      'C029': 'Catch Block Logging'
-    };
-    
-    return ruleNames[ruleId] || `Rule ${ruleId}`;
+    // Use adapter to get rule name
+    const rule = this.ruleAdapter.getRuleById(ruleId);
+    return rule ? rule.name : `Rule ${ruleId}`;
   }
 }
 

package/docs/CONFIGURATION.md

@@ -2,6 +2,28 @@
 
 This document provides a comprehensive guide to all SunLint configuration options.
 
+## 🏗️ Architecture Overview
+
+SunLint uses a **unified adapter pattern** for rule management, ensuring consistency between CLI and VSCode extension:
+
+### Rule Access Architecture
+```
+CLI Tools → SunlintRuleAdapter → Rule Sources (Registry + Origin Rules)
+     ↓              ↓
+VSCode Extension → RuleReaderService → Rule Sources (Registry + Origin Rules)
+```
+
+### Key Benefits
+- **Unified Rule Model**: Both CLI and extension use the same rule access pattern
+- **No Direct Parser Access**: All rule queries go through adapter layer
+- **AI Context Consistency**: OpenAI integration gets correct context from origin-rules
+- **Extensible**: Easy to add new rule sources or engines
+
+### Rule Sources Priority
+1. **Primary**: `config/rules/rules-registry-generated.json` (auto-generated from origin-rules)
+2. **Fallback**: `origin-rules/*.md` files (direct markdown parsing)
+3. **Cache**: Memory cache for performance optimization
+
 ## 📋 Quick Start
 
 Create `.sunlint.json` in your project root:
@@ -248,9 +270,38 @@ Below is the full configuration schema with all available options and their desc
 - `@sun/sunlint/ci` - Optimized for CI/CD environments
 
 ### Engine Selection
-- `heuristic` - SunLint's native analysis engine (default)
-- `eslint` - ESLint-based analysis
-- `ai` - AI-powered analysis (future feature)
+
+SunLint supports multiple analysis engines with automatic rule compatibility detection:
+
+- `heuristic` - SunLint's native pattern-based analysis engine (default)
+  - **Coverage**: 244/256 rules (95.3%)
+  - **Performance**: Fast, low memory usage
+  - **Languages**: All supported languages
+  - **Best for**: General analysis, CI/CD pipelines
+
+- `eslint` - ESLint-based analysis with automatic rule mapping
+  - **Coverage**: 17/256 rules (6.6%)
+  - **Performance**: Moderate, requires ESLint dependencies
+  - **Languages**: JavaScript, TypeScript, JSX, TSX
+  - **Best for**: Projects already using ESLint
+
+- `ai` - AI-powered analysis using OpenAI/LLMs
+  - **Coverage**: 256/256 rules (100%)
+  - **Performance**: Slower, requires API access
+  - **Languages**: All supported languages
+  - **Best for**: Complex context analysis, legacy code review
+
+### Engine Architecture
+
+```
+Analysis Orchestrator
+├── SunlintRuleAdapter (unified rule access)
+├── Heuristic Engine (pattern matching)
+├── ESLint Engine (integration layer)
+└── AI Engine (LLM integration)
+```
+
+**Auto-Engine Selection**: SunLint automatically selects the best engine for each rule based on compatibility and performance.
 
 ## 🎯 Common Configuration Examples
 
@@ -412,3 +463,60 @@ Engine preferences:
 - **R*** rules: ESLint → Heuristic → AI
 - **C*** rules: Heuristic → ESLint → AI  
 - **T*** rules: ESLint → Heuristic → AI
+
+## 🚀 Performance & Architecture Benefits
+
+### Adapter Pattern Benefits
+- **Unified Rule Access**: Both CLI and VSCode extension use the same adapter layer
+- **No Model Duplication**: Single rule model across all tools
+- **Memory Efficiency**: Singleton pattern prevents duplicate instances
+- **Fast Queries**: 0.07ms average per rule query with caching
+
+### Rule Loading Performance
+- **Registry Loading**: 256 rules in ~10ms
+- **Memory Cache**: Rules cached after first load
+- **Fallback Support**: Automatic fallback to origin-rules if registry unavailable
+
+### Engine Performance Comparison
+| Engine | Rules Coverage | Speed | Memory | Best Use Case |
+|--------|---------------|-------|---------|--------------|
+| Heuristic | 244/256 (95.3%) | Fast | Low | CI/CD, general analysis |
+| ESLint | 17/256 (6.6%) | Moderate | Medium | Existing ESLint projects |
+| AI | 256/256 (100%) | Slow | High | Complex analysis, legacy code |
+
+### Architecture Validation
+```bash
+# Test adapter performance and coverage
+npx sunlint --test-adapter
+
+# Show engine compatibility for specific rules
+npx sunlint --show-engines --rules=C010,R001,S005
+
+# Verbose mode shows adapter and engine selection
+npx sunlint --verbose --rules=C010,C020 --input=src
+```
+
+## 🔧 Development & Debugging
+
+### Internal Architecture Access
+For development and debugging, SunLint exposes internal adapter methods:
+
+```javascript
+// Access the rule adapter (for extensions or custom tools)
+const SunlintRuleAdapter = require('@sun/sunlint/core/adapters/sunlint-rule-adapter');
+
+const adapter = SunlintRuleAdapter.getInstance();
+await adapter.initialize();
+
+// Get all rules with metadata
+const allRules = adapter.getAllRules();
+
+// Generate AI context for specific rules
+const aiContext = adapter.generateAIContext(['C010', 'C020']);
+
+// Check engine compatibility
+const heuristicRules = adapter.getRulesByEngine('heuristic');
+```
+
+### VSCode Extension Integration
+The SunLint VSCode extension uses the same adapter pattern via `RuleReaderService`, ensuring complete consistency between CLI and editor experience.

package/docs/LANGUAGE-SPECIFIC-RULES.md

@@ -0,0 +1,308 @@
+# Language-Specific Rules Configuration Guide
+
+## Overview
+This guide explains how to configure language-specific rules in SunLint projects. Language-specific rules are **opt-in** and must be explicitly enabled via project configuration.
+
+## Core vs Language-Specific Rules
+
+### Core Rules (Always Available)
+- **Files**: `common-en.md`, `security-en.md`
+- **Count**: 135 rules
+- **Usage**: Included in category commands (`--security`, `--quality`)
+- **Scope**: Universal rules applicable to all languages
+
+### Language-Specific Rules (Opt-In)
+- **Files**: `typescript-en.md`, `reactjs-en.md`, `java-en.md`, etc.
+- **Count**: 121 rules
+- **Usage**: Must be enabled via project config
+- **Scope**: Rules specific to particular languages/frameworks
+
+## Configuration Methods
+
+### 1. Project Configuration (.sunlint.json)
+
+Create or edit `.sunlint.json` in your project root:
+
+```json
+{
+  "rules": [
+    "TS001",
+    "TS002", 
+    "REACT001"
+  ],
+  "presets": ["typescript", "reactjs"],
+  "categories": ["security", "quality"]
+}
+```
+
+### 2. Package.json Configuration
+
+Add sunlint config to your `package.json`:
+
+```json
+{
+  "sunlint": {
+    "rules": ["TS001", "TS002"],
+    "presets": ["typescript"],
+    "categories": ["security"]
+  }
+}
+```
+
+### 3. CLI Rule Selection
+
+Use CLI flags for one-time rule selection:
+
+```bash
+# Specific language rules
+sunlint --rules="TS001,TS002,REACT001"
+
+# Mix core categories with specific rules  
+sunlint --security --rules="TS001,TS002"
+
+# Use presets
+sunlint --preset=typescript
+```
+
+## Available Language-Specific Rules
+
+### TypeScript Rules (typescript-en.md)
+```bash
+# Example TypeScript-specific rules
+TS001 - TypeScript strict mode enforcement
+TS002 - Type assertion guidelines
+TS003 - Interface vs type usage
+# ... more TypeScript rules
+```
+
+### React Rules (reactjs-en.md)
+```bash
+# Example React-specific rules
+REACT001 - Component prop validation
+REACT002 - State mutation prevention
+REACT003 - Effect dependency handling
+# ... more React rules
+```
+
+### Java Rules (java-en.md)
+```bash
+# Example Java-specific rules
+JAVA001 - Exception handling patterns
+JAVA002 - Thread safety guidelines
+JAVA003 - Memory management best practices
+# ... more Java rules
+```
+
+## Configuration Examples
+
+### TypeScript Project
+```json
+{
+  "presets": ["typescript"],
+  "categories": ["security", "quality"],
+  "rules": [
+    "TS001",
+    "TS005", 
+    "TS010"
+  ]
+}
+```
+
+### React + TypeScript Project
+```json
+{
+  "presets": ["typescript", "reactjs"],
+  "categories": ["security"],
+  "rules": [
+    "TS001",
+    "REACT001",
+    "REACT005"
+  ]
+}
+```
+
+### Multi-Language Project
+```json
+{
+  "presets": ["typescript", "java"],
+  "categories": ["security", "quality"],
+  "rules": [
+    "TS001",
+    "JAVA001",
+    "JAVA010"
+  ]
+}
+```
+
+## Rule Priority System
+
+SunLint follows this priority order:
+
+1. **CLI `--rule`** (highest priority)
+2. **CLI `--rules`** 
+3. **CLI `--category`** (core rules only)
+4. **Project config file** (lowest priority)
+
+### Example Priority Resolution
+```bash
+# Command: sunlint --security --rules="TS001,TS002" --rule="CUSTOM001"
+# Result: Only CUSTOM001 is used (--rule overrides everything)
+
+# Command: sunlint --security --rules="TS001,TS002"  
+# Result: TS001, TS002 are used (--rules overrides --security)
+
+# Command: sunlint --security
+# Result: 60 core security rules are used
+```
+
+## Preset Configurations
+
+Presets provide curated rule collections for specific languages:
+
+### Creating Custom Presets
+```json
+// config/presets/my-typescript-preset.json
+{
+  "rules": [
+    "TS001", "TS002", "TS005",
+    "S001", "S010", "S020",
+    "C001", "C005", "C010"
+  ],
+  "description": "Custom TypeScript preset with security focus"
+}
+```
+
+### Using Presets
+```bash
+# CLI usage
+sunlint --preset=my-typescript-preset
+
+# Project config usage
+{
+  "presets": ["my-typescript-preset"]
+}
+```
+
+## Best Practices
+
+### 1. Start with Core Categories
+Begin with core categories, then add language-specific rules:
+```json
+{
+  "categories": ["security", "quality"],
+  "rules": ["TS001", "TS002"]
+}
+```
+
+### 2. Use Presets for Common Configurations
+Create and reuse presets for consistent team configurations:
+```json
+{
+  "presets": ["team-typescript", "security-strict"]
+}
+```
+
+### 3. Gradual Rule Adoption
+Add language-specific rules incrementally:
+```json
+{
+  "categories": ["security"],
+  "rules": [
+    // Week 1: Start with essential rules
+    "TS001",
+    
+    // Week 2: Add more specific rules
+    "TS002", "TS005",
+    
+    // Week 3: Add advanced rules
+    "TS010", "TS015"
+  ]
+}
+```
+
+### 4. Document Team Standards
+Create team-specific documentation:
+```json
+{
+  "presets": ["team-standard"],
+  "description": "Our team's agreed-upon rule set",
+  "rules": ["TS001", "TS002", "REACT001"]
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Language Rules Not Applied
+**Problem**: Language-specific rules don't appear in results
+**Solution**: Check that rules are in project config, not just CLI categories
+
+```bash
+# This only uses core rules
+sunlint --security  
+
+# This includes language-specific rules
+sunlint --security --rules="TS001,TS002"
+```
+
+#### 2. Rule Conflicts
+**Problem**: Different tools report different rule counts
+**Solution**: Verify same configuration is used everywhere
+
+```json
+// Ensure consistent config across tools
+{
+  "presets": ["typescript"],
+  "categories": ["security"]
+}
+```
+
+#### 3. Missing Rules
+**Problem**: Expected rules don't appear
+**Solution**: Check rule priority and configuration merge
+
+```bash
+# Debug with verbose output
+sunlint --verbose --security
+```
+
+## Migration from Legacy Configuration
+
+### Old Approach (Deprecated)
+```json
+{
+  "includeLanguageRules": true,
+  "language": "typescript"
+}
+```
+
+### New Approach (Recommended)
+```json
+{
+  "presets": ["typescript"],
+  "categories": ["security", "quality"]
+}
+```
+
+## Validation
+
+Test your configuration:
+
+```bash
+# Verify rule selection
+sunlint --input=src --verbose
+
+# Test specific configuration
+sunlint --config=.sunlint.json --verbose
+
+# Validate rule counts
+node test-category-filtering.js
+```
+
+## Related Documentation
+
+- [Standardized Category Filtering](./STANDARDIZED-CATEGORY-FILTERING.md)
+- [Configuration Guide](./CONFIGURATION.md)
+- [Preset System](./PRESETS.md)
+- [CLI Commands](./COMMAND-EXAMPLES.md)

package/docs/README.md

@@ -28,5 +28,8 @@
 
 ## Configuration
 
+- **[Configuration Guide](CONFIGURATION.md)** - Complete configuration reference
+- **[Standardized Category Filtering](STANDARDIZED-CATEGORY-FILTERING.md)** - Core vs language-specific rules
+- **[Language-Specific Rules](LANGUAGE-SPECIFIC-RULES.md)** - How to configure language-specific rules
 - **[.sunlint-simple.json](../.sunlint-simple.json)** - Simple configuration example
 - **[sunlint.config.json](../sunlint.config.json)** - Full configuration with all features