開発者ガイド

big-code-analysis の開発に貢献したい方のために、ビルド作業の助けとなる一連のガイドラインをここにまとめています。

前提条件として、Rust の最新バージョンをインストールする必要があります。その方法は こちら で確認できます。

リポジトリのクローン

まず、リポジトリをクローンする必要があります。次の方法で実行できます。

HTTPS を使う方法

git clone -j8 https://github.com/dekobon/big-code-analysis.git

または SSH を使う方法

git clone -j8 git@github.com:dekobon/big-code-analysis.git

Make が正式なエントリポイント

このリポジトリには、ビルド・テスト・リント・フォーマット・ドキュメント生成といった一般的なタスクをすべてラップする Makefile が同梱されています。make help を実行するとターゲットの全一覧を確認でき、make check-tools を実行すると、オプションのツール（taplo、rumdl、shellcheck、shfmt、checkmake、mdbook、cargo-insta、cargo-udeps、cargo-nextest）のどれがマシンに存在するかを確認できます。

最もよく使うことになる 2 つの複合ターゲットは次のとおりです。

  • make pre-commit — コミット前に推奨されるローカルゲートです。cargo fmt --check、2 種類の clippy 実行（デフォルトフィーチャと --all-features）、make test + make test-doc によるテストスイート全体（lib + bin + 統合 + doc）、cargo +nightly udeps、および Markdown / TOML / シェル / Makefile のリント群を 1 回の並列パスで実行します。
  • make ci — CI が実行するのと同じチェックを同じ順序で、自動修正なしで実行します。CI の失敗をローカルで再現するために使用してください。

GNU Make 4 やオプションのツールが利用できない場合は、以下に示す生の cargo コマンドにフォールバックしてください。これらは対応する Make ターゲットと同等です。

ビルド

big-code-analysis ライブラリ、CLI、Web サーバーを一括でビルドするには、次を実行します。

make build           # cargo build --workspace --all-targets
make build-release   # cargo build --workspace --release

個別のクレートに対しては、cargo を直接呼び出します。

cargo build                              # library only
cargo build -p big-code-analysis-cli     # CLI only
cargo build -p big-code-analysis-web     # web server only

make check は cargo check --workspace --all-targets を実行し、反復作業中の高速な型チェックを行います。

テスト

すべてのテストが通ることを確認するには、次を実行します。

make test       # cargo nextest run --workspace --all-features
make test-doc   # cargo test --workspace --all-features --doc

make test は cargo-nextest を優先します。CI が実行しているのもこちらです。素の cargo test は各テストバイナリを終えてから次を開始するため、並列性はバイナリ内にしか存在しません。nextest はすべてのバイナリのテストを 1 つのグローバルなプールにスケジュールします。cargo install --locked cargo-nextest でインストールできます。

nextest がない場合、make test は cargo test --workspace --all-features --lib --bins --tests にフォールバックし、同じテスト集合を実行します。ただし 2 つのランナーは完全に交換可能ではありません。nextest は各テストを独自のプロセスで実行するため、バイナリ内でテスト間に状態を共有するもの — OnceLock キャッシュ、環境変数、カレントディレクトリ — は nextest では分離され、cargo test では共有されます。ローカルで nextest を優先するということは、その軸においてローカル実行が CI と一致するということです。

NEXTEST= を設定すると、何もアンインストールせずにフォールバックを強制できます（make test NEXTEST=）。特定のバイナリを指すこともできます（make test NEXTEST=/path/to/cargo-nextest）。

doctest は nextest が実行できないため、別のターゲットになっています。make pre-commit と make ci はその両方を実行します。

cargo コマンドだけを自分で実行したい場合は、次のとおりです。

cargo test --workspace --all-features --verbose

insta テストの更新

本プロジェクトでは insta を使用しています。スナップショットを管理するには cargo insta をインストールしてください。必要になる 2 つの操作は Makefile がラップしています。

make insta-review   # cargo insta test --review (interactive)
make insta-accept   # cargo insta test --accept (use with care)

make insta-review はテストを実行して新しいスナップショット参照を生成し、各差分をレビューできるようにします。make insta-accept は、差分のパターンが一様であることを確認済みの、メトリクス値のみが変わる一括更新（文法のバージョンアップ、Halstead 演算子の再分類など）に限って使用してください。

コードフォーマット

これまでのステップがすべて問題なく完了し、あなたの貴重な貢献をコードベースに取り込むためのプルリクエストを作成したいなら、最後に残っているステップはコードフォーマットです。make fmt ターゲットはプロジェクト内のすべてのフォーマッタ（Rust、Markdown、TOML、Bash）を一括で実行します。make fmt-check はファイルを変更せずにフォーマットを検証します。

make fmt         # cargo fmt + rumdl check --fix + shfmt -w + taplo fmt
make fmt-check   # the equivalent --check variants

Rustfmt

このツールは、Rust のスタイルガイドラインに従ってコードをフォーマットします。

インストールするには、次を実行します。

rustup component add rustfmt

コードをフォーマットするには、次を実行します（make fmt が自動的に処理します）。

cargo fmt

Clippy

このツールは、よくある間違いの多くを自動的に検出し、開発者がより良いコードを書く手助けをします。コード内の一連のエラーや警告を検出し、これらはプルリクエストを作成する前に必ず修正しなければなりません。

make clippy は、プロジェクトが強制する 2 種類の clippy 実行（デフォルトフィーチャと --all-features）を実行します。make lint はさらに Markdown、シェル、TOML、Makefile のリンターも実行します。

インストールするには、次を実行します。

rustup component add clippy

エラーと警告を検出するには、次を実行します。

make clippy
# or, manually:
cargo clippy --workspace --all-targets -- -D warnings
cargo clippy --workspace --all-targets --all-features -- -D warnings

未使用の依存関係

make udeps は cargo +nightly udeps --workspace --all-targets を実行し、Cargo.toml に宣言されているものの一度も参照されていない依存関係を検出します。nightly ツールチェーン（rustup toolchain install nightly）と cargo-udeps が必要です。

コードドキュメント

make doc        # cargo doc --no-deps --workspace --all-features  (warning-tolerant)
make doc-open   # same, then open in a browser
make doc-check  # strict gate: appends -D warnings to RUSTDOCFLAGS, fails on any rustdoc warning

make doc と make doc-open は対話的なビューアーで、ビルドできるものをビルドするため、リファクタリングの途中でもレンダリング結果を確認できます。make doc-check は make pre-commit と CI の一部として実行される厳格なゲートで（RUSTDOCFLAGS に -D warnings を追加した cargo doc --no-deps --workspace --all-features）、壊れたドキュメント内リンク、非公開アイテムへのリンク、その他の rustdoc の回帰を検出します。

big-code-analysis が使用する各依存関係のドキュメントもビルドしたい場合は、基になる cargo 呼び出しから --no-deps オプションを削除してください。

本書のビルド

いま読んでいる本書は big-code-analysis-book/ 以下にあります。

make book        # mdbook build
make book-serve  # mdbook serve with live reload

コードの実行

bca は次のように実行できます。

cargo run -p big-code-analysis-cli -- [bca-parameters]

bca のパラメーター一覧を確認するには、次を実行します。

cargo run -p big-code-analysis-cli -- --help

bca-web は次のように実行できます。

cargo run -p big-code-analysis-web -- [bca-web-parameters]

bca-web のパラメーター一覧を確認するには、次を実行します。

cargo run -p big-code-analysis-web -- --help

make install、make install-cli、make install-web は、それぞれ対応するバイナリクレートに対して cargo install --path を呼び出します。

実践的なアドバイス

  • 新機能を追加するときは、すべてが正しく動作することを確認するために、少なくとも 1 つのユニットテストまたは統合テストを追加してください
  • 公開 API をドキュメント化してください
  • デッドコードを追加しないでください
  • 複雑なコードには、何を実現したのかを他の人が理解できるようにコメントを付けてください
  • プッシュ前に make pre-commit を実行してください — CI が実行するのと同じゲートです