依赖升级自动化：Renovate 与 Dependabot 实践

依赖腐化的三个阶段：
  阶段一：落后 1~2 个 minor，升级无痛
  阶段二：落后 1~2 个 major，API 有破坏性变更，升级要改代码
  阶段三：多个 major 落后 + 依赖链冲突，升级变成「重写模块」

越晚升级，单次升级的回归面越大，风险越集中。

每天 40 个升级 PR 的真实成本：
  - PR 数量 > 人的处理能力 → 全部积压
  - 积压的 PR 基于旧 main → 大量冲突，需要反复 rebase
  - 反复 rebase 触发重复 CI → runner 成本上升
  - 最终没人信任这些 PR → 全部关闭 → 回到「从不升级」

健康的目标形态：
  - 每周人工需要处理的升级 PR：个位数
  - 其中绝大多数（patch/minor、有测试覆盖）自动合并
  - major 升级与安全更新单独走审核通道
  - 所有升级都有可追溯的记录（谁、何时、从什么版本到什么版本）

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "09:00"
      timezone: "Asia/Shanghai"
    open-pull-requests-limit: 5
    versioning-strategy: "increase"
    labels: ["dependencies", "npm"]
    commit-message:
      prefix: "chore(deps)"
      include: "scope"

    groups:
      # 所有 patch 更新合成一个 PR
      patch-updates:
        applies-to: version-updates
        update-types: ["patch"]
      # 开发依赖（devDependencies）单独一组
      dev-dependencies:
        dependency-type: "development"
      # 框架相关的 minor 更新合成一组
      framework-minor:
        patterns: ["next", "react", "react-dom", "@types/react*"]
        update-types: ["minor"]

分组的收益：
  PR 数量从「每个依赖一个」降到「每类一个」
  但注意：一组里任何一个依赖导致测试失败，整组都要排查
  → 组不宜过大，按「同类、同风险」划分

安全更新的特点：
  - 触发源是 CVE/GHSA，而非「有新版本」
  - 即使版本更新被限流，安全更新也会开 PR
  - 可以在仓库 Settings → Code security 中单独开关
  - 建议与代码扫描（CodeQL）联动，形成「发现→修复」闭环

// renovate.json
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
    ":dependencyDashboard",
    ":semanticCommits",
    "schedule:weekly"
  ],
  "timezone": "Asia/Shanghai",
  "prConcurrentLimit": 5,
  "prHourlyLimit": 2,
  "rangeStrategy": "bump",
  "labels": ["dependencies"]
}

{
  "packageRules": [
    {
      "description": "所有 patch 更新自动合并",
      "matchUpdateTypes": ["patch"],
      "automerge": true,
      "automergeType": "pr",
      "platformAutomerge": true
    },
    {
      "description": "开发依赖的 minor 更新自动合并",
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["minor"],
      "automerge": true
    },
    {
      "description": "React 全家桶同组，避免版本错配",
      "groupName": "react",
      "matchPackageNames": ["react", "react-dom", "@types/react", "@types/react-dom"],
      "automerge": false
    },
    {
      "description": "major 更新需人工审核",
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "addLabels": ["major-update", "needs-review"]
    },
    {
      "description": "内部镜像源上的包不走公网升级",
      "matchDatasources": ["npm"],
      "matchPackagePrefixes": ["@internal/"],
      "enabled": false
    }
  ]
}

{
  "schedule": ["after 9am and before 5pm every weekday"],
  "dependencyDashboard": true,
  "dependencyDashboardTitle": "依赖升级看板"
}

Dashboard 上的操作：
  ☐ 勾选某行 → Renovate 立即为该依赖开 PR
  ☐ 取消勾选 → 暂停该依赖的升级
  ☐ 勾选 "Create all rate-limited PRs" → 一次性放开限流

MAJOR：不兼容的 API 变更（破坏性）
MINOR：向后兼容地新增功能
PATCH：向后兼容地修复缺陷

但现实中「MINOR 引入破坏性变更」并不罕见，
所以自动合并策略要建立在「测试能覆盖」的前提上，而不是盲信版本号。

rangeStrategy 决定「升级时如何改写版本范围」：
  bump    ：只把下界提到新版本，如 ^1.2.0 → ^1.3.0
  replace ：直接替换为精确版本，如 1.2.0 → 1.3.0
  widen   ：扩大范围而不移动下界，如 ^1.2.0 → >=1.2.0 <2.0.0
  pin     ：固定为精确版本

应用库（被其他项目依赖）→ 倾向 widen/bump，给使用者空间
应用服务（直接部署）   → 倾向 pin，保证可复现

lockfile（package-lock.json / pnpm-lock.yaml / go.sum）：
  - 记录「实际解析到的精确版本」，保证安装可复现
  - 升级 PR 必须同时更新 lockfile，否则 CI 装的是旧版本
  - lockfile 冲突是升级 PR 积压的主要原因 → 减少并发 PR 数可缓解

自动合并的硬前提：
  1. 有测试覆盖：改动能被执行到的测试捕获
  2. CI 必需检查全绿：单元测试、类型检查、构建
  3. 版本类型在白名单内（通常是 patch、devDependencies 的 minor）
  4. 非安全敏感包（加密、鉴权、序列化等要人工看）
  5. 有回滚手段（能快速 revert 或回退版本）

# GitHub Actions：为自动合并提供必需检查
name: ci
on:
  pull_request:
jobs:
  verify:
    if: github.actor == 'renovate[bot]' || github.actor == 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --ci
      - run: npm run build

升级的灰度思路：
  - 先合并到开发环境，观察一段时间再进生产
  - 关键依赖（数据库驱动、HTTP 客户端）单独升级并做压测
  - 保留一键回滚：把版本改回去 + 重新部署

Monorepo 依赖治理要点：
  1. 统一版本：同一依赖在多个包中出现时，尽量收敛到同一版本（pnpm overrides / npm overrides）
  2. 分组升级：把「同源」依赖（如 React 全家桶）合成一组，避免版本错配
  3. lockfile 单一：整个仓库一个 lockfile，减少冲突
  4. 提升升级到 workspace 根：在根统一升级，避免每个包各自升

// pnpm workspace 根：强制统一某些依赖版本
{
  "pnpm": {
    "overrides": {
      "typescript": "5.4.5",
      "eslint": "8.57.0"
    }
  }
}

联动链路：
  1. 依赖清单（SBOM）：知道用了什么、什么版本
  2. 漏洞数据库比对（GitHub Advisory / OSV）：知道哪个版本有洞
  3. 升级 PR 自动生成：从「发现」到「修复 PR」自动衔接
  4. 签名与来源校验：确保升级到的是官方制品

{
  "packageRules": [
    { "matchPackageNames": ["node"], "enabled": false },
    {
      "matchPackageNames": ["some-frozen-lib"],
      "enabled": false,
      "description": "该库已停止维护，锁定版本直到迁移"
    }
  ],
  "ignorePaths": ["**/fixtures/**", "**/testdata/**"]
}

依赖治理的核心指标：
  - 升级 PR 的平均存活时间（从开到合/关）
  - 每周需人工处理的 PR 数（目标：个位数）
  - 自动合并占比（目标：patch 与 devDeps 中 > 70%）
  - 已知漏洞的平均修复时长（MTTR for vulns）
  - 依赖滞后度（当前版本与最新稳定版的差距分布）

依赖升级自动化 = 机器负责发现与开 PR + 门禁负责判断 + 人负责定义策略。
人的精力只花在「策略」和「major/安全」上，其余交给自动化。