@sun-asterisk/sunlint/docs/ESLINT_INTEGRATION.md

☀️ SunLint - Multi-language static analysis tool for code quality and security | Sun* Engineering Standards

# 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!