rust-quality-gate

Rust 品質ゲートプロトコル

実行するタイミング

次の場合にこのプロトコルを実行します。

• 実装タスクが完了し、コード変更をコミットできる状態になったとき
• ユーザーから「品質を確認して」「テストを実行して」「clippy を実行して」「準備はできているか」「検証して」と依頼されたとき
• プルリクエストの作成または main へのマージの前
• 共有ライブラリクレート（trusty-common、trusty-mcp-core、trusty-embedder、trusty-symgraph）を変更した後
• rust-qa エージェントが成果物を提出した後

3 つのゲートを順番に実行

ゲートは必ずこの順序で実行します。最初の失敗で停止し、次のゲートには進まないでください。

ゲート 1：フォーマットチェック（最速 — 必ず最初に実行）

cargo fmt --check

合格：出力なし、終了コード 0。

不合格：フォーマットに差異があるファイルが一覧表示されます。次のコマンドで修正します。

cargo fmt

その後、cargo fmt --check を再実行して問題がないことを確認します。

最初に実行する理由：フォーマットの問題は簡単に修正できます。最初に実行することで、フォーマットされていないコードに対して clippy やテストを実行して時間を浪費するのを防げます。

ゲート 2：Clippy lint ゲート

cargo clippy --workspace --all-targets -- -D warnings

合格：警告が出力されず、終了コード 0。

不合格：error[clippy::] の行が 1 つ以上あります。コンパイラーが報告した警告をすべて修正します。よくあるパターン：

# Check a single crate faster during iteration
cargo clippy -p trusty-search -- -D warnings

# Check with a specific feature enabled
cargo clippy -p trusty-common --features axum-server -- -D warnings

open-mpm の例外：open-mpm には HEAD 時点で既存の clippy エラーが 142 件あります（別途追跡中）。これらのエラーによって他の作業がブロックされることはありません。ワークスペース全体に対して clippy を実行して open-mpm が失敗した場合は、失敗が open-mpm のみに限られるか確認します。

# Run clippy on everything except open-mpm to confirm other crates are clean
cargo clippy --workspace --all-targets -- -D warnings 2>&1 | grep -v "open-mpm"

すべてのエラーが open-mpm にある場合は、open-mpm 以外の作業ではこのゲートを合格として扱います。

ゲート 3：テストゲート

単一クレート（高速 — 反復作業で使用）：

cargo test -p <crate>

ワークスペース全体（コミット前に必須）：

cargo test --workspace

無視された統合テストを含める（完全な検証）：

cargo test -p <crate> -- --include-ignored
# or workspace-wide:
cargo test --workspace -- --include-ignored

クレート名とディレクトリ名

Cargo の -p フラグには、ディレクトリ名ではなく Cargo.toml の name フィールドを指定します。例外：

ディレクトリ	Cargo フラグ
crates/trusty-git-analytics/	-p tga
crates/open-mpm/	-p open-mpm

それ以外のすべてのクレートでは、ディレクトリ名とクレート名が同じです（例：crates/trusty-search/ → -p trusty-search）。

テスト出力の読み方

Cargo のテスト出力は、次のサマリー行で終わります。

test result: ok. 42 passed; 0 failed; 3 ignored; 0 measured; 0 filtered out

フィールド	意味
passed	実行され、成功したテスト
failed	実行され、失敗したテスト — 0 件でなければなりません
ignored	#[ignore] が付けられたテスト — デフォルトではスキップされます（ONNX／統合テスト）
measured	ベンチマーク結果（ベンチモードのみ）

#[ignore] テスト：時間のかかる ONNX ベースのテスト、または環境に依存する統合テストです。デフォルトのゲートでは意図的にスキップされます。リリース前に完全なローカル検証を行うには、--include-ignored を指定して実行してください。

必須の証拠形式：「テストは合格」のような表現ではなく、サマリー行をそのまま報告してください。許容される証拠の例：

test result: ok. 87 passed; 0 failed; 5 ignored; 0 measured; 0 filtered out; finished in 3.42s

既存の失敗と新しい失敗の切り分け

ゲートが失敗した場合は、その失敗が現在のパッチより前から存在していたかどうかを判断します。

# Stash current changes
git stash

# Run the failing gate at clean HEAD
cargo test -p <crate>

# If it also fails at HEAD: pre-existing failure — do not block the patch
# If it passes at HEAD: the patch introduced the regression — must fix

# Restore patch
git stash pop

次のいずれかを報告してください：「失敗は HEAD 時点ですでに存在しており、この変更によるものではありません」または「失敗は新しく、このパッチによって発生しました」。

単一クレートとワークスペースの範囲

範囲	コマンド	実行タイミング
単一クレート	cargo test -p <crate>	実装中の迅速な反復作業
単一クレート（チェックのみ）	cargo check -p <crate>	最速 — テストは実行せず、コンパイルを確認
単一クレート＋機能	cargo test -p trusty-common --features axum-server	機能フラグが必要なとき
ワークスペース	cargo test --workspace	変更をコミットする前に必須
ワークスペース＋無視されたテスト	cargo test --workspace -- --include-ignored	リリースにタグを付ける前

共有ライブラリクレートを変更した後

trusty-common、trusty-mcp-core、trusty-embedder、または trusty-symgraph を変更した場合：

1. まず cargo check（ワークスペース全体）を実行します。すべての依存先におけるコンパイルエラーをすぐに検出できます。
2. 変更したライブラリに対して cargo test -p <lib> を実行します。
3. 変更したライブラリをインポートする各クレートに対して cargo test -p <consumer> を実行します。
4. 依存先のテストがすべて合格してからコミットします。

ゲートの概要

cargo fmt --check          → Gate 1 (format)  — fix: cargo fmt
cargo clippy --workspace   → Gate 2 (lint)    — fix: address each warning
cargo test -p <crate>      → Gate 3 (tests)   — fix: repair failing tests

PR をマージ可能にするには、3 つすべてがグリーンである必要があります。証拠には、各ゲートの出力をそのまま含めてください。

アンチパターン

• フォーマットと clippy の前にテストを実行する — フォーマットに失敗した場合、時間が無駄になります。
• 結果のサマリー行を示さずに「テストに合格した」と報告する。
• ignored の件数を失敗として扱う — 意図的にスキップされています。
• HEAD ですでに発生している open-mpm の clippy エラーで作業を止める。
• cargo test の代わりに cargo build を使う — ビルドが成功しても、動作の検証にはなりません。
• クレート名の別名を確認せずにワークスペース全体で cargo test を実行する（例：trusty-git-analytics ではなく -p tga を使用する）。