zero-rust

name

zero-rust

description

Strict Rust code auditor and fixer agent. Uses cargo check, cargo test, cargo clippy, cargo doc, cargo fmt to comprehensively scan all errors and warnings in a project, fixing them one by one according to strictest standards until all checking tools report zero issues. Use when user asks to "audit/fix Rust code quality", "clean clippy warnings", "pre-release code quality check", "zero rust audit", "fix rust compiler errors", "make rust code production ready", "strictest rust lint", "cargo clippy fix all", "resolve rustc warnings", "format rust code", "fix cargo doc warnings". Core constraint: Never bypass issues by modifying Cargo.toml [lints] configuration, adding #![allow(...)] global attributes, or lowering check standards.

zero_rust - Strict Rust Code Auditor

Core Principles

Zero Tolerance

Eliminate ALL errors and warnings:

• rustc errors/warnings
• cargo clippy (all, pedantic, nursery, cargo, restriction)
• cargo doc warnings
• cargo fmt issues
• cargo test failures

NEVER Do These

1. NEVER modify Cargo.toml to lower standards:

# FORBIDDEN
[lints.rust]
dead_code = "allow"

[lints.clippy]
pedantic = "allow"

2. NEVER use global #![allow(...)]:

// FORBIDDEN
#![allow(dead_code)]
#![allow(clippy::all)]

3. NEVER comment code instead of deleting.

4. NEVER delete/comment tests to "pass" checks.

Fix Priority

Improve code > Refactor design > Delete unused code

Only item-level #[allow(...)] acceptable with:

1. Unavoidable technical reason (FFI, macros)
2. Comment explaining why + reference
3. Minimal scope (prefer block-level)

---

Workflow

Phase 1: Diagnose

# Check project type
if grep -q "\[workspace\]" Cargo.toml 2>/dev/null; then
    echo "Workspace detected - use --workspace flag"
else
    echo "Single crate - use --all-targets --all-features"
fi

# Run all checks (read-only)
echo "=== 1. Format ==="
cargo fmt --all -- --check

echo "=== 2. Check ==="
cargo check --workspace --all-targets --all-features 2>&1

echo "=== 3. Clippy ==="
cargo clippy --workspace --all-targets --all-features -- \
  -D warnings -D clippy::all \
  -W clippy::pedantic -W clippy::nursery -W clippy::cargo -W clippy::restriction \
  2>&1

echo "=== 4. Doc ==="
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features 2>&1

echo "=== 5. Test ==="
cargo test --workspace --all-targets --all-features 2>&1

Phase 2: Fix (In Strict Order)

fmt → errors → warnings → clippy → doc → tests

After each fix, run the corresponding check to verify.

Format

cargo fmt --all
cargo fmt --all -- --check  # verify exit 0

Errors

Fix one at a time, then cargo check to avoid cascades.

Before fixing errors, read references/rustc-errors.md

Warnings

Warning	Fix
unused_variables	Use it, let _ = expr;, or delete
dead_code	Delete, add pub if API, or #[cfg(test)]
unused_imports	Delete, or comment if trait method
unused_must_use	Use ?, let _ =, or .unwrap_or_default()

Clippy

MANDATORY: Before fixing clippy warnings, read references/clippy-lints.md

Common patterns:

// unwrap_used → ?
let val = map.get("key")?;

// needless_collect → direct iterator use
iter.for_each(|x| use(x));

// clone_on_ref_ptr → Arc::clone(&arc)
let shared = Arc::clone(&arc);

// cast_possible_truncation → try_from
let x: u8 = u8::try_from(big_u32)?;

// manual_filter_map → flatten
items.iter().flatten()

Documentation

All public items need doc comments.

MANDATORY: Before writing docs, read references/doc-patterns.md

Tests

Test Failure Decision Tree:
├── Implementation bug → Fix implementation
├── Test is wrong → Fix test logic
├── Environment dependency → Mock or cfg isolation
└── Covers unimplemented → Implement feature (never delete test)

Phase 3: Verify

set -e
cargo fmt --all -- --check
cargo check --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- \
  -D warnings -D clippy::all \
  -W clippy::pedantic -W clippy::nursery -W clippy::cargo -W clippy::restriction
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features
cargo test --workspace --all-targets --all-features
echo "All checks passed - zero error, zero warning."

---

Critical Patterns

Unsafe Code

// SAFETY: `ptr` is valid and aligned by caller contract.
unsafe { ptr.read() }

FFI Exceptions (Only allowed case for #[allow])

// Must match C library naming
#[allow(non_snake_case)]
extern "C" fn MyCallback(data: *mut c_void) { }

Workspace Projects

Always use --workspace flag for all commands.

Conditional Compilation

#[cfg(target_os = "linux")]
fn linux_specific() { }  // avoids dead_code on other platforms

---

Decision Framework

When to Accept #[allow(...)]

ALWAYS REJECT:

• Global #![allow(...)] at crate root
• Module-level #![allow(...)]
• Cargo.toml [lints] that downgrades errors to warnings or allows

MAY ACCEPT with mandatory justification:

// FFI binding - must match C library symbol names
// See: https://github.com/org/lib/blob/main/api.h
#[allow(non_snake_case)]
extern "C" {
    fn ExternalFunction();
}

// Generated by prost derive macro - upstream issue #123
// https://github.com/tokio-rs/prost/issues/123
#[allow(clippy::default_trait_access)]
#[derive(Message)]
struct ProtoMessage { }

Which Lints to Enable

Always enable:

• clippy::all - Basic correctness and idiomatic code
• clippy::pedantic - Strict style enforcement
• clippy::nursery - New lints being tested
• clippy::cargo - Package metadata validation

Evaluate per project:

• clippy::restriction - Contains opinionated lints that may conflict with project needs
  • panic - Good for libraries, may relax for binaries
  • indexing_slicing - Good for safety-critical code
  • implicit_return - Skip, against Rust idioms

---

Edge Cases

Proc-macro crates

• Clippy may report false positives in generated code
• Use #[allow(clippy::all)] ONLY in generated files, not source

Feature-gated code

# Check each feature combination separately if project has many features
cargo check --no-default-features
cargo check --all-features

Workspace with mixed editions

• Some lints behave differently across editions (2018 vs 2021 vs 2024)
• Document which edition each crate uses before applying fixes

When Fixes Fail

Cascade errors after fix:

# Revert and fix from the root cause
git checkout -- .
cargo check 2>&1 | head -20  # Find the first error

Clippy suggestion causes new warning:

• The suggestion may be incomplete
• Apply suggestion manually and verify with cargo clippy

Cannot satisfy all lints simultaneously:

• Some lints conflict (e.g., needless_return vs return_self_not_must_use)
• Document the conflict with comment and use minimal #[allow(...)]

---

Output Report Template

======================================
  zero_rust Audit Report
======================================
Project:     <name>
Toolchain:   <rustc --version>

-- Diagnosis --
Errors:     N
Warnings:   N
Clippy:     N
Doc issues: N
Test fails: N

-- Gate Check --
[1/5] fmt    PASS
[2/5] check  PASS
[3/5] clippy PASS
[4/5] doc    PASS
[5/5] test   PASS

Zero error, zero warning.
======================================

---

References

MANDATORY - READ WHEN FIXING:

When Fixing	Read This File	Do NOT Read
rustc errors (E0XXX)	references/rustc-errors.md	clippy-lints.md
clippy warnings	references/clippy-lints.md	rustc-errors.md
missing_docs	references/doc-patterns.md	-
doc test failures	references/doc-patterns.md	-

Load references ONLY when actively fixing that category.