@sun-asterisk/sunlint 1.0.7 → 1.1.3

package/docs/AI.md

@@ -0,0 +1,163 @@
+# 🤖 AI-Powered Analysis
+
+Sunlint supports AI-powered code analysis alongside traditional pattern-based analysis for more intelligent and context-aware rule checking.
+
+## Overview
+
+- **🎯 Smart Analysis**: Uses AI to understand code context and intent
+- **🔄 Fallback Strategy**: Automatically falls back to pattern analysis if AI fails
+- **⚡ Performance**: AI analysis runs per-file with caching support
+- **🔧 Configurable**: Multiple AI providers and models supported
+
+## Configuration
+
+### In `.sunlint.json`:
+
+```json
+{
+  "ai": {
+    "enabled": true,
+    "provider": "openai",
+    "model": "gpt-4o-mini",
+    "apiKey": "${OPENAI_API_KEY}",
+    "fallbackToPattern": true
+  }
+}
+```
+
+### Environment Variables:
+
+```bash
+export OPENAI_API_KEY="your-openai-api-key"
+```
+
+## Supported Providers
+
+### OpenAI
+- **Models**: `gpt-4`, `gpt-4o-mini`, `gpt-3.5-turbo`
+- **API Key**: Required via `OPENAI_API_KEY` environment variable
+- **Cost**: Pay-per-use based on OpenAI pricing
+
+### GitHub Copilot (Planned)
+- **Integration**: VS Code extension integration
+- **Models**: GitHub Copilot models
+- **Authentication**: VS Code Copilot session
+
+## AI-Enhanced Rules
+
+### C019 - Log Level Usage
+✅ **AI-Enabled**: Understands code context to determine appropriate log levels
+
+**AI Analysis Features:**
+- **Context Understanding**: Analyzes surrounding code to determine error criticality
+- **Intent Recognition**: Understands whether errors are expected or exceptional
+- **Semantic Analysis**: Goes beyond pattern matching to understand meaning
+
+**Example:**
+```typescript
+// AI understands this is a validation error, suggests warn level
+if (!user.email) {
+  console.error('Missing email'); // AI: Should use console.warn()
+}
+
+// AI understands this is a critical system error, keeps error level
+try {
+  await database.connect();
+} catch (error) {
+  console.error('Database connection failed:', error); // AI: Appropriate error level
+}
+```
+
+## Usage
+
+### CLI Commands
+
+**Enable AI for specific rule:**
+```bash
+sunlint --rule=C019 --input=src --ai
+```
+
+**Enable AI for all rules:**
+```bash
+sunlint --quality --input=src --ai
+```
+
+**Debug AI analysis:**
+```bash
+sunlint --rule=C019 --input=src --ai --verbose
+```
+
+### VS Code Integration
+
+1. **Debug Configuration**: Use "Debug Sunlint - AI Analysis"
+2. **Task**: Run "Sunlint: AI Analysis Test"
+3. **Set API Key**: Configure `OPENAI_API_KEY` in environment
+
+## Output Differences
+
+### Pattern Analysis Output:
+```
+WARNING: Error log level used for non-critical issue - should use warn/info level
+  at src/user.ts:15:5 (C019)
+```
+
+### AI Analysis Output:
+```
+WARNING: Email validation error should use console.warn() - this is user input validation, not a system error
+  at src/user.ts:15:5 (C019)
+  Suggestion: Change to console.warn('User email validation failed:', email)
+```
+
+## Performance Considerations
+
+- **Caching**: AI responses are cached per file content hash
+- **Concurrency**: AI calls are made concurrently with rate limiting
+- **Timeout**: 30-second timeout per AI request
+- **Cost**: Monitor API usage in OpenAI dashboard
+
+## Troubleshooting
+
+### Common Issues
+
+**API Key Not Found:**
+```bash
+⚠️  AI API key not found, falling back to pattern analysis
+```
+Solution: Set `OPENAI_API_KEY` environment variable
+
+**API Rate Limit:**
+```bash
+AI Analysis failed: OpenAI API error: 429 Too Many Requests
+```
+Solution: Reduce `maxConcurrentRules` in config or wait
+
+**Network Issues:**
+```bash
+AI Analysis failed: OpenAI API error: Network timeout
+```
+Solution: Check internet connection, increase `timeoutMs`
+
+### Debug AI Issues
+
+1. **Enable verbose mode**: `--verbose`
+2. **Check API key**: `echo $OPENAI_API_KEY`
+3. **Test connection**: Use debug configuration
+4. **Check API quota**: Visit OpenAI dashboard
+
+## Future Enhancements
+
+- **🔄 GitHub Copilot Integration**: Direct integration with VS Code Copilot
+- **📊 Custom Models**: Support for fine-tuned models
+- **🎯 Rule-Specific Prompts**: Specialized prompts per rule type
+- **💾 Smart Caching**: Semantic caching across similar code patterns
+- **📈 Analytics**: AI vs Pattern analysis effectiveness metrics
+
+## Cost Estimation
+
+**OpenAI API Costs** (approximate):
+- **gpt-4o-mini**: ~$0.001 per 1K tokens
+- **gpt-4**: ~$0.03 per 1K tokens
+- **Average file**: ~500 tokens
+- **1000 files with gpt-4o-mini**: ~$0.50
+
+**Recommendation**: Start with `gpt-4o-mini` for cost-effectiveness.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,78 @@
+# SunLint Modular Architecture
+
+## Phase 1: TypeScript Focus với Kiến trúc Modular
+
+### Cấu trúc mới:
+
+```
+cli.js                    # CLI entry point (simplified)
+core/
+├── cli-program.js        # CLI options definition (Rule C005)
+├── cli-action-handler.js # Main execution flow (Rule C005)
+├── rule-selection-service.js # Rule selection logic (Rule C005)
+├── analysis-orchestrator.js  # Analysis coordination (Rule C005)
+├── output-service.js     # Output formatting (Rule C005)
+├── eslint-engine-service.js   # ESLint integration (future)
+└── sunlint-engine-service.js  # Native SunLint engine
+```
+
+### Nguyên tắc thiết kế:
+
+1. **Rule C005**: Mỗi class/file chỉ làm một việc
+2. **Rule C014**: Dependency injection thay vì new trực tiếp
+3. **Rule C012**: Tách rõ Command và Query
+4. **Modular**: Dễ mở rộng cho Phase 2
+
+### Luồng hoạt động:
+
+1. `cli.js` → `CliActionHandler`
+2. `CliActionHandler` → Load config, validate input
+3. `RuleSelectionService` → Select rules based on options
+4. `AnalysisOrchestrator` → Run analysis (SunLint or ESLint)
+5. `OutputService` → Format and display results
+
+### Các tính năng hiện tại:
+
+- ✅ Modular CLI với dependency injection
+- ✅ Rule selection (single, multiple, all, category)
+- ✅ Dry run mode
+- ✅ TypeScript-specific options (chuẩn bị cho Phase 1)
+- ✅ Graceful fallback khi không tìm thấy dependencies
+- ✅ Clean error handling và logging
+
+### Phase 1 roadmap:
+
+1. **✅ Done**: Modular CLI architecture
+2. **✅ Done**: ESLint integration cho TypeScript
+3. **Next**: TypeScript custom rules thông qua ESLint
+4. **✅ Done**: Hybrid engine (ESLint + SunLint)
+
+### Phase 2 roadmap:
+
+1. Native SunLint engine cho tất cả ngôn ngữ
+2. Mở rộng Dart, Kotlin rules
+3. AI-powered analysis
+4. VS Code extension integration
+
+### Usage Examples:
+
+```bash
+# Basic usage
+sunlint --rule=C006 --input=src
+
+# Category-based
+sunlint --quality --input=src
+
+# TypeScript-specific (Phase 1)
+sunlint --typescript --input=src
+sunlint --typescript-engine=eslint --input=src
+
+# Dry run
+sunlint --dry-run --all --input=src
+```
+
+### Dependencies:
+
+- Minimal core dependencies
+- ESLint integration sẽ được thêm trong Phase 1
+- Graceful fallback khi dependencies không có sẵn

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