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
ワークスペースを解析し、.dowsing/dowsing.json を生成して要約を表示します。
dowsing analyze [dir]| オプション | 既定 | 説明 |
|---|---|---|
--top <n> | 10 | 表示する hotspot 件数 |
--out <path> | .dowsing/dowsing.json | 出力先 |
--verify-churn [n] | 無効 | 上位 N 件（既定 20）の変更頻度を AST 比較で検証 |
--min-degree <n> | 0.3 | coupling の最小結合度（30 のような % 表記も可） |
--min-shared <n> | 5 | coupling の最小共有コミット数 |
--json を付けると dowsing.json の内容を標準出力に出し、ファイルは書きません。
hotspots
hotspot ランキングだけを素早く表示します。
dowsing hotspots [dir] --top 15coupling
change coupling を表示します。
dowsing coupling [dir] --hidden| オプション | 既定 | 説明 |
|---|---|---|
--hidden | false | 隠れた結合（依存関係のない共変更）のみ |
--files | false | ファイル粒度の coupling も表示 |
--top <n> | 20 | 表示件数 |
--min-degree <n> | 0.3 | 最小結合度 |
--min-shared <n> | 5 | 最小共有コミット数 |
閾値を下げて見落としを拾う
活発なパッケージ同士は分母が大きく degree が下がります。--min-degree 15 で拾えることがあります。
why
2 つの対象がなぜ一緒に変わるのかを説明します。
dowsing why <a> <b>対象はパッケージ名・ファイルパス・ディレクトリのいずれでも指定できます（パッケージ名 → 完全一致パス → 前方一致の順に解決）。
| オプション | 既定 | 説明 |
|---|---|---|
--cwd <path> | . | 解析対象ディレクトリ |
--top <n> | 10 | 表示するファイル件数 |
--commits <n> | 10 | 表示する代表コミット件数 |
dowsing why @acme/admin-web @acme/customer-web
dowsing why packages/ui src/api --since "6 months ago"health
Code Health と smell の内訳を表示します。
dowsing health [dir]
dowsing health --file src/foo.ts # 1 ファイルの減点内訳| オプション | 既定 | 説明 |
|---|---|---|
--file <path> | — | 特定ファイルの内訳だけを表示 |
--top <n> | 10 | 表示件数 |
knowledge
ownership と bus factor を表示します。
dowsing knowledge [dir] --top 15パッケージ単位の bus factor、貢献者一覧、主要開発者が抜けたときの影響（off-boarding シミュレーション）が出ます。
report
自己完結の単一 HTML レポートを生成します。外部リクエストを一切行わず、データも埋め込み済みなのでそのまま共有できます。
dowsing report [dir] --out report.htmlinit
AGENTS.md に dowsing のセクションを追記します。このリポジトリで作業するエージェントが、ホストを問わず dowsing の存在を知ることができます。
dowsing init
dowsing init --dry-run| オプション | 既定 | 説明 |
|---|---|---|
--cwd <path> | . | 対象ディレクトリ |
--file <path> | AGENTS.md | 追記先 |
--dry-run | false | 書き込まずに内容を表示する |
再実行しても増えません（dowsing のセクションだけを更新します）。
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
base からの変更がリスクの高い場所に触れているかを評価し、2 つのリビジョン間で複雑度が実際にどう動いたかを実測します。
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 以上の型ストリップ）、ビルド手順は要りません。
知らないキーは黙って無視せずエラーにします。設定したつもりの閾値が効いていない状態のほうが、起動時に落ちるより有害だからです。