CLI 命令
npx dowsing <command> [options]通用选项
大多数命令都可用。
| 选项 | 默认值 | 说明 |
|---|---|---|
--since <date> | 12 months ago | git 时间窗口的起点。任何 git 能解析的表达式。 |
--until <date> | — | git 时间窗口的终点 |
--complexity <type> | loc | 复杂度代理：loc | cyclomatic | cognitive |
--json | false | 将 JSON 写到标准输出 |
--config <path> | 自动探测 | 配置文件（dowsing.config.ts / .mts / .mjs / .js） |
--refresh | false | 忽略缓存，重新分析 |
--no-cache | — | 既不读也不写缓存 |
分析结果缓存在 .dowsing/cache，以 HEAD、工作区状态和以上选项为键。命中缓存时会在 stderr 说明。
这一页的摘要可以用 dowsing --help 得到（也包含前提、输出格式、退出码与缓存）。
analyze
分析 workspace，写出 .dowsing/dowsing.json，并打印摘要。
dowsing analyze [dir]| 选项 | 默认值 | 说明 |
|---|---|---|
--top <n> | 10 | 显示的 hotspot 数量 |
--out <path> | .dowsing/dowsing.json | 输出路径 |
--verify-churn [n] | 关闭 | 用 AST 验证前 N 个文件（默认 20）的改动频率 |
--min-degree <n> | 0.3 | 最小耦合度（也接受 30 这样的百分比写法） |
--min-shared <n> | 5 | 耦合的最小共享提交数 |
加上 --json 时报告输出到标准输出，不写文件。
hotspots
只打印 hotspot 排名。
dowsing hotspots [dir] --top 15coupling
显示变更耦合。
dowsing coupling [dir] --hidden| 选项 | 默认值 | 说明 |
|---|---|---|
--hidden | false | 只显示隐藏耦合（无依赖的共变更） |
--files | false | 同时显示文件粒度的耦合 |
--top <n> | 20 | 行数 |
--min-degree <n> | 0.3 | 最小耦合度 |
--min-shared <n> | 5 | 最小共享提交数 |
调低阈值以捞回遗漏
两个非常活跃的包分母很大，会把耦合度压下去。--min-degree 15 常常能捞出真实的配对。
why
解释两个对象为什么一起改动。
dowsing why <a> <b>每个对象可以是包名、文件路径或目录——按这个顺序解析（包名 → 精确路径 → 前缀匹配）。
dowsing why @acme/admin-web @acme/customer-web
dowsing why packages/ui src/api --since "6 months ago"| 选项 | 默认值 | 说明 |
|---|---|---|
--cwd <path> | . | 要分析的目录 |
--top <n> | 10 | 显示的文件对数量 |
--commits <n> | 10 | 代表性提交数量 |
health
显示 Code Health 与坏味道明细。
dowsing health [dir]
dowsing health --file src/foo.ts # 单个文件的扣分明细| 选项 | 默认值 | 说明 |
|---|---|---|
--file <path> | — | 只显示单个文件的明细 |
--top <n> | 10 | 行数 |
knowledge
显示 ownership 与 bus factor。
dowsing knowledge [dir] --top 15按包给出 bus factor、贡献者列表，以及主要开发者离开后哪些文件会无人负责的模拟。
report
生成自包含的单文件 HTML 报告。它不发起任何外部请求，数据已内嵌，可以直接分享。
dowsing report [dir] --out report.htmlinit
向 AGENTS.md 追加一节 dowsing 说明，让在这个仓库里工作的代理——无论运行在哪个宿主上——都知道这个工具的存在。
dowsing init
dowsing init --dry-run| 选项 | 默认值 | 说明 |
|---|---|---|
--cwd <path> | . | 目标目录 |
--file <path> | AGENTS.md | 追加到哪个文件 |
--dry-run | false | 只打印内容，不写入文件 |
重复执行只会更新那一节，不会重复添加。
check
质量门禁。有违规时退出码为 1。
dowsing check [dir] --min-file-health 3| 选项 | 说明 |
|---|---|
--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> | 隐藏耦合数量上限 |
--sarif <path> | 输出 SARIF 供 GitHub Code Scanning |
默认什么都不检查
只有你显式指定的阈值才会被执行。请先测量现状，从今天能通过的水平起步。
diff
评估自某个基线以来的改动是否踩到了高风险区域，并实测两个版本之间复杂度实际的变化。
dowsing diff <base>
dowsing diff origin/main --markdown| 选项 | 默认值 | 说明 |
|---|---|---|
--head <ref> | HEAD | 比较目标 |
--cwd <path> | . | 要分析的目录 |
--markdown | false | 把 PR 评论用的 Markdown 输出到标准输出 |
--out <path> | — | 把 Markdown 写入文件 |
每个变更的 .ts / .tsx 都会在两个版本上分别读取并重新解析，因此这个差值与谁改的无关。参见实测改善效果。
配置文件
以上这些都可以固定在 dowsing.config.ts 里，不必每次传。优先级是 CLI 参数 > 配置文件 > 默认值。
import { defineConfig } from "dowsing";
export default defineConfig({
since: "12 months ago",
complexity: "cognitive",
coupling: { minDegree: 0.3, minShared: 5 },
health: { thresholds: { cognitive: 15 }, weights: { "large-file": 1.5 } },
check: { minFileHealth: 4, maxHiddenCoupling: 0 },
});查找顺序为 dowsing.config.ts → .mts → .mjs → .js，也可以用 --config <path> 明确指定。TypeScript 可以直接读取（Node 22.18+ 会剥离类型），无需构建步骤。
未知的键会直接报错，而不是被悄悄忽略——「以为设置了、其实没生效」的阈值比启动失败更有害。