rust-sota-arsenal

Rust SOTA Arsenal

リファクタリング、プロファイリング、ベンチマーク、テスト、SIMD 最適化に関する最先端の Rust ツール知識です。LLM が深い学習データを持っていないことの多いツールを扱います。

自己進化型スキル：このスキルは使用を通じて改善されます。指示が誤っていた場合、パラメーターがずれていた場合、または回避策が必要になった場合は、後回しにせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

重要：作業の前にウェブで確認する

このスキルの参考ドキュメントは出発点であり、絶対的な根拠ではありません。 ツールのバージョン、互換性マトリックス、API の仕様は、静的なドキュメントよりも速く変化します。特定のバージョンを推奨したり、アップグレードを判断したりする前に、次の手順を実行してください。

1. crates.io で最新バージョンを確認する：crates.io API に WebFetch を使用して、現在のバージョン情報を取得します

   WebFetch: https://crates.io/api/v1/crates/{crate_name}
   Prompt: "What is the latest version? List recent versions."
   

2. 依存関係の互換性を確認する：アップグレード時（例：PyO3）は、下流クレートとの互換性を確認します

   WebFetch: https://crates.io/api/v1/crates/{crate_name}/{version}/dependencies
   Prompt: "What version of {dependency} does this require?"
   

3. 破壊的変更を検索する：変更履歴と移行ガイドを WebSearch で検索します

   WebSearch: "{crate_name} latest version changelog migration"
   

4. 代替手段：Firecrawl でスクレイピングする（WebFetch が失敗するか、不完全なデータを返す場合。例：JavaScript を多用するページ、レート制限）：

   curl -s -X POST https://api.firecrawl.dev/v2/scrape \
     -H "Content-Type: application/json" \
     -d '{"url": "https://crates.io/crates/{crate_name}", "formats": ["markdown"], "waitFor": 0}' \
     | jq -r '.data.markdown'
   

   パブリック API のため、キーもテールネットも不要です。API の全リファレンスについては、/devops-tools:firecrawl-research-patterns を参照してください。

理由：opendeviationbar のセッションでは、ウェブ検索を行って初めて、PyO3 が 0.28 ではなく 0.28.2 であり、pyo3-arrow が 0.17.0 であることが判明しました。静的なドキュメントだけでは、誤ったアップグレード判断につながっていたでしょう。

使用する場面

• Rust コードのリファクタリング（AST 対応の検索／置換、API 互換性）
• パフォーマンス改善（プロファイリング、PGO、Cargo プロファイルの調整）
• ベンチマーク（divan と Criterion の選択、ベンチマークのセットアップ）
• テスト（高速なテストランナー、ミューテーションテスト、フィーチャーフラグのテスト）
• SIMD 最適化（安定版 Rust でのポータブル SIMD）
• PyO3 バインディングの移行（0.22 以降）

クイックリファレンス

ツール	インストール	一言で説明	カテゴリ
ast-grep	cargo install ast-grep	Rust の AST を認識した検索・書き換え	リファクタリング
cargo-semver-checks	cargo install cargo-semver-checks	API 互換性の lint（数百種類の lint）	リファクタリング
samply	cargo install samply	プロファイル → Firefox Profiler UI	パフォーマンス
cargo-pgo	cargo install cargo-pgo	PGO + BOLT による最適化	パフォーマンス
cargo-wizard	cargo install cargo-wizard	Cargo プロファイルを自動設定	パフォーマンス
divan	dev-deps の divan = "<version>"	#[divan::bench] 属性 API	ベンチマーク
criterion	dev-deps の criterion = "<version>"	統計に基づく Gnuplot レポート	ベンチマーク
cargo-nextest	cargo install cargo-nextest	3 倍高速、テストごとにプロセスを起動	テスト
cargo-mutants	cargo install cargo-mutants	ミューテーションテスト（見逃し／検出）	テスト
cargo-hack	cargo install cargo-hack	機能のべき集合テスト	テスト
macerator	deps の macerator = "<version>"	型ジェネリック SIMD + マルチバージョニング	SIMD
cargo-audit	cargo install cargo-audit	RUSTSEC の脆弱性スキャン	依存関係
cargo-deny	cargo install cargo-deny	ライセンス + アドバイザリー + 禁止事項	依存関係
cargo-vet	cargo install cargo-vet	Mozilla のサプライチェーン監査	依存関係
cargo-outdated	cargo install cargo-outdated	依存関係の最新性	依存関係
cargo-geiger	cargo install cargo-geiger	依存関係内の unsafe コードを検出	依存関係
cargo-machete	cargo install cargo-machete	未使用の依存関係を検出	依存関係

リファクタリングのワークフロー

ast-grep：AST を認識した検索と書き換え

使用する場面：コードベース全体でパターンをリファクタリングする場合。Rust の構文を理解するため、正規表現より安全です。

# Search for .unwrap() calls
ast-grep --pattern '$X.unwrap()' --lang rust

# Replace unwrap with expect
ast-grep --pattern '$X.unwrap()' --rewrite '$X.expect("TODO: handle error")' --lang rust

# Find unsafe blocks
ast-grep --pattern 'unsafe { $$$BODY }' --lang rust

# Convert match to if-let (single-arm + wildcard)
ast-grep --pattern 'match $X { $P => $E, _ => () }' --rewrite 'if let $P = $X { $E }' --lang rust

複雑な複数ルールの変換には、YAML ルールファイルを使用してください。ast-grep のリファレンスを参照してください。

cargo-semver-checks：API 互換性

使用する場面：クレートのバージョンを公開する前。意図しない破壊的変更を検出します。

# Check current changes against last published version
cargo semver-checks check-release

# Check against specific baseline
cargo semver-checks check-release --baseline-version 1.2.0

# Workspace mode
cargo semver-checks check-release --workspace

関数の削除、型の変更、トレイト実装の変更などを対象とする、数百種類の組み込み lint が用意されています（lint の数はリリースごとに増加します）。cargo-semver-checks のリファレンスを参照してください。

パフォーマンスのワークフロー

ステップ 1：samply でプロファイリングする

# Build with debug info (release speed + symbols)
cargo build --release

# Profile (macOS — uses dtrace, needs SIP consideration)
samply record ./target/release/my-binary

# Opens Firefox Profiler UI in browser automatically
# Look for: hot functions, call trees, flame graphs

macOS の dtrace 設定とフレームグラフの読み方については、samply のリファレンスを参照してください。

ステップ 2：cargo-wizard でプロファイルを自動設定する

# Interactive — choose optimization goal
cargo wizard

# Templates:
# 1. "fast-compile" — minimize build time (incremental, low opt)
# 2. "fast-runtime" — maximize performance (LTO, codegen-units=1)
# 3. "min-size"     — minimize binary size (opt-level="z", LTO, strip)

cargo-wizard は Cargo.toml の [profile.*] セクションに直接書き込みます。Cargo チームが推奨しています。cargo-wizard のリファレンスを参照してください。

ステップ 3：cargo-pgo で PGO + BOLT を行う

最大限のパフォーマンスを引き出すための 3 段階のワークフローです。

# Phase 1: Instrument
cargo pgo build

# Phase 2: Collect profiles (run representative workload)
./target/release/my-binary < typical_input.txt

# Phase 3: Optimize with collected profiles
cargo pgo optimize

# Optional Phase 4: BOLT (post-link optimization, Linux only)
cargo pgo bolt optimize

PGO により、CPU バウンドなコードでは通常 10～20％高速化します。cargo-pgo のリファレンスを参照してください。

ベンチマークのワークフロー

divan と Criterion — どちらを使うべきか

観点	divan	Criterion
API スタイル	#[divan::bench] 属性	criterion_group! + criterion_main! マクロ
セットアップ	依存関係を追加 + #[divan::bench]	依存関係を追加 + benches/ ディレクトリ + Cargo.toml [[bench]]
ジェネリックベンチマーク	組み込みの #[divan::bench(types = [...])]	マクロで手動設定
アロケーションのプロファイリング	組み込みの AllocProfiler	外部ツールが必要
レポート	ターミナル（カラー表示）	HTML + Gnuplot グラフ
CI との統合	CodSpeed（ネイティブ対応）	CodSpeed + criterion-compare
メンテナンス	メンテナンス中（更新頻度は crates.io を確認）	活発（criterion-rs 組織）

推奨：新規プロジェクトでは divan（よりシンプルな API）、既存プロジェクトや HTML レポートが必要な場合は Criterion を使います。divan と Criterion のリファレンスを参照してください。

divan クイックスタート

fn main() {
    divan::main();
}

#[divan::bench]
fn my_benchmark(bencher: divan::Bencher) {
    bencher.bench(|| {
        // code to benchmark
    });
}

Criterion クイックスタート

use criterion::{criterion_group, criterion_main, Criterion};

fn my_benchmark(c: &mut Criterion) {
    c.bench_function("name", |b| {
        b.iter(|| {
            // code to benchmark
        });
    });
}

criterion_group!(benches, my_benchmark);
criterion_main!(benches);

テストのワークフロー

cargo-nextest：より高速なテストランナー

# Run all tests (3x faster than cargo test)
cargo nextest run

# Run with specific profile
cargo nextest run --profile ci

# Retry flaky tests
cargo nextest run --retries 2

# JUnit XML output (for CI)
cargo nextest run --profile ci --message-format libtest-json

設定ファイル：.config/nextest.toml。cargo-nextest のリファレンスを参照してください。

cargo-mutants：ミューテーションテスト

# Run mutation testing on entire crate
cargo mutants

# Filter to specific files/functions
cargo mutants --file src/parser.rs
cargo mutants --regex "parse_.*"

# Use nextest as test runner (faster)
cargo mutants -- --test-tool nextest

# Check results
cat mutants.out/missed.txt     # Tests that didn't catch mutations
cat mutants.out/caught.txt     # Tests that caught mutations

結果の分類：caught（良好）、missed（テストが不十分）、timeout、unviable（コンパイルできません）。cargo-mutants のリファレンスを参照してください。

cargo-hack：フィーチャーフラグのテスト

# Test every feature individually
cargo hack test --each-feature

# Test all feature combinations (powerset)
cargo hack test --feature-powerset

# Exclude dev-dependencies (check only)
cargo hack check --feature-powerset --no-dev-deps

# CI: verify no feature combination breaks compilation
cargo hack check --feature-powerset --depth 2

複数のフィーチャーを持つライブラリクレートでは必須です。cargo-hack のリファレンスを参照してください。

SIMD の選択基準

クレート	Stable Rust	型ジェネリック	マルチバージョニング	メンテナンス状況
macerator	はい	はい	はい（stable）	活発
wide	はい	いいえ（具象型）	いいえ	活発
pulp	はい	はい	はい	macerator に引き継がれました
std::simd	Nightly のみ	はい	いいえ	Nightly 専用（追跡 issue：rust-lang/rust#86656）

推奨：Stable Rust で新たに SIMD を使用する場合は macerator を使います。これは pulp のフォークで、型ジェネリックな操作と実行時のマルチバージョニング（SSE4.2 → AVX2 → AVX-512 のディスパッチ）を備えています。macerator のリファレンスを参照してください。

ウォッチリスト：fearless_simd（アーキテクチャのサポートが限定的 — NEON/WASM/SSE4.2 のみ）、std::simd（Nightly 専用 — 安定化の状況は追跡 issue を確認してください）。

PyO3 のアップグレードパス

Rust と Python のバインディングには PyO3 を使用します。PyO3 は 0.22 以降、大きく進化しています。最新バージョンは必ず PyO3 の変更履歴で確認してください。

バージョン	主な変更点
0.22	Bound<'_, T> API を導入（GIL 参照を置き換え）
0.23	GIL 参照の削除が完了、IntoPyObject トレイトを追加
0.24	vectorcall のサポート、パフォーマンスの改善
0.25+	フリースレッド Python（3.13t）のサポート、UniqueGilRef

移行パターンについては、PyO3 のアップグレードガイドを参照してください。

リファレンスドキュメント

• ast-grep-rust.md — AST を考慮したリファクタリングパターン
• cargo-hack.md — フィーチャーフラグのテスト
• cargo-mutants.md — ミューテーションテスト
• cargo-nextest.md — 次世代テストランナー
• cargo-pgo.md — プロファイルに基づく最適化
• cargo-semver-checks.md — API 互換性
• cargo-wizard.md — プロファイルの自動設定
• divan-and-criterion.md — ベンチマークの比較
• macerator-simd.md — 型ジェネリックな SIMD
• pyo3-upgrade-guide.md — PyO3 の移行
• samply-profiling.md — 対話型プロファイリング

リリースパイプライン

4 フェーズのリリースゲートスクリプトを plugins/rust-tools/scripts/rust-release-check.sh で利用できます。すべての品質ゲートを単一の実行可能ファイルにまとめており、あらゆる Rust プロジェクトに合わせて調整できます。

実行方法

# Full pipeline (Phases 1-3)
./plugins/rust-tools/scripts/rust-release-check.sh

# Include nightly-only checks (Phase 4)
./plugins/rust-tools/scripts/rust-release-check.sh --nightly

# Skip test suite (Phases 1-2 only)
./plugins/rust-tools/scripts/rust-release-check.sh --skip-tests

プロジェクトで moon タスクとして使用するには、スクリプトを tasks/ にコピーし、moon.yml に組み込みます。

cp plugins/rust-tools/scripts/rust-release-check.sh tasks/release-check

tasks:
  release-check:
    description: "4-phase Rust release pipeline"
    script: "bash tasks/release-check"

フェーズの概要

フェーズ	名前	ツール	ブロック対象	備考
1	高速ゲート	fmt, clippy, audit, machete, geiger	はい	高速化のため並列実行します
2	詳細ゲート	deny, semver-checks, outdated	混在	outdated は助言のみ（ビルドを失敗させません）
3	テスト	nextest（または cargo test にフォールバック）	はい	--skip-tests でスキップできます
4	Nightly 専用	udeps, hack	はい	--nightly フラグでオプトイン

フェーズ 1 — 高速ゲートでは、バックグラウンドプロセスを使用してすべてのツールを並列実行します。各ツールのインストール状況を最初に確認し、見つからないツールは失敗させずに警告を出してスキップします。

フェーズ 2 — 詳細ゲートは順番に実行されます。cargo deny の実行には deny.toml が必要です。cargo semver-checks はライブラリクレートの場合にのみ実行されます（Cargo.toml の [lib] または src/lib.rs で判定）。cargo outdated は助言のみを行い、レポートを出力しますが、処理をブロックすることはありません。

フェーズ 3 — テストでは速度を優先して cargo nextest run を実行し、nextest がインストールされていない場合は cargo test にフォールバックします。

フェーズ 4 — Nightly 専用では、--nightly フラグと nightly ツールチェーンが必要です。cargo +nightly udeps は実際に未使用の依存関係を検出します。cargo hack check --each-feature は、各フィーチャーフラグが個別にコンパイルできることを確認します。

終了コード

• 0 — ブロック対象のゲートをすべて通過（助言的な警告は問題ありません）
• 1 — ブロック対象のゲートが 1 つ以上失敗

最後に表示される概要には、成功数、失敗数、助言的な警告数が報告されます。

トラブルシューティング

問題	解決策
ast-grep で一致なし	--lang rust フラグを確認してください。パターンはテキストではなく AST ノードに一致する必要があります
samply でアクセス拒否	macOS：sudo samply record を実行するか、dtrace のために SIP を無効にしてください
cargo-pgo で速度向上しない	プロファイリング中のワークロードは、実際の使用状況を代表するものである必要があります
cargo-mutants が遅すぎる	--file または --regex で絞り込み、-- --test-tool nextest を使用してください
divan と criterion の競合	共存できます。Cargo.toml で個別のベンチターゲットを使用してください
macerator のコンパイルエラー	Rust の最小バージョンを確認してください。SIMD ターゲット機能が必要です
cargo-nextest でテストが不足	ドキュメントテストには対応していません。別途 cargo test --doc を使用してください
cargo-hack が powerset で OOM	--depth 2 を使用して組み合わせを制限してください

実行後の振り返り

このスキルの実行が完了したら、タスクを終了する前に振り返ってください。

0. 現在位置を確認します。 — 編集する前に、この SKILL.md の正規パスを見つけてください。
1. 何が失敗しましたか？ — 原因となった指示を修正してください。
2. 期待以上にうまくいったことは何ですか？ — 推奨される実践方法として取り入れてください。
3. 現状とずれている点は何ですか？ — 実態に合わなくなったスクリプト、参照先、依存関係を修正してください。
4. 記録してください。 — きっかけ、修正内容、根拠を含む進化ログのエントリーを追加してください。

先送りしないでください。次回の実行では、あなたが残したものが引き継がれます。