@sun-asterisk/sunlint 1.0.7 → 1.1.3

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/CONFIGURATION.md

@@ -0,0 +1,414 @@
+# SunLint Configuration Guide
+
+This document provides a comprehensive guide to all SunLint configuration options.
+
+## 📋 Quick Start
+
+Create `.sunlint.json` in your project root:
+
+```json
+{
+  "extends": "@sun/sunlint/recommended",
+  "input": ["src"],
+  "exclude": ["**/*.test.*", "**/*.generated.*"],
+  "rules": {
+    "C019": "error",
+    "C006": "warn", 
+    "S005": "error"
+  }
+}
+```
+
+## 📖 Complete Configuration Reference
+
+Below is the full configuration schema with all available options and their descriptions:
+
+```json
+{
+  "//": "=== SunLint Full Configuration Example ===",
+  "//": "Copy this configuration and customize as needed",
+  
+  "//extends": "Configuration preset to extend from",
+  "extends": "@sun/sunlint/recommended",
+  "//extends-options": [
+    "@sun/sunlint/recommended",
+    "@sun/sunlint/security", 
+    "@sun/sunlint/quality",
+    "@sun/sunlint/beginner",
+    "@sun/sunlint/ci"
+  ],
+
+  "//engine": "Analysis engine selection (future-proof for multi-engine support)",
+  "engine": "heuristic",
+  "//engine-options": ["heuristic", "eslint", "ai"],
+
+  "//input": "Default input paths when --input is not specified",
+  "input": ["src", "lib"],
+
+  "//include": "File patterns to include in analysis",
+  "include": [
+    "src/**/*.{js,ts,jsx,tsx}",
+    "lib/**/*.{js,ts,jsx,tsx}",
+    "api/**/*.{js,ts}",
+    "**/*.dart"
+  ],
+
+  "//exclude": "File patterns to exclude from analysis", 
+  "exclude": [
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/*.generated.*",
+    "**/*.d.ts",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.git/**",
+    "**/coverage/**"
+  ],
+
+  "//languages": "Language-specific configurations",
+  "languages": {
+    "typescript": {
+      "//": "TypeScript specific patterns and rules",
+      "include": ["**/*.ts", "**/*.tsx"],
+      "exclude": ["**/*.d.ts", "**/*.test.ts"],
+      "rules": {
+        "//": "Override rules for TypeScript files",
+        "C006": "error",
+        "C019": "warn"
+      }
+    },
+    "javascript": {
+      "include": ["**/*.js", "**/*.jsx"],
+      "exclude": ["**/*.test.js", "**/*.config.js"]
+    },
+    "dart": {
+      "include": ["**/*.dart"],
+      "exclude": ["**/*.g.dart", "**/*.freezed.dart"]
+    }
+  },
+
+  "//testPatterns": "Test file specific configurations",
+  "testPatterns": {
+    "include": [
+      "**/*.test.*",
+      "**/*.spec.*", 
+      "**/tests/**",
+      "**/__tests__/**"
+    ],
+    "rules": {
+      "//": "Rules often relaxed for test files",
+      "C006": "off",
+      "C007": "warn",
+      "S012": "off"
+    }
+  },
+
+  "//rules": "Rule-specific configurations",
+  "rules": {
+    "//": "=== Quality Rules ===",
+    "C005": "error",  "//C005": "Single Responsibility Principle",
+    "C006": "warn",   "//C006": "Function Naming Conventions", 
+    "C007": "error",  "//C007": "Comment Quality Standards",
+    "C012": "warn",   "//C012": "Command Query Separation",
+    "C014": "error",  "//C014": "Dependency Injection Patterns",
+    "C015": "warn",   "//C015": "Domain Language Usage",
+    "C019": "error",  "//C019": "Proper Log Level Usage",
+    "C031": "error",  "//C031": "Validation Separation",
+    "C037": "warn",   "//C037": "API Response Format Standards",
+
+    "//": "=== Security Rules (sample - 43+ total) ===",
+    "S001": "error",  "//S001": "Fail Securely Access Control",
+    "S002": "error",  "//S002": "Prevent IDOR Vulnerabilities", 
+    "S005": "error",  "//S005": "No Origin Header Authentication",
+    "S007": "error",  "//S007": "Secure OTP Storage",
+    "S008": "error",  "//S008": "Crypto Agility Requirements",
+    "S012": "error",  "//S012": "No Hardcoded Secrets",
+    "S013": "error",  "//S013": "Always Use TLS",
+    
+    "//": "Rule severity levels: 'error', 'warn', 'off'"
+  },
+
+  "//output": "Output formatting and destination",
+  "output": {
+    "format": "summary", 
+    "//format-options": ["summary", "detailed", "json", "junit", "sarif"],
+    "file": null,
+    "//file-example": "reports/sunlint-report.json",
+    "colors": true,
+    "//": "Enable colorized output (auto-detected in CI)"
+  },
+
+  "//git": "Git integration settings",
+  "git": {
+    "changedFiles": {
+      "//": "Default branch for comparison",
+      "baseBranch": "main",
+      "includeUntracked": false,
+      "includeStagedOnly": false
+    },
+    "commitHooks": {
+      "preCommit": true,
+      "//": "Enable pre-commit validation",
+      "failOnViolations": true
+    }
+  },
+
+  "//baseline": "Baseline comparison for CI/CD",
+  "baseline": {
+    "enabled": false,
+    "file": ".sunlint-baseline.json",
+    "//": "Store baseline violations to track new issues only",
+    "updateOnPass": false
+  },
+
+  "//performance": "Performance and analysis settings",
+  "performance": {
+    "maxFileSize": "5MB",
+    "//": "Skip files larger than this size",
+    "parallel": true,
+    "//": "Enable parallel analysis (auto-detected based on CPU cores)",
+    "timeout": 30000,
+    "//": "Timeout per file in milliseconds"
+  },
+
+  "//eslint": "ESLint integration settings",
+  "eslint": {
+    "enabled": false,
+    "//": "Enable ESLint integration (--eslint-integration flag)",
+    "configFile": null,
+    "//configFile-example": ".eslintrc.js",
+    "mergeReports": true,
+    "//": "Merge ESLint violations with SunLint report"
+  },
+
+  "//react": "React.js specific configuration", 
+  "react": {
+    "version": "detect",
+    "//": "React version for rule compatibility",
+    "rules": {
+      "R001": "error", "//R001": "Function Component Definition Style",
+      "R002": "warn",  "//R002": "Avoid Side Effects in Render",  
+      "R003": "error", "//R003": "No Direct State Mutation",
+      "R004": "warn",  "//R004": "Prefer Readonly Props",
+      "R005": "warn",  "//R005": "Avoid Function Binding in JSX",
+      "R006": "error", "//R006": "Component Naming Conventions",
+      "R007": "error", "//R007": "Proper Hook Usage",
+      "R008": "warn",  "//R008": "Effect Dependencies",
+      "R009": "error"  "//R009": "Conditional Hook Usage"
+    }
+  },
+
+  "//ai": "AI analysis settings (future feature)",
+  "ai": {
+    "enabled": false,
+    "provider": "openai",
+    "//provider-options": ["openai", "anthropic", "local"],
+    "model": "gpt-4",
+    "confidence": 0.8,
+    "//": "Minimum confidence threshold for AI suggestions"
+  },
+
+  "//debug": "Debug and development settings",
+  "debug": {
+    "verbose": false,
+    "//": "Enable verbose logging",
+    "timing": false,
+    "//": "Show performance timing information", 
+    "dryRun": false,
+    "//": "Show what would be analyzed without running"
+  },
+
+  "//cache": "Analysis caching for performance",
+  "cache": {
+    "enabled": true,
+    "//": "Enable analysis result caching",
+    "directory": ".sunlint-cache",
+    "ttl": 86400,
+    "//": "Cache TTL in seconds (24 hours)"
+  }
+}
+```
+
+## 🚨 Migration Notes
+
+**BREAKING CHANGE**: `ignorePatterns` has been deprecated in favor of `exclude` for better consistency.
+
+**Migration:**
+- **Old:** `"ignorePatterns": ["**/*.test.*"]`
+- **New:** `"exclude": ["**/*.test.*"]`
+
+## 📋 Configuration Presets
+
+### Available Presets
+- `@sun/sunlint/recommended` - Balanced rules for all projects
+- `@sun/sunlint/security` - Security-focused rules only  
+- `@sun/sunlint/quality` - Quality-focused rules only
+- `@sun/sunlint/beginner` - Gentle introduction for new teams
+- `@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)
+
+## 🎯 Common Configuration Examples
+
+### Frontend Project
+```json
+{
+  "extends": "@sun/sunlint/recommended",
+  "input": ["src"],
+  "include": ["src/**/*.{js,ts,jsx,tsx}"],
+  "exclude": ["**/*.test.*", "**/*.d.ts", "**/dist/**"],
+  "languages": {
+    "typescript": {
+      "rules": {
+        "C006": "error",
+        "C019": "warn"
+      }
+    }
+  }
+}
+```
+
+### React.js Project
+```json
+{
+  "extends": "@sun/sunlint/recommended", 
+  "input": ["src"],
+  "include": ["src/**/*.{js,ts,jsx,tsx}"],
+  "exclude": ["**/*.test.*", "**/*.d.ts", "**/dist/**"],
+  "react": {
+    "version": "detect",
+    "rules": {
+      "R001": "error",
+      "R002": "warn", 
+      "R003": "error",
+      "R006": "error"
+    }
+  },
+  "eslint": {
+    "enabled": true,
+    "mergeReports": true
+  }
+}
+```
+
+### Backend API Project
+```json
+{
+  "extends": "@sun/sunlint/security",
+  "input": ["src", "api"],
+  "rules": {
+    "S001": "error",
+    "S005": "error",
+    "S012": "error",
+    "C031": "error"
+  },
+  "git": {
+    "changedFiles": {
+      "baseBranch": "develop"
+    }
+  }
+}
+```
+
+### CI/CD Optimized
+```json
+{
+  "extends": "@sun/sunlint/ci",
+  "input": ["."],
+  "exclude": ["**/node_modules/**", "**/dist/**", "**/*.test.*"],
+  "output": {
+    "format": "json",
+    "file": "reports/sunlint-report.json"
+  },
+  "baseline": {
+    "enabled": true,
+    "file": ".sunlint-baseline.json"
+  }
+}
+```
+
+## 🔧 ESLint Integration Setup
+
+SunLint can integrate with existing ESLint configurations for seamless adoption:
+
+### Basic Setup
+1. **Enable ESLint integration:**
+   ```bash
+   npx sunlint --eslint-integration --input=src
+   ```
+
+2. **Configure in `.sunlint.json`:**
+   ```json
+   {
+     "eslint": {
+       "enabled": true,
+       "mergeReports": true
+     }
+   }
+   ```
+
+### React.js Integration
+For React projects, SunLint automatically maps React rules to ESLint equivalents:
+
+```bash
+# Example: Analyze React components with both SunLint and ESLint rules
+npx sunlint --rules=R001,R002,R006 --eslint-integration --input=src
+```
+
+**Required dependencies:**
+```bash
+npm install --save-dev \
+  eslint \
+  @typescript-eslint/parser \
+  @typescript-eslint/eslint-plugin \
+  eslint-plugin-react \
+  eslint-plugin-react-hooks
+```
+
+**Example `.eslintrc.js` for React:**
+```javascript
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    ecmaFeatures: { jsx: true }
+  },
+  plugins: ['@typescript-eslint', 'react', 'react-hooks'],
+  extends: [
+    'eslint:recommended',
+    'plugin:react/recommended',
+    'plugin:react-hooks/recommended'
+  ],
+  settings: {
+    react: { version: 'detect' }
+  }
+};
+```
+
+### Rule Mapping
+SunLint automatically maps its rules to ESLint equivalents:
+
+| SunLint Rule | ESLint Rule(s) | Description |
+|--------------|----------------|-------------|
+| R001 | `react/function-component-definition` | Function component style |
+| R002 | `react-hooks/rules-of-hooks`, `react-hooks/exhaustive-deps` | Hook usage patterns |
+| R003 | `react/no-direct-mutation-state` | Prevent state mutation |
+| R006 | `react/jsx-pascal-case` | Component naming |
+
+### Multi-Engine Orchestration
+SunLint intelligently selects the best engine for each rule:
+
+```bash
+# Verbose output shows engine selection
+npx sunlint --rules=C010,R001,T003 --eslint-integration --verbose
+```
+
+Engine preferences:
+- **R*** rules: ESLint → Heuristic → AI
+- **C*** rules: Heuristic → ESLint → AI  
+- **T*** rules: ESLint → Heuristic → AI