Skip to content

README.ja.md

Latest commit

 

History

History
151 lines (116 loc) · 11.4 KB

README.ja.md

File metadata and controls

151 lines (116 loc) · 11.4 KB
Raw

big-code-analysis

crates.io MSRV CI codecov CodeQL OpenSSF Scorecard OpenSSF Best Practices docs.rs License

English | 日本語

big-code-analysis はコードの保守性を測定するツールです。 コマンドラインツール bca は、20 を超えるプログラミング言語を対象に、 関数単位のメトリクスを計算します。循環的複雑度、 認知的複雑度、 Halstead メトリクス、保守容易性指数、ABC、各種コード行数など、 メトリクス一式をサポートします。 パースには tree-sitter を使うため、 コンパイラもビルドステップも言語ランタイムも不要です。ディレクトリを指定するだけで数値が出力されます。

本プロジェクトは Mozilla の rust-code-analysis のハードフォークで、 メトリクスエンジンをコード品質ツールチェーンへと発展させたものです。

  • bca check — ベースライン、ソース内抑制マーカー、CI 向け終了コードを備えたしきい値ゲート。
  • エージェントフィードバック — 編集のたびに違反を Claude Code や opencode にフィードバック（下記参照）。
  • bca report — Markdown / HTML のホットスポットレポート。
  • bca vcs — git ツリーに対する変更履歴メトリクス（チャーン、所有権の希薄化、バグ修正履歴）。
  • ライブラリバインディング — 同じエンジンを Rust クレート、 Python パッケージ、REST サーバー（bca-web）として利用できます。

インストール前に出力を確認したい場合は、bca が main へのプッシュのたびに 自分自身のソースを解析して公開している結果をご覧ください。

完全なドキュメントはドキュメントブック（日本語版）にあります。 メトリクスの定義、コマンドリファレンス、CI レシピ、ライブラリガイドを収録しています。

コーディングエージェントにメトリクスをフィードする

コーディングエージェントは大量のコードを書きますが、 そのループの中に「この関数は保守できないほど複雑になった」と教えてくれる仕組みはありません。 bca check はそのループを閉じます。エージェントが編集した各ファイルをチェックし、編集が確定した瞬間に、 問題のある関数をモデルのコンテキストへ報告します。 必要なのは PATH 上の bca（クイックスタート参照）と数行の設定だけです。

  • Claude Code — PostToolUse フックが編集されたファイルに対して bca check を実行し、違反をモデルにフィードバックします。 本リポジトリ自身がリファレンス実装のフック .claude/hooks/bca-check.sh をドッグフーディングしています。
  • opencode — tool.execute.after プラグインが同じ役割を果たします。 リファレンスコピーは .opencode/plugins/bca-check.js にあります。

エージェントフィードバックのレシピには、 両ツール向けのコピー＆ペーストで使える設定に加えて、 エージェントがコードを簡潔にする代わりにメトリクスの数値だけを下げる「メトリクスのゲーム化」を防ぐガイダンスブロックも掲載しています。

クイックスタート

リリースページからビルド済みの bca をインストールするか （Linux・macOS・Windows 向けの署名付き tarball と .deb・.rpm・.apk パッケージ）、パッケージレジストリからインストールします。

cargo install big-code-analysis-cli    # または: pip install big-code-analysis-cli

その後、プロジェクトのルートで次を実行します。

bca metrics src/main.rs      # 1 ファイルの関数単位メトリクスツリー
bca init                     # bca.toml・.bcaignore・.bca-baseline.toml を生成
bca check                    # 関数がしきい値を超えると終了コード 2
bca report -O html -o report.html

全サブコマンド・フラグ・出力形式は、 ブックの Commands の章に記載されています。

CI での品質ゲートとレポート

bca check はしきい値・ベースライン・除外設定をコミット済みの bca.toml から読み込むため、CI、ローカル実行、 エージェントフックのすべてが同じシグナルでゲートされます。bca report は同じ実行結果を、 プルリクエスト向けの Markdown コメントや HTML のホットスポットページに変換します。 本リポジトリはプッシュのたびに自分自身をゲートし、その結果を公開しています。

CI 統合レシピが導入ガイドです。 チェックサム検証付きのリリース固定インストール、そのまま使える GitHub Actions / GitLab CI ジョブに加えて、 既存コードベースを段階的に締めていくためのベースラインと ローカルしきい値ゲートのレシピがあります。

ライブラリとして使う

big-code-analysis クレートは、明文化された安定性契約（STABILITY.md、英語）のもとで crates.io に公開されています。公開 API は 2.x 系のパッチ・マイナーバンプの間は安定を保ち、 破壊的変更は次のメジャーバンプまで持ち越されます。ただし、 文法のバージョン固定が更新された場合やメトリクス定義が修正された場合には、 メトリクスの値はマイナーバンプでも変動することがあります。何が約束され、何が約束されないかは契約に明記されています。

[dependencies]
big-code-analysis = "2"

各文法は言語ごとの Cargo フィーチャーの背後に置かれています。デフォルトではすべて有効で、 一部だけ必要な場合はデフォルトフィーチャーを無効化して個別の言語を再度有効化できます。 ブックの言語別 Cargo フィーチャーと、 タスク指向のウォークスルー（クイックスタート、インメモリ解析、FuncSpace 結果の走査、エラーハンドリング）をまとめた ライブラリとして使うの章を参照してください。 API リファレンスは docs.rs にあります。

Python バインディング（PyO3）は big-code-analysis-py/ にあり、 PyPI の big-code-analysis パッケージとして同じメトリクスパイプラインを提供します。 ブックの Python バインディングの章で、 インストール、バッチ処理・非同期処理、 SARIF 出力を解説しています。

サービスとして動かす場合は、bca-web がライブラリを REST API としてラップします。 bca-web の運用を参照してください。

ビルドと貢献

このリポジトリは Cargo ワークスペースで、よく使うタスクのための Makefile ラッパーを備えています。 make help で全タスクの一覧を確認できます。

make build        # ワークスペース全体のデバッグビルド
make test         # 完全なテストスイート（ワークスペース、全フィーチャー）
make pre-commit   # CI と同等のローカルゲート一式

貢献のワークフローは CONTRIBUTING.md（英語）に、 内部構造（言語の追加、メトリクスの実装、文法の更新）はブックの 開発者ガイドにまとまっています。

ライセンス

  • 同梱の文法クレート（tree-sitter-ccomment、tree-sitter-mozcpp、tree-sitter-mozjs、 tree-sitter-preproc、tree-sitter-tcl）は MIT ライセンスで公開されています。

  • big-code-analysis、big-code-analysis-ast、big-code-analysis-cli、 big-code-analysis-web、big-code-analysis-py は Mozilla Public License v2.0 のもとで公開されています。