@sun-asterisk/sunlint 1.1.8 → 1.2.0

package/docs/STANDARDIZED-CATEGORY-FILTERING.md

@@ -0,0 +1,156 @@
+# Standardized Category Filtering
+
+## Overview
+SunLint implements standardized category filtering to ensure consistent behavior between CLI and VSCode extension. Category commands (like `--security`, `--quality`) now use a unified approach that only includes rules from core files.
+
+## Core Principles
+
+### 1. Core Files Only
+Category filtering exclusively uses rules from core files:
+- `common-en.md` - Universal quality and security rules
+- `security-en.md` - Specialized security rules
+- Language-specific files (typescript-en.md, etc.) are **excluded** from category commands
+
+### 2. Language-Specific Rules are Opt-In
+- Language-specific rules are not included in category commands by default
+- Must be explicitly enabled via project configuration
+- This ensures category commands remain language-agnostic
+
+### 3. Principle-Based Filtering
+Rules are filtered by their `principle` field based on actual rule catalog:
+- `--security` → includes rules with principle: "SECURITY"
+- `--quality` → includes rules with principle: "CODE_QUALITY"
+
+Available principles in rule catalog:
+- **SECURITY** - Security-focused rules
+- **CODE_QUALITY** - Code quality and maintainability
+- **PERFORMANCE** - Performance optimization rules  
+- **MAINTAINABILITY** - Code maintainability rules
+- **TESTABILITY** - Testing and testability rules
+- **RELIABILITY** - System reliability rules
+- **DESIGN_PATTERNS** - Design pattern compliance
+- **INTEGRATION** - Integration best practices
+- **USABILITY** - User experience and usability
+
+## Implementation
+
+### SunlintRuleAdapter Methods
+
+```javascript
+// Get rules for standardized category filtering (core files only)
+getStandardCategoryRules(category) {
+  const coreRules = this.getCoreRules();
+  return coreRules.filter(rule => rule.principle === category);
+}
+
+// Category mapping based on actual principles
+const categoryPrincipleMap = {
+  'security': ['SECURITY'],
+  'quality': ['CODE_QUALITY'], 
+  'performance': ['PERFORMANCE'],
+  'maintainability': ['MAINTAINABILITY'],
+  'testability': ['TESTABILITY'],
+  'reliability': ['RELIABILITY'],
+  'design': ['DESIGN_PATTERNS'],
+  'integration': ['INTEGRATION'],
+  'usability': ['USABILITY']
+};
+```
+
+### CLI Integration
+
+The rule selection service now uses standardized category filtering:
+
+```javascript
+// core/rule-selection-service.js
+const rules = adapter.getStandardCategoryRules(category);
+console.log(`📋 Selected ${rules.length} ${category} rules from core files`);
+```
+
+## Rule Counts
+
+Based on current rule catalog:
+- **Total rules**: 256
+- **Core rules**: 135 (common-en.md + security-en.md)
+- **Security rules (core only)**: 60 rules
+- **Quality rules (core only)**: 112 rules
+- **Language-specific rules**: 121 rules (excluded from categories)
+
+## Usage Examples
+
+### CLI Commands
+```bash
+# Uses 60 security rules from core files only
+sunlint --input=src --security
+
+# Uses 112 quality rules from core files only  
+sunlint --input=src --quality
+
+# Custom rule selection (can include language-specific)
+sunlint --input=src --rules="TS001,TS002,S001"
+
+# Future categories (when CLI support is added)
+sunlint --input=src --performance
+sunlint --input=src --maintainability
+```
+
+### Project Configuration
+To include language-specific rules, use project config:
+
+```json
+{
+  "rules": ["TS001", "TS002"],
+  "presets": ["typescript", "security"]
+}
+```
+
+## Benefits
+
+### 1. Consistency
+- CLI and VSCode extension use identical rule selection logic
+- Predictable behavior across all interfaces
+
+### 2. Maintainability
+- Single source of truth for category definitions
+- Easy to add new categories or core rules
+
+### 3. Extensibility
+- Clear separation between core and language-specific rules
+- Framework for adding new languages without breaking existing categories
+
+### 4. Performance
+- Reduced rule count for category commands
+- Faster analysis for common security/quality checks
+
+## Migration from Legacy System
+
+### Before (Legacy)
+- Category commands included all rules matching principle
+- Language-specific rules were included by default
+- Different behavior between CLI and VSCode extension
+
+### After (Standardized)
+- Category commands use core files only
+- Language-specific rules are opt-in via config
+- Unified behavior across all interfaces
+
+## Validation
+
+Use the test script to validate category filtering:
+
+```bash
+node test-category-filtering.js
+```
+
+Expected output:
+- Core rules: 135
+- Security rules (core): 60  
+- Quality rules (core): 112
+- All tests pass ✅
+
+## Related Files
+
+- `core/adapters/sunlint-rule-adapter.js` - Main implementation
+- `core/rule-selection-service.js` - CLI integration
+- `test-category-filtering.js` - Validation script
+- `config/presets/recommended.json` - Updated preset config

package/engines/heuristic-engine.js

@@ -8,6 +8,7 @@
 const AnalysisEngineInterface = require('../core/interfaces/analysis-engine.interface');
 const ASTModuleRegistry = require('../core/ast-modules/index');
 const dependencyChecker = require('../core/dependency-checker');
+const SunlintRuleAdapter = require('../core/adapters/sunlint-rule-adapter');
 const fs = require('fs');
 const path = require('path');
 
@@ -17,7 +18,7 @@ class HeuristicEngine extends AnalysisEngineInterface {
     
     this.ruleAnalyzers = new Map();
     this.supportedRulesList = [];
-    this.rulesRegistry = {};
+    this.ruleAdapter = SunlintRuleAdapter.getInstance();
     this.astRegistry = ASTModuleRegistry;
   }
 
@@ -34,8 +35,8 @@ class HeuristicEngine extends AnalysisEngineInterface {
       // Check for optional AST dependencies
       dependencyChecker.checkAndNotify('ast');
       
-      // Load rules registry
-      await this.loadRulesRegistry(config);
+      // Initialize rule adapter
+      await this.ruleAdapter.initialize();
       
       // Scan for available rule analyzers
       await this.scanRuleAnalyzers(config);
@@ -51,30 +52,6 @@ class HeuristicEngine extends AnalysisEngineInterface {
     }
   }
 
-  /**
-   * Load rules registry configuration
-   * Following Rule C006: Verb-noun naming
-   */
-  async loadRulesRegistry(config = {}) {
-    try {
-      const registryPath = path.resolve(__dirname, '../config/rules/rules-registry.json');
-      if (fs.existsSync(registryPath)) {
-        this.rulesRegistry = require(registryPath);
-        if (config.verbose) {
-        if (this.verbose) {
-          console.log('📋 Loaded rules registry');
-        }
-        }
-      } else {
-        console.warn('⚠️ Rules registry not found, using minimal support');
-        this.rulesRegistry = { rules: {} };
-      }
-    } catch (error) {
-      console.warn('⚠️ Failed to load rules registry:', error.message);
-      this.rulesRegistry = { rules: {} };
-    }
-  }
-
   /**
    * Scan for available rule analyzers
    * Following Rule C006: Verb-noun naming
@@ -324,10 +301,10 @@ class HeuristicEngine extends AnalysisEngineInterface {
    * @returns {string[]} Supported languages
    */
   getRuleLanguages(rule) {
-    // Get from rules registry
-    const registryRule = this.rulesRegistry.rules?.[rule.id];
-    if (registryRule?.languages) {
-      return registryRule.languages;
+    // Get from rule adapter
+    const adapterRule = this.ruleAdapter.getRuleById(rule.id);
+    if (adapterRule?.languages) {
+      return adapterRule.languages;
     }
 
     // Fallback to rule object