@sun-asterisk/sunlint 1.0.5

package/docs/CI-CD-GUIDE.md

@@ -0,0 +1,315 @@
+# 🚀 SunLint CI/CD Integration Guide
+
+## 📋 **Tổng quan các chức năng CLI**
+
+### ✅ **Phạm vi kiểm tra**
+- ✅ Kiểm tra 1 file: `node cli.js --all --input=file.js`
+- ✅ Kiểm tra 1 folder: `node cli.js --all --input=src`  
+- ✅ Kiểm tra toàn project: `node cli.js --all --input=.`
+- ✅ Kiểm tra changed files: `node cli.js --all --changed-files`
+- ✅ Kiểm tra staged files: `node cli.js --all --staged-files`
+
+### ✅ **Lựa chọn rules**
+- ✅ 1 rule: `node cli.js --rule=C019 --input=src`
+- ✅ Nhiều rules: `node cli.js --rules=C019,C006 --input=src`
+- ✅ Tất cả rules: `node cli.js --all --input=src`
+- ✅ Theo category: `node cli.js --quality --input=src`
+
+### ✅ **Phương pháp phân tích**
+- ✅ Pattern-based (free): `node cli.js --all --input=src --no-ai`
+- ✅ AI-powered (cost): `node cli.js --all --input=src --ai`
+
+### ✅ **CI/CD Features**
+- ✅ Git integration: `--changed-files`, `--staged-files`, `--diff-base`
+- ✅ Baseline comparison: `--baseline`, `--save-baseline`
+- ✅ New violations only: `--fail-on-new-violations`
+- ✅ Multiple output formats: `--format=json|eslint|github|summary`
+
+## 🎯 **CI/CD Strategies**
+
+### **Strategy 1: Full Coverage (Traditional)**
+```bash
+# Advantages: Complete analysis, no missed issues
+# Disadvantages: Slow, expensive, noisy for large projects
+
+# Usage:
+node cli.js --all --input=. --format=json --output=report.json
+```
+
+### **Strategy 2: Incremental (Recommended)**
+```bash
+# PR Check: Only changed files
+node cli.js --all --changed-files --diff-base=origin/main --fail-on-new-violations
+
+# Main Branch: Full scan + baseline
+node cli.js --all --input=. --save-baseline=baseline.json --format=json
+```
+
+### **Strategy 3: Risk-Based**
+```bash
+# High-risk areas only
+node cli.js --security --input=src/auth,src/payment --format=summary
+
+# Critical rules only
+node cli.js --rules=C019,S001,S003 --changed-files --format=github
+```
+
+## 📊 **Performance Comparison**
+
+| Scope | Files | Time | Use Case |
+|-------|-------|------|----------|
+| Single file | 1 | ~1-3s | IDE integration, pre-commit |
+| Changed files (PR) | 5-20 | ~10-30s | PR checks, fast feedback |
+| Module/folder | 50-200 | ~1-2min | Feature development |
+| Full project | 500+ | ~3-10min | Nightly builds, releases |
+
+## 🔄 **Workflow Examples**
+
+### **GitHub Actions - Complete Setup**
+
+```yaml
+name: SunLint Quality Gates
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  NODE_VERSION: '18'
+
+jobs:
+  # Job 1: PR Quality Check (fast)
+  pr-check:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+    
+    - name: Setup Node.js
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ env.NODE_VERSION }}
+    
+    - name: Install SunLint
+      run: |
+        cd coding-quality/extensions/sunlint
+        npm install
+    
+    - name: Download Baseline
+      uses: actions/download-artifact@v3
+      with:
+        name: sunlint-baseline
+        path: coding-quality/extensions/sunlint/
+      continue-on-error: true
+    
+    - name: Run SunLint on Changed Files
+      run: |
+        cd coding-quality/extensions/sunlint
+        node cli.js --all --changed-files \
+        --diff-base=origin/${{ github.base_ref }} \
+        --baseline=baseline.json \
+        --fail-on-new-violations \
+        --format=github \
+        --no-ai
+    
+    - name: Comment PR
+      if: failure()
+      uses: actions/github-script@v6
+      with:
+        script: |
+          github.rest.issues.createComment({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: '❌ SunLint found code quality issues. Please check the Actions log for details.'
+          })
+
+  # Job 2: Full Scan + Baseline (comprehensive)  
+  full-scan:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Setup Node.js
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ env.NODE_VERSION }}
+    
+    - name: Install SunLint
+      run: |
+        cd coding-quality/extensions/sunlint
+        npm install
+    
+    - name: Run Full SunLint Scan
+      run: |
+        cd coding-quality/extensions/sunlint
+        node cli.js --all --input=. \
+        --save-baseline=baseline.json \
+        --format=json \
+        --output=sunlint-report.json \
+        --no-ai
+    
+    - name: Upload Baseline
+      uses: actions/upload-artifact@v3
+      with:
+        name: sunlint-baseline
+        path: coding-quality/extensions/sunlint/baseline.json
+        retention-days: 30
+    
+    - name: Upload Report
+      uses: actions/upload-artifact@v3
+      with:
+        name: sunlint-report
+        path: coding-quality/extensions/sunlint/sunlint-report.json
+```
+
+### **GitLab CI - Complete Setup**
+
+```yaml
+stages:
+  - quality-check
+  - quality-baseline
+
+variables:
+  SUNLINT_PATH: "coding-quality/extensions/sunlint"
+
+# Fast PR check
+sunlint:pr:
+  stage: quality-check
+  image: node:18
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  before_script:
+    - cd $SUNLINT_PATH
+    - npm install
+  script:
+    - |
+      if [ -f baseline.json ]; then
+        echo "Using existing baseline"
+        node cli.js --all --changed-files \
+        --diff-base=origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME \
+        --baseline=baseline.json \
+        --fail-on-new-violations \
+        --format=summary \
+        --no-ai
+      else
+        echo "No baseline found, running on changed files only"
+        node cli.js --all --changed-files \
+        --diff-base=origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME \
+        --format=summary \
+        --no-ai
+      fi
+  artifacts:
+    reports:
+      junit: $SUNLINT_PATH/sunlint-report.xml
+    when: always
+    expire_in: 1 week
+
+# Full scan for main branch
+sunlint:baseline:
+  stage: quality-baseline
+  image: node:18
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+  before_script:
+    - cd $SUNLINT_PATH
+    - npm install
+  script:
+    - |
+      node cli.js --all --input=. \
+      --save-baseline=baseline.json \
+      --format=json \
+      --output=sunlint-report.json \
+      --no-ai
+  artifacts:
+    paths:
+      - $SUNLINT_PATH/baseline.json
+      - $SUNLINT_PATH/sunlint-report.json
+    expire_in: 1 month
+```
+
+## 🎲 **Pre-commit Hook**
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit
+
+cd coding-quality/extensions/sunlint
+
+echo "🔍 Running SunLint on staged files..."
+node cli.js --all --staged-files --format=summary --no-ai
+
+if [ $? -ne 0 ]; then
+  echo "❌ SunLint found issues. Commit aborted."
+  echo "💡 Fix the issues or use 'git commit --no-verify' to bypass."
+  exit 1
+fi
+
+echo "✅ SunLint passed!"
+```
+
+## 📈 **Monitoring & Metrics**
+
+### **Track Quality Trends**
+```bash
+# Generate trend report
+node cli.js --all --input=. --format=json --output=reports/$(date +%Y-%m-%d).json
+
+# Compare with previous scan
+node cli.js --all --input=. --baseline=reports/baseline.json --format=trend
+```
+
+### **Quality Gates**
+```bash
+# Fail if more than 10 new violations
+node cli.js --all --changed-files --max-new-violations=10
+
+# Fail on any security issues
+node cli.js --security --changed-files --severity=error
+
+# Allow warnings but fail on errors
+node cli.js --all --changed-files --severity=error
+```
+
+## 🚨 **Troubleshooting**
+
+### **Common Issues**
+
+1. **"No changed files detected"**
+   ```bash
+   # Check git status
+   git status
+   git diff --name-only origin/main
+   
+   # Force include specific files
+   node cli.js --all --input=src/specific-file.ts
+   ```
+
+2. **"Baseline not found"**
+   ```bash
+   # Create initial baseline
+   node cli.js --all --input=. --save-baseline=baseline.json --no-ai
+   ```
+
+3. **"Too many violations"**
+   ```bash
+   # Focus on high-priority rules first
+   node cli.js --rules=C019,S001 --changed-files
+   
+   # Use severity filtering
+   node cli.js --all --changed-files --severity=error
+   ```
+
+## 🎯 **Best Practices Summary**
+
+1. **Start Small**: Begin with changed files only
+2. **Incremental Adoption**: Add rules gradually  
+3. **Use Baselines**: For large existing projects
+4. **Monitor Performance**: Track CI execution time
+5. **Focus on New Code**: Don't overwhelm with legacy issues
+6. **Automate Everything**: Pre-commit + PR checks + nightly scans
+7. **Cost Optimization**: Use `--no-ai` for CI to avoid API costs

package/docs/COMMAND-EXAMPLES.md

@@ -0,0 +1,256 @@
+# 🎮 SunLint Command Examples & Demos
+
+## 📋 **Tổng hợp đầy đủ các chức năng CLI đã hỗ trợ**
+
+### ✅ **1. Phạm vi kiểm tra (Input Scope)**
+
+```bash
+# Kiểm tra 1 file cụ thể
+node cli.js --all --input=cli.js --format=summary --no-ai
+
+# Kiểm tra 1 folder/directory  
+node cli.js --all --input=core --format=summary --no-ai
+
+# Kiểm tra toàn bộ project/workspace
+node cli.js --all --input=. --format=summary --no-ai
+
+# Kiểm tra nhiều folders (comma-separated)
+node cli.js --all --input=core,rules --format=summary --no-ai
+
+# Kiểm tra chỉ files đã thay đổi (Git integration)
+node cli.js --all --changed-files --format=summary --no-ai
+
+# Kiểm tra chỉ files đã staged (Pre-commit)
+node cli.js --all --staged-files --format=summary --no-ai
+
+# Kiểm tra files thay đổi so với branch cụ thể
+node cli.js --all --changed-files --diff-base=origin/main --format=summary
+```
+
+### ✅ **2. Lựa chọn Rules**
+
+```bash
+# Kiểm tra 1 rule cụ thể
+node cli.js --rule=C019 --input=. --format=summary --no-ai
+
+# Kiểm tra nhiều rules cụ thể
+node cli.js --rules=C019,C006,C029 --input=. --format=summary --no-ai
+
+# Kiểm tra tất cả rules
+node cli.js --all --input=. --format=summary --no-ai
+
+# Kiểm tra theo category (quality rules)
+node cli.js --quality --input=. --format=summary --no-ai
+
+# Kiểm tra theo category (security rules) 
+node cli.js --security --input=. --format=summary --no-ai
+
+# Loại trừ một số rules cụ thể
+node cli.js --all --exclude-rules=C031 --input=. --format=summary --no-ai
+```
+
+### ✅ **3. Phương pháp phân tích**
+
+```bash
+# Pattern-based analysis (free, fast)
+node cli.js --all --input=. --format=summary --no-ai
+
+# AI-powered analysis (cost, more accurate)
+node cli.js --all --input=. --format=summary --ai
+
+# Hybrid: AI cho rules cụ thể, pattern cho còn lại
+node cli.js --rule=C019 --input=. --ai --format=summary
+```
+
+### ✅ **4. Output Formats**
+
+```bash
+# Human-readable summary
+node cli.js --all --input=. --format=summary --no-ai
+
+# ESLint-compatible JSON (for IDEs)
+node cli.js --all --input=. --format=eslint --no-ai
+
+# Structured JSON (for processing)
+node cli.js --all --input=. --format=json --no-ai
+
+# Table format (for reports)
+node cli.js --all --input=. --format=table --no-ai
+
+# GitHub Actions format (for CI)
+node cli.js --all --input=. --format=github --no-ai
+
+# Save to file
+node cli.js --all --input=. --format=json --output=report.json --no-ai
+```
+
+### ✅ **5. CI/CD Features**
+
+```bash
+# PR Mode: Chỉ check violations mới
+node cli.js --all --changed-files --fail-on-new-violations --format=summary
+
+# Baseline comparison
+node cli.js --all --input=. --save-baseline=baseline.json --format=json --no-ai
+node cli.js --all --changed-files --baseline=baseline.json --fail-on-new-violations
+
+# Severity filtering
+node cli.js --all --input=. --severity=error --format=summary --no-ai
+
+# Language filtering  
+node cli.js --all --input=. --languages=typescript,javascript --format=summary
+```
+
+### ✅ **6. Performance & Advanced Options**
+
+```bash
+# Control concurrent execution
+node cli.js --all --input=. --max-concurrent=10 --format=summary --no-ai
+
+# Set timeout for rules
+node cli.js --all --input=. --timeout=60000 --format=summary --no-ai
+
+# Disable caching
+node cli.js --all --input=. --no-cache --format=summary --no-ai
+
+# Verbose logging
+node cli.js --all --input=. --verbose --format=summary --no-ai
+
+# Quiet mode (errors only)
+node cli.js --all --input=. --quiet --format=summary --no-ai
+
+# Debug mode
+node cli.js --all --input=. --debug --format=summary --no-ai
+
+# Dry run (show what would be analyzed)
+node cli.js --all --input=. --dry-run --format=summary --no-ai
+```
+
+## 🚀 **Use Cases & Scenarios**
+
+### **Local Development** 🏠
+
+```bash
+# Quick check before commit
+node cli.js --all --staged-files --format=summary --no-ai
+
+# Check current work
+node cli.js --all --changed-files --format=summary --no-ai  
+
+# Focus on specific issue type
+node cli.js --rule=C019 --input=. --format=summary --no-ai
+
+# Deep analysis with AI
+node cli.js --quality --input=src --ai --format=detailed
+```
+
+### **Code Review** 👀
+
+```bash
+# Check PR changes
+node cli.js --all --changed-files --diff-base=origin/main --format=github
+
+# Focus on security for sensitive changes
+node cli.js --security --changed-files --format=summary --no-ai
+
+# New violations only
+node cli.js --all --changed-files --baseline=baseline.json --fail-on-new-violations
+```
+
+### **CI/CD Pipeline** 🔄
+
+```bash
+# Fast PR check
+node cli.js --all --changed-files --format=github --no-ai --timeout=30000
+
+# Full scan for main branch
+node cli.js --all --input=. --format=json --output=report.json --no-ai
+
+# Security-critical check
+node cli.js --security --input=. --severity=error --format=summary --no-ai
+
+# Quality gate
+node cli.js --quality --changed-files --max-new-violations=5 --format=summary
+```
+
+### **Project Health Monitoring** 📊
+
+```bash
+# Full project assessment
+node cli.js --all --input=. --format=detailed --output=health-report.json --no-ai
+
+# Trend analysis
+node cli.js --all --input=. --baseline=last-month.json --format=trend --no-ai
+
+# Focus areas
+node cli.js --rules=C019,C029 --input=core --format=table --no-ai
+```
+
+## 🎯 **Practical Examples**
+
+### **Example 1: New Feature Development**
+```bash
+# Day 1: Start development
+node cli.js --all --staged-files --format=summary --no-ai
+
+# Day 2: Check progress  
+node cli.js --all --changed-files --format=summary --no-ai
+
+# Day 3: Pre-review check
+node cli.js --all --changed-files --diff-base=origin/main --format=github --no-ai
+
+# Day 4: Final validation
+node cli.js --all --changed-files --ai --format=detailed
+```
+
+### **Example 2: Legacy Code Improvement**
+```bash
+# Step 1: Baseline assessment
+node cli.js --all --input=legacy-module --save-baseline=legacy-baseline.json --no-ai
+
+# Step 2: Focus on critical issues
+node cli.js --security --input=legacy-module --severity=error --format=summary
+
+# Step 3: Incremental improvement
+node cli.js --rule=C019 --input=legacy-module --format=summary --no-ai
+
+# Step 4: Track progress
+node cli.js --all --input=legacy-module --baseline=legacy-baseline.json --format=trend
+```
+
+### **Example 3: Team Onboarding**
+```bash
+# Level 1: Basic checks
+node cli.js --rules=C006,C019 --input=. --format=summary --no-ai
+
+# Level 2: Quality focus
+node cli.js --quality --input=. --format=table --no-ai
+
+# Level 3: Full analysis
+node cli.js --all --input=. --format=detailed --no-ai
+
+# Level 4: AI-assisted learning
+node cli.js --all --input=. --ai --verbose --format=detailed
+```
+
+## 📝 **Command Cheat Sheet**
+
+| Task | Command |
+|------|---------|
+| Quick pre-commit check | `node cli.js --all --staged-files --format=summary --no-ai` |
+| PR review | `node cli.js --all --changed-files --diff-base=origin/main --format=github` |
+| Full project scan | `node cli.js --all --input=. --format=json --output=report.json --no-ai` |
+| Security audit | `node cli.js --security --input=. --severity=error --format=summary` |
+| New violations only | `node cli.js --all --changed-files --baseline=baseline.json --fail-on-new-violations` |
+| AI deep analysis | `node cli.js --quality --input=src --ai --format=detailed` |
+| Performance test | `node cli.js --all --input=. --max-concurrent=1 --timeout=10000 --no-ai` |
+| Debug issues | `node cli.js --rule=C019 --input=problematic-file.js --debug --verbose` |
+
+## 💡 **Pro Tips**
+
+1. **Start with `--no-ai`** for faster feedback, use `--ai` for complex issues
+2. **Use `--changed-files`** in development, `--input=.` for comprehensive checks  
+3. **Save baselines** for large projects to track progress over time
+4. **Combine `--severity=error`** with CI to focus on critical issues
+5. **Use `--dry-run`** to understand what will be analyzed before running
+6. **Set `--timeout`** appropriately based on project size and CI time limits

package/docs/DEBUG.md

@@ -0,0 +1,86 @@
+# 🐛 Debugging Sunlint
+
+## Quick Start
+
+### Debug Configurations Available
+
+1. **Debug Sunlint CLI** - Debug the main CLI with quality rules
+2. **Debug Sunlint - Single Rule** - Debug a specific rule (C006)
+3. **Debug Sunlint - Multiple Rules** - Debug multiple rules with JSON output
+4. **Debug Sunlint - Custom Input** - Debug with custom input path and format
+5. **Debug Rule Analyzer - C006** - Debug the function naming analyzer
+6. **Debug Rule Analyzer - C019** - Debug the log level analyzer
+7. **Debug Rule Analyzer - C029** - Debug the catch block analyzer
+
+### How to Debug
+
+1. **Open VS Code** in the sunlint folder
+2. **Press F5** or go to `Run and Debug` panel
+3. **Select a configuration** from the dropdown
+4. **Click Start Debugging** (green play button)
+
+### Tasks Available
+
+- **Sunlint: Run Quality Check** - Run quality analysis (Ctrl+Shift+P → Tasks: Run Task)
+- **Sunlint: Run Single Rule** - Run a specific rule 
+- **Sunlint: Run All Rules** - Run all rules with JSON output
+- **Sunlint: Demo Script** - Run the demo script
+- **Sunlint: Install Dependencies** - Install npm dependencies
+- **Sunlint: Validate Registry** - Validate the rules registry
+
+### Breakpoints
+
+Set breakpoints in:
+- **cli.js** - Main CLI logic
+- **core/multi-rule-runner.js** - Rule execution
+- **core/config-manager.js** - Configuration loading
+- **core/report-generator.js** - Report generation
+- **rules/*/analyzer.js** - Individual rule analyzers
+
+### Debug Environment
+
+- **NODE_ENV** is set to `development`
+- **Console** output goes to integrated terminal
+- **Skip Files** configured to ignore Node.js internals
+- **Problem Matcher** configured to parse sunlint output
+
+### Configuration Files
+
+- **launch.json** - Debug configurations
+- **tasks.json** - Build and test tasks
+- **settings.json** - VS Code workspace settings
+- **extensions.json** - Recommended extensions
+- **sunlint-schema.json** - JSON schema for .sunlint.json files
+
+### Tips
+
+1. **Use breakpoints** in analyzer files to debug rule logic
+2. **Check Variables panel** to inspect rule results
+3. **Use Debug Console** to test expressions
+4. **Watch expressions** for complex debugging
+5. **Step through code** to understand execution flow
+
+### Common Debug Scenarios
+
+#### Debug Rule Not Working
+1. Set breakpoint in rule analyzer
+2. Use "Debug Rule Analyzer - C006" configuration
+3. Check if rule is properly detecting violations
+
+#### Debug CLI Arguments
+1. Set breakpoint in cli.js
+2. Use "Debug Sunlint CLI" configuration  
+3. Check if arguments are parsed correctly
+
+#### Debug Report Generation
+1. Set breakpoint in report-generator.js
+2. Use any CLI debug configuration
+3. Check if violations are formatted correctly
+
+### JSON Schema Support
+
+The workspace includes JSON schema for `.sunlint.json` files, providing:
+- **IntelliSense** for configuration options
+- **Validation** of configuration values
+- **Hover documentation** for properties
+- **Auto-completion** for rule IDs and values