CI 集成

首要前提：fetch-depth: 0

忘了这个，一切都会坏掉

dowsing 从 git 历史计算改动频率。CI 的检出默认是浅克隆，所以你必须显式要求完整历史。dowsing 检测到浅克隆时会警告，但它打印的数字不可信。

- uses: actions/checkout@v7
  with:
    fetch-depth: 0

dowsing 只读取你的 git 历史与 TypeScript 源码。它不需要仓库的 node_modules，所以安装依赖这一步可以完全跳过。

质量门禁

dowsing check --min-file-health 3

有违规时以退出码 1 结束。

默认什么都不检查

只有你显式指定的阈值才会被执行。

dowsing check          # → 什么都不检查，总是成功

这是刻意的。第一天就把仓库变红的门禁不会被修复——它会被关掉。 先测量现状，从今天能通过的水平起步，随着改善逐步收紧。

可用的阈值

选项	含义
--min-file-health <n>	文件 health 下限
--min-package-health <n>	包 health 下限
--max-hotspot <n>	hotspot 分数上限（0–1）
--min-bus-factor <n>	包 bus factor 下限
--max-hidden-coupling <n>	隐藏耦合数量上限

违规会连同原因一起显示。

✗ 1 violation (1 rule checked)
┌─────────────────┬──────────────────────────┬────────┬───────────┐
│ rule            │ target                   │ actual │ threshold │
├─────────────────┼──────────────────────────┼────────┼───────────┤
│ min-file-health │ src/ast/metrics.ts       │    4.5 │         5 │
└─────────────────┴──────────────────────────┴────────┴───────────┘

PR 的风险评估

dowsing diff origin/main --markdown

以 Markdown 报告这个 PR 踩到了什么样的高风险区域。

## dowsing — 风险评估

`origin/main...HEAD`: 21 个文件变更，其中 16 个被分析，涉及 4 个包

> **它触及了 7 个 hotspot。** 这些地方改动频繁且复杂——请重点评审。

| file                             | hotspot | health | commits | lines |
| -------------------------------- | ------: | -----: | ------: | ----: |
| `packages/core/src/report.ts` 🔥 |    0.96 |   10.0 |       6 |    76 |

### 🔗 通常会一起改动、但本次未被触及的包

| 已修改          | 未触及                 | 耦合度 | 共变更 |
| --------------- | ---------------------- | -----: | -----: |
| @acme/admin-web | **@acme/customer-web** |    33% |     91 |

它不判断修改是否正确

dowsing 不是 linter。它从不说「这个修改是错的」。它呈现你踩到的地方的风险，请你确认。即便某个常见的共变更伙伴这次没被触及，它也会补上「这不一定需要修改」——因为相关不等于因果。

GitHub Code Scanning (SARIF)

dowsing check --sarif dowsing.sarif

- uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: dowsing.sarif
    category: dowsing

它刻意不输出全部

SARIF 输出仅限于 findings（多个指标重叠之处）与阈值违规。

把每一个坏味道都列成告警会产生数千条，并且背叛这个工具存在的全部意义——给你一个优先级。dowsing 不是静态分析 linter 的替代品。

分析条件（时间窗口、排除计数、是否浅克隆）保留在 properties 中，所以你随时可以知道结果基于什么。

模板

templates/github-actions/ 提供了两个。

文件	用途
dowsing-pr.yml	在 PR 上评论风险评估
dowsing-check.yml	质量门禁 + Code Scanning

可以直接复制使用。里面也写了如何选择阈值。

在 monorepo 上的耗时

参考值——3,920 个提交、40 个包、2,238 个文件：

命令	耗时
analyze	约 7 秒
analyze --verify-churn	约 12 秒
diff	约 8 秒

完全在 CI 可以承受的范围内。