@sun-asterisk/sunlint 1.3.50 → 1.3.52

package/core/summary-report-service.js

@@ -154,42 +154,67 @@ class SummaryReportService {
     const gitInfo = this.getGitInfo(options.cwd);
 
     // Override with environment variables if available (from CI/CD)
+    // Supports GitHub Actions, GitLab CI, and Bitbucket Pipelines
     const repository_url = process.env.GITHUB_REPOSITORY
       ? `https://github.com/${process.env.GITHUB_REPOSITORY}`
-      : gitInfo.repository_url;
+      : process.env.CI_PROJECT_URL    // GitLab CI: full URL available directly
+        || (process.env.BITBUCKET_WORKSPACE && process.env.BITBUCKET_REPO_SLUG
+          ? `https://bitbucket.org/${process.env.BITBUCKET_WORKSPACE}/${process.env.BITBUCKET_REPO_SLUG}`
+          : null)
+        || gitInfo.repository_url;
 
     const repository_name = process.env.GITHUB_REPOSITORY
       ? process.env.GITHUB_REPOSITORY.split('/')[1]
-      : (gitInfo.repository_name || null);
+      : process.env.CI_PROJECT_NAME   // GitLab CI
+        || process.env.BITBUCKET_REPO_SLUG  // Bitbucket Pipelines
+        || (gitInfo.repository_name || null);
 
-    const branch = process.env.GITHUB_REF_NAME || gitInfo.branch;
-    const commit_hash = process.env.GITHUB_SHA || gitInfo.commit_hash;
+    const branch = process.env.GITHUB_REF_NAME
+      || process.env.CI_COMMIT_REF_NAME   // GitLab CI
+      || process.env.BITBUCKET_BRANCH      // Bitbucket Pipelines
+      || gitInfo.branch;
 
-    // Get commit details from GitHub context or git
+    const commit_hash = process.env.GITHUB_SHA
+      || process.env.CI_COMMIT_SHA         // GitLab CI
+      || process.env.BITBUCKET_COMMIT      // Bitbucket Pipelines
+      || gitInfo.commit_hash;
+
+    // Get commit details from CI context or git
     const commit_message = process.env.GITHUB_EVENT_HEAD_COMMIT_MESSAGE
       || (process.env.GITHUB_EVENT_PATH
         ? this._getGitHubEventData('head_commit.message')
         : null)
-      || gitInfo.commit_message;
+      || process.env.CI_COMMIT_MESSAGE     // GitLab CI
+      || gitInfo.commit_message;            // Bitbucket: no env var, fallback to git
 
     const author_email = process.env.GITHUB_EVENT_HEAD_COMMIT_AUTHOR_EMAIL
       || (process.env.GITHUB_EVENT_PATH
         ? this._getGitHubEventData('head_commit.author.email')
         : null)
-      || gitInfo.author_email;
+      || process.env.GITLAB_USER_EMAIL     // GitLab CI
+      || gitInfo.author_email;             // Bitbucket: no env var, fallback to git
 
     const author_name = process.env.GITHUB_EVENT_HEAD_COMMIT_AUTHOR_NAME
       || (process.env.GITHUB_EVENT_PATH
         ? this._getGitHubEventData('head_commit.author.name')
         : null)
-      || gitInfo.author_name;
+      || process.env.GITLAB_USER_NAME      // GitLab CI
+      || gitInfo.author_name;              // Bitbucket: no env var, fallback to git
 
-    // Get PR number from GitHub event or git
+    // Get PR/MR number from CI context or git
     let pr_number = null;
     if (process.env.GITHUB_EVENT_PATH) {
       pr_number = this._getGitHubEventData('pull_request.number')
         || this._getGitHubEventData('number');
     }
+    // GitLab CI: Merge Request IID
+    if (!pr_number && process.env.CI_MERGE_REQUEST_IID) {
+      pr_number = parseInt(process.env.CI_MERGE_REQUEST_IID);
+    }
+    // Bitbucket Pipelines: Pull Request ID
+    if (!pr_number && process.env.BITBUCKET_PR_ID) {
+      pr_number = parseInt(process.env.BITBUCKET_PR_ID);
+    }
     pr_number = pr_number || gitInfo.pr_number;
 
     // Get project path (for mono-repo support)

package/core/tui-select.js

@@ -8,12 +8,8 @@
 
 'use strict';
 
-const readline = require('readline');
-
 // ─── ANSI helpers ────────────────────────────────────────────────────────────
 const ansi = {
-    saveCursor:    '\x1b7',
-    restoreCursor: '\x1b8',
     clearToEnd:    '\x1b[J',
     clearLine:     '\x1b[2K\r',
     hideCursor:    '\x1b[?25l',
@@ -108,13 +104,13 @@ function tuiSelect({ question, options, labels = {}, badges = {}, defaultIndex =
             return badges[value] ? c('green', ` ${badges[value]}`) : '';
         }
 
+        // question(1) + hint(1) + blank(1) + options(N)
+        const totalLines = 3 + options.length;
+
         function render(firstRender = false) {
-            if (firstRender) {
-                // Save cursor position BEFORE first render
-                process.stdout.write(ansi.saveCursor);
-            } else {
-                // Restore to saved position, then clear everything below
-                process.stdout.write(ansi.restoreCursor + ansi.clearToEnd);
+            if (!firstRender) {
+                // Move cursor up to where the prompt started, then clear to end
+                process.stdout.write(`\x1b[${totalLines}A\r` + ansi.clearToEnd);
             }
 
             // Question line
@@ -177,7 +173,7 @@ function tuiSelect({ question, options, labels = {}, badges = {}, defaultIndex =
                 const label = renderLabel(value);
                 const badge = renderBadge(value);
                 process.stdout.write(
-                    ansi.restoreCursor + ansi.clearToEnd +
+                    `\x1b[${totalLines}A\r` + ansi.clearToEnd +
                     ` ${c('green', '✔')} ${bold(question)} ${c('cyan', label)}${badge}\n\n`
                 );
 
@@ -186,7 +182,7 @@ function tuiSelect({ question, options, labels = {}, badges = {}, defaultIndex =
                 // Esc / Ctrl+C
                 cleanup();
                 process.stdin.removeListener('data', onKeypress);
-                process.stdout.write(ansi.restoreCursor + ansi.clearToEnd + '\n');
+                process.stdout.write(`\x1b[${totalLines}A\r` + ansi.clearToEnd + '\n');
                 reject(new Error('Cancelled by user'));
             }
         }

package/core/upload-service.js

@@ -221,9 +221,10 @@ class UploadService {
 
   /**
    * Get OIDC token from environment variables (for CI authentication)
+   * Supports both GitHub Actions and GitLab CI
    */
   getOidcToken() {
-    // Try to get GitHub Actions OIDC token first (requires API call)
+    // Try GitHub Actions OIDC token (requires API call)
     if (process.env.GITHUB_ACTIONS && process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN && process.env.ACTIONS_ID_TOKEN_REQUEST_URL) {
       try {
         const githubToken = this.requestGitHubOidcToken();
@@ -235,9 +236,32 @@ class UploadService {
       }
     }
 
-    // Check if running in GitHub Actions without OIDC token
+    // Try GitLab CI OIDC token (available directly as env var)
+    if (process.env.GITLAB_CI) {
+      try {
+        const gitlabToken = this.requestGitLabOidcToken();
+        if (gitlabToken) {
+          return gitlabToken;
+        }
+      } catch (error) {
+        console.log(chalk.yellow(`⚠️  Failed to get GitLab OIDC token: ${error.message}`));
+      }
+    }
+
+    // Try API_SECRET_KEY (for Bitbucket Pipelines or any CI without OIDC)
+    const apiKey = process.env.SUNLINT_API_KEY || process.env.API_SECRET_KEY;
+    if (apiKey) {
+      console.log(chalk.green('🔑 Using API key authentication'));
+      return apiKey;
+    }
+
+    // Warn if running in CI without any authentication
     if (process.env.GITHUB_ACTIONS) {
       console.log(chalk.yellow('⚠️  Running in GitHub Actions but no OIDC token available. Upload may require authentication.'));
+    } else if (process.env.GITLAB_CI) {
+      console.log(chalk.yellow('⚠️  Running in GitLab CI but no OIDC token available. Add id_tokens to your .gitlab-ci.yml.'));
+    } else if (process.env.BITBUCKET_PIPELINE_UUID) {
+      console.log(chalk.yellow('⚠️  Running in Bitbucket Pipelines but no API key found. Set SUNLINT_API_KEY in repository variables.'));
     }
 
     return null;
@@ -249,34 +273,53 @@ class UploadService {
   requestGitHubOidcToken() {
     const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
     const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
-    
+
     if (!requestToken || !requestUrl) {
       throw new Error('Missing GitHub OIDC request credentials');
     }
 
     try {
       // Use curl to request OIDC token from GitHub with specific audience
-      const curlCommand = `curl -H "Authorization: bearer ${requestToken}" "${requestUrl}&audience=coding-standards-report-api"`;
-      
-      const response = execSync(curlCommand, { 
+      const curlCommand = `curl -s -H "Authorization: bearer ${requestToken}" "${requestUrl}&audience=coding-standards-report-api"`;
+
+      const response = execSync(curlCommand, {
         encoding: 'utf8',
         timeout: 10000, // 10 second timeout
         stdio: 'pipe'
       });
 
       const responseData = JSON.parse(response);
-      
+
       if (responseData.value) {
         return responseData.value;
       } else {
         throw new Error('No token in response');
       }
-      
+
     } catch (error) {
       throw new Error(`GitHub OIDC request failed: ${error.message}`);
     }
   }
 
+  /**
+   * Get OIDC token from GitLab CI
+   * GitLab provides the JWT directly as an environment variable (no API call needed).
+   * Requires id_tokens configuration in .gitlab-ci.yml:
+   *   id_tokens:
+   *     SUNLINT_ID_TOKEN:
+   *       aud: coding-standards-report-api
+   */
+  requestGitLabOidcToken() {
+    // GitLab CI id_tokens: custom-named token with specific audience
+    const token = process.env.SUNLINT_ID_TOKEN || process.env.CI_JOB_JWT_V2 || process.env.CI_JOB_JWT;
+
+    if (!token) {
+      throw new Error('No GitLab OIDC token found. Configure id_tokens in .gitlab-ci.yml');
+    }
+
+    return token;
+  }
+
   /**
    * Generate idempotency key for safe retries
    */
@@ -284,20 +327,35 @@ class UploadService {
     // Create deterministic key based on file content and timestamp
     const fileContent = fs.readFileSync(filePath, 'utf8');
     const timestamp = new Date().toISOString().split('T')[0]; // YYYY-MM-DD format
-    
+
     // Include CI context for uniqueness across environments and attempts
-    const ciContext = process.env.GITHUB_ACTIONS ? 
-      `${process.env.GITHUB_REPOSITORY || 'unknown'}-${process.env.GITHUB_RUN_ID || 'local'}-${process.env.GITHUB_RUN_ATTEMPT || '1'}` : 
-      'local';
-    
+    const ciContext = this.buildCiContext();
+
     // Create hash from content + date + CI context + run attempt
     const hashInput = `${fileContent}-${timestamp}-${ciContext}`;
     const hash = crypto.createHash('sha256').update(hashInput).digest('hex');
-    
+
     // Return first 32 characters for reasonable key length
     return `sunlint-${hash.substring(0, 24)}`;
   }
 
+  /**
+   * Build CI context string for idempotency key generation
+   * Supports GitHub Actions and GitLab CI
+   */
+  buildCiContext() {
+    if (process.env.GITHUB_ACTIONS) {
+      return `${process.env.GITHUB_REPOSITORY || 'unknown'}-${process.env.GITHUB_RUN_ID || 'local'}-${process.env.GITHUB_RUN_ATTEMPT || '1'}`;
+    }
+    if (process.env.GITLAB_CI) {
+      return `${process.env.CI_PROJECT_PATH || 'unknown'}-${process.env.CI_PIPELINE_ID || 'local'}-${process.env.CI_JOB_ID || '1'}`;
+    }
+    if (process.env.BITBUCKET_PIPELINE_UUID) {
+      return `${process.env.BITBUCKET_REPO_SLUG || 'unknown'}-${process.env.BITBUCKET_BUILD_NUMBER || 'local'}-${process.env.BITBUCKET_STEP_UUID || '1'}`;
+    }
+    return 'local';
+  }
+
   /**
    * Validate API endpoint accessibility
    */

package/docs/CI_REPORT_UPLOAD_FLOW.md

@@ -0,0 +1,777 @@
+# CI Report Upload Flow: GitHub Actions / GitLab CI / Bitbucket Pipelines
+
+Tài liệu chi tiết luồng hoạt động khi chạy SunLint trên CI/CD,
+từ lúc scan code đến khi report được lưu vào database.
+Hỗ trợ 3 nền tảng: GitHub Actions, GitLab CI, Bitbucket Pipelines.
+
+---
+
+## Workflow YAML mẫu
+
+### GitHub Actions
+
+```yaml
+name: Sunlint Code Quality Check
+on: [pull_request]
+jobs:
+  sunlint:
+    runs-on: "macos-latest"
+    permissions:
+      id-token: write    # BẮT BUỘC - cho phép request OIDC token
+      contents: read
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: "21"
+      - run: npm install -g @sun-asterisk/sunlint
+      - run: sunlint --specific --languages=dart --input=lib --output-summary=report.json --upload-report --quiet
+```
+
+### GitLab CI
+
+```yaml
+sunlint:
+  image: node:21
+  stage: test
+  # Cấu hình OIDC token cho SunLint
+  id_tokens:
+    SUNLINT_ID_TOKEN:
+      aud: coding-standards-report-api
+  script:
+    - npm install -g @sun-asterisk/sunlint
+    - sunlint --specific --languages=dart --input=lib --output-summary=report.json --upload-report --quiet
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+```
+
+### Bitbucket Pipelines
+
+```yaml
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          name: SunLint Code Quality Check
+          image: node:21
+          script:
+            - npm install -g @sun-asterisk/sunlint
+            - sunlint --specific --languages=dart --input=lib --output-summary=report.json --upload-report --quiet
+```
+
+> **Lưu ý Bitbucket**: Dùng `SUNLINT_API_KEY` (API key) thay vì OIDC.
+> Cấu hình trong Repository Settings → Repository variables → `SUNLINT_API_KEY` (đánh dấu Secured).
+
+---
+
+## Tổng quan 8 phases
+
+```
+PHASE 1: Khởi tạo CLI
+PHASE 2: Chọn rules & files
+PHASE 3: Phân tích code
+PHASE 4: Tạo report.json
+PHASE 5: Upload report (xác thực)
+PHASE 6: Server nhận & xác thực
+PHASE 7: Lưu vào Database
+PHASE 8: CI kết thúc
+```
+
+## Data flow tổng quát
+
+```
+┌──────────┐    ┌──────────┐    ┌───────────┐    ┌──────────┐    ┌──────────┐
+│    CI     │    │  SunLint │    │   OIDC    │    │ Dashboard│    │PostgreSQL│
+│  Runner   │───>│  CLI     │───>│ Provider  │    │  API     │    │    DB    │
+│           │    │          │    │ /API Key  │    │          │    │          │
+└──────────┘    └────┬─────┘    └─────┬─────┘    └────┬─────┘    └────┬─────┘
+                     │                │               │               │
+              1. Scan code            │               │               │
+              2. Tạo report.json      │               │               │
+              3. Lấy auth token ─────>│               │               │
+              4. Nhận JWT/API key <───┘               │               │
+              5. POST report.json + token ───────────>│               │
+              6. Verify token ─────────────────────── │               │
+              7. Token hợp lệ                         │               │
+              8. Parse report.json                    │               │
+              9. INSERT repository ───────────────────┼──────────────>│
+             10. INSERT report ───────────────────────┼──────────────>│
+             11. INSERT violations ───────────────────┼──────────────>│
+             12. Invalidate cache                     │               │
+             13. HTTP 201 <───────────────────────────┘               │
+             14. CI exit(0)                                           │
+```
+
+---
+
+## PHASE 1: Khởi tạo CLI
+
+**File**: `core/cli-action-handler.js` - `execute()` (line 42-141)
+
+```
+cli.js  →  CliActionHandler.execute()
+  ├── displayModernBanner()        → "SunLint v1.x.x"
+  ├── handleShortcuts()            → check --version, --list-rules
+  └── loadConfiguration()          → ConfigManager đọc .sunlint.json (nếu có)
+```
+
+### Validate input (line 316-390)
+
+```
+validateInput(config)
+  ├── Check --engine option hợp lệ
+  ├── Check --upload-report CẦN --output-summary
+  │     └── options.uploadReport chưa có URL?
+  │         → Gán default: "https://coding-standards-report.sun-asterisk.vn/api/reports"
+  └── Check --input=lib tồn tại
+```
+
+---
+
+## PHASE 2: Chọn rules & files
+
+### Select rules (line 63)
+
+```
+ruleSelectionService.selectRules(config, options)
+  └── --specific --languages=dart
+      → Chọn tất cả rules hỗ trợ Dart:
+        C001, C002, C003, C005, C006, C008, C010...
+        D001, D002, D003, D004, D005...
+        S001, S002, S003...
+        (khoảng 80-100 rules cho Dart)
+```
+
+### File targeting (line 71)
+
+```
+fileTargetingService.getTargetFiles(["lib"], config, options)
+  └── Scan thư mục lib/
+      → Tìm tất cả file *.dart
+      → Trả về danh sách: ["lib/main.dart", "lib/app.dart", ...]
+      → KHÔNG filter bởi git diff → QUÉT TOÀN BỘ CODE
+```
+
+> **Lưu ý**: Với lệnh `--input=lib` (KHÔNG có `--changed-files`),
+> sunlint quét **TOÀN BỘ** code trong thư mục `lib/`, không chỉ phần diff.
+> Muốn chỉ quét diff, thêm `--changed-files`.
+
+---
+
+## PHASE 3: Phân tích code
+
+### Khởi tạo engines (line 146-188)
+
+```
+runModernAnalysis(rulesToRun, files, config)
+  └── orchestrator.initialize({
+        enabledEngines: ["heuristic"],     ← Dart chỉ dùng heuristic
+        heuristicConfig: {
+          targetFiles: ["lib/*.dart"],
+          projectPath: "/path/to/project",
+          maxSemanticFiles: 1000
+        }
+      })
+```
+
+### Chạy phân tích
+
+```
+orchestrator.analyze(files, rulesToRun, options)
+  │
+  ├── Với mỗi file .dart:
+  │     ├── HeuristicEngine: pattern matching (regex)
+  │     └── DartAnalyzer: sunlint-dart-macos binary (nếu spawn OK)
+  │           ├── Binary chạy được? → Deep AST analysis (nhiều violations)
+  │           └── Binary FAIL?      → Fallback regex (ít violations)
+  │
+  └── Kết quả: { results: [...], summary: { total, errors, warnings } }
+```
+
+---
+
+## PHASE 4: Tạo report.json
+
+### Output results
+
+**File**: `core/output-service.js` - `outputResults()` (line 38-129)
+
+```
+outputService.outputResults(results, options, metadata)
+  │
+  ├── generateReport(results)           → Formatted text + violations array
+  │
+  ├── console.log(report.formatted)     ← ĐÂY LÀ CHỖ BỊ KILL nếu quá nhiều output
+  │                                        --quiet sẽ skip dòng này
+  │
+  └── options.outputSummary = "report.json"  → Vào bước tiếp theo
+```
+
+### Tạo summary report
+
+**File**: `core/summary-report-service.js` - `generateSummaryReport()` (line 152-335)
+
+#### Thu thập Git info (line 37-143)
+
+```
+getGitInfo()
+  ├── git config --get remote.origin.url  → "https://github.com/org/repo"
+  ├── git rev-parse --abbrev-ref HEAD     → "feature/xyz"
+  ├── git rev-parse HEAD                  → "abc123..."
+  ├── git log -1 --pretty=%B              → "feat: add login page"
+  ├── git log -1 --pretty=%ae             → "dev@sun-asterisk.com"
+  ├── git log -1 --pretty=%an             → "Nguyen Van A"
+  └── Trích PR number từ commit message hoặc branch name
+```
+
+Trên CI, override bằng env vars (theo thứ tự ưu tiên: GitHub → GitLab → Bitbucket → git):
+
+| Trường | GitHub Actions | GitLab CI | Bitbucket Pipelines |
+|--------|----------------|-----------|---------------------|
+| repository_url | `GITHUB_REPOSITORY` (ghép) | `CI_PROJECT_URL` | `BITBUCKET_WORKSPACE` + `BITBUCKET_REPO_SLUG` (ghép) |
+| repository_name | `GITHUB_REPOSITORY` (split) | `CI_PROJECT_NAME` | `BITBUCKET_REPO_SLUG` |
+| branch | `GITHUB_REF_NAME` | `CI_COMMIT_REF_NAME` | `BITBUCKET_BRANCH` |
+| commit_hash | `GITHUB_SHA` | `CI_COMMIT_SHA` | `BITBUCKET_COMMIT` |
+| commit_message | `GITHUB_EVENT_PATH` (JSON) | `CI_COMMIT_MESSAGE` | git fallback |
+| author_email | `GITHUB_EVENT_PATH` (JSON) | `GITLAB_USER_EMAIL` | git fallback |
+| author_name | `GITHUB_EVENT_PATH` (JSON) | `GITLAB_USER_NAME` | git fallback |
+| PR/MR number | `GITHUB_EVENT_PATH` (JSON) | `CI_MERGE_REQUEST_IID` | `BITBUCKET_PR_ID` |
+
+> **Bitbucket**: Không cung cấp commit_message, author_email, author_name qua env vars.
+> SunLint tự lấy từ `git log` trên runner (luôn có vì đã checkout code).
+
+#### Build report JSON (line 152-335)
+
+Gom violations theo rule:
+
+```
+violations[] → { C006: 150, C010: 89, D008: 200, ... }
+```
+
+Cấu trúc file `report.json`:
+
+```json
+{
+  "repository_url": "https://github.com/org/my-flutter-app",
+  "repository_name": "my-flutter-app",
+  "project_path": null,
+  "branch": "feature/login",
+  "commit_hash": "abc123def456...",
+  "commit_message": "feat: add login page (#42)",
+  "author_email": "dev@sun-asterisk.com",
+  "author_name": "Nguyen Van A",
+  "pr_number": 42,
+  "score": 65,
+  "total_violations": 4293,
+  "error_count": 12,
+  "warning_count": 4281,
+  "info_count": 0,
+  "lines_of_code": 50000,
+  "files_analyzed": 320,
+  "sunlint_version": "1.3.25",
+  "analysis_duration_ms": 15000,
+  "scoring_mode": "project",
+  "violations": [
+    { "rule_code": "D008", "count": 200, "severity": "warning" },
+    { "rule_code": "C006", "count": 150, "severity": "warning" },
+    { "rule_code": "C010", "count": 89, "severity": "warning" }
+  ],
+  "metadata": {
+    "generated_at": "2026-03-12T10:30:00.000Z",
+    "tool": "SunLint",
+    "version": "1.3.25"
+  },
+  "quality": {
+    "score": 65,
+    "grade": "C",
+    "metrics": { "errors": 12, "warnings": 4281, "linesOfCode": 50000 }
+  }
+}
+```
+
+```
+fs.writeFileSync("report.json", JSON.stringify(summaryReport))
+→ "Summary report saved to: report.json"
+```
+
+---
+
+## PHASE 5: Upload report
+
+### Kích hoạt upload
+
+**File**: `core/output-service.js` (line 110-112)
+
+```
+options.uploadReport = "https://coding-standards-report.sun-asterisk.vn/api/reports"
+  → handleUploadReport("report.json", apiUrl, options)
+    → uploadService.uploadReportToApi("report.json", apiUrl)
+```
+
+### Lấy auth token
+
+**File**: `core/upload-service.js` - `getOidcToken()` (line 226-280)
+
+Thứ tự thử xác thực:
+
+```
+getOidcToken()
+  │
+  ├── 1. GitHub Actions OIDC?
+  │     Check: GITHUB_ACTIONS + ACTIONS_ID_TOKEN_REQUEST_TOKEN + ACTIONS_ID_TOKEN_REQUEST_URL
+  │     → requestGitHubOidcToken()  (gọi API GitHub để lấy JWT)
+  │
+  ├── 2. GitLab CI OIDC?
+  │     Check: GITLAB_CI
+  │     → requestGitLabOidcToken()  (đọc env var SUNLINT_ID_TOKEN)
+  │
+  ├── 3. API Key? (Bitbucket hoặc bất kỳ CI nào)
+  │     Check: SUNLINT_API_KEY || API_SECRET_KEY
+  │     → return apiKey
+  │
+  └── 4. Không có gì → return null + warning message
+```
+
+#### GitHub Actions: Lấy OIDC token qua API
+
+```
+requestGitHubOidcToken()
+  │
+  │  curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN"
+  │       "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=coding-standards-report-api"
+  │
+  │  HTTPS request tới GitHub OIDC Provider
+  │
+  └── Response: { "value": "eyJhbGciOiJSUzI1NiIs..." }
+                              │
+                              └── JWT Token chứa:
+                                  {
+                                    "iss": "https://token.actions.githubusercontent.com",
+                                    "aud": "coding-standards-report-api",
+                                    "sub": "repo:org/my-flutter-app:ref:refs/heads/feature/login",
+                                    "repository": "org/my-flutter-app",
+                                    "repository_owner": "sun-asterisk",
+                                    "actor": "nguyen-van-a",
+                                    "exp": 1741689600   ← hết hạn sau ~5 phút
+                                  }
+```
+
+#### GitLab CI: Token có sẵn trong env var
+
+```
+requestGitLabOidcToken()
+  │
+  └── return process.env.SUNLINT_ID_TOKEN
+        │
+        └── JWT Token chứa:
+            {
+              "iss": "https://gitlab.com",
+              "aud": "coding-standards-report-api",
+              "sub": "project_path:group/repo:ref_type:branch:ref:main",
+              "project_path": "group/repo",
+              "namespace_path": "group",
+              "user_login": "nguyen-van-a",
+              "pipeline_id": "12345"
+            }
+```
+
+#### Bitbucket Pipelines: API key từ env var
+
+```
+Không có OIDC → Fallback sang API key:
+  process.env.SUNLINT_API_KEY  →  "k7Hs9mPqR2xYwN3v..."
+```
+
+### Gửi report
+
+**File**: `core/upload-service.js` - `buildCurlCommand()` (line 180-208)
+
+```bash
+curl -X POST \
+  --connect-timeout 30 \
+  --max-time 30 \
+  -H "Content-Type: application/json" \
+  -H "User-Agent: SunLint-Report-Uploader/1.0" \
+  -H "Idempotency-Key: sunlint-a1b2c3d4e5f6..." \
+  -H "Authorization: Bearer <OIDC_TOKEN hoặc API_KEY>" \
+  --data-binary @"report.json" \
+  -i -s \
+  "https://coding-standards-report.sun-asterisk.vn/api/reports"
+```
+
+```
+execSync(curlCommand)
+  → Parse HTTP response headers + body
+  → Trích xuất status code (201 = thành công)
+```
+
+---
+
+## PHASE 6: Server nhận & xác thực
+
+### API Route
+
+**File**: `coding-standards-reports/app/api/reports/route.ts` - `POST` (line 45-406)
+
+```
+POST /api/reports
+  │
+  └── verifyAuth(authHeader)
+        │
+        ├── 1. Thử API_SECRET_KEY match?
+        │     token === process.env.API_SECRET_KEY → OK (actor: "api-key")
+        │     (Bitbucket Pipelines dùng cách này)
+        │
+        ├── 2. Thử GitHub OIDC?
+        │     verifyGitHubOIDCToken(token) → OK (actor: github username)
+        │
+        ├── 3. Thử GitLab OIDC?
+        │     verifyGitLabOIDCToken(token) → OK (actor: gitlab username)
+        │
+        └── 4. Tất cả fail → 401 Unauthorized
+```
+
+### Xác minh JWT (GitHub OIDC)
+
+**File**: `coding-standards-reports/lib/auth/github-oidc.ts` (line 79-111)
+
+```
+verifyGitHubOIDCToken(token, "coding-standards-report-api")
+  │
+  ├── Fetch JWKS:
+  │     GET https://token.actions.githubusercontent.com/.well-known/jwks
+  │     → Lấy public keys của GitHub (RSA)
+  │
+  ├── jwtVerify(token, JWKS, {
+  │     issuer: "https://token.actions.githubusercontent.com",
+  │     audience: "coding-standards-report-api",
+  │     requiredClaims: ["iss","sub","aud","repository","repository_owner"]
+  │   })
+  │
+  ├── Verify chữ ký RSA                               OK
+  ├── Check issuer khớp                                OK
+  ├── Check audience = "coding-standards-report-api"   OK
+  ├── Check token chưa hết hạn (exp)                   OK
+  ├── Check có đủ required claims                      OK
+  │
+  └── Return payload:
+      {
+        repository: "org/my-flutter-app",
+        repository_owner: "sun-asterisk",
+        actor: "nguyen-van-a"
+      }
+```
+
+### Xác minh JWT (GitLab OIDC)
+
+**File**: `coding-standards-reports/lib/auth/gitlab-oidc.ts` (line 122-153)
+
+```
+verifyGitLabOIDCToken(token, "coding-standards-report-api")
+  │
+  ├── Fetch JWKS:
+  │     GET https://gitlab.com/oauth/discovery/keys
+  │     → Lấy public keys của GitLab (RSA)
+  │
+  ├── jwtVerify(token, JWKS, {
+  │     issuer: "https://gitlab.com",
+  │     audience: "coding-standards-report-api",
+  │     requiredClaims: ["iss","sub","aud","project_path","namespace_path"]
+  │   })
+  │
+  └── Return payload:
+      {
+        project_path: "group/my-flutter-app",
+        namespace_path: "group",
+        user_login: "nguyen-van-a"
+      }
+```
+
+### Xác minh API key (Bitbucket)
+
+```
+token === process.env.API_SECRET_KEY?
+  → Có: authenticated = true, actor = "api-key"
+  → Không: tiếp tục thử OIDC providers
+```
+
+---
+
+## So sánh 3 phương thức xác thực
+
+| | GitHub Actions | GitLab CI | Bitbucket Pipelines |
+|---|---|---|---|
+| **Phương thức** | OIDC (JWT) | OIDC (JWT) | API Key |
+| **Cấu hình CI** | `permissions: id-token: write` | `id_tokens: SUNLINT_ID_TOKEN` | `SUNLINT_API_KEY` (Secured variable) |
+| **Cách lấy token** | Gọi API GitHub runtime | Có sẵn trong env var | Có sẵn trong env var |
+| **Server verify** | Fetch JWKS → verify chữ ký RSA | Fetch JWKS → verify chữ ký RSA | So sánh string với `API_SECRET_KEY` |
+| **Shared secret** | Không | Không | Có (API key) |
+| **Token hết hạn** | ~5 phút (tự động) | ~5 phút (tự động) | Không bao giờ (rotate thủ công) |
+| **Audit trail** | Biết repo + actor + workflow | Biết project + user + pipeline | Chỉ biết "api-key" |
+| **Server config** | Không cần | `GITLAB_OIDC_ISSUER` (nếu self-hosted) | `API_SECRET_KEY` |
+
+### Bảo mật
+
+| | OIDC (GitHub/GitLab) | API Key (Bitbucket) |
+|---|---|---|
+| Rủi ro lộ secret | Không có secret để lộ | Key lộ → ai cũng upload được |
+| Phạm vi | Gắn với repo/workflow cụ thể | Ai có key đều dùng được |
+| Rotation | Tự động mỗi lần chạy CI | Phải đổi thủ công cả 2 phía |
+| Giảm thiểu rủi ro | -- | Đánh dấu Secured + rotate định kỳ |
+
+---
+
+## PHASE 7: Lưu vào Database
+
+### Parse body & nhận diện format
+
+**File**: `coding-standards-reports/app/api/reports/route.ts` (line 56-129)
+
+```
+Kiểm tra format:
+  body.repository_url        OK
+  body.commit_hash           OK
+  body.score                 OK
+  body.violations[]          OK
+  body.metadata.tool === "SunLint"  OK
+  → Nhận diện: "Native SunLint CLI format"
+```
+
+3 formats được hỗ trợ:
+1. **Native SunLint CLI** (`--output-summary`) - format hiện tại
+2. **Enriched format** (legacy, nested git object)
+3. **Legacy manual format** (từ old workflow)
+
+### Tìm/tạo repository (line 150-238)
+
+```sql
+-- Tìm repository đã tồn tại chưa?
+SELECT * FROM repositories
+  WHERE repository_url = 'https://github.com/org/my-flutter-app'
+  AND project_path IS NULL
+  LIMIT 1;
+
+-- Nếu chưa có → INSERT
+INSERT INTO repositories (repository_url, repository_name, project_path)
+  VALUES ('https://github.com/org/my-flutter-app', 'my-flutter-app', NULL)
+  RETURNING *;
+
+-- Tìm rubato_id từ project_access (Google Sheets sync)
+SELECT rubato_id FROM project_access
+  WHERE repository LIKE '%https://github.com/org/my-flutter-app%'
+  LIMIT 1;
+
+-- Nếu tìm được → Tạo mapping
+INSERT INTO project_repository_mapping (...)
+```
+
+### Thêm report (line 241-270)
+
+```sql
+INSERT INTO reports (
+  repository_id, repository_url, repository_name,
+  branch, commit_hash, commit_message,
+  author_email, author_name, pr_number,
+  score, total_violations, error_count, warning_count,
+  info_count, lines_of_code, files_analyzed,
+  sunlint_version, analysis_duration_ms
+) VALUES (
+  42, 'https://github.com/org/my-flutter-app', 'my-flutter-app',
+  'feature/login', 'abc123...', 'feat: add login page (#42)',
+  'dev@sun-asterisk.com', 'Nguyen Van A', 42,
+  65, 4293, 12, 4281,
+  0, 50000, 320,
+  '1.3.25', 15000
+) RETURNING *;
+```
+
+### Thêm violations (line 276-287)
+
+```sql
+-- Với mỗi violation summary:
+INSERT INTO violations (report_id, rule_code, violation_count)
+  VALUES (report_id, 'D008', 200)
+  ON CONFLICT (report_id, rule_code) DO UPDATE
+  SET violation_count = EXCLUDED.violation_count;
+
+INSERT INTO violations (report_id, rule_code, violation_count)
+  VALUES (report_id, 'C006', 150) ...
+
+-- ... lặp cho tất cả rules có violations
+```
+
+### Thêm dữ liệu architecture (line 290-381, nếu có)
+
+```sql
+INSERT INTO report_architecture (
+  report_id, primary_pattern, primary_confidence, health_score,
+  violation_count, rules_checked, rules_passed, rules_failed,
+  is_hybrid, combination, secondary_patterns, analysis_time_ms
+) VALUES (...) RETURNING *;
+
+-- Thêm architecture rules + violations
+INSERT INTO report_architecture_rules (...) VALUES ...;
+INSERT INTO report_architecture_violations (...) VALUES ...;
+```
+
+### Xóa cache & phản hồi (line 383-398)
+
+```
+revalidateTag("department-health")
+revalidateTag("dept-adoption")
+revalidateTag("dept-scores")
+revalidateTag("score-trend")
+revalidateTag("violations-severity")
+revalidateTag("projects-filter")
+
+→ Response: { success: true, report_id: 1234, message: "Report submitted successfully" }
+→ HTTP 201 Created
+```
+
+---
+
+## PHASE 8: CI kết thúc
+
+```
+uploadService nhận HTTP 201
+  → "Report uploaded successfully!"
+  → "HTTP Status: 201"
+
+handleExit(results)
+  → Có errors? → process.exit(1)  → CI job FAIL
+  → Chỉ warnings? → process.exit(0) → CI job PASS
+```
+
+---
+
+## Env vars mapping đầy đủ
+
+### Detect CI platform
+
+| Mục đích | GitHub Actions | GitLab CI | Bitbucket Pipelines |
+|----------|----------------|-----------|---------------------|
+| Detect CI | `GITHUB_ACTIONS` | `GITLAB_CI` | `BITBUCKET_PIPELINE_UUID` |
+
+### Report metadata
+
+| Mục đích | GitHub Actions | GitLab CI | Bitbucket Pipelines |
+|----------|----------------|-----------|---------------------|
+| Repository URL | `GITHUB_REPOSITORY` (ghép) | `CI_PROJECT_URL` | `BITBUCKET_WORKSPACE` + `BITBUCKET_REPO_SLUG` (ghép) |
+| Repository name | `GITHUB_REPOSITORY` (split `/`) | `CI_PROJECT_NAME` | `BITBUCKET_REPO_SLUG` |
+| Branch | `GITHUB_REF_NAME` | `CI_COMMIT_REF_NAME` | `BITBUCKET_BRANCH` |
+| Commit SHA | `GITHUB_SHA` | `CI_COMMIT_SHA` | `BITBUCKET_COMMIT` |
+| Commit message | `GITHUB_EVENT_PATH` (JSON file) | `CI_COMMIT_MESSAGE` | git fallback |
+| Author email | `GITHUB_EVENT_PATH` (JSON file) | `GITLAB_USER_EMAIL` | git fallback |
+| Author name | `GITHUB_EVENT_PATH` (JSON file) | `GITLAB_USER_NAME` | git fallback |
+| PR/MR number | `GITHUB_EVENT_PATH` (JSON file) | `CI_MERGE_REQUEST_IID` | `BITBUCKET_PR_ID` |
+
+### Authentication
+
+| Mục đích | GitHub Actions | GitLab CI | Bitbucket Pipelines |
+|----------|----------------|-----------|---------------------|
+| Auth method | OIDC | OIDC | API Key |
+| Token source | `ACTIONS_ID_TOKEN_REQUEST_*` (API) | `SUNLINT_ID_TOKEN` (env var) | `SUNLINT_API_KEY` (env var) |
+| Audience | `coding-standards-report-api` | `coding-standards-report-api` | N/A |
+
+### Idempotency key context
+
+| Mục đích | GitHub Actions | GitLab CI | Bitbucket Pipelines |
+|----------|----------------|-----------|---------------------|
+| Run ID | `GITHUB_RUN_ID` | `CI_PIPELINE_ID` | `BITBUCKET_BUILD_NUMBER` |
+| Run attempt | `GITHUB_RUN_ATTEMPT` | `CI_JOB_ID` | `BITBUCKET_STEP_UUID` |
+| Repo identifier | `GITHUB_REPOSITORY` | `CI_PROJECT_PATH` | `BITBUCKET_REPO_SLUG` |
+
+---
+
+## Source files tham chiếu
+
+| Phase | File | Function |
+|-------|------|----------|
+| 1 | `core/cli-action-handler.js` | `execute()`, `validateInput()` |
+| 2 | `core/rule-selection-service.js` | `selectRules()` |
+| 2 | `core/file-targeting-service.js` | `getTargetFiles()` |
+| 3 | `core/analysis-orchestrator.js` | `analyze()` |
+| 3 | `core/adapters/dart-analyzer.js` | `resolveBinary()`, `analyze()` |
+| 4 | `core/output-service.js` | `outputResults()`, `generateAndSaveSummaryReport()` |
+| 4 | `core/summary-report-service.js` | `generateSummaryReport()`, `getGitInfo()` |
+| 5 | `core/upload-service.js` | `uploadReportToApi()`, `getOidcToken()`, `requestGitHubOidcToken()`, `requestGitLabOidcToken()` |
+| 6 | `coding-standards-reports/app/api/reports/route.ts` | `POST()`, `verifyAuth()` |
+| 6 | `coding-standards-reports/lib/auth/github-oidc.ts` | `verifyGitHubOIDCToken()` |
+| 6 | `coding-standards-reports/lib/auth/gitlab-oidc.ts` | `verifyGitLabOIDCToken()` |
+| 7 | `coding-standards-reports/app/api/reports/route.ts` | SQL queries (INSERT) |
+
+---
+
+## Hướng dẫn cấu hình nhanh
+
+### GitHub Actions
+
+1. Thêm `permissions: id-token: write` vào job
+2. Thêm `--upload-report --quiet` vào lệnh sunlint
+3. Không cần cấu hình gì thêm trên server
+
+### GitLab CI
+
+1. Thêm `id_tokens` vào job trong `.gitlab-ci.yml`:
+   ```yaml
+   id_tokens:
+     SUNLINT_ID_TOKEN:
+       aud: coding-standards-report-api
+   ```
+2. Thêm `--upload-report --quiet` vào lệnh sunlint
+3. Nếu GitLab self-hosted: set `GITLAB_OIDC_ISSUER` trên server Dashboard
+
+### Bitbucket Pipelines
+
+1. Tạo API key trên server: `openssl rand -base64 32`
+2. Đặt giá trị vào server Dashboard `.env.local` → `API_SECRET_KEY=<giá_trị>`
+3. Đặt **cùng giá trị** vào Bitbucket → Repository Settings → Repository variables:
+   - Name: `SUNLINT_API_KEY`
+   - Value: `<giá_trị>`
+   - Secured: ✅
+4. Thêm `--upload-report --quiet` vào lệnh sunlint
+
+---
+
+## Xử lý sự cố
+
+### Process bị kill khi output quá nhiều
+- **Nguyên nhân**: `console.log(report.formatted)` in tất cả violations ra stdout
+- **Cách xử lý**: Thêm `--quiet` để skip console output, report.json vẫn được tạo đầy đủ
+
+### Binary Dart không chạy trên CI
+- **Nguyên nhân**: `sunlint-dart-macos` là ARM64, không chạy trên Intel runner
+- **Cách xử lý**: Dùng `macos-14` hoặc `macos-latest` (Apple Silicon)
+
+### Upload thất bại 401 Unauthorized (GitHub)
+- **Nguyên nhân**: Thiếu `permissions: id-token: write` trong workflow
+- **Cách xử lý**: Thêm permission vào job
+
+### Upload thất bại 401 Unauthorized (GitLab)
+- **Nguyên nhân**: Thiếu `id_tokens` trong `.gitlab-ci.yml`
+- **Cách xử lý**: Thêm cấu hình `id_tokens` với audience `coding-standards-report-api`
+
+### Upload thất bại 401 Unauthorized (Bitbucket)
+- **Nguyên nhân**: `SUNLINT_API_KEY` không khớp với `API_SECRET_KEY` trên server
+- **Cách xử lý**: Kiểm tra giá trị 2 bên phải giống nhau. Tạo lại bằng `openssl rand -base64 32`
+
+### Upload thất bại - không có token (GitHub)
+- **Nguyên nhân**: `ACTIONS_ID_TOKEN_REQUEST_TOKEN` không được set
+- **Cách xử lý**: Đảm bảo `id-token: write` và workflow chạy trên GitHub Actions
+
+### Upload thất bại - không có token (GitLab)
+- **Nguyên nhân**: `SUNLINT_ID_TOKEN` không được set
+- **Cách xử lý**: Thêm `id_tokens` vào job:
+  ```yaml
+  id_tokens:
+    SUNLINT_ID_TOKEN:
+      aud: coding-standards-report-api
+  ```
+
+### Upload thất bại - không có token (Bitbucket)
+- **Nguyên nhân**: `SUNLINT_API_KEY` chưa được cấu hình
+- **Cách xử lý**: Thêm `SUNLINT_API_KEY` vào Repository Settings → Repository variables (đánh dấu Secured)
+
+### Self-hosted GitLab: JWKS fetch thất bại
+- **Nguyên nhân**: Server Dashboard không biết URL GitLab instance
+- **Cách xử lý**: Set `GITLAB_OIDC_ISSUER=https://gitlab.your-company.com` trên server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sunlint",
-  "version": "1.3.50",
+  "version": "1.3.52",
   "description": "☀️ SunLint - Multi-language static analysis tool for code quality and security | Sun* Engineering Standards",
   "main": "cli.js",
   "bin": {