品質レポート

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

Wiring reports into CI? See the CI integration recipe for runnable GitHub Actions and GitLab CI examples that post the Markdown report as a PR/MR comment and surface threshold violations through the platform’s native code quality widgets.

実際のレポート例

big-code-analysis publishes the output of bca report -O markdown --vcs and bca report -O html --vcs against its own source tree on every push to main. Open either to see what the recipes on this page produce on a multi-language Rust + Python codebase:

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 keeps the file paths short and stable across machines. Without it every row carries the absolute path of the current checkout.
--top controls how many rows appear in each hotspot table. 20 is a reasonable default for a PR comment; drop to 5 for a dashboard tile, or pass 0 to list every row.
--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/**"。

Leading ./ is optional. A bare-relative pattern and its ./-prefixed spelling are equivalent: --exclude "vendor/**" matches exactly what --exclude "./vendor/**" does. This holds for every glob surface: --include, --exclude, --exclude-from, .bcaignore, and the [check.exclude] gate-exemption set.

リポジトリ全体で安定した除外セットを維持するには、パターンをリポジトリルートのファイル（慣例として .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 します：

work=$(mktemp -d "${TMPDIR:-/tmp}/bca-report-diff.XXXXXX")
git worktree add "$work/before" main
bca report -p "$work/before" -O markdown \
    --strip-prefix "$work/before/" --output "$work/before.md"

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

diff -u "$work/before.md" "$work/after.md" | less

Because both reports use the same --strip-prefix shape, the path columns line up and the diff shows metric changes rather than path noise.

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

For macro-heavy C/C++ codebases, feed preprocessor data into the analyzer so conditional compilation is interpreted the way the compiler sees it. The workflow is two steps:

# 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

Every metric-computing walking subcommand (metrics, ops, functions, report, check, …) accepts --preproc-data. Subcommands that do not consume it (vcs, preproc, list-metrics, diff-baseline) reject it as a usage error.

Step 1’s document is deterministic. The files map is written in sorted path order, and each entry’s direct_includes, indirect_includes, and macros arrays in sorted name order, so two bca preproc runs over an unchanged tree produce byte-identical output, on stdout as well as through --output. Check /tmp/preproc.json into a build cache or diff it between branches without spurious churn, as you can a metrics --output or ops --output document.

You need the sorting rules only when reproducing the output order. The files keys sort by path component, so a/x.h precedes a-b/x.h. Include and macro arrays sort by bytes, so a-b/x.h precedes a/x.h. You do not need to reproduce either sort when reading the document; jq preserves the stored order.

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 keeps Added and Modified files and drops Deletions, since a file that no longer exists cannot be analyzed.
--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

A directory walk honors .gitignore automatically, so the recipes earlier on this page need no explicit -X "**/target/**" -X "**/node_modules/**" when your project’s .gitignore already covers those paths. Add --no-ignore to analyze gitignored trees.

Keyboard shortcuts

big-code-analysis Documentation