# Rust Cursor Rules

## Code Style & Formatting
- **Formatter**: Always use `rustfmt` for formatting code.
- **Naming Conventions**:
  - Types (structs, enums, traits): `UpperCamelCase`
  - Variables, functions, methods, modules: `snake_case`
  - Constants, statics: `SCREAMING_SNAKE_CASE`
- **Imports**: Group imports by crate. Use `use crate::module::Item;` for internal items.

## Linting & Quality
- **Clippy**: Address all `clippy` warnings. Prefer idiomatic solutions suggested by clippy.
- **Safety**: Avoid `unsafe` blocks unless absolutely necessary and documented with a `// SAFETY:` comment explaining why it is safe.
- **Unwrap/Expect**: Avoid `.unwrap()` in production code. Use `.expect("msg")` if panic is acceptable, but prefer handling `Result` and `Option` with `match`, `if let`, or `?` operator.

## Idiomatic Rust
- **Ownership**: Prefer borrowing (`&T`) over cloning (`.clone()`) when possible.
- **Iterators**: Use iterator chains (`map`, `filter`, `fold`) over explicit loops for data transformation.
- **Pattern Matching**: Use extensive pattern matching (`match`) for control flow based on enum variants.
- **Types**: Use the Newtype pattern (tuple structs) to enforce type safety for primitives (e.g., `struct Width(u32);`).
- **Traits**: Prefer defining behavior via Traits. Use `impl Trait` or generics with trait bounds for flexible APIs.

## Error Handling
- **Result**: Return `Result<T, E>` for fallible operations.
- **Crates**:
  - Use `thiserror` for library error types.
  - Use `anyhow` for application-level error handling.
- **Propagation**: Use the `?` operator for error propagation.

## Testing
- **Unit Tests**: Place unit tests in the same file as the code in a `mod tests` module annotated with `#[cfg(test)]`.
- **Integration Tests**: Place integration tests in the `tests/` directory.
- **Doc Tests**: specific examples in documentation comments (`///`) are tested automatically.

## Documentation
- **Doc Comments**: Use `///` for function/struct documentation and `//!` for module-level documentation.
- **Examples**: Include usage examples in documentation.

## Snake Game Specifics
- **Game Loop**: Ensure the game loop is decoupled from rendering logic if possible.
- **State Management**: Consider using a `struct GameState` to hold the snake, food, and grid.
- **Coordinates**: Use a `struct Point { x: i32, y: i32 }` or similar for grid positions.