rust-sota-arsenal

What this skill does

# 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):

   ```bash
   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.

```bash
# 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](./references/ast-grep-rust.md).

### cargo-semver-checks: API Compatibility

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

```bash
# 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](./references/cargo-semver-checks.md).

## Performance Workflow

### Step 1: Profile with samply

```bash
# 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](./references/samply-profiling.md) for macOS dtrace setup and flame graph interpretation.

### Step 2: Auto-configure profiles with cargo-wizard

```bash
# 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](./references/cargo-wizard.md).

### Step 3: PGO + BOLT with cargo-pgo

Three-phase workflow for maximum performance:

```bash
# 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](./references/cargo-pgo.md).

## 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]`