レポート

bca report [--format <FORMAT>] は、走査したすべてのファイルにわたる品質メトリクスの集約レポートを生成します。プルリクエスト、wiki、課題トラッカーへの貼り付けを想定して設計されています。

フォーマットは --format / -O で選択します（bca report --format html）。省略時のデフォルトは markdown です。素の位置引数形式（bca report markdown）は非推奨のエイリアスとして引き続き動作しますが、次のメジャーバージョンで削除される予定です。--format を使用してください。

CI 統合。 Markdown レポートを PR/MR コメントとして投稿する、実行可能な GitHub Actions と GitLab CI のレシピについては、CI 統合レシピを参照してください。

利用できるフォーマットは 2 つです。markdown（プレーンテキストで、PR コメントに最適）と html（ソート可能なテーブルを備えた自己完結型ダッシュボードで、ビルド成果物として共有するのに最適）です。

移行の際は。 このコマンドは、再構成前の --metrics -O markdown 呼び出しを置き換えるものです。移行ガイドを参照してください。

クイックスタート

標準出力に表示：

bca report --paths /path/to/project markdown

ファイルに書き出し：

bca report --paths /path/to/project markdown --output report.md

注： --output はディレクトリではなく「ファイル」パスでなければなりません。

フラグ

抑制マーカー

デフォルトでは、bca report markdown|html はソース内の抑制マーカーを尊重します — bca check と SARIF エミッターが尊重するのと同じ // bca: suppress、// bca: suppress-file、#lizard forgives コメントです（抑制を参照）。あるメトリクスが抑制されている関数はそのメトリクスのホットスポットテーブルから除外されるため、公開されるレポートは、沈黙済みの違反をすべて再表示するのではなく、しきい値ゲートと一致します。

抑制はメトリクス単位です。// bca: suppress(cyclomatic) マーカーは関数を Cyclomatic テーブルからのみ除外します — Cognitive、Halstead などのテーブルには引き続き表示されます。引数なしの // bca: suppress（または // bca: suppress-file）はすべてのメトリクスをカバーします。

マーカーに関係なくすべての違反を列挙する生の監査ビューには --no-suppress を渡します。この設定は bca.toml マニフェストに固定することもできます：

[report]
no_suppress = true

CLI フラグが優先されます。素の --no-suppress は監査ビューを強制的に有効化できますが、マニフェストがそれを強制的に無効化することはありません。

使用例

セクションごとに最悪のホットスポット 5 件のみを表示：

bca report -p src/ markdown --top 5

表示されるパスからワークスペースルートを取り除く：

bca report -p /home/user/project markdown \
    --strip-prefix /home/user/project/

日常使いの呼び出し例：

bca report \
    --paths "$PWD" \
    markdown \
    --top 20 \
    --strip-prefix "$PWD/"

レポートの構成

生成されたレポートには以下のセクションが含まれます（データが存在しないセクションは省略されます）。すべてのホットスポットテーブルには SLOC と並んで Tokens 列（Lizard 方式の葉トークン数、コメントは除外）が含まれ、行ごとに補完的な 2 つのサイズ指標を確認できます。

1. プロジェクトサマリー — 分析したファイル数、言語、SLOC / PLOC / コメントの総数、関数数とクラス数、コメント比率。
2. 言語別概要テーブル — 言語ごとに 1 行で、ファイル数、SLOC、関数数、SLOC 加重平均の保守容易性指数（MI）、平均循環的複雑度（CC）、平均認知的複雑度を示します。MI の平均はサイズ加重で、「クランプされていない」 Visual Studio の値を使用するため、ファイルの大半が保守不能な言語は、ファイルごとの MI 列の下限 0 で飽和するのではなく負の値として表示されます。
3. 言語別ホットスポットセクション（言語ごとに繰り返されます）。すべてのホットスポットのタイトルは <Concept> hotspots (top N by <column>) という 1 つのテンプレートに従い、切り詰め句は実際の --top の状態を示します（top 20 by CC、--top 0 の場合は all, by CC）：
   • Summary — ファイル数、SLOC、PLOC、コメント比率、および GOOD / MODERATE / LOW の評価付き Average MI (SLOC-weighted)。見出しの値は「クランプされていない」 Visual Studio MI の SLOC 加重平均です。大きなファイルが支配的になり、表示上の MI が 0 にクランプされるファイルも、誤解を招く 0 ではなく真の（多くの場合負の）保守性で寄与します。
   • Actionable Summary — 一般的なしきい値を超える関数の数（デフォルトでは CC > 10、cognitive > 15、SLOC > 100、args > 3、Halstead bugs > 1。マニフェストの [thresholds] テーブルで各カットオフを上書きできます）。Summary の直後、どのホットスポットテーブルよりも前に最初に出力されるため、テーブルを 1〜2 個読んで止めた読者でも最も俯瞰的なカウントを目にできます。これらは抑制を無視した生のカウントです。セクションのキャプションにその旨が記され、抑制された関数がいくつ含まれているかが明示されます。このサマリーがカウントしているメトリクスのホットスポットテーブルが抑制によって空になった場合、そのテーブルは「table omitted: all N matching functions suppressed」という 1 行の注記に置き換えられ、サマリーの箇条書きが存在しないテーブルを指すことはありません。
   • Maintainability Index hotspots (lowest N by MI) — MI の昇順でソートされたファイル。
   • Cyclomatic complexity hotspots (top N by CC) — CC の降順でソートされた関数。要約統計（平均、最大、10 超・20 超の件数）付き。
   • Cognitive complexity hotspots (top N by Cognitive) — 認知的複雑度の降順でソートされた関数。
   • Halstead effort hotspots (top N by Effort) — Halstead effort の降順でソートされた関数。volume と推定バグ数を含みます。Effort と Volume は千区切り付きの丸め整数（8,845）として表示され、完全な精度は JSON/CSV に保持されます。
   • Function size hotspots (top N by SLOC) — ソースコード行数の降順でソートされた関数。
   • Many parameters hotspots (top N by Args) — パラメータが 3 個を超える関数。降順でソートされます。
   • Type hotspots (top N by WMC) — Weighted Methods per Class の降順でソートされた型。NOM、NPA、NPM 付き。「Type」はレポートが数える 6 種類すべて（class、struct、trait、impl、interface、namespace）をカバーします（凡例の WMC エントリに列挙されています）。
   • Exit points hotspots (top N by Exits) — 出口点が 2 個を超える関数。降順でソートされます。単一の return は基準であってホットスポットではないため、テーブルには nexits > 2 のみが載ります。下限を超えるものがなければセクションは省略されます。
   • ABC magnitude hotspots (top N by ABC) — ABC メトリクスの大きさの降順でソートされた関数。

フォーマット間の一貫性

Markdown レポートと HTML レポートは、1 つの基盤データモデルの 2 つのレンダリングであり、常に同じデータを提示します。共有されるすべての数値（プロジェクトおよび言語別のサマリー、ホットスポットテーブルのメンバーシップ、循環的複雑度の Average / Max / CC > 10 注記のような各ホットスポットのキャプション）は一度だけ計算されて両方でレンダリングされるため、1 回の実行で --format markdown と --format html のどちらを出力しても同一の数値になります。

どちらのフォーマットにも、すべてのメトリクス列の略語（CC、MI、ABC、WMC、…）とグローバルヘッダーの統計（PLOC、Comments、Comment ratio）を定義する凡例が含まれます — Markdown では ## Legend セクション（最後の言語の下に入れ子になるのではなく、独立したアウトラインエントリ）、HTML では展開済みの（<details open>）ブロックです。これにより、ホバーツールチップに加えて、印刷・モバイル・スクリーンリーダーでも凡例が失われません。各エントリは対応メトリクスリファレンスの該当章にリンクしているため、1 行の定義から完全な説明へ読者を案内できます。定義はツールチップが使うのと同じ共有列仕様に由来するため、2 つのフォーマットが乖離することはありません。

どちらのフォーマットも、bca のバージョン、生成日、走査したシードパス、テーブルごとの --top 値、抑制マーカーを尊重したかどうかを記した来歴フッターで締めくくられます — これにより、切り離された成果物（PR コメント、Pages デプロイ、チケットに添付されたファイル）に、それが何から生成されたのかが記録されます。生成日は再現可能ビルドのために SOURCE_DATE_EPOCH を尊重します。HTML レポートはさらに <meta name="viewport"> タグを持ち、すべてのテーブルを水平スクロールコンテナで包むため、幅の広いテーブルもモバイルや狭いウィンドウで閲覧可能なままです。また目次では、各言語のホットスポットのサブセクションが折りたたみ可能なエントリの下に入れ子になります。

抑制はレポートだけでなくすべての出力に一律に適用されます。あるメトリクスについて — ソース内マーカーまたはベースラインにより — 沈黙させられた関数は、bca check の違反出力フォーマット（code-climate、sarif、checkstyle、clang-warning、msvc-warning）からも、対応するレポートのホットスポットテーブルからも同様に除外されます。CodeClimate、SARIF、Checkstyle の各ドキュメント自体が 1 つの違反集合の 3 つのレンダリングなので、構造上一致します。レポートも同じメトリクス単位の抑制判断を尊重します。

唯一の意図的な例外は Actionable Summary です。これはコードベース全体の健全性指標であり、抑制に関係なく生の測定値を意図的にカウントします — あるメトリクスのホットスポットテーブルで関数を沈黙させても、この集約された懸念カウントからは消えません。各ホットスポットテーブルのキャプションを含む他のすべての数値は、抑制でフィルタリングされた集合を反映します。読者が 2 つの母集団を二重カウントと取り違えないよう、それぞれにキャプションが付きます。循環的複雑度の注記には「(excluding suppressed functions)」が追加され、Actionable Summary はそのカウントが抑制を無視した生の値に基づくことを明示します。

HTML フォーマット

bca report html は、Markdown レポートと同じセクションをカバーする単一の自己完結型 HTML ページを出力します。静的成果物として配信することを想定した設計です。インライン CSS、すべてのホットスポットテーブルをクリックでソートするためのインラインのプレーンな JavaScript を備え、外部依存はゼロです（CDN なし、フォントなし、テンプレートエンジンなし）。ページはオフラインでも同一にレンダリングされます。

ファイルに書き出して任意のブラウザで開きます：

bca report --paths /path/to/project \
    html --top 10 --output report.html

任意の列ヘッダーをクリックするとそのテーブルが昇順でソートされ、もう一度クリックすると降順に切り替わります。各テーブルは独立してソートされます。空のセル（メトリクスが測定されなかった箇所）は正の無限大であるかのようにソートされるため、「データなし」の行がホットスポットの見える上位に紛れ込むことはありません。

任意のメトリクス列ヘッダー — SLOC、MI、CC、ABC、WMC、NPA、NPM、Exits など — にホバー（ブラウザが対応していればキーボードフォーカスでも可）すると、そのメトリクスの平易な英語による 1 文の説明が表示されます。ツールチップはネイティブの HTML title 属性で提供されるため、JavaScript なしでもオフラインで機能します。

title ツールチップはホバー時のみ有効で — 印刷・モバイル・スクリーンリーダーでは見えないため — ページの末尾には、すべてのメトリクス列の 1 行定義を列挙する、目に見える折りたたみ可能な凡例（<details>）も置かれます。ツールチップと凡例は同じ列仕様から生成されるため、ホバー時と凡例とで定義が食い違うことはありません。

補間されるすべての文字列 — 関数名、ファイルパス、言語ラベル — は出力時に HTML エスケープされるため、細工されたソースパスやシンボル名がマークアップを注入したり、属性値の外に抜け出したりすることはできません。

言語ごとの各 <section> には安定した lang-<name> クラス（例：lang-rust、lang-python）が付与され、低アルファの背景色とそれに対応する左ボーダーでスタイル付けされるため、多言語レポートのセクション境界が一目で分かります。明示的なパレットエントリを持たない言語は中立的な lang-other の色にフォールバックし、prefers-color-scheme: dark アダプターがアルファを引き上げるため、どちらのテーマでもコントラストが保たれます。

メトリクス値のゼロ

レポート内のメトリクス値 0 は、その項目についてメトリクスが測定されなかったことを意味します（例：空の関数に対する Halstead メトリクス）。エントリがすべてゼロのセクションは完全に省略されます。