agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/anti-string-for-str.md

@@ -0,0 +1,122 @@
+# anti-string-for-str
+
+> Don't accept &String when &str works
+
+## Why It Matters
+
+`&String` is strictly less flexible than `&str`. A `&str` can be created from `String`, `&str`, literals, and slices. A `&String` requires exactly a `String`. This forces callers to allocate when they might not need to.
+
+## Bad
+
+```rust
+// Forces callers to have a String
+fn greet(name: &String) {
+    println!("Hello, {}", name);
+}
+
+// Caller must allocate
+greet(&"Alice".to_string());  // Unnecessary allocation
+greet(&name);                 // Only works if name is String
+
+// In struct
+struct Config {
+    name: String,
+}
+
+impl Config {
+    fn set_name(&mut self, name: &String) {  // Too restrictive
+        self.name = name.clone();
+    }
+}
+```
+
+## Good
+
+```rust
+// Accept &str - works with String, &str, literals
+fn greet(name: &str) {
+    println!("Hello, {}", name);
+}
+
+// All these work
+greet("Alice");           // String literal
+greet(&name);             // &String coerces to &str
+greet(name.as_str());     // Explicit &str
+
+// In struct
+impl Config {
+    fn set_name(&mut self, name: &str) {
+        self.name = name.to_string();
+    }
+    
+    // Or accept owned String if caller usually has one
+    fn set_name_owned(&mut self, name: String) {
+        self.name = name;
+    }
+    
+    // Or be generic
+    fn set_name_into(&mut self, name: impl Into<String>) {
+        self.name = name.into();
+    }
+}
+```
+
+## Deref Coercion
+
+`String` implements `Deref<Target = str>`, so `&String` automatically coerces to `&str`:
+
+```rust
+fn takes_str(s: &str) { }
+
+let owned = String::from("hello");
+takes_str(&owned);  // &String -> &str via Deref
+```
+
+## When to Accept &String
+
+Rarely. Maybe if you need `String`-specific methods:
+
+```rust
+fn needs_capacity(s: &String) -> usize {
+    s.capacity()  // Only String has capacity()
+}
+```
+
+But usually you'd take `&str` and let the caller manage the `String`.
+
+## Pattern: Flexible APIs
+
+```rust
+// Most flexible: accept anything that can become &str
+fn process(input: impl AsRef<str>) {
+    let s: &str = input.as_ref();
+    // ...
+}
+
+process("literal");
+process(String::from("owned"));
+process(&some_string);
+```
+
+## Similar Anti-patterns
+
+| Anti-pattern | Better |
+|--------------|--------|
+| `&String` | `&str` |
+| `&Vec<T>` | `&[T]` |
+| `&Box<T>` | `&T` |
+| `&PathBuf` | `&Path` |
+| `&OsString` | `&OsStr` |
+
+## Clippy Detection
+
+```toml
+[lints.clippy]
+ptr_arg = "warn"  # Catches &String, &Vec, &PathBuf
+```
+
+## See Also
+
+- [anti-vec-for-slice](./anti-vec-for-slice.md) - Similar pattern for Vec
+- [own-slice-over-vec](./own-slice-over-vec.md) - Slice patterns
+- [api-impl-asref](./api-impl-asref.md) - AsRef pattern

package/template/agent/skills/rust-developer/references/rust-rules/anti-stringly-typed.md

@@ -0,0 +1,167 @@
+# anti-stringly-typed
+
+> Don't use strings where enums or newtypes would provide type safety
+
+## Why It Matters
+
+Strings are the most primitive way to represent data—they accept any value, provide no validation, and offer no IDE support. When you have a fixed set of valid values or a semantic type, use enums or newtypes. The compiler catches mistakes at compile time instead of runtime.
+
+## Bad
+
+```rust
+fn process_order(status: &str, priority: &str) {
+    // What are valid statuses? "pending"? "Pending"? "PENDING"?
+    // What are valid priorities? "high"? "1"? "urgent"?
+    match status {
+        "pending" => { ... }
+        "completed" => { ... }
+        _ => panic!("unknown status"),  // Runtime error
+    }
+}
+
+struct User {
+    email: String,    // Any string, even "not an email"
+    phone: String,    // Any string, even "hello"
+    user_id: String,  // Could be confused with other string IDs
+}
+
+// Easy to make mistakes
+process_order("complete", "high");  // Typo: "complete" vs "completed"
+process_order("high", "pending");   // Swapped arguments - compiles!
+```
+
+## Good
+
+```rust
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum OrderStatus {
+    Pending,
+    Processing,
+    Completed,
+    Cancelled,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+enum Priority {
+    Low,
+    Medium,
+    High,
+    Critical,
+}
+
+fn process_order(status: OrderStatus, priority: Priority) {
+    match status {
+        OrderStatus::Pending => { ... }
+        OrderStatus::Processing => { ... }
+        OrderStatus::Completed => { ... }
+        OrderStatus::Cancelled => { ... }
+    }  // Exhaustive - compiler checks all cases
+}
+
+// Validated newtypes
+struct Email(String);
+struct PhoneNumber(String);
+struct UserId(u64);
+
+impl Email {
+    pub fn new(s: &str) -> Result<Self, ValidationError> {
+        if is_valid_email(s) {
+            Ok(Email(s.to_string()))
+        } else {
+            Err(ValidationError::InvalidEmail)
+        }
+    }
+}
+
+struct User {
+    email: Email,       // Must be valid email
+    phone: PhoneNumber, // Must be valid phone
+    user_id: UserId,    // Can't confuse with other IDs
+}
+
+// Compile errors catch mistakes
+process_order(OrderStatus::Completed, Priority::High);  // Clear and correct
+process_order(Priority::High, OrderStatus::Pending);    // Compile error!
+```
+
+## Parsing Strings to Types
+
+```rust
+use std::str::FromStr;
+
+#[derive(Debug, Clone, Copy)]
+enum OrderStatus {
+    Pending,
+    Processing,
+    Completed,
+    Cancelled,
+}
+
+impl FromStr for OrderStatus {
+    type Err = ParseError;
+    
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_lowercase().as_str() {
+            "pending" => Ok(OrderStatus::Pending),
+            "processing" => Ok(OrderStatus::Processing),
+            "completed" => Ok(OrderStatus::Completed),
+            "cancelled" | "canceled" => Ok(OrderStatus::Cancelled),
+            _ => Err(ParseError::UnknownStatus(s.to_string())),
+        }
+    }
+}
+
+// Parse at boundary, use types internally
+fn handle_request(status_str: &str) -> Result<(), Error> {
+    let status: OrderStatus = status_str.parse()?;  // Validate once
+    process_order(status);  // Type-safe from here
+    Ok(())
+}
+```
+
+## With Serde
+
+```rust
+use serde::{Serialize, Deserialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+enum Status {
+    Pending,
+    InProgress,
+    Completed,
+}
+
+// JSON: {"status": "in_progress"}
+// Deserialization validates automatically
+```
+
+## Error Messages
+
+```rust
+#[derive(Debug, Clone, Copy)]
+enum Color {
+    Red,
+    Green,
+    Blue,
+}
+
+impl std::fmt::Display for Color {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Color::Red => write!(f, "red"),
+            Color::Green => write!(f, "green"),
+            Color::Blue => write!(f, "blue"),
+        }
+    }
+}
+
+// Type-safe and displayable
+println!("Selected color: {}", Color::Red);
+```
+
+## See Also
+
+- [api-newtype-safety](./api-newtype-safety.md) - Newtype pattern
+- [api-parse-dont-validate](./api-parse-dont-validate.md) - Parse at boundaries
+- [type-newtype-ids](./type-newtype-ids.md) - Type-safe IDs

package/template/agent/skills/rust-developer/references/rust-rules/anti-type-erasure.md

@@ -0,0 +1,134 @@
+# anti-type-erasure
+
+> Don't use Box<dyn Trait> when impl Trait works
+
+## Why It Matters
+
+`Box<dyn Trait>` (type erasure) introduces heap allocation and dynamic dispatch overhead. When you have a single concrete type or can use generics, `impl Trait` provides the same flexibility with zero overhead through monomorphization.
+
+## Bad
+
+```rust
+// Unnecessary type erasure
+fn get_iterator() -> Box<dyn Iterator<Item = i32>> {
+    Box::new((0..10).map(|x| x * 2))
+}
+
+// Boxing for no reason
+fn make_handler() -> Box<dyn Fn(i32) -> i32> {
+    Box::new(|x| x + 1)
+}
+
+// Vec of boxed trait objects when one type would do
+fn get_validators() -> Vec<Box<dyn Validator>> {
+    vec![
+        Box::new(LengthValidator),
+        Box::new(RegexValidator),
+    ]
+}
+```
+
+## Good
+
+```rust
+// impl Trait - zero overhead, inlined
+fn get_iterator() -> impl Iterator<Item = i32> {
+    (0..10).map(|x| x * 2)
+}
+
+// impl Fn - no boxing
+fn make_handler() -> impl Fn(i32) -> i32 {
+    |x| x + 1
+}
+
+// When mixed types are genuinely needed, Box is OK
+fn get_validators() -> Vec<Box<dyn Validator>> {
+    // Actually different types at runtime - Box is appropriate
+    config.validators.iter()
+        .map(|v| v.create_validator())
+        .collect()
+}
+```
+
+## When to Use Box<dyn Trait>
+
+Type erasure IS appropriate when:
+
+```rust
+// Heterogeneous collection of different types
+let handlers: Vec<Box<dyn Handler>> = vec![
+    Box::new(LogHandler),
+    Box::new(MetricsHandler),
+    Box::new(AuthHandler),
+];
+
+// Type cannot be known at compile time
+fn create_from_config(config: &Config) -> Box<dyn Database> {
+    match config.db_type {
+        DbType::Postgres => Box::new(PostgresDb::new()),
+        DbType::Sqlite => Box::new(SqliteDb::new()),
+    }
+}
+
+// Recursive types
+struct Node {
+    value: i32,
+    children: Vec<Box<dyn NodeTrait>>,
+}
+
+// Breaking cycles in complex ownership
+struct EventLoop {
+    handlers: Vec<Box<dyn EventHandler>>,
+}
+```
+
+## Comparison
+
+| Approach | Allocation | Dispatch | Binary Size |
+|----------|------------|----------|-------------|
+| `impl Trait` | Stack/inline | Static | Larger (monomorphization) |
+| `Box<dyn Trait>` | Heap | Dynamic | Smaller |
+| Generics `<T>` | Stack/inline | Static | Larger |
+
+## impl Trait Positions
+
+```rust
+// Return position - caller doesn't need to know concrete type
+fn process() -> impl Future<Output = Result> { }
+
+// Argument position - like generics but simpler
+fn handle(handler: impl Handler) { }
+
+// Can't use in trait definitions (use associated types instead)
+trait Processor {
+    type Output: Display;  // Not impl Display
+    fn process(&self) -> Self::Output;
+}
+```
+
+## Pattern: Enum Instead of dyn
+
+```rust
+// Instead of Box<dyn Shape>
+enum Shape {
+    Circle { radius: f64 },
+    Rectangle { width: f64, height: f64 },
+    Triangle { base: f64, height: f64 },
+}
+
+impl Shape {
+    fn area(&self) -> f64 {
+        match self {
+            Shape::Circle { radius } => PI * radius * radius,
+            Shape::Rectangle { width, height } => width * height,
+            Shape::Triangle { base, height } => 0.5 * base * height,
+        }
+    }
+}
+```
+
+## See Also
+
+- [anti-over-abstraction](./anti-over-abstraction.md) - Excessive generics
+- [type-generic-bounds](./type-generic-bounds.md) - Generic constraints
+- [mem-box-large-variant](./mem-box-large-variant.md) - Boxing enum variants

package/template/agent/skills/rust-developer/references/rust-rules/anti-unwrap-abuse.md

@@ -0,0 +1,143 @@
+# anti-unwrap-abuse
+
+> Don't use `.unwrap()` in production code
+
+## Why It Matters
+
+`.unwrap()` panics on `None` or `Err`, crashing your program. In production, this means lost data, failed requests, and unhappy users. It also makes debugging harder since panic messages often lack context.
+
+## Bad
+
+```rust
+// Crashes if file doesn't exist
+let content = std::fs::read_to_string("config.toml").unwrap();
+
+// Crashes on invalid input
+let num: i32 = user_input.parse().unwrap();
+
+// Crashes if key missing
+let value = map.get("key").unwrap();
+
+// Crashes if channel closed
+let msg = receiver.recv().unwrap();
+```
+
+## Good
+
+```rust
+// Propagate with ?
+fn load_config() -> Result<Config, Error> {
+    let content = std::fs::read_to_string("config.toml")?;
+    Ok(toml::from_str(&content)?)
+}
+
+// Provide default
+let num: i32 = user_input.parse().unwrap_or(0);
+
+// Handle missing key
+let value = map.get("key").ok_or(Error::MissingKey)?;
+
+// Or use if-let
+if let Some(value) = map.get("key") {
+    process(value);
+}
+
+// Channel with proper handling
+match receiver.recv() {
+    Ok(msg) => handle(msg),
+    Err(_) => break,  // Channel closed
+}
+```
+
+## When unwrap() Is Acceptable
+
+```rust
+// 1. Tests - panics are expected failures
+#[test]
+fn test_parse() {
+    let result = parse("valid").unwrap();  // OK in tests
+    assert_eq!(result, expected);
+}
+
+// 2. Const/static initialization (compile-time guaranteed)
+static REGEX: Lazy<Regex> = Lazy::new(|| {
+    Regex::new(r"^\d+$").unwrap()  // Known-valid pattern
+});
+
+// 3. After a check that guarantees success
+if map.contains_key("key") {
+    let value = map.get("key").unwrap();  // Just checked
+}
+// Better: use if-let or entry API instead
+
+// 4. Truly impossible cases with proof comment
+let last = vec.pop().unwrap();  
+// OK only if you just checked !vec.is_empty()
+// Better: use last() or pattern match
+```
+
+## Alternatives to unwrap()
+
+```rust
+// unwrap_or - provide default
+let x = opt.unwrap_or(default);
+
+// unwrap_or_default - use Default trait
+let x = opt.unwrap_or_default();
+
+// unwrap_or_else - compute default lazily
+let x = opt.unwrap_or_else(|| expensive_default());
+
+// ? operator - propagate errors
+let x = opt.ok_or(Error::Missing)?;
+
+// if let - handle Some/Ok case
+if let Some(x) = opt {
+    use_x(x);
+}
+
+// match - handle all cases
+match opt {
+    Some(x) => use_x(x),
+    None => handle_none(),
+}
+
+// map - transform if present
+let y = opt.map(|x| x + 1);
+
+// and_then - chain fallible operations
+let z = opt.and_then(|x| x.checked_add(1));
+```
+
+## expect() Is Slightly Better
+
+```rust
+// unwrap() - no context
+let file = File::open(path).unwrap();
+// Panics with: "called `Result::unwrap()` on an `Err` value: Os { code: 2, ... }"
+
+// expect() - adds context
+let file = File::open(path)
+    .expect("config file should exist at startup");
+// Panics with: "config file should exist at startup: Os { code: 2, ... }"
+
+// But still use only for invariants, not error handling
+```
+
+## Clippy Lint
+
+```rust
+// Enable these lints to catch unwrap usage:
+#![warn(clippy::unwrap_used)]
+#![warn(clippy::expect_used)]  // Stricter
+
+// Or per-function:
+#[allow(clippy::unwrap_used)]
+fn tests_only() { }
+```
+
+## See Also
+
+- [err-question-mark](err-question-mark.md) - Use ? for propagation
+- [err-result-over-panic](err-result-over-panic.md) - Return Result instead of panicking
+- [anti-expect-lazy](anti-expect-lazy.md) - Don't use expect for recoverable errors

package/template/agent/skills/rust-developer/references/rust-rules/anti-vec-for-slice.md

@@ -0,0 +1,121 @@
+# anti-vec-for-slice
+
+> Don't accept &Vec<T> when &[T] works
+
+## Why It Matters
+
+`&Vec<T>` is strictly less flexible than `&[T]`. A slice can be created from `Vec`, arrays, and other slice-like types. Accepting `&Vec<T>` forces callers to have exactly a `Vec`, preventing them from using arrays, slices, or other collections.
+
+## Bad
+
+```rust
+// Forces callers to have a Vec
+fn sum(numbers: &Vec<i32>) -> i32 {
+    numbers.iter().sum()
+}
+
+// Caller must allocate
+let arr = [1, 2, 3, 4, 5];
+sum(&arr.to_vec());  // Unnecessary allocation
+
+// Slice won't work
+let slice: &[i32] = &[1, 2, 3];
+// sum(slice);  // Error: expected &Vec<i32>
+```
+
+## Good
+
+```rust
+// Accept slice - works with Vec, arrays, slices
+fn sum(numbers: &[i32]) -> i32 {
+    numbers.iter().sum()
+}
+
+// All these work
+sum(&[1, 2, 3, 4, 5]);        // Array
+sum(&vec![1, 2, 3]);          // Vec
+sum(&numbers[1..3]);          // Slice of slice
+sum(numbers.as_slice());      // Explicit slice
+```
+
+## Deref Coercion
+
+`Vec<T>` implements `Deref<Target = [T]>`, so `&Vec<T>` automatically coerces to `&[T]`:
+
+```rust
+fn takes_slice(s: &[i32]) { }
+
+let vec = vec![1, 2, 3];
+takes_slice(&vec);  // &Vec<i32> -> &[i32] via Deref
+```
+
+## Mutable Slices
+
+Same applies to `&mut`:
+
+```rust
+// Bad
+fn double(numbers: &mut Vec<i32>) {
+    for n in numbers.iter_mut() {
+        *n *= 2;
+    }
+}
+
+// Good
+fn double(numbers: &mut [i32]) {
+    for n in numbers.iter_mut() {
+        *n *= 2;
+    }
+}
+```
+
+## When to Accept &Vec<T>
+
+Rarely. Only when you need Vec-specific operations:
+
+```rust
+fn needs_capacity(v: &Vec<i32>) -> usize {
+    v.capacity()  // Only Vec has capacity
+}
+
+fn might_grow(v: &mut Vec<i32>) {
+    v.push(42);  // Slice can't push
+}
+```
+
+## Pattern: Accepting Multiple Types
+
+```rust
+// Accept anything that can be viewed as a slice
+fn process<T: AsRef<[u8]>>(data: T) {
+    let bytes: &[u8] = data.as_ref();
+    // ...
+}
+
+process(&[1u8, 2, 3]);       // Array
+process(vec![1u8, 2, 3]);    // Vec
+process(&some_vec);          // &Vec
+process(b"bytes");           // Byte string
+```
+
+## Similar Anti-patterns
+
+| Anti-pattern | Better |
+|--------------|--------|
+| `&Vec<T>` | `&[T]` |
+| `&String` | `&str` |
+| `&PathBuf` | `&Path` |
+| `&Box<T>` | `&T` |
+
+## Clippy Detection
+
+```toml
+[lints.clippy]
+ptr_arg = "warn"  # Catches &Vec, &String, &PathBuf
+```
+
+## See Also
+
+- [anti-string-for-str](./anti-string-for-str.md) - Similar for String
+- [own-slice-over-vec](./own-slice-over-vec.md) - Slice patterns
+- [api-impl-asref](./api-impl-asref.md) - AsRef pattern