メトリクス

bca metrics computes per-file metrics and emits them to stdout, to a single aggregate file (--output), or to a directory of per-file structured files (--output-dir). It is the command for feeding downstream tooling; for a human-readable summary see bca report, and for a pass/fail gate see bca check. The shared walker flags (paths, includes, ignore handling) are described in Commands.

Migrating? This command replaces the pre-restructure --metrics flag. The aggregated report previously selected with -O markdown now lives under bca report, and the CI/IDE offender formats (Checkstyle, SARIF, code-climate, clang-warning, msvc-warning) moved to bca check --report-format <fmt>. See the migration guide.

メトリクスの表示

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

bca metrics --paths /path/to/your/file/or/directory

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

Explicitly named files must be parseable. When you name a file directly (positionally or via --paths / --paths-from) whose language the tool cannot recognize, bca prints a warning on stderr. If the run produced no output at all it exits 1, the same way a nonexistent explicit path fails; a mixed run that analyzed at least one file still exits 0 with the warning. Pass --language <lang> to force a parser when a file’s extension lies about its contents. Files reached only by walking a directory are skipped silently, since a tree full of READMEs and configs must not be noisy; pass -w to surface those skips too.

A file that is recognized but cannot be read is a stricter case and follows the unreadable-input rule: the run exits 1 even when other files analyzed fine, because a silently shorter metrics document reads as a complete one.

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

bca metrics supports five per-file output formats: CBOR, CSV, JSON, TOML, and YAML. JSON and TOML can also be pretty-printed.

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

The CI/IDE offender formats (Checkstyle, SARIF, code-climate, clang-warning, msvc-warning) used to live on bca metrics -O <fmt>. They moved to bca check --report-format <fmt> because their input is a list of threshold violations, not the per-file metric tree the other formats carry. See Exporting offender records for the new invocation.

エクスポートコマンド

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

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

• -O, --format: output format. Defaults to text, a human-readable colored metric tree printed to stdout; pass --format text to request that default explicitly (for example to override a bca.toml that set a structured format). The structured per-file serializers are cbor, csv, json, toml, and yaml. --output-format is accepted as a deprecated alias and is slated for removal in the next major.
• -o, --output: a single file holding one aggregate document for the whole run, a top-level array of the per-file results (TOML wraps the array under a files key; CSV concatenates each file’s rows). If omitted, results are printed to stdout.
• --output-dir: 入力ファイルごとに 1 つのドキュメントを保持するディレクトリで、各ドキュメントは入力パスにフォーマットの拡張子を付けた名前になります。--output とは相互排他で、両方を渡すとエラーです。
• CBOR はバイナリのため、出力先（--output または --output-dir）が必須です。構造化された --format なしでいずれかの出力先を渡すとエラーになります（デフォルトの text フォーマットは stdout にストリームし、ファイルを書きません）。これにより、出力先の指定が黙って無視されることはありません（#661）。
• --metrics <name,…>: restrict computation to a subset of metrics, comma-separated or repeated (--metrics cyclomatic,cognitive --metrics loc). Names are the canonical ids bca list-metrics prints, the same vocabulary bca check --threshold and bca diff --metric use. Dotted (cyclomatic.modified) and bare loc sub-metric (sloc) spellings are accepted, as is a family name (loc). Each selects its whole family: --metrics sloc prints the full loc block. The Python bindings’ metrics= takes the same names. Derived metrics pull in their dependencies automatically. An unknown name errors with a “did you mean” hint. Omit it to compute every metric (#691).

CSV (spreadsheets and pandas)

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

The CSV writer emits one row per FuncSpace (function, class, struct, unit, and so on) with the entire metric matrix as columns, a shape a spreadsheet or pandas loads directly. Header order is fixed; CSV_HEADER in src/output/csv.rs is the canonical list. Identity columns come first (path, space_name, space_kind, start_line, end_line), followed by every leaf metric under the same dotted JSON-style names (loc.lloc, halstead.volume, cyclomatic.modified.average), so a single column name addresses the metric in both CSV and JSON.

Empty cells (no value, not 0) signal “not applicable for this space”; for example, the OOP-only metrics (wmc.*, npm.*, npa.*) appear empty for procedural code. RFC 4180 quoting is delegated to the csv crate, so paths and names containing commas, quotes, or newlines round-trip cleanly.

Redirect stdout to collect the CSV output in one file:

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

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

An aggregated HTML report covering the whole walk is available via bca report html. The previous per-file bca metrics -O html writer was removed because it degraded to an unopenable single-file table on real-world repos; CSV is the right shape for flat per-FuncSpace rows.

整形出力

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 ファイルでは、主要メトリクスに本番コードとテストコードが混在します。

Pass --exclude-tests to elide test-only subtrees before any metric is computed. The flag is recognised by every subcommand that walks a source tree (metrics, ops, report, check, dump, find, count, functions, and the rest of the walker group), and currently understands the following Rust attribute shapes:

• #[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)]（内部属性形式）

Languages without a Checker::should_skip_subtree override ignore the flag; only Rust applies the pruning today. The default remains off so existing metric numbers stay byte-identical for users who do not opt in.

To opt a whole project in without repeating the flag, set exclude_tests = true in the repo’s bca.toml manifest. Because --exclude-tests is presence-only (no =false form), the manifest key can only turn pruning on; a CLI --exclude-tests still wins, but the manifest cannot turn it back off.

Pruning lowers the node-counted metrics (cyclomatic, cognitive, Halstead, nom, nargs, and the rest), and loc.sloc drops with them. Unlike node-counted metrics, loc.sloc comes from source spans. The walker subtracts each pruned subtree’s rows from every enclosing span, up to the file. Rows a pruned item shares with retained code or comments are kept, so sloc never falls below the ploc and cloc that survive the prune.

集約レポート

For a human-readable quality report, use bca report markdown. That command aggregates metrics across all analyzed files and produces per-language hotspot tables.

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

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

bca list-metrics

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

bca list-metrics descriptions