rust

---
name: rust
description: "Rust idioms for this repo: async/tokio, anyhow error handling, serde, clippy discipline, and cargo conventions."
user-invocable: false
allowed-tools:
  - Bash(cargo *)
---

# Rust Project Guide

This repo is written in Rust. Apply these conventions.

## Error Handling

- Use `anyhow::Result` for fallible functions that cross module boundaries.
- Use `anyhow::bail!("message")` to return early with a string error.
- Use `.with_context(|| format!("while doing {}", detail))` to annotate error sites.
- No `unwrap()` or `expect()` in non-test code — every panic site is a bug.
- `?` propagates errors; use it consistently rather than `match` on `Err`.

## Async

- Runtime is `tokio`; use `#[tokio::main]` for the entry point.
- Prefer `tokio::fs` over `std::fs` in async contexts.
- Avoid `.await` inside iterators — collect futures into `Vec` and `join_all`.
- `Arc<Mutex<T>>` for shared state; prefer message passing (`mpsc`) when possible.

## Serde

- Derive `Deserialize`, `Serialize` for all config and model types.
- Use `#[serde(default)]` on optional collection fields so missing keys deserialize to empty vec/map.
- Use `#[serde(rename_all = "snake_case")]` for JSON consistency.
- Tag enums with `#[serde(tag = "type")]` for readable JSON output.

## Cargo

- Always specify `edition = "2021"` in `Cargo.toml`.
- Feature flags for optional heavy dependencies (e.g., ML libraries) — keep the default build lean.
- Run `cargo clippy --no-default-features -- -D warnings` in CI.
- Pin workspace dependencies via `[workspace.dependencies]` to avoid version skew.

## Testing

- Unit tests go in the same file as the code under `#[cfg(test)]`.
- Integration tests in `tests/` — they compile as separate crates.
- Use `cargo test -q` for a compact summary; `--nocapture` when debugging output.
- Mock external I/O at the trait boundary, not deep inside implementations.