静态分析与质量左移：从 SonarQube 门禁到 CodeQL 语义扫描的工程化实践

编码时（IDE 实时提示） 1x  →  提交前 3x  →  CI 静态扫描 8x
集成测试 20x  →  生产环境 100x+

结论：越早发现越便宜。静态分析的价值不是"找到更多 bug"，
      而是"把发现时机提前到成本最低的那一刻"。

层级一：格式化与风格   Prettier / Black / gofmt / rustfmt
        → 零争议、可自动修复、必须强制

层级二：Lint（模式匹配）  ESLint / Ruff / golangci-lint / Clippy
        → 基于 AST 规则，快、可配置、误报可控

层级三：类型检查  TypeScript / mypy / Pyright
        → 证明"某类错误不可能发生"

层级四：SAST / 污点分析  CodeQL / Semgrep / SonarQube
        → 跟踪数据从 Source 到 Sink，慢但深

层级五：形式化验证  Frama-C / Dafny / TLA+
        → 数学证明，成本极高，只用于核心模块

// eslint.config.mjs — ESLint 9 扁平配置
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import react from 'eslint-plugin-react-hooks';

export default tseslint.config(
  { ignores: ['dist/**', 'coverage/**', '**/*.generated.ts'] },
  js.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  {
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
    plugins: { 'react-hooks': react },
    rules: {
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'warn',
      // 关键：把 any 泄漏视为错误而非警告
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-misused-promises': 'error',
      // 圈复杂度内建检查
      complexity: ['error', { max: 12 }],
      'max-depth': ['error', 4],
      'max-lines-per-function': ['warn', { max: 80 }],
    },
  },
);

// tsconfig.json — 严格模式是"免费的静态分析"
{
  "compilerOptions": {
    "strict": true,                    // 打开全部严格检查
    "noUncheckedIndexedAccess": true,  // arr[0] 类型为 T | undefined
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  }
}

策略一：大爆炸式 —— 一次性打开 strict → 成百上千错误 → 团队崩溃 ✗

策略二：按目录灰度 —— tsconfig.strict.json 只 include 新目录，
  老代码保持宽松，新代码强制严格 ✓ 新代码零债务

策略三：递减预算 —— 生成 baseline 记录当前全部错误，
  CI 只允许"错误数不增加"，逐步消减 ✓ 老代码可控收敛

策略四：逐条开启 —— 先 noImplicitAny，再 strictNullChecks，
  再其余；每步修复完再进下一步 ✓ 适合超大型遗留项目

一个典型的质量门禁条件组合：
  · 新代码覆盖率 ≥ 80%      · 新代码重复率 ≤ 3%
  · 新代码技术债务比率 ≤ 5%  · 新增 Blocker / Critical = 0
  · 新代码安全热点评审率 = 100%
  · 可维护性 / 可靠性 / 安全评级均为 A

关键理念：门禁只盯"新代码"（New Code），
        历史债务不阻断，但持续偿还。

# sonar-project.properties
sonar.projectKey=myorg:payment-service
sonar.organization=myorg
sonar.sources=src
sonar.tests=src
sonar.test.inclusions=**/*.test.ts,**/*.spec.ts
sonar.exclusions=**/node_modules/**,**/dist/**,**/*.generated.ts

# 覆盖率报告导入（LCOV 格式）
sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.typescript.tsconfigPaths=tsconfig.json

# 新代码周期定义：以版本号界定
sonar.newCode.referenceBranch=main

# 质量门禁
sonar.qualitygate.wait=true
sonar.qualitygate.timeout=600

# .github/workflows/quality.yml
name: Quality Gate
on: [pull_request]

jobs:
  sonar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # 增量分析必须完整历史
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - run: npm run test:coverage
      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@v5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
        with:
          args: >
            -Dsonar.pullrequest.key=${{ github.event.pull_request.number }}
            -Dsonar.pullrequest.branch=${{ github.head_ref }}
            -Dsonar.pullrequest.base=${{ github.base_ref }}
      - name: Quality Gate Check
        uses: SonarSource/sonarqube-quality-gate-action@v1
        timeout-minutes: 10
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

传统 SAST：正则 / 模式匹配
  → 只能发现"长得像漏洞"的代码，误报高

CodeQL：把源代码编译成关系型数据库（CodeQL DB）
  → 用类 SQL 的 QL 语言查询数据流
  → 能追踪 "用户输入 → 拼接 SQL → 执行" 的完整路径

污点分析（Taint Tracking）三要素：
  Source（污染源）：req.query、req.body、process.argv
  Sink（危险汇聚点）：db.query()、exec()、fs.writeFile()
  Sanitizer（净化器）：escape()、parseInt()、白名单校验

name: "CodeQL Advanced"
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '30 2 * * 1'   # 每周一凌晨全量扫描

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      actions: read
      contents: read
    strategy:
      fail-fast: false
      matrix:
        language: ['javascript-typescript', 'python']
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/init@v3
        with:
          languages: ${{ matrix.language }}
          queries: security-extended,security-and-quality
      - uses: github/codeql-action/autobuild@v3
      - uses: github/codeql-action/analyze@v3
        with:
          category: "/language:${{ matrix.language }}"

全量扫描的困境：100 万行代码全量分析需 20~40 分钟 → 每次 PR 都跑
  → 反馈太慢 → 开发者绕过检查；历史债务 5000 条告警淹没新告警。

增量扫描的三层含义：
  1. 只分析变更文件（Lint 层面）
  2. 只对变更行判定门禁（SonarQube New Code）
  3. 只对变更引入的依赖做 SCA 扫描

// package.json
{
  "scripts": {
    "lint": "eslint . --max-warnings 0",
    "typecheck": "tsc --noEmit",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix --max-warnings 0",
      "prettier --write"
    ],
    "*.{json,md,yml}": ["prettier --write"]
  }
}

# .husky/pre-commit
npx lint-staged
# 只对暂存文件运行，毫秒级反馈

# .husky/pre-push
npm run typecheck && npm run test:unit -- --bail

圈复杂度（Cyclomatic Complexity）= 判定点数量 + 1
  判定点：if / else if / for / while / case / catch / && / || / ?:
  意义：独立路径数，也是"需要多少个测试用例覆盖"的下界

认知复杂度（Cognitive Complexity）：在圈复杂度基础上增加
  · 嵌套深度惩罚（越深越难懂） · 递归 +1
  · 连续逻辑运算符不重复计数（a && b && c 算 1 而非 2）
  意义：更贴近"人理解代码的难度"

# 安装并度量圈复杂度
pip install radon
radon cc src/ -s -a --total-average
#   src/order.py
#       F 42:0 process_order - B (7)
#       C 88:0 OrderService.validate - C (14)
#   Average complexity: B (6.3)

# 可维护性指数（Maintainability Index，0~100）
radon mi src/ -s
#   src/order.py - A (87.42)

# CI 中卡阈值
radon cc src/ --min C --show-closures || exit 1

手段一：卫语句（Guard Clause）替代深层嵌套
  重构前：if (a) { if (b) { if (c) { ... } } }
  重构后：if (!a) return; if (!b) return; if (!c) return; ...

手段二：查表法 / 策略模式替代 switch 分支
  Map<Type, Handler> 替代 20 个 case；PriceStrategy 多态替代 if-else 链

手段三：提取纯函数
  把复杂方法中的计算段落提取为独立可测函数

原则：复杂度降低的同时测试覆盖率必须同步提升，
     否则只是把复杂度藏进了更深的地方。