Cursor rule

1---
2paths:
3  - "**/*.rs"
4---
5# Rust Coding Style
6 
7> This file extends [common/coding-style.md](../common/coding-style.md) with Rust-specific content.
8 
9## Formatting
10 
11- **rustfmt** for enforcement — always run `cargo fmt` before committing
12- **clippy** for lints — `cargo clippy -- -D warnings` (treat warnings as errors)
13- 4-space indent (rustfmt default)
14- Max line width: 100 characters (rustfmt default)
15 
16## Immutability
17 
18Rust variables are immutable by default — embrace this:
19 
20- Use `let` by default; only use `let mut` when mutation is required
21- Prefer returning new values over mutating in place
22- Use `Cow<'_, T>` when a function may or may not need to allocate
23 
24```rust
25use std::borrow::Cow;
26 
27// GOOD — immutable by default, new value returned
28fn normalize(input: &str) -> Cow<'_, str> {
29    if input.contains(' ') {
30        Cow::Owned(input.replace(' ', "_"))
31    } else {
32        Cow::Borrowed(input)
33    }
34}
35 
36// BAD — unnecessary mutation
37fn normalize_bad(input: &mut String) {
38    *input = input.replace(' ', "_");
39}
40```
41 
42## Naming
43 
44Follow standard Rust conventions:
45- `snake_case` for functions, methods, variables, modules, crates
46- `PascalCase` (UpperCamelCase) for types, traits, enums, type parameters
47- `SCREAMING_SNAKE_CASE` for constants and statics
48- Lifetimes: short lowercase (`'a`, `'de`) — descriptive names for complex cases (`'input`)
49 
50## Ownership and Borrowing
51 
52- Borrow (`&T`) by default; take ownership only when you need to store or consume
53- Never clone to satisfy the borrow checker without understanding the root cause
54- Accept `&str` over `String`, `&[T]` over `Vec<T>` in function parameters
55- Use `impl Into<String>` for constructors that need to own a `String`
56 
57```rust
58// GOOD — borrows when ownership isn't needed
59fn word_count(text: &str) -> usize {
60    text.split_whitespace().count()
61}
62 
63// GOOD — takes ownership in constructor via Into
64fn new(name: impl Into<String>) -> Self {
65    Self { name: name.into() }
66}
67 
68// BAD — takes String when &str suffices
69fn word_count_bad(text: String) -> usize {
70    text.split_whitespace().count()
71}
72```
73 
74## Error Handling
75 
76- Use `Result<T, E>` and `?` for propagation — never `unwrap()` in production code
77- **Libraries**: define typed errors with `thiserror`
78- **Applications**: use `anyhow` for flexible error context
79- Add context with `.with_context(|| format!("failed to ..."))?`
80- Reserve `unwrap()` / `expect()` for tests and truly unreachable states
81 
82```rust
83// GOOD — library error with thiserror
84#[derive(Debug, thiserror::Error)]
85pub enum ConfigError {
86    #[error("failed to read config: {0}")]
87    Io(#[from] std::io::Error),
88    #[error("invalid config format: {0}")]
89    Parse(String),
90}
91 
92// GOOD — application error with anyhow
93use anyhow::Context;
94 
95fn load_config(path: &str) -> anyhow::Result<Config> {
96    let content = std::fs::read_to_string(path)
97        .with_context(|| format!("failed to read {path}"))?;
98    toml::from_str(&content)
99        .with_context(|| format!("failed to parse {path}"))
100}
101```
102 
103## Iterators Over Loops
104 
105Prefer iterator chains for transformations; use loops for complex control flow:
106 
107```rust
108// GOOD — declarative and composable
109let active_emails: Vec<&str> = users.iter()
110    .filter(|u| u.is_active)
111    .map(|u| u.email.as_str())
112    .collect();
113 
114// GOOD — loop for complex logic with early returns
115for user in &users {
116    if let Some(verified) = verify_email(&user.email)? {
117        send_welcome(&verified)?;
118    }
119}
120```
121 
122## Module Organization
123 
124Organize by domain, not by type:
125 
126```text
127src/
128├── main.rs
129├── lib.rs
130├── auth/           # Domain module
131│   ├── mod.rs
132│   ├── token.rs
133│   └── middleware.rs
134├── orders/         # Domain module
135│   ├── mod.rs
136│   ├── model.rs
137│   └── service.rs
138└── db/             # Infrastructure
139    ├── mod.rs
140    └── pool.rs
141```
142 
143## Visibility
144 
145- Default to private; use `pub(crate)` for internal sharing
146- Only mark `pub` what is part of the crate's public API
147- Re-export public API from `lib.rs`
148 
149## References
150 
151See skill: `rust-patterns` for comprehensive Rust idioms and patterns.
152