Skills
skills/terrylica/cc-skills/rust-sota-arsenal

rust-sota-arsenal

SKILL.md

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.

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://172.25.236.1: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 ZeroTier 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

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
Weekly Installs
11
Repository
terrylica/cc-skills
GitHub Stars
19
First Seen
11 days ago
Security Audits
Gen Agent Trust HubPass
SocketFail
SnykWarn
Installed on
opencode11
gemini-cli11
claude-code11
github-copilot11
codex11
kimi-cli11