rust-sota-arsenal

Rust SOTA Arsenal

State-of-the-art Rust tooling knowledge for refactoring, profiling, benchmarking, testing, and SIMD optimization — tools that LLMs often lack deep training data on.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

CRITICAL: Web-Verify Before Acting

The reference docs in this skill are a starting point, not ground truth. Tool versions, compatibility matrices, and API surfaces evolve faster than static docs. Before recommending specific versions or making upgrade decisions:

1. Check crates.io for latest versions: WebFetch the crates.io API to get current version info

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

2. Check dependency compatibility: When upgrading (e.g., PyO3), verify downstream crate compatibility

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

3. Search for breaking changes: WebSearch for changelogs and migration guides

   WebSearch: "{crate_name} latest version changelog migration"
   

4. Fallback: Firecrawl scrape (if WebFetch fails or returns incomplete data — e.g., JS-heavy pages, rate limits):

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

   Requires Tailscale connectivity. See /devops-tools:firecrawl-research-patterns for full API reference.

Why: The opendeviationbar-py session discovered PyO3 was at 0.28.2 (not 0.28) and pyo3-arrow at 0.17.0 only by web-searching — static docs would have led to wrong upgrade decisions.

When to Use

• Refactoring Rust code (AST-aware search/replace, API compatibility)
• Performance work (profiling, PGO, Cargo profile tuning)
• Benchmarking (choosing divan vs Criterion, setting up benchmarks)
• Testing (faster test runner, mutation testing, feature flag testing)
• SIMD optimization (portable SIMD on stable Rust)
• Migrating PyO3 bindings (0.22+)

Quick Reference

Tool	Install	One-liner	Category
ast-grep	cargo install ast-grep	AST-aware search/rewrite for Rust	Refactoring
cargo-semver-checks	cargo install cargo-semver-checks	API compat linting (hundreds of lints)	Refactoring
samply	cargo install samply	Profile → Firefox Profiler UI	Performance
cargo-pgo	cargo install cargo-pgo	PGO + BOLT optimization	Performance
cargo-wizard	cargo install cargo-wizard	Auto-configure Cargo profiles	Performance
divan	divan = "<version>" in dev-deps	#[divan::bench] attribute API	Benchmarking
criterion	criterion = "<version>" in dev-deps	Statistics-driven, Gnuplot reports	Benchmarking
cargo-nextest	cargo install cargo-nextest	3x faster, process-per-test	Testing
cargo-mutants	cargo install cargo-mutants	Mutation testing (missed/caught)	Testing
cargo-hack	cargo install cargo-hack	Feature powerset testing	Testing
macerator	macerator = "<version>" in deps	Type-generic SIMD + multiversioning	SIMD
cargo-audit	cargo install cargo-audit	RUSTSEC vulnerability scan	Dependencies
cargo-deny	cargo install cargo-deny	License + advisory + ban	Dependencies
cargo-vet	cargo install cargo-vet	Mozilla supply chain audit	Dependencies
cargo-outdated	cargo install cargo-outdated	Dependency freshness	Dependencies
cargo-geiger	cargo install cargo-geiger	Detect unsafe code in deps	Dependencies
cargo-machete	cargo install cargo-machete	Find unused dependencies	Dependencies

Refactoring Workflow

ast-grep: AST-Aware Search and Rewrite

When to use: Refactoring patterns across a codebase — safer than regex because it understands Rust syntax.

# 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

For complex multi-rule transforms, use YAML rule files. See ast-grep reference.

cargo-semver-checks: API Compatibility

When to use: Before publishing a crate version — catches accidental breaking changes.

# 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

Hundreds of built-in lints covering function removal, type changes, trait impl changes, and more (lint count grows with each release). See cargo-semver-checks reference.

Performance Workflow

Step 1: Profile with 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

See samply reference for macOS dtrace setup and flame graph interpretation.

Step 2: Auto-configure profiles with 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 writes directly to Cargo.toml [profile.*] sections. Endorsed by the Cargo team. See cargo-wizard reference.

Step 3: PGO + BOLT with cargo-pgo

Three-phase workflow for maximum performance:

# 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 typically gives 10-20% speedup on CPU-bound code. See cargo-pgo reference.

Benchmarking Workflow

divan vs Criterion — When to Use Which

Aspect	divan	Criterion
API style	#[divan::bench] attribute	criterion_group! + criterion_main! macros
Setup	Add dep + #[divan::bench]	Add dep + benches/ dir + Cargo.toml [[bench]]
Generic benchmarks	Built-in #[divan::bench(types = [...])]	Manual with macros
Allocation profiling	Built-in AllocProfiler	Needs external tools
Reports	Terminal (colored)	HTML + Gnuplot graphs
CI integration	CodSpeed (native)	CodSpeed + criterion-compare
Maintenance	Maintained (check crates.io for cadence)	Active (criterion-rs organization)

Recommendation: divan for new projects (simpler API); Criterion for existing projects or when HTML reports needed. See divan-and-criterion reference.

divan Quick Start

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

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

Criterion Quick Start

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);

Testing Workflow

cargo-nextest: Faster Test Runner

# 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 file: .config/nextest.toml. See cargo-nextest reference.

cargo-mutants: Mutation Testing

# 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

Result categories: caught (good), missed (weak test), timeout, unviable (won't compile). See cargo-mutants reference.

cargo-hack: Feature Flag Testing

# 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

Essential for library crates with multiple features. See cargo-hack reference.

SIMD Decision Matrix

Crate	Stable Rust	Type-Generic	Multiversioning	Maintained
macerator	Yes	Yes	Yes (stable)	Active
wide	Yes	No (concrete types)	No	Active
pulp	Yes	Yes	Yes	Superseded by macerator
std::simd	Nightly only	Yes	No	Nightly-only (tracking issue: rust-lang/rust#86656)

Recommendation: macerator for new SIMD work on stable Rust. It's a fork of pulp with type-generic operations and runtime multiversioning (SSE4.2 → AVX2 → AVX-512 dispatch). See macerator reference.

Watch list: fearless_simd (limited arch support — only NEON/WASM/SSE4.2), std::simd (nightly-only — check tracking issue for stabilization status).

PyO3 Upgrade Path

For Rust↔Python bindings, PyO3 has evolved significantly since 0.22. Always check the PyO3 changelog for the latest version:

Version	Key Change
0.22	Bound<'_, T> API introduced (replaces GIL refs)
0.23	GIL ref removal complete, IntoPyObject trait
0.24	vectorcall support, performance improvements
0.25+	Free-threaded Python (3.13t) support, UniqueGilRef

See PyO3 upgrade guide for migration patterns.

Reference Documents

• ast-grep-rust.md — AST-aware refactoring patterns
• cargo-hack.md — Feature flag testing
• cargo-mutants.md — Mutation testing
• cargo-nextest.md — Next-gen test runner
• cargo-pgo.md — Profile-Guided Optimization
• cargo-semver-checks.md — API compatibility
• cargo-wizard.md — Profile auto-configuration
• divan-and-criterion.md — Benchmarking comparison
• macerator-simd.md — Type-generic SIMD
• pyo3-upgrade-guide.md — PyO3 migration
• samply-profiling.md — Interactive profiling

Release Pipeline

A 4-phase release gate script is available at plugins/rust-tools/scripts/rust-release-check.sh. It consolidates all quality gates into a single executable that can be adapted to any Rust project.

Running

# 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

To use as a mise task in your project, copy the script and add to .mise/tasks/:

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

Phase Overview

Phase	Name	Tools	Blocking	Notes
1	Fast Gates	fmt, clippy, audit, machete, geiger	Yes	Runs in parallel for speed
2	Deep Gates	deny, semver-checks, outdated	Mixed	outdated is advisory-only (never fails build)
3	Tests	nextest (or cargo test fallback)	Yes	Skippable with --skip-tests
4	Nightly-Only	udeps, hack	Yes	Opt-in via --nightly flag

Phase 1 -- Fast Gates runs all tools in parallel using background processes. Each tool is checked for installation first; missing tools are skipped with a warning rather than failing.

Phase 2 -- Deep Gates runs sequentially. cargo deny requires a deny.toml to be present. cargo semver-checks only runs for library crates (detected via [lib] in Cargo.toml or src/lib.rs). cargo outdated is advisory -- it reports but never blocks.

Phase 3 -- Tests prefers cargo nextest run for speed but falls back to cargo test if nextest is not installed.

Phase 4 -- Nightly-Only requires the --nightly flag and a nightly toolchain. cargo +nightly udeps finds truly unused dependencies. cargo hack check --each-feature verifies every feature flag compiles independently.

Exit Codes

• 0 -- All blocking gates passed (advisory warnings are OK)
• 1 -- One or more blocking gates failed

The summary at the end reports total passes, failures, and advisory warnings.

Troubleshooting

Problem	Solution
ast-grep no matches	Check --lang rust flag; patterns must match AST nodes, not text
samply permission denied	macOS: sudo samply record or disable SIP for dtrace
cargo-pgo no speedup	Workload during profiling must be representative of real usage
cargo-mutants too slow	Filter with --file or --regex; use -- --test-tool nextest
divan vs criterion conflict	They can coexist — use separate bench targets in Cargo.toml
macerator compile errors	Check minimum Rust version; requires SIMD target features
cargo-nextest missing tests	Doc-tests not supported; use cargo test --doc separately
cargo-hack OOM on powerset	Use --depth 2 to limit combinations

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path before editing.
1. What failed? — Fix the instruction that caused it.
2. What worked better than expected? — Promote to recommended practice.
3. What drifted? — Fix any script, reference, or dependency that no longer matches reality.
4. Log it. — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.