メトリクス

bca metrics はファイル単位のメトリクスを計算し、stdout、単一の集約ファイル（--output）、またはファイル単位の構造化ファイルを収めるディレクトリ（--output-dir）のいずれかに出力します。

移行中ですか？ このコマンドは、再構成前の --metrics フラグを置き換えるものです。以前 -O markdown で選択していた集約レポートは bca report に移り、CI/IDE 向けの違反レポートフォーマット（Checkstyle、SARIF、code-climate、clang-warning、msvc-warning）は bca check --report-format <fmt> に移動しました。移行ガイド を参照してください。

メトリクスの表示

指定したファイルまたはディレクトリのメトリクスを計算して表示するには、次を実行します:

bca metrics --paths /path/to/your/file/or/directory
  • --paths（または -p）: 解析するファイルまたはディレクトリ。ディレクトリを指定すると、その中のすべての対応ファイルについてメトリクスが計算されます。パスは位置引数でも指定できます（bca metrics file.rs dir/）。

明示的に名前を指定したファイルはパース可能でなければなりません。 言語をツールが認識できないファイルを直接（位置引数または --paths/--paths-from 経由で）指定すると、bca は stderr に警告を出力し、実行が出力をまったく生成しなかった場合は 1 で終了します。これは、存在しない明示パスが失敗するのと同じ挙動です。少なくとも 1 ファイルを解析した混在実行は、警告を出しつつ 0 で終了します。ファイルの拡張子が内容と食い違う場合は、--language <lang> を渡してパーサーを強制してください。「ディレクトリ」 の走査によってのみ到達したファイルは黙ってスキップされます（README や設定ファイルだらけのツリーで騒がしくなってはいけません）。そうしたスキップも表示したい場合は -w を渡してください。

認識は_される_ものの読み取れないファイルはより厳格な扱いになり、読み取れない入力の規則に従います。他のファイルの解析が成功していても実行は 1 で終了します。黙って短くなったメトリクスドキュメントは、完全なものとして読まれてしまうからです。

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

bca metrics は 5 つのファイル単位出力フォーマットに対応しています:

  • CBOR
  • CSV
  • JSON
  • TOML
  • YAML

JSON と TOML は、いずれも整形（pretty-print）してエクスポートできます。

トップレベルの 3 種類の出力は 3 つの別々のコマンドに対応しており、それぞれが自身のデータモデルとの一貫性を保ちます:

コマンド出力対象
bca metricsファイル単位のメトリクスツリー下流のツール
bca report集約された品質ダッシュボード人間 / プルリクエスト
bca checkしきい値違反レポートCI / IDE

CI/IDE 向けの違反レポートフォーマット（Checkstyle、SARIF、code-climate、clang-warning、msvc-warning）は、かつて bca metrics -O <fmt> にありました。これらの入力はしきい値違反のリストであって、上記の他フォーマットが扱うファイル単位のメトリクスツリーではないため、bca check --report-format <fmt> に移動しました。新しい呼び出し方は bca check の章 を参照してください。

エクスポートコマンド

メトリクスを JSON ファイルとしてエクスポートするには:

bca metrics --paths /path/to/your/file/or/directory \
    -O json --output metrics.json
  • -O, --format: 出力フォーマット。デフォルトは text で、stdout に表示される人間可読のカラー付きメトリクスツリーです。このデフォルトを明示的に要求するには --format text を渡します（たとえば、構造化フォーマットを設定した bca.toml を上書きする場合）。構造化されたファイル単位のシリアライザーは cbor、csv、json、toml、yaml です。--output-format は非推奨のエイリアスとして受け付けられますが、次のメジャーリリースで削除予定です。
  • -o, --output: 実行全体の集約ドキュメント 1 つを保持する単一ファイル — ファイル単位の結果を並べたトップレベル配列です（TOML は配列を files キーの下にラップし、CSV は各ファイルの行を連結します）。省略した場合、結果は stdout に出力されます。
  • --output-dir: 入力ファイルごとに 1 つのドキュメントを保持するディレクトリで、各ドキュメントは入力パスにフォーマットの拡張子を付けた名前になります。--output とは相互排他で、両方を渡すとエラーです。
  • CBOR はバイナリのため、出力先（--output または --output-dir）が必須です。構造化された --format なしでいずれかの出力先を渡すとエラーになります（デフォルトの text フォーマットは stdout にストリームし、ファイルを書きません）。これにより、出力先の指定が黙って無視されることはありません（#661）。
  • --metrics <name,…>: 計算をメトリクスのサブセットに制限します（カンマ区切りまたは繰り返し指定、例: --metrics cyclomatic,cognitive --metrics loc）。名前は bca list-metrics が表示する正規 ID で、bca check --threshold や bca diff --metric と同じ語彙です。ドット付き（cyclomatic.modified）や、loc サブメトリクスの単独表記（sloc）も受け付けられます。派生メトリクスは依存するメトリクスを自動的に取り込みます。未知の名前は「did you mean」ヒント付きのエラーになります。省略すると、すべてのメトリクスを計算します（#691）。

CSV（スプレッドシートと Pandas）

bca metrics --paths /path/to/your/code \
    -O csv --output-dir csv-output

CSV ライターは FuncSpace（関数、クラス、構造体、ユニットなど）ごとに 1 行を出力し、メトリクス行列全体を列として並べます。ヘッダーの順序は固定です — 正規のリストは src/output/csv.rs の CSV_HEADER を参照してください。識別列（path、space_name、space_kind、start_line、end_line）が先頭に来て、その後にすべての葉メトリクスが JSON と同じドット付き名（loc.lloc、halstead.volume、cyclomatic.modified.average など）で続くため、1 つの列名で CSV と JSON の両方のメトリクスを指せます。

空セル（0 ではなく値なし）は「このスペースには該当しない」ことを示します — たとえば、OOP 専用メトリクス（wmc.*、npm.*、npa.*）は手続き型コードでは空になります。RFC 4180 の引用符処理は [csv] クレートに委譲されているため、カンマ、引用符、改行を含むパスや名前も正しく往復します。

- を使って、結果を単一の出力にストリームします:

bca metrics --paths /path/to/your/code -O csv \
    > metrics.csv

CSV はファイル単位のフォーマットです。--output-dir <dir> を指定すると、各入力ファイルは出力ディレクトリ配下に <input>.csv のミラーを生成します。--output <file> を指定すると、すべてのファイルの行が 1 つの集約 CSV に連結されます。

走査全体をカバーする集約 HTML レポート は bca report html で利用できます。以前のファイル単位の bca metrics -O html ライターは、実際のリポジトリでは開けないほど巨大な単一ファイルのテーブルに劣化してしまうため削除されました — フラットな FuncSpace 単位の行には CSV が適切な形です。

整形出力

bca metrics --paths /path/to/your/file/or/directory \
    --pretty -O json

インラインテストコードの除外

bca metrics --paths /path/to/your/code --exclude-tests

デフォルトでは、インラインのテスト項目を含む AST 内のすべてのノードがカウントされます。そのため、慣用的な #[cfg(test)] mod tests { ... } レイアウトに従う Rust ファイルでは、主要メトリクスに本番コードとテストコードが混在します。

メトリクスが計算される前にテスト専用のサブツリーを取り除くには、--exclude-tests を渡します。このフラグは AST を走査するすべてのサブコマンド（metrics、report、check）で認識され、現在は次の Rust 属性の形を理解します:

  • #[test] および #[rstest] / #[test_case] / #[wasm_bindgen_test]
  • #[cfg(test)]、#[cfg(all(test, ...))]、#[cfg(any(test, ...))]
  • #[tokio::test]、#[async_std::test]、#[test_log::test] など（::test で終わる任意のパス）
  • mod アイテムに付く #![cfg(test)]（内部属性形式）

Checker::should_skip_subtree のオーバーライドを持たない言語では、このフラグは単に無視されます — 現在プルーニングを適用するのは Rust のみです。デフォルトはオフのままなので、オプトインしないユーザーの既存のメトリクス値はバイト単位で同一に保たれます。

フラグを繰り返さずにプロジェクト全体をオプトインするには、リポジトリの bca.toml マニフェストで exclude_tests = true を設定します。--exclude-tests は存在のみのフラグ（=false 形式なし）のため、マニフェストキーはプルーニングをオンにすることしかできません。CLI の --exclude-tests は引き続き優先されますが、マニフェスト側からオフに戻すことはできません。プルーニングはノード数ベースのメトリクス（cyclomatic、cognitive、Halstead、nom、nargs など）を下げますが、ユニットレベルの loc.sloc はファイル全体の範囲のまま残ります。ユニット SLOC はトラバーサルの累積ではなくファイルルートのスパンだからです。

集約レポート

包括的で人間が読みやすい品質レポートには、bca report markdown を使用してください。このコマンドは解析したすべてのファイルにわたってメトリクスを集約し、言語ごとのホットスポットテーブルを生成します。

利用可能なメトリクスの一覧

CLI を駆動するツールは、メトリクスのカタログをハードコードする代わりに実行時に検出できます。

bca list-metrics

はメトリクス名を 1 行に 1 つずつ出力します。各メトリクスの 1 行要約を得るには descriptions を渡します。

bca list-metrics descriptions