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

ast-grep

cargo install ast-grep

cargo-semver-checks

cargo install cargo-semver-checks

samply

cargo install samply

cargo-pgo

cargo install cargo-pgo

cargo-wizard

cargo install cargo-wizard

divan

divan = "<version>"

#[divan::bench]

criterion

criterion = "<version>"

cargo-nextest

cargo install cargo-nextest

cargo-mutants

cargo install cargo-mutants

cargo-hack

cargo install cargo-hack

macerator

macerator = "<version>"

cargo-audit

cargo install cargo-audit

cargo-deny

cargo install cargo-deny

cargo-vet

cargo install cargo-vet

cargo-outdated

cargo install cargo-outdated

cargo-geiger

cargo install cargo-geiger

cargo-machete

cargo install cargo-machete

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.*]

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

#[divan::bench]

criterion_group!

criterion_main!

#[divan::bench]

benches/

Cargo.toml

[[bench]]

#[divan::bench(types = [...])]

AllocProfiler

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

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

wide

pulp

std::simd

Recommendation: macerator for new SIMD work on stable Rust. It's a fork of

pulp

Watch list:

fearless_simd

std::simd

PyO3 Upgrade Path

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

Bound<'_, T>

IntoPyObject

vectorcall

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

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

--skip-tests

--nightly

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

deny.toml

cargo semver-checks

[lib]

src/lib.rs

cargo outdated

Phase 3 -- Tests prefers

cargo nextest run

cargo test

Phase 4 -- Nightly-Only requires the

--nightly

cargo +nightly udeps

cargo hack check --each-feature

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

ast-grep

--lang rust

samply

sudo samply record

cargo-pgo

cargo-mutants

--file

--regex

-- --test-tool nextest

divan

criterion

Cargo.toml

macerator

cargo-nextest

cargo test --doc

cargo-hack

--depth 2

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.