品質レポート

集約された人間可読の Markdown レポートを生成するためのレシピです。

レポートを CI に組み込みたい場合。 Markdown レポートを PR/MR コメントとして投稿し、しきい値違反をプラットフォーム標準のコード品質ウィジェットで表示する、実行可能な GitHub Actions と GitLab CI の例は CI 統合レシピを参照してください。

実際のレポート例

big-code-analysis は、main へのプッシュごとに、自身のソースツリーに対する bca report -O markdown --vcs と bca report -O html --vcs の出力を公開しています。どちらかを開けば、このページのレシピが多言語の Rust + Python コードベースで生成する結果をそのまま確認できます:

HTML ホットスポットレポート（ソート可能なテーブル、言語別セクション、さらに --vcs による「変更履歴リスク」セクション付き）: https://dekobon.github.io/big-code-analysis/reports/index.html
Markdown の PR/MR コメント（そのまま issue に貼り付け可能）: https://dekobon.github.io/big-code-analysis/reports/report.md
変更履歴リスク。上位 100 件の完全なランキングを機械可読な JSON で提供します（bca vcs を参照）: https://dekobon.github.io/big-code-analysis/reports/vcs-report.json

これらを生成する仕組みは .github/workflows/pages.yml にあります。同じワークフローがしきい値ゲートも実行します。パイプライン全体の構成は CI 統合を参照してください。

プロジェクト全体の品質レポートを生成する

プロジェクトルートから実行し、レポートをファイルに書き出します：

bca report \
    --paths "$PWD" \
    -O markdown \
    --top 20 \
    --strip-prefix "$PWD/" \
    --output report.md

--strip-prefix はファイルパスを短く保ち、マシン間で安定させます。指定しない場合、各行には現在のチェックアウトの絶対パスが含まれます。
--top は各ホットスポットテーブルに表示される行数を制御します。PR コメントには 20 が適切なデフォルトです。ダッシュボードのタイルなら 5 に減らし、すべての行を表示するには 0 を渡します。
--jobs のデフォルトは実効 CPU 数です（Linux では cgroup / cpuset を考慮します）。デバッグのために直列モードを強制したい場合にのみ --jobs 1 を渡してください。

レポートを特定の言語に限定する

bca は拡張子から言語を推定するため、include / exclude のグロブでフィルタリングを行います：

bca report \
    --include "*.rs" --include "*.py" \
    --paths "$PWD" \
    -O markdown --output report.md

ベンダリングされたツリーや生成されたツリーを除外するには、さらに --exclude を重ねます：

bca report \
    --include "*.rs" \
    --exclude "**/target/**" --exclude "**/vendor/**" \
    --paths "$PWD" \
    -O markdown

フラグの引数個数。 --include と --exclude は 1 回の指定につきちょうど 1 つのグロブを受け取ります。パターンを追加するにはフラグを繰り返してください。= 形式も同様に動作します: --include="*.rs" --exclude="**/target/**"。

先頭の ./ は省略可能です。 素の相対パターンと ./ 付きの表記は等価です。--exclude "vendor/**" は --exclude "./vendor/**" とまったく同じものにマッチします。これは --include、--exclude、--exclude-from、.bcaignore、そして [check.exclude] ゲート免除セットという、すべてのグロブ入力面に当てはまります。

リポジトリ全体で安定した除外セットを維持するには、パターンをリポジトリルートのファイル（慣例として .bcaignore）に置き、--exclude-from で読み込みます。パターンはインラインの --exclude の値と和集合になります。空行と # で始まるコメントはスキップされます：

bca report \
    --paths . \
    --exclude-from .bcaignore \
    -O markdown --output report.md

最も深刻な違反だけを表示する

セクションごとに上位 3 件の問題をハイライトする簡易トリアージビューには次を使います：

bca report -p src/ -O markdown --top 3

レポートには引き続きすべてのセクションが含まれますが、各テーブルは一目で確認できる程度に短くなります。

2 つのリビジョンを比較する

集約レポート自体にはリビジョン間の差分を取る機能はありません。両側でそれぞれレポートを実行し、Markdown を diff します：

git worktree add /tmp/before main
bca report -p /tmp/before -O markdown \
    --strip-prefix /tmp/before/ --output /tmp/before.md

bca report -p "$PWD" -O markdown \
    --strip-prefix "$PWD/" --output /tmp/after.md

diff -u /tmp/before.md /tmp/after.md | less

両方のレポートが同じ --strip-prefix の形式を使うため、パスの列が揃い、diff はパスのノイズではなくメトリクスの変化が中心になります。

C/C++ プリプロセッサ対応レポート

マクロを多用する C/C++ コードベースでは、プリプロセッサデータをアナライザーに与えることで、条件付きコンパイルをコンパイラが見るのと同じように解釈できます。ワークフローは 2 段階です：

# 1. ヘッダーとソースからプリプロセッサデータの JSON を構築します。
bca preproc \
    --paths src/ include/ \
    --output /tmp/preproc.json

# 2. そのデータを添えてレポート（または他の任意のコマンド）を実行します。
bca report \
    --paths src/ \
    --preproc-data /tmp/preproc.json \
    -O markdown --output report.md

--preproc-data は、メトリクスを計算してツリーをウォークするすべてのサブコマンド（metrics、ops、functions、report、check など）で受け付けられます。正確な C/C++ 解析が重要な場面ならどこでも使えます。これを消費しないサブコマンド（vcs、preproc、list-metrics、diff-baseline）では、使用方法エラーとして拒否されます。

PR で変更されたファイルだけを解析する

変更されたファイルの一覧を --paths-from - にパイプすると、ツリー全体ではなく差分だけを採点できます：

git diff --name-only --diff-filter=AM origin/main...HEAD \
    | bca metrics --paths-from - -O json --output-dir ./out

--diff-filter=AM は追加（Added）と変更（Modified）されたファイルを残し、削除（Deletion）を除外します。もはや存在しないファイルは解析できないためです。
--paths-from - は標準入力から改行区切りのパスを読み取ります。ファイル引数でも同様に動作します: --paths-from changed.txt。
この方法で渡されたパスは明示的なものとして扱われるため、ディレクトリウォークではそれらを隠していたはずの .gitignore ルールをバイパスします。言語で絞り込むには -I '*.py' -I '*.rs' を組み合わせてください（グロブごとにフラグを 1 回ずつ繰り返します）。

PR 範囲の Markdown サマリーが必要な場合は、metrics をレポートパイプラインに置き換えます：

git diff --name-only --diff-filter=AM origin/main...HEAD \
    | bca report --paths-from - -O markdown \
        --top 10 --output pr-report.md

ディレクトリをウォークする際は .gitignore が自動的に尊重されるため、このページの前半のレシピでは、対象のパスがプロジェクトの .gitignore で既にカバーされていれば、明示的な -X "**/target/**" -X "**/node_modules/**" はもう不要です。gitignore されたツリーを解析する必要がある場合は --no-ignore を追加してください。

big-code-analysis Documentation