Rust

What this skill does

<!-- RUST:START -->
# Rust Project Rules

## Agent Automation Commands

**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).

```bash
# Complete quality check sequence:
cargo fmt --all -- --check           # Format check
cargo clippy --workspace --all-targets --all-features -- -D warnings  # Lint
cargo test --workspace --all-features  # All tests (100% pass)
cargo build --release                # Build verification
cargo llvm-cov --all                 # Coverage (95%+ required)

# Security audit:
cargo audit                          # Vulnerability scan
cargo outdated                       # Check outdated deps
```

## Rust Edition and Toolchain

**CRITICAL**: Always use Rust Edition 2024 with nightly toolchain.

- **Edition**: 2024
- **Toolchain**: nightly 1.85+
- **Update**: Run `rustup update nightly` regularly

### Formatting

- Use `rustfmt` with nightly toolchain
- Configuration in `rustfmt.toml` or `.rustfmt.toml`
- Always format before committing: `cargo +nightly fmt --all`
- CI must check formatting: `cargo +nightly fmt --all -- --check`

### Linting

- Use `clippy` with `-D warnings` (warnings as errors)
- Fix all clippy warnings before committing
- Acceptable exceptions must be documented with `#[allow(clippy::...)]` and justification
- CI must enforce clippy: `cargo clippy --workspace -- -D warnings`

### Testing

- **Location**: Tests in `/tests` directory for integration tests
- **Unit Tests**: In same file as implementation with `#[cfg(test)]`
- **Coverage**: Must meet project threshold (default 95%)
- **Tools**: Use `cargo-nextest` for faster test execution
- **Async**: Use `tokio::test` for async tests with Tokio runtime

Example test structure:
```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_feature() {
        // Test implementation
    }

    #[tokio::test]
    async fn test_async_feature() {
        // Async test implementation
    }
}
```

### Test Categories: S2S and Slow Tests

**CRITICAL**: Tests must be categorized based on execution time and dependencies.

#### Test Time Limits

- **Fast Tests**: Must complete in ≤ 10-20 seconds
- **Slow Tests**: Any test taking > 10-20 seconds must be marked as slow
- **S2S Tests**: Tests requiring active server/database must be isolated and run on-demand

#### S2S (Server-to-Server) Tests

**Tests that require active servers, databases, or external services must be isolated using Cargo features.**

**Implementation**:

1. **Create `s2s` feature in `Cargo.toml`**:
```toml
[features]
default = []
s2s = []  # Enable server-to-server tests
```

2. **Mark S2S tests with feature flag**:
```rust
#[cfg(test)]
mod tests {
    use super::*;

    // Regular fast test (always runs)
    #[test]
    fn test_local_computation() {
        // Fast test, no external dependencies
    }

    // S2S test (only runs with --features s2s)
    #[cfg(feature = "s2s")]
    #[tokio::test]
    async fn test_database_connection() {
        // Requires active database server
        let db = connect_to_database().await?;
        // ... test implementation
    }

    #[cfg(feature = "s2s")]
    #[tokio::test]
    async fn test_api_integration() {
        // Requires active API server
        let client = create_api_client().await?;
        // ... test implementation
    }
}
```

3. **Run tests**:
```bash
# Regular tests (excludes S2S)
cargo test

# Include S2S tests (requires active servers)
cargo test --features s2s

# CI/CD: Run S2S tests only when servers are available
cargo test --features s2s --test-args '--test-threads=1'
```

#### Slow Tests

**Tests that take > 10-20 seconds must be marked and run separately.**

**Implementation**:

1. **Create `slow` feature in `Cargo.toml`**:
```toml
[features]
default = []
slow = []  # Enable slow tests
```

2. **Mark slow tests**:
```rust
#[cfg(test)]
mod tests {
    use super::*;

    // Fast test (always runs)
    #[test]
    fn test_quick_operation() {
        // Completes in < 1 second
    }

    // Slow test (only runs with --features slow)
    #[cfg(feature = "slow")]
    #[test]
    fn test_heavy_computation() {
        // Takes 30+ seconds
        // Heavy processing, large dataset, etc.
    }

    #[cfg(feature = "slow")]
    #[tokio::test]
    async fn test_large_file_processing() {
        // Processes large files, takes > 20 seconds
    }
}
```

3. **Run tests**:
```bash
# Regular tests (excludes slow)
cargo test

# Include slow tests
cargo test --features slow

# Run both S2S and slow tests
cargo test --features s2s,slow
```

#### Best Practices

- ✅ **Always run fast tests** in CI/CD by default
- ✅ **Isolate S2S tests** - never run them in standard test suite
- ✅ **Mark slow tests** - prevent CI/CD timeouts
- ✅ **Document requirements** - specify which servers/services are needed for S2S tests
- ✅ **Use timeouts** - Set appropriate timeouts for S2S tests: `tokio::time::timeout(Duration::from_secs(30), test_fn).await?`
- ❌ **Never mix** fast and slow/S2S tests in same test run
- ❌ **Never require** external services for standard test suite
- ❌ **Never exceed** 10-20 seconds for regular tests

## Async Programming

**CRITICAL**: Follow Tokio best practices for async code.

- **Runtime**: Use Tokio for async runtime
- **Blocking**: Never block in async context - use `spawn_blocking` for CPU-intensive tasks
- **Channels**: Use `tokio::sync::mpsc` or `tokio::sync::broadcast` for async communication
- **Timeouts**: Always set timeouts for network operations: `tokio::time::timeout`

Example:
```rust
use tokio::time::{timeout, Duration};

async fn fetch_data() -> Result<Data, Error> {
    timeout(Duration::from_secs(30), async {
        // Network operation
    }).await?
}
```

## Dependency Management

**CRITICAL**: Always verify latest versions before adding dependencies.

### Before Adding Any Dependency

1. **Check Context7 for latest version**:
   - Use MCP Context7 tool if available
   - Search for the crate documentation
   - Verify the latest stable version
   - Review breaking changes and migration guides

2. **Example Workflow**:
   ```
   Adding tokio → Check crates.io and docs.rs
   Adding serde → Verify latest version with security updates
   Adding axum → Check for breaking changes in latest version
   ```

3. **Document Version Choice**:
   - Note why specific version chosen in `Cargo.toml` comments
   - Document any compatibility constraints
   - Update CHANGELOG.md with new dependencies

### Dependency Guidelines

- ✅ Use latest stable versions
- ✅ Check for security advisories: `cargo audit`
- ✅ Prefer well-maintained crates (active development, good documentation)
- ✅ Minimize dependency count
- ✅ Use workspace dependencies for monorepos
- ❌ Don't use outdated versions without justification
- ❌ Don't add dependencies without checking latest version

## Codespell Configuration

**CRITICAL**: Use codespell to catch typos in code and documentation.

Install: `pip install 'codespell[toml]'`

Configuration in `pyproject.toml`:
```toml
[tool.codespell]
skip = "*.lock,*.json,target,node_modules,.git"
ignore-words-list = "crate,ser,deser"
```

Or run with flags:
```bash
codespell \
  --skip="*.lock,*.json,target,node_modules,.git" \
  --ignore-words-list="crate,ser,deser"
```

## Error Handling

- Use `Result<T, E>` for recoverable errors
- Use `thiserror` for custom error types
- Use `anyhow` for application-level error handling
- Document error conditions in function docs
- Never use `unwrap()` or `expect()` in production code without justification

Example:
```rust
use thiserror::Error;

#[derive(Error, Debug)]
pub enum MyError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
    
    #[error("Invalid input: {0}")]
    InvalidInput(String),
}

pub fn process_data(input: &str) -> Result<Data, MyError> {
    // Implementation
}
```

## Documentation

- **Public APIs**: Must have doc comments (`///`)
- **Examples**: Include examples in doc comments
- **Mo