cargo-fa 0.11.1

Overview

cargo-fa is a static analysis tool for framealloc that detects memory intent violations at build time. It catches patterns that compile but violate frame allocation principles — issues that would otherwise only surface as performance problems or subtle bugs at runtime.

What It Catches

Installation

cargo install cargo-fa

Or from source:

git clone https://github.com/YelenaTor/framealloc

cd framealloc/cargo-fa

cargo install --path .

Usage

Basic Checks

# Check specific categories

cargo fa --dirtymem       # Lifetime/escape issues (FA6xx)

cargo fa --async-safety   # Async/await issues (FA7xx)

cargo fa --threading      # Thread safety issues (FA2xx)

cargo fa --budgets        # Budget violations (FA3xx)

cargo fa --architecture   # Tag/module issues (FA8xx)


# Run all checks (optimized order)

cargo fa --all

Filtering

# Treat specific diagnostic as error

cargo fa --all --deny FA701


# Suppress specific diagnostic

cargo fa --all --allow FA602


# Exclude paths (glob pattern)

cargo fa --all --exclude "**/tests/**"


# Stop on first error

cargo fa --all --fail-fast


# Minimum severity threshold

cargo fa --all --min-severity warning

Output Formats

# Human-readable (default)

cargo fa --all


# JSON for programmatic consumption

cargo fa --all --format json


# SARIF for GitHub Actions

cargo fa --all --format sarif


# JUnit XML for test reporters

cargo fa --all --format junit


# Checkstyle XML for Jenkins

cargo fa --all --format checkstyle


# Compact one-line-per-issue

cargo fa --all --format compact

Subcommands

# Explain a diagnostic code in detail

cargo fa explain FA601


# Analyze a single file

cargo fa show src/physics.rs


# List all diagnostic codes

cargo fa list


# Filter by category

cargo fa list --category async


# Generate configuration file

cargo fa init

Diagnostics

Diagnostic Codes

Example Output

error[FA701]: frame allocation in async function
  --> src/network/client.rs:45:12
   |
45 |     let buffer = alloc.frame_box(vec![0u8; 1024]);
   |            ^^^^^^ frame allocation here
   |
   = note: async functions can suspend across frame boundaries
   = help: use `alloc.heap_box()` or `alloc.pool_box()` instead

warning[FA602]: allocation in hot loop
  --> src/physics/collision.rs:128:16
   |
128|         let contact = alloc.pool_alloc::<Contact>();
   |                ^^^^^^ allocation inside loop
   |
   = note: loop may execute many times per frame
   = help: consider pre-allocating with `alloc.frame_vec()`

Getting Detailed Explanations

$ cargo fa explain FA701


━━━ FA701 ━━━


Name: async-frame

Category: Async Safety

Severity: error


Summary

Frame allocation in async function


Description

Async functions can suspend at await points. When they resume, they might

be on a different thread or at a different point in the frame lifecycle...


Example (incorrect)
async fn load_asset(alloc: &SmartAlloc) {
    let buffer = alloc.frame_box(vec![0u8; 1024]);  // FA701

    ...


Example (correct)
async fn load_asset(alloc: &SmartAlloc) {
    let buffer = alloc.heap_box(vec![0u8; 1024]);  // Safe

    ...

CI Integration

GitHub Actions (SARIF)

- name: Run cargo-fa
  run: cargo fa --all --format sarif > results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

Jenkins (Checkstyle)

stage('Static Analysis') {
    sh 'cargo fa --all --format checkstyle > checkstyle.xml'
    recordIssues tools: [checkStyle(pattern: 'checkstyle.xml')]
}

Generic CI

# Exit with error on any issues

cargo fa --all --deny-warnings


# Exit with error only on specific codes

cargo fa --all --deny FA701 --deny FA702

Configuration

Create a .fa.toml in your project root:

cargo fa init

Example configuration:

[global]

enabled = true

exclude = ["target/**", "tests/**"]



[lints.FA601]

level = "warn"



[lints.FA701]

level = "deny"



[tags]

known = ["physics", "rendering", "audio", "network"]



[tags.modules]

"src/physics/**" = "physics"

"src/render/**" = "rendering"

Related

• framealloc — The memory allocation library
• TECHNICAL.md — Architecture documentation

License

Licensed under either of:

• Apache License, Version 2.0
• MIT License

at your option.