CI 連携

大前提: fetch-depth: 0

これを忘れると全部壊れます

dowsing は git 履歴から変更頻度を計算します。CI の既定は shallow clone なので、明示的に全履歴を取得してください。dowsing は浅い履歴を検出すると警告しますが、出力される数字は信用できません。

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

品質ゲート

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 件の違反（1 ルールを検査）
┌─────────────────┬──────────────────────────┬────────┬───────────┐
│ rule            │ target                   │ actual │ threshold │
├─────────────────┼──────────────────────────┼────────┼───────────┤
│ min-file-health │ src/ast/metrics.ts       │    4.5 │         5 │
└─────────────────┴──────────────────────────┴────────┴───────────┘

PR のリスク評価

dowsing diff origin/main --markdown

その PR がどんなリスクのある場所に触れたかを Markdown で出力します。

## dowsing — 変更のリスク評価

`origin/main...HEAD`: 21 ファイル変更、うち解析対象 16 ファイル / 4 パッケージ

> **hotspot に 7 件触れています。** 変更頻度が高く複雑な箇所なので、レビューを厚めに。

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

### 🔗 一緒に変わることが多いのに、今回触れられていないパッケージ

| 変更した        | 触れていない           | 結合度 | 共変更 |
| --------------- | ---------------------- | -----: | -----: |
| @acme/admin-web | **@acme/customer-web** |    33% |  91 回 |

変更の可否は判定しません

dowsing はリンタではありません。「この変更は間違っている」とは言わず、触れた場所のリスクを提示して確認を促すだけです。共変更の相手が触れられていない場合も「変更が必要とは限りません」と添えます。相関を因果として扱わないためです。

GitHub Code Scanning (SARIF)

dowsing check --sarif dowsing.sarif

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

全部は出しません

SARIF に出力するのは findings（複数指標が重なった箇所）と閾値超えのみです。

全 smell を警告として並べると数千件になり、「優先順位を付ける」というツールの目的そのものを裏切ります。dowsing は静的解析リンタの代わりではありません。

解析条件（期間・除外件数・shallow かどうか）も properties に残るので、後から「何を見た結果か」を追えます。

テンプレート

templates/github-actions/ に 2 つ用意しています。

ファイル	用途
dowsing-pr.yml	PR にリスク評価をコメント
dowsing-check.yml	品質ゲート + Code Scanning

そのままコピーして使えます。閾値の決め方もコメントに書いてあります。

モノレポでの実行時間

参考値（3,920 コミット / 40 パッケージ / 2,238 ファイル）:

コマンド	時間
analyze	約 7 秒
analyze --verify-churn	約 12 秒
diff	約 8 秒

CI に入れても支障のない範囲です。