cargo-perf

Static analysis for async correctness and runtime performance in Rust.

The Problem

These bugs compile fine and ship to production:

// Blocks the async runtime — causes timeouts under load
async fn read_config() -> Config {
    let data = std::fs::read_to_string("config.toml").unwrap();
    toml::from_str(&data).unwrap()
}

// Deadlock — holds lock across yield point
async fn update(mutex: &tokio::sync::Mutex<Data>) {
    let guard = mutex.lock().await;
    some_async_op().await; // guard still held across await
}

// 737x slower — regex compilation in hot loop
for line in lines {
    if Regex::new(r"\d+").unwrap().is_match(line) { ... }
}

cargo-perf catches all of these.

Installation

cargo install cargo-perf

Usage

cargo perf                          # Analyze current directory
cargo perf --strict                 # High-confidence rules only (CI recommended)
cargo perf --strict --fail-on error # Fail CI on issues
cargo perf --format sarif           # For GitHub Code Scanning
cargo perf fix --dry-run            # Preview auto-fixes
cargo perf fix                      # Apply auto-fixes

Rules

Errors (High Confidence)

Warnings (Medium Confidence)

CI Integration

GitHub Action

Use the official GitHub Action for the easiest setup:

# .github/workflows/perf.yml
name: Performance Analysis

on: [push, pull_request]

jobs:
  cargo-perf:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write  # For SARIF upload

    steps:
      - uses: actions/checkout@v4
      - uses: cschuman/cargo-perf@v1
        with:
          path: '.'
          fail-on-error: 'true'
          sarif: 'true'  # Enables GitHub Code Scanning integration

Action Inputs

Manual Setup

# .github/workflows/ci.yml
- name: Performance lint
  run: |
    cargo install cargo-perf
    cargo perf --strict --fail-on error

For a complete workflow with SARIF integration for GitHub Code Scanning, see examples/github-workflow.yml.

Suppressing warnings

// cargo-perf-ignore: clone-in-hot-loop
let owned = data.clone(); // intentional in cold path

Or for a whole function:

#[allow(cargo_perf::clone_in_hot_loop)]
fn cold_path() { ... }

Benchmarks

Real measurements (Apple M1 Pro, 1000 iterations):

See benchmarks/ for methodology.

IDE Integration

cargo-perf includes an LSP server for real-time diagnostics in your editor.

Installation

cargo install cargo-perf --features lsp

VS Code

See editors/vscode/ for the extension.

Neovim

require('lspconfig.configs').cargo_perf = {
  default_config = {
    cmd = { 'cargo-perf', 'lsp' },
    filetypes = { 'rust' },
    root_dir = require('lspconfig.util').root_pattern('Cargo.toml'),
  },
}
require('lspconfig').cargo_perf.setup({})

Other Editors

See editors/README.md for Emacs, Helix, Zed, and generic LSP setup.

Custom Rules (Plugin System)

Extend cargo-perf with your own rules:

use cargo_perf::plugin::{PluginRegistry, analyze_with_plugins};
use cargo_perf::rules::{Rule, Diagnostic, Severity};

struct MyCustomRule;

impl Rule for MyCustomRule {
    fn id(&self) -> &'static str { "my-rule" }
    fn name(&self) -> &'static str { "My Rule" }
    fn description(&self) -> &'static str { "Detects my anti-pattern" }
    fn default_severity(&self) -> Severity { Severity::Warning }

    fn check(&self, ctx: &AnalysisContext) -> Vec<Diagnostic> {
        // Your detection logic
        Vec::new()
    }
}

let mut registry = PluginRegistry::new();
registry.add_rule(Box::new(MyCustomRule));
let diagnostics = analyze_with_plugins(path, &config, &registry)?;

See examples/custom_rule.rs for a complete example.

License

MIT OR Apache-2.0