@sun-asterisk/sunlint 1.3.19 → 1.3.21

package/docs/GITHUB_ACTIONS_INTEGRATION.md

@@ -0,0 +1,421 @@
+# GitHub Actions Integration
+
+Hướng dẫn tích hợp SunLint với GitHub Actions để tự động review Pull Requests.
+
+## Tính năng mới: Auto GitHub Annotation
+
+SunLint giờ đây có thể tự động tạo review comments trên Pull Requests mà **không cần chỉ định `--output` và `--format=json`**.
+
+### 3 Annotation Modes
+
+`--github-annotate` hỗ trợ 3 modes:
+
+#### 1. **`annotate`** - Inline Comments Only
+Tạo review comments trực tiếp trên code (inline comments)
+```bash
+sunlint --all --input=src --github-annotate=annotate
+```
+- ✅ Comment trên từng dòng code có lỗi
+- ✅ Duplicate detection
+- ✅ Batch processing (30 comments/review)
+
+#### 2. **`summary`** - Summary Comment Only
+Tạo 1 comment tổng hợp (như GitHub Actions summary)
+```bash
+sunlint --all --input=src --github-annotate=summary
+```
+- ✅ Thống kê tổng quan (errors, warnings, files)
+- ✅ Top 10 files có nhiều lỗi nhất
+- ✅ Auto update comment cũ (không spam)
+
+#### 3. **`all`** - Both (Default)
+Tạo cả inline comments và summary comment
+```bash
+sunlint --all --input=src --github-annotate        # default
+sunlint --all --input=src --github-annotate=all    # explicit
+```
+- ✅ Full experience: inline + summary
+- ✅ Resilient: nếu 1 task fail, task kia vẫn chạy
+
+### Cách hoạt động
+
+Khi sử dụng flag `--github-annotate`:
+
+1. ✅ **Tự động phát hiện PR event** - Chỉ chạy khi event là `pull_request`
+2. ✅ **Tự động tạo JSON report** - Không cần `--output` và `--format=json`
+3. ✅ **Tự động cleanup** - Xóa temp file sau khi annotate
+4. ✅ **Intelligent error handling** - Báo lỗi chi tiết và gợi ý fix
+5. ✅ **Duplicate detection** - Tránh spam comments trùng lặp
+6. ✅ **3 flexible modes** - Chọn mode phù hợp với workflow
+
+## Quick Start
+
+### Workflow đơn giản nhất
+
+```yaml
+name: SunLint PR Review
+on:
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  sunlint:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install SunLint
+        run: npm install -g sunlint
+
+      - name: Run SunLint with Auto Annotation
+        run: sunlint --all --input=src --github-annotate
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+**Đó là tất cả!** SunLint sẽ tự động:
+- Phân tích code
+- Tạo JSON report (tạm thời)
+- Comment lên PR
+- Xóa file tạm
+
+## Advanced Usage
+
+### 1. Analyze only changed files
+
+```yaml
+- name: Run SunLint on Changed Files
+  run: sunlint --all --changed-files --github-annotate
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### 2. Save report file + annotate
+
+```yaml
+- name: Run SunLint
+  run: sunlint --all --input=src --output=sunlint-report.json --github-annotate
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+- name: Upload Report
+  uses: actions/upload-artifact@v4
+  if: always()
+  with:
+    name: sunlint-report
+    path: sunlint-report.json
+```
+
+### 3. Run specific rules
+
+```yaml
+- name: Run Security Rules Only
+  run: sunlint --security --input=src --github-annotate
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### 4. Multiple languages
+
+```yaml
+- name: Run SunLint on TypeScript and Kotlin
+  run: sunlint --all --languages=typescript,kotlin --input=. --github-annotate
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### 5. Với verbose logging
+
+```yaml
+- name: Run SunLint (Verbose)
+  run: sunlint --all --input=src --github-annotate --verbose
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## Complete Example Workflow
+
+```yaml
+name: Code Quality Check
+on:
+  pull_request:
+    branches: [main, develop, 'release/**']
+    paths:
+      - '**.ts'
+      - '**.tsx'
+      - '**.js'
+      - '**.jsx'
+      - '**.kt'
+      - '**.dart'
+
+jobs:
+  sunlint:
+    name: SunLint Analysis
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # For git diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install SunLint
+        run: npm install -g sunlint
+
+      - name: Run SunLint on Changed Files
+        id: sunlint
+        continue-on-error: true  # Don't fail the workflow
+        run: |
+          sunlint --all \
+            --changed-files \
+            --diff-base=origin/${{ github.base_ref }} \
+            --github-annotate \
+            --output=sunlint-report.json \
+            --verbose
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload Report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: sunlint-report-${{ github.event.pull_request.number }}
+          path: sunlint-report.json
+          retention-days: 30
+
+      - name: Comment Summary
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            if (!fs.existsSync('sunlint-report.json')) return;
+
+            const report = JSON.parse(fs.readFileSync('sunlint-report.json', 'utf8'));
+            let violations = 0;
+            let errors = 0;
+            let warnings = 0;
+
+            for (const file of report) {
+              violations += file.messages.length;
+              errors += file.errorCount;
+              warnings += file.warningCount;
+            }
+
+            const body = `## SunLint Report
+
+            📊 **Summary:**
+            - Total violations: ${violations}
+            - Errors: ${errors}
+            - Warnings: ${warnings}
+
+            ${violations === 0 ? '✅ No issues found!' : '⚠️ Please check the PR comments for details.'}
+            `;
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: body
+            });
+```
+
+## Environment Variables
+
+SunLint tự động đọc các biến môi trường từ GitHub Actions:
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `GITHUB_TOKEN` | GitHub token for API access | ✅ Yes |
+| `GITHUB_REPOSITORY` | Repository (owner/repo) | Auto |
+| `GITHUB_EVENT_NAME` | Event type (pull_request) | Auto |
+| `GITHUB_EVENT_PATH` | Path to event payload | Auto |
+| `RUNNER_TEMP` | Temp directory | Auto |
+
+## Permissions Required
+
+```yaml
+permissions:
+  contents: read         # To checkout code
+  pull-requests: write   # To create review comments
+```
+
+## Troubleshooting
+
+### 1. "GitHub annotation only works on pull_request events"
+
+**Nguyên nhân:** Workflow chạy trên `push` event thay vì `pull_request`
+
+**Giải pháp:**
+```yaml
+on:
+  pull_request:  # Thay vì push
+    branches: [main]
+```
+
+### 2. "Missing GITHUB_TOKEN"
+
+**Nguyên nhân:** Thiếu GITHUB_TOKEN trong env
+
+**Giải pháp:**
+```yaml
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### 3. "Permission denied"
+
+**Nguyên nhân:** Token không có quyền `pull-requests: write`
+
+**Giải pháp:**
+```yaml
+permissions:
+  pull-requests: write
+```
+
+### 4. Annotations không hiển thị
+
+**Nguyên nhân:** File paths không đúng format
+
+**Giải pháp:** Đảm bảo paths là relative từ repo root:
+```yaml
+- uses: actions/checkout@v4  # Checkout đúng branch
+```
+
+### 5. Fork PRs không annotate được
+
+**Nguyên nhân:** `pull_request` event từ fork có quyền hạn chế
+
+**Giải pháp:** Dùng `pull_request_target` (cẩn thận về security!)
+```yaml
+on:
+  pull_request_target:  # Cho fork PRs
+```
+
+## Best Practices
+
+### 1. Fail on errors, warn on warnings
+
+```yaml
+- name: Run SunLint
+  run: sunlint --all --input=src --github-annotate
+  continue-on-error: false  # Fail if errors found
+```
+
+### 2. Cache SunLint installation
+
+```yaml
+- name: Cache SunLint
+  uses: actions/cache@v3
+  with:
+    path: ~/.npm
+    key: ${{ runner.os }}-sunlint-${{ hashFiles('**/package-lock.json') }}
+```
+
+### 3. Run only on specific files
+
+```yaml
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+      - '!src/**/*.test.ts'
+```
+
+### 4. Matrix strategy for multiple projects
+
+```yaml
+jobs:
+  sunlint:
+    strategy:
+      matrix:
+        project: [frontend, backend, mobile]
+    steps:
+      - run: sunlint --all --input=${{ matrix.project }} --github-annotate
+```
+
+### 5. Skip on draft PRs
+
+```yaml
+jobs:
+  sunlint:
+    if: github.event.pull_request.draft == false
+    steps:
+      - run: sunlint --all --github-annotate
+```
+
+## Migration Guide
+
+### From old style (with --output)
+
+**Before:**
+```yaml
+- name: Run SunLint
+  run: sunlint --all --input=src --output=report.json --format=json
+
+- name: Annotate PR
+  run: node annotate-script.js
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+**After:**
+```yaml
+- name: Run SunLint with Auto Annotation
+  run: sunlint --all --input=src --github-annotate
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## FAQ
+
+**Q: Có thể dùng cho push events không?**
+A: Không. `--github-annotate` chỉ hoạt động cho `pull_request` events. Dùng `--output` để save report cho push events.
+
+**Q: Có bị rate limit không?**
+A: SunLint có retry mechanism và batch processing để tránh rate limit. Maximum 30 comments/review, tự động chia batches nếu nhiều hơn.
+
+**Q: Có thể customize comment format không?**
+A: Hiện tại format là `[rule-id] message`. Customize format đang được phát triển.
+
+**Q: Có delete được comments cũ không?**
+A: SunLint có duplicate detection để tránh spam. Comments cũ được giữ lại cho lịch sử.
+
+**Q: Performance với large PRs?**
+A: SunLint optimize cho large PRs với:
+- Batch processing
+- Only comment on changed files
+- Async operations
+- Retry mechanism
+
+## Examples Repository
+
+Xem thêm examples tại: [examples/github-actions/](../examples/github-actions/)
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/sun-asterisk/engineer-excellence/issues)
+- Docs: [Documentation](../README.md)
+- Community: [Discussions](https://github.com/sun-asterisk/engineer-excellence/discussions)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sunlint",
-  "version": "1.3.19",
+  "version": "1.3.21",
   "description": "☀️ SunLint - Multi-language static analysis tool for code quality and security | Sun* Engineering Standards",
   "main": "cli.js",
   "bin": {
@@ -139,4 +139,4 @@
     "url": "https://github.com/sun-asterisk/engineer-excellence/issues"
   },
   "homepage": "https://github.com/sun-asterisk/engineer-excellence/tree/main/coding-quality/extensions/sunlint#readme"
-}
+}