メトリクスデータのエクスポート

The metrics, ops, and preproc subcommands all support structured output formats meant for machine consumption. This page covers writing those documents, diffing two runs, discovering the metric catalog at runtime, and stripping comments for downstream tools. Pair the output with a JSON processor like jq for ad-hoc analysis, or feed it into a database or dashboard.

ファイルごとのメトリクスを JSON でエクスポートする

bca metrics \
    --paths src/ \
    -O json \
    --output-dir /tmp/metrics

これは解析対象のソースファイルごとに 1 つの JSON ファイルを /tmp/metrics/ 以下に書き出します。出力ファイル名は入力パスにフォーマットの拡張子を付加したものです — src/lib.rs は src/lib.json ではなく src/lib.rs.json になります。手で読むつもりなら --pretty を使ってください：

bca metrics -p src/ --pretty -O json --output-dir /tmp/metrics

実行全体をツリーではなく 1 つのファイルにまとめるには --output <file> を使います。単一の集約ドキュメント（ファイルごとの結果のトップレベル JSON 配列）を書き出します：

bca metrics -p src/ -O json --output /tmp/metrics.json

Its elements are ordered by file path regardless of the order the parallel workers finished in, so the document is byte-identical between runs over unchanged sources. bca ops --output <file> orders its aggregate the same way.

CBOR（-O cbor）は最もコンパクトなフォーマットですが、バイナリのため出力先（--output または --output-dir）が必要です。JSON、TOML、YAML は出力先が指定されない場合いずれも stdout にストリームでき、パイプラインに便利です。

`bca diff` で 2 つのメトリクス実行を比較する

bca diff は 2 つの JSON メトリクス実行を比較し、メトリクスごとに、どのファイルが変化したか（旧 → 新）に加えて、2 つのセット間で追加・削除されたファイルを報告します。各サイドは単一のファイル別 JSON ドキュメント、またはそれらのディレクトリツリー全体（metrics -O json --output-dir <dir> 形式が書き出すもの）なので、一般的なワークフローは 2 回の bca metrics 実行を別々のディレクトリへ出力することです：

# 「変更前」の状態を取得する。
bca metrics -p src/ -O json --output-dir /tmp/before

# ...変更を加える（例: tree-sitter 文法のバンプ）...

# 「変更後」の状態を取得して diff を取る。
bca metrics -p src/ -O json --output-dir /tmp/after
bca diff /tmp/before /tmp/after

出力はファイルごとの差分をメトリクス名でまとめます — bca list-metrics が出力するのと同じ名前です（cyclomatic、cognitive、sloc、…）：

2 metric(s) changed, 1 added file(s), 0 removed file(s)

## Added files
  src/new_module.rs.json

## cyclomatic (2 change(s))
  src/lib.rs.json.sum  12 → 14
  src/lib.rs.json.max   4 → 6

## halstead (1 change(s))
  src/lib.rs.json.effort  5820.3 → 7104.9

便利なフラグ：

--format markdown はスティッキーな PR コメント向け、--format json は安定した機械可読スキーマ向け（CI コンシューマー）です。
--min-change <N> は絶対変化量が N 以上の差分のみを報告します（デフォルトの 0 はあらゆる変化を報告します）。
--metric <name>（繰り返し可能）は diff を特定のメトリクスに限定します。

`--since` で git ref と比較する

「コミットしていない変更はメトリクスに何をしたか?」という対話的なケースでは、--since <ref> が 2 回キャプチャする手間を省きます。変更前サイドとして git ref 時点のツリーを解析し、現在の作業ツリー（または明示的に指定した変更後サイドのツリー）と比較します：

# 変更前 = HEAD~1 時点のツリー。変更後 = 現在の作業ツリー。
bca diff --since HEAD~1 -p src/

# 変更後 = 作業ツリーの代わりに明示的なツリー（例: 2 つ目のチェックアウト）。
# 唯一の位置引数が変更後サイドになる。
bca diff --since main /path/to/other-checkout -p src/

--since materializes the ref's tree into a temporary directory (via git ls-tree + git cat-file), runs the same metric walk against it, then diffs — the temp tree is removed automatically, including on error. The same -p/--paths, -I/--include, and -X/--exclude selection applies to both sides so they analyze the same file set. Selection paths are repo-root-relative and must be relative: the working-tree side is anchored at the repository root (matching the whole-tree materialization of the ref), so bca diff --since produces the same result from any subdirectory. An absolute --paths is rejected (exit 1) — it cannot address the extracted ref tree.

ベストエフォートの bca check --since とは異なり、bca diff --since は明示的な要求です。解決できない ref、git の欠如、git 管理外の作業ディレクトリはハードエラー（終了コード 1）になります。--since は位置引数を最大 1 つ（変更後サイド）しか取りません。2 つ渡すとエラーです。

bca diff exits 0 on success — it is informational, not a gate — unless the opt-in --exit-code flag is passed, which exits 2 when the filtered diff is non-empty.

ツリー全体から単一のメトリクスを取り出す

ストリームされた JSON 出力を jq と組み合わせて、ファイルごとに 1 つの値を抽出します：

bca metrics -p src/ -O json \
  | jq -c '{file: .name, mi: .metrics.mi.visual_studio}'

同じ考え方はどのメトリクスにも使えます — cyclomatic.sum、cognitive.sum、loc.sloc など。カタログを見るには bca list-metrics descriptions を実行してください。

実行時にメトリクスカタログを発見する

CLI を駆動するツールはメトリクス名をハードコードすべきではありません。バイナリに尋ねてください：

bca list-metrics                # 1 行につき 1 つの名前
bca list-metrics descriptions   # 名前 + 概要

これはコードジェネレーター、スキーマ定義、タブ補完に適した入力です。

オペランドとオペレーターを抽出する（Halstead）

ops emits the raw operand and operator lists per file, which is the input to Halstead-style metric calculations beyond what the built-in report shows:

bca ops \
    --include "*.rs" \
    --paths src/ \
    -O json --pretty \
    --output-dir /tmp/ops

1 回の指定につきグロブ 1 つ。 --include と --exclude は出現ごとにちょうど 1 つの値を取ります。複数のグロブにはフラグを繰り返してください（--include "*.rs" --include "*.py"）。後続の位置引数パスが飲み込まれることはありません。= 形式（--include="*.rs"）も使えます。

各出力ファイルは入力パスを /tmp/ops/ 以下にミラーします。

どちらのリストもソート済みなので、変更のないソースに対して ops を再実行するとバイト単位で同一の出力が得られます — 実行間で差分を取ったり、リポジトリにコミットしたり、キャッシュキーとして使ったりしても安全です。

ツリーからコメントを除去する

strip-comments は、コメント構文を理解しない下流のツールでもコードを利用できるようにソースを書き換えます。出力ルーティングには 3 つのモードがあります：

stdout（デフォルト）。 どちらのフラグもない場合、除去済みソースは stdout にストリームされます — パイプライン内の単一ファイルに最適です。
--output / -o <FILE>（単一ファイル）。 除去済みソースを <FILE> に書き出し、入力はそのまま残します。入力ファイルが 1 つの場合にのみ意味を持ち、--in-place とは相互排他です。
--in-place（複数ファイル）。 マッチした各入力ファイルをディスク上で書き換えます。ツリー全体にはこれを使ってください。--output とは相互排他です。

# コメントを除去した単一ファイルをストリーム出力する。
bca strip-comments --paths src/lib.rs

# 除去済みの単一ファイルを新しいパスに書き出す（入力は変更しない）。
bca strip-comments --paths src/lib.rs --output src/lib.stripped.rs

# src/ 内のすべての Python ファイルをインプレースで書き換える。
bca strip-comments --include "*.py" --paths src/ \
    --in-place

--in-place は破壊的です — 事前にツリーがコミット済みまたはバックアップ済みであることを確認してください。--in-place と --output の両方を渡すのは使用方法エラーです。

big-code-analysis Documentation