@sun-asterisk/sunlint 1.0.7 → 1.1.4

package/docs/ESLINT-INTEGRATION-STRATEGY.md

@@ -0,0 +1,392 @@
+# 🎯 SunLint vs ESLint Integration Strategy Analysis
+
+## 📊 **Current Situation Assessment**
+
+### **Team Assets:**
+- ✅ **29+ mature ESLint custom rules** đã được team phát triển
+- ✅ **Production-ready** codebase với nhiều contributors  
+- ✅ **Comprehensive coverage** for TypeScript
+- ✅ **Established workflow** với ESLint integration
+
+### **SunLint Unique Value:**
+- ✅ **Multi-language support** (TypeScript, Dart, Kotlin)
+- ✅ **AI-powered analysis** capabilities
+- ✅ **Specialized rules** (C019, C029, C031) không có trong ESLint
+- ✅ **CI/CD optimization** features
+
+### **Overlap Analysis:**
+| Rule | ESLint Custom | SunLint | Status |
+|------|---------------|---------|--------|
+| **C003** | ✅ Mature | ❌ Không có | ESLint wins |
+| **C006** | ✅ Mature | ✅ Basic | ESLint better |
+| **C019** | ❌ Không có | ✅ Specialized | SunLint unique |
+| **C029** | ✅ c029, c035 | ✅ Specialized | Both have |
+| **C031** | ❌ Không có | ✅ Specialized | SunLint unique |
+
+## 🎯 **SOLUTION ANALYSIS**
+
+### **Solution 1: Makefile Integration**
+```bash
+# Makefile approach
+.PHONY: lint
+lint: lint-eslint lint-sunlint
+
+lint-eslint:
+	cd coding-quality/config/typescript && ./run.sh
+
+lint-sunlint:  
+	cd coding-quality/extensions/sunlint && node cli.js --all --input=src
+
+lint-report:
+	$(MAKE) lint-eslint --json > eslint-report.json
+	$(MAKE) lint-sunlint --format=json > sunlint-report.json
+	node merge-reports.js eslint-report.json sunlint-report.json
+```
+
+**✅ Pros:**
+- ✅ **Zero migration cost** - giữ nguyên existing work
+- ✅ **Fast implementation** - 1-2 days setup
+- ✅ **Parallel execution** - có thể chạy concurrent
+- ✅ **Tool independence** - mỗi tool độc lập
+- ✅ **Team harmony** - không ảnh hưởng existing work
+
+**❌ Cons:**
+- ❌ **Fragmented results** - cần merge reports
+- ❌ **Duplicated overhead** - chạy 2 tools
+- ❌ **Configuration drift** - 2 sets of configs
+- ❌ **Learning curve** - team cần biết cả 2 tools
+
+**🎯 Score: 7/10** - Good short-term solution
+
+---
+
+### **Solution 2: Keep Separate Tools**
+```bash
+# Current approach - no changes
+npm run lint:eslint
+npm run lint:sunlint  
+```
+
+**✅ Pros:**
+- ✅ **No migration cost**
+- ✅ **Maximum flexibility**
+- ✅ **Tool specialization**
+- ✅ **Zero risk**
+
+**❌ Cons:**
+- ❌ **Manual coordination**
+- ❌ **Inconsistent adoption**
+- ❌ **Results fragmentation**
+- ❌ **CI/CD complexity**
+
+**🎯 Score: 5/10** - Status quo, but not scalable
+
+---
+
+### **Solution 3A: ESLint Plugin for SunLint**
+```bash
+# Embed ESLint rules into SunLint
+node cli.js --all --include-eslint --input=src
+```
+
+**✅ Pros:**
+- ✅ **Unified command** - single entry point
+- ✅ **Leverage existing rules** - 29+ rules preserved
+- ✅ **Fast to implement** - ESLint integration
+- ✅ **Consistent output** - single report format
+
+**❌ Cons:**
+- ❌ **TypeScript only** - hard to extend to Dart/Kotlin
+- ❌ **ESLint dependency** - adds complexity
+- ❌ **Performance overhead** - running ESLint inside SunLint
+- ❌ **Limited AI integration** - ESLint rules can't use AI
+
+**🎯 Score: 6/10** - Quick fix but not scalable
+
+---
+
+### **Solution 3B: Migrate ESLint Rules to SunLint**
+```bash
+# Pure SunLint approach
+node cli.js --all --input=src  # All rules in SunLint
+```
+
+**✅ Pros:**
+- ✅ **Unified architecture** - single system
+- ✅ **Multi-language ready** - Dart, Kotlin support
+- ✅ **AI integration** - all rules can use AI
+- ✅ **Performance optimized** - single pass analysis
+- ✅ **Future-proof** - scalable architecture
+
+**❌ Cons:**
+- ❌ **High migration cost** - 3-6 months effort
+- ❌ **Team disruption** - major workflow change
+- ❌ **Risk of regression** - might miss edge cases
+- ❌ **Doesn't acknowledge team effort** - feels like "starting over"
+
+**🎯 Score: 8/10** - Best long-term but expensive
+
+## 🏆 **RECOMMENDED SOLUTION: Hybrid Evolution Strategy**
+
+### **Phase 1: Immediate Integration (1-2 weeks)**
+```bash
+# Enhanced Makefile + Report Merger
+make lint-all    # Runs both ESLint + SunLint  
+make lint-report # Unified JSON report
+```
+
+**Implementation:**
+```makefile
+# Makefile
+.PHONY: lint-all lint-eslint lint-sunlint lint-report
+
+lint-all: lint-eslint lint-sunlint
+
+lint-eslint:
+	@echo "🔍 Running ESLint analysis..."
+	cd coding-quality/config/typescript && \
+	./run.sh --json --export-json --json-file ../../extensions/sunlint/eslint-results.json $(INPUT)
+
+lint-sunlint:
+	@echo "☀️ Running SunLint analysis..."
+	cd coding-quality/extensions/sunlint && \
+	node cli.js --all --input=$(INPUT) --format=json --output=sunlint-results.json --no-ai
+
+lint-report: lint-all
+	@echo "📊 Generating unified report..."
+	cd coding-quality/extensions/sunlint && \
+	node scripts/merge-reports.js eslint-results.json sunlint-results.json --output=unified-report.json
+	@echo "✅ Unified report: unified-report.json"
+
+# Usage
+INPUT ?= src
+lint: lint-all
+```
+
+### **Phase 2: SunLint ESLint Adapter (1-2 months)**
+```javascript
+// SunLint với ESLint integration
+node cli.js --all --include-eslint --eslint-config=../config/typescript/.eslintrc.cjs --input=src
+```
+
+**Implementation Strategy:**
+1. **ESLint Runner Integration** trong SunLint
+2. **Report normalization** - convert ESLint output to SunLint format
+3. **Unified configuration** - single config controls both
+4. **Gradual migration** - opt-in per rule
+
+### **Phase 3: Selective Migration (3-6 months)**
+```javascript
+// Migrate high-value rules only
+const migrationPriority = {
+  immediate: ['c003', 'c006'], // High overlap with SunLint
+  later: ['c010', 'c013'],     // Complex but valuable  
+  keep_eslint: ['t002', 't003'] // TypeScript-specific
+};
+```
+
+**Migration Strategy:**
+1. **Automated conversion tools** - convert ESLint AST → SunLint patterns
+2. **A/B testing** - run both versions, compare results
+3. **Gradual rollout** - migrate 2-3 rules per sprint
+4. **Team validation** - original authors review migrations
+
+## 🎯 **DETAILED IMPLEMENTATION PLAN**
+
+### **Week 1-2: Quick Win (Makefile + Report Merger)**
+
+#### **Step 1: Enhanced Makefile**
+```makefile
+# coding-quality/Makefile
+include config/typescript/eslint.mk
+include extensions/sunlint/sunlint.mk
+
+.PHONY: install lint lint-quick lint-full ci-lint
+
+install:
+	cd config/typescript && npm install
+	cd extensions/sunlint && npm install
+
+lint-quick: lint-sunlint-changed
+lint-full: lint-eslint lint-sunlint-all  
+lint: lint-full
+
+ci-lint:
+	$(MAKE) lint-full INPUT=src FORMAT=github
+	node scripts/ci-report.js
+
+# Development shortcuts
+lint-staged:
+	$(MAKE) lint-sunlint-staged
+	
+lint-pr: 
+	$(MAKE) lint-sunlint-changed BASE=origin/main
+```
+
+#### **Step 2: Report Merger Script**
+```javascript
+// scripts/merge-reports.js
+const fs = require('fs');
+const path = require('path');
+
+class ReportMerger {
+  mergeReports(eslintReport, sunlintReport) {
+    return {
+      tools: {
+        eslint: this.normalizeESLintReport(eslintReport),
+        sunlint: this.normalizeSunLintReport(sunlintReport)
+      },
+      summary: this.generateSummary(eslintReport, sunlintReport),
+      violations: this.mergeViolations(eslintReport, sunlintReport),
+      metadata: {
+        timestamp: new Date().toISOString(),
+        tools_version: {
+          eslint: this.getESLintVersion(),
+          sunlint: this.getSunLintVersion()
+        }
+      }
+    };
+  }
+
+  generateSummary(eslint, sunlint) {
+    return {
+      total_files: this.getTotalFiles(eslint, sunlint),
+      total_violations: this.getTotalViolations(eslint, sunlint),
+      by_severity: this.mergeSeverities(eslint, sunlint),
+      by_tool: {
+        eslint: this.getToolSummary(eslint),
+        sunlint: this.getToolSummary(sunlint)
+      }
+    };
+  }
+}
+```
+
+### **Month 1-2: ESLint Integration**
+
+#### **Step 1: SunLint ESLint Adapter**
+```javascript
+// core/eslint-adapter.js
+class ESLintAdapter {
+  constructor(eslintConfigPath) {
+    this.eslintConfigPath = eslintConfigPath;
+    this.eslint = require('eslint');
+  }
+
+  async runESLintRules(files, options) {
+    const engine = new this.eslint.ESLint({
+      configFile: this.eslintConfigPath,
+      useEslintrc: false
+    });
+
+    const results = await engine.lintFiles(files);
+    return this.convertToSunLintFormat(results);
+  }
+
+  convertToSunLintFormat(eslintResults) {
+    return eslintResults.map(result => ({
+      file: result.filePath,
+      violations: result.messages.map(msg => ({
+        ruleId: `eslint/${msg.ruleId}`,
+        line: msg.line,
+        column: msg.column,
+        message: msg.message,
+        severity: this.mapSeverity(msg.severity),
+        source: 'eslint'
+      }))
+    }));
+  }
+}
+```
+
+#### **Step 2: Enhanced CLI Options**
+```javascript
+// cli.js enhancements
+program
+  .option('--include-eslint', 'Include ESLint custom rules')
+  .option('--eslint-config <path>', 'ESLint config file path')
+  .option('--eslint-only', 'Run only ESLint rules')
+  .option('--sunlint-only', 'Run only SunLint rules')
+  .option('--tool-comparison', 'Run both tools and compare results');
+```
+
+### **Month 3-6: Selective Migration**
+
+#### **Migration Priority Matrix:**
+```javascript
+const migrationPlan = {
+  // High priority - good candidates for migration
+  immediate: {
+    'c003': {
+      reason: 'Variable naming - core feature',
+      complexity: 'medium',
+      ai_potential: 'high',
+      estimated_effort: '1 week'
+    },
+    'c006': {
+      reason: 'Function naming - already exists in SunLint',
+      complexity: 'low', 
+      ai_potential: 'medium',
+      estimated_effort: '3 days'
+    }
+  },
+  
+  // Medium priority - valuable but complex
+  later: {
+    'c010': {
+      reason: 'Block nesting - architectural rule',
+      complexity: 'high',
+      ai_potential: 'high', 
+      estimated_effort: '2 weeks'
+    },
+    'c013': {
+      reason: 'Dead code - useful across languages',
+      complexity: 'high',
+      ai_potential: 'very_high',
+      estimated_effort: '3 weeks'
+    }
+  },
+  
+  // Keep in ESLint - TypeScript specific
+  keep_eslint: {
+    't002': { reason: 'Interface prefix - TS specific syntax' },
+    't003': { reason: 'TS ignore reason - TS compiler specific' },
+    't004': { reason: 'Interface public only - TS type system' }
+  }
+};
+```
+
+## 📊 **COST-BENEFIT ANALYSIS**
+
+| Solution | Implementation Time | Maintenance Cost | Team Disruption | Long-term Value |
+|----------|-------------------|------------------|-----------------|-----------------|
+| **Makefile** | 1-2 weeks | Low | Minimal | Medium |
+| **ESLint Integration** | 1-2 months | Medium | Low | High |
+| **Full Migration** | 3-6 months | Low | High | Very High |
+| **Hybrid Evolution** | 3-4 months total | Medium | Gradual | Very High |
+
+## 🎯 **FINAL RECOMMENDATION**
+
+### **🏆 Choose: Hybrid Evolution Strategy**
+
+**Rationale:**
+1. **Preserves team effort** - ESLint rules remain valuable
+2. **Immediate benefits** - unified reporting in weeks  
+3. **Future flexibility** - gradual migration path
+4. **Risk mitigation** - incremental changes
+5. **Team buy-in** - respects existing work
+
+**Success Metrics:**
+- ✅ **Week 2**: Unified report generation  
+- ✅ **Month 1**: Single command execution
+- ✅ **Month 2**: ESLint integration in SunLint
+- ✅ **Month 6**: 50% rules migrated to SunLint
+- ✅ **Year 1**: Multi-language support with migrated rules
+
+**Key Decision Factors:**
+- ✅ **Team productivity** > tool purity
+- ✅ **Incremental value** > big bang approach  
+- ✅ **Respect existing work** > reinvent everything
+- ✅ **Multi-language future** > TypeScript-only optimization
+
+This strategy acknowledges your team's investment while building toward a unified, scalable future! 🚀

package/docs/ESLINT_INTEGRATION.md

@@ -0,0 +1,238 @@
+# ESLint Integration Feature
+
+## 🎯 **Overview**
+
+SunLint ESLint Integration cho phép teams **merge** existing ESLint configuration với SunLint rules trong **single execution pipeline**. Thay vì chạy parallel, SunLint sẽ **orchestrate** và **combine** cả 2 rule sets.
+
+### **Problem Solved**
+- ✅ Teams có existing ESLint (20 rules) + muốn add SunLint (93 rules) = **113 rules total**
+- ✅ Single command execution thay vì multiple tool chains
+- ✅ No degradation của existing ESLint workflow
+- ✅ Combined reporting cho easier debugging
+
+## 📖 **Configuration**
+
+### **Method 1: package.json Configuration**
+```json
+{
+  "scripts": {
+    "lint:integrated": "sunlint --all --eslint-integration --input=src"
+  },
+  "sunlint": {
+    "eslintIntegration": {
+      "enabled": true,
+      "mergeRules": true,
+      "preserveUserConfig": true
+    },
+    "rules": {
+      "C006": "warn",
+      "C019": "error"
+    }
+  }
+}
+```
+
+### **Method 2: .sunlint.json Configuration**
+```json
+{
+  "eslintIntegration": {
+    "enabled": true,
+    "mergeRules": true,
+    "preserveUserConfig": true,
+    "runAfterSunLint": false
+  },
+  "rules": {
+    "C006": "warn", 
+    "C019": "error",
+    "S047": "warn"
+  }
+}
+```
+
+### **Method 3: CLI Flags**
+```bash
+# Enable integration
+sunlint --all --eslint-integration --input=src
+
+# Merge rules (default: true)
+sunlint --all --eslint-integration --eslint-merge-rules --input=src
+
+# Preserve user config (default: true) 
+sunlint --all --eslint-integration --eslint-preserve-config --input=src
+
+# Run ESLint after SunLint (alternative to merge)
+sunlint --all --eslint-integration --eslint-run-after --input=src
+```
+
+## 🔧 **Integration Modes**
+
+### **Mode 1: Merged Execution (Default)**
+```bash
+sunlint --all --eslint-integration --input=src
+```
+
+**How it works:**
+1. SunLint discovers existing `.eslintrc.json`
+2. Merges SunLint rules + User ESLint rules
+3. Creates combined ESLint configuration
+4. Runs single ESLint execution with **merged ruleset**
+5. Categorizes results by rule source (SunLint vs User)
+
+**Output:**
+```
+🔗 ESLint Integration Summary:
+  📋 SunLint violations: 4
+  🔧 User ESLint violations: 6  
+  📊 Total combined violations: 10
+```
+
+### **Mode 2: Sequential Execution**
+```bash
+sunlint --all --eslint-integration --eslint-run-after --input=src
+```
+
+**How it works:**
+1. Run SunLint rules first
+2. Run user ESLint rules after
+3. Combine results for reporting
+4. Maintain separation of concerns
+
+## 🚀 **Usage Examples**
+
+### **Basic Integration**
+```bash
+# Analyze with both SunLint + existing ESLint rules
+sunlint --typescript --eslint-integration --input=src
+
+# Git integration + ESLint integration
+sunlint --all --eslint-integration --changed-files
+
+# CI pipeline
+sunlint --all --eslint-integration --changed-files --format=summary --fail-on-new-violations
+```
+
+### **Team Migration Scripts**
+```json
+{
+  "scripts": {
+    "lint": "npm run lint:integrated",
+    "lint:integrated": "sunlint --all --eslint-integration --input=src",
+    "lint:changed": "sunlint --all --eslint-integration --changed-files",
+    "lint:staged": "sunlint --all --eslint-integration --staged-files",
+    "ci:lint": "sunlint --all --eslint-integration --changed-files --format=summary"
+  }
+}
+```
+
+### **GitHub Actions Integration**
+```yaml
+name: Code Quality Check
+on: [pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - name: Run Integrated Linting
+        run: |
+          sunlint --all --eslint-integration --changed-files \
+            --diff-base=origin/main \
+            --format=summary \
+            --fail-on-new-violations
+```
+
+## 🏗️ **Architecture**
+
+### **ESLintIntegrationService**
+- **Responsibility**: Detect, load, and merge ESLint configurations
+- **Methods**:
+  - `hasExistingESLintConfig()`: Auto-detect existing ESLint setup
+  - `loadExistingESLintConfig()`: Load user's ESLint configuration
+  - `createMergedConfig()`: Merge SunLint + User rules
+  - `runIntegratedAnalysis()`: Execute combined analysis
+
+### **Configuration Merging Strategy**
+```javascript
+mergedConfig = {
+  extends: [...sunlintExtends, ...userExtends],
+  plugins: [...sunlintPlugins, ...userPlugins], 
+  rules: {
+    ...sunlintRules,
+    ...userRules  // User rules override SunLint in case of conflicts
+  }
+}
+```
+
+### **Result Categorization**
+```javascript
+{
+  results: [...],
+  categorized: {
+    sunlint: [/* SunLint violations */],
+    user: [/* User ESLint violations */],
+    combined: [/* All violations */]
+  },
+  integration: {
+    totalRules: 113,
+    sunlintRules: 93, 
+    userRules: 20
+  }
+}
+```
+
+## 🎯 **Benefits**
+
+### **For Development Teams**
+- ✅ **No workflow disruption**: Existing ESLint continues working
+- ✅ **Single command**: One execution for all quality checks
+- ✅ **Incremental adoption**: Can enable/disable integration easily
+- ✅ **Conflict resolution**: User rules take precedence over SunLint
+
+### **For CI/CD Pipelines**  
+- ✅ **Faster execution**: Single tool execution vs multiple tools
+- ✅ **Unified reporting**: Combined results, easier to track
+- ✅ **Git integration**: Works with `--changed-files`, `--staged-files`
+- ✅ **Baseline comparison**: `--fail-on-new-violations`
+
+### **For Enterprise Adoption**
+- ✅ **Backward compatibility**: No existing config changes required
+- ✅ **Gradual migration**: Teams can test integration without commitment
+- ✅ **Centralized enforcement**: SunLint rules + team-specific ESLint rules
+- ✅ **Compliance reporting**: Combined violation tracking
+
+## 📊 **Example Scenario**
+
+**Before Integration:**
+```bash
+# Team workflow (2 separate commands)
+npm run lint:eslint    # 20 rules, 6 violations
+npm run lint:sunlint   # 93 rules, 4 violations
+# Total: 10 violations, 2 command executions
+```
+
+**After Integration:**
+```bash
+# Single integrated command  
+npm run lint:integrated  # 113 rules, 10 violations
+# Total: 10 violations, 1 command execution
+```
+
+## 🔍 **Demo**
+
+Run the integration demo:
+```bash
+./demo-eslint-integration.sh
+```
+
+This demonstrates:
+1. Existing ESLint workflow (20 rules)
+2. SunLint-only analysis (93 rules)
+3. **Integrated analysis (113 rules total)**
+4. Available npm scripts for team adoption
+
+---
+
+**🎉 Result**: Teams can now run **113 total rules** (93 SunLint + 20 existing ESLint) in **single command execution** without disrupting existing workflows!

package/docs/FOLDER_STRUCTURE.md

@@ -0,0 +1,59 @@
+# Sunlint Folder Structure
+
+## Rules Directory Naming Convention
+
+All rule folders follow the consistent pattern: `C{ID}_{descriptive_name}`
+
+### Current Rules Structure
+
+```
+rules/
+├── C006_function_naming/           # Function naming conventions
+│   ├── analyzer.js                 # Rule implementation
+│   └── config.json                 # Rule configuration
+├── C019_log_level_usage/           # Log level usage validation
+│   ├── analyzer.js
+│   └── config.json
+├── C029_catch_block_logging/       # Catch block error logging
+│   ├── analyzer.js
+│   └── config.json
+└── C031_validation_separation/     # Validation logic separation (planned)
+    ├── analyzer.js
+    └── config.json
+```
+
+### Benefits of This Naming Convention
+
+1. **Consistency** - All folders follow the same pattern
+2. **Resilience** - If rule IDs change, descriptive names provide context
+3. **Readability** - Easy to understand rule purpose from folder name
+4. **Maintainability** - Clear organization for developers
+
+### Adding New Rules
+
+When adding a new rule, follow this pattern:
+
+1. Create folder: `C{ID}_{snake_case_description}/`
+2. Add `analyzer.js` with rule implementation
+3. Add `config.json` with rule configuration
+4. Update `rules-registry.json` with correct paths
+5. Add tests in `test/fixtures/`
+
+### Example
+
+For a new rule C040 about "API Response Format":
+```
+rules/C040_api_response_format/
+├── analyzer.js
+└── config.json
+```
+
+Registry entry:
+```json
+"C040": {
+  "name": "API Response Format",
+  "description": "Hàm xử lý API nên return response object chuẩn",
+  "analyzer": "./rules/C040_api_response_format/analyzer.js",
+  "config": "./rules/C040_api_response_format/config.json"
+}
+```