agy-superpowers 5.2.2 → 5.2.4

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

@@ -1,167 +0,0 @@
-# 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

@@ -1,134 +0,0 @@
-# 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

@@ -1,143 +0,0 @@
-# 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

@@ -1,121 +0,0 @@
-# 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

package/template/agent/skills/rust-developer/references/rust-rules/api-builder-must-use.md

@@ -1,143 +0,0 @@
-# api-builder-must-use
-
-> Mark builder methods with `#[must_use]` to prevent silent drops
-
-## Why It Matters
-
-Builder pattern methods return a modified builder. Without `#[must_use]`, calling a builder method and ignoring the return value silently does nothing—the builder is dropped, and the configuration is lost. This creates confusing bugs where code appears correct but has no effect.
-
-## Bad
-
-```rust
-struct RequestBuilder {
-    url: String,
-    timeout: Option<Duration>,
-    headers: Vec<(String, String)>,
-}
-
-impl RequestBuilder {
-    fn timeout(mut self, duration: Duration) -> Self {
-        self.timeout = Some(duration);
-        self
-    }
-    
-    fn header(mut self, key: &str, value: &str) -> Self {
-        self.headers.push((key.to_string(), value.to_string()));
-        self
-    }
-}
-
-// Bug: builder methods are ignored - no warning!
-let request = RequestBuilder::new("https://api.example.com");
-request.timeout(Duration::from_secs(30));  // Dropped silently!
-request.header("Authorization", "Bearer token");  // Dropped silently!
-let response = request.send();  // Sends with no timeout or headers
-```
-
-## Good
-
-```rust
-struct RequestBuilder {
-    url: String,
-    timeout: Option<Duration>,
-    headers: Vec<(String, String)>,
-}
-
-impl RequestBuilder {
-    #[must_use = "builder methods return modified builder - chain or assign"]
-    fn timeout(mut self, duration: Duration) -> Self {
-        self.timeout = Some(duration);
-        self
-    }
-    
-    #[must_use = "builder methods return modified builder - chain or assign"]
-    fn header(mut self, key: &str, value: &str) -> Self {
-        self.headers.push((key.to_string(), value.to_string()));
-        self
-    }
-}
-
-// Now warns: unused return value that must be used
-let request = RequestBuilder::new("https://api.example.com");
-request.timeout(Duration::from_secs(30));  // Warning!
-
-// Correct: chain methods
-let response = RequestBuilder::new("https://api.example.com")
-    .timeout(Duration::from_secs(30))
-    .header("Authorization", "Bearer token")
-    .send();
-```
-
-## Apply to Entire Type
-
-```rust
-#[must_use = "builders do nothing unless consumed"]
-struct ConfigBuilder {
-    log_level: Level,
-    max_connections: usize,
-}
-
-// Now all methods returning Self warn if ignored
-impl ConfigBuilder {
-    fn log_level(mut self, level: Level) -> Self {
-        self.log_level = level;
-        self
-    }
-    
-    fn max_connections(mut self, n: usize) -> Self {
-        self.max_connections = n;
-        self
-    }
-    
-    fn build(self) -> Config {
-        Config {
-            log_level: self.log_level,
-            max_connections: self.max_connections,
-        }
-    }
-}
-```
-
-## Message Guidelines
-
-```rust
-// Descriptive message helps users understand
-#[must_use = "builder methods return modified builder"]
-fn with_foo(self, foo: Foo) -> Self { ... }
-
-#[must_use = "this creates a new String and does not modify the original"]
-fn to_uppercase(&self) -> String { ... }
-
-#[must_use = "iterator adaptors are lazy - use .collect() to consume"]
-fn map<F>(self, f: F) -> Map<Self, F> { ... }
-```
-
-## Clippy Lint
-
-```toml
-[lints.clippy]
-must_use_candidate = "warn"  # Suggests where #[must_use] would help
-return_self_not_must_use = "warn"  # Specifically for -> Self methods
-```
-
-## Standard Library Examples
-
-```rust
-// std::Option - must_use on map, and, or
-let x: Option<i32> = Some(5);
-x.map(|v| v * 2);  // Warning: unused return value
-
-// std::Result - must_use on the type itself
-#[must_use = "this `Result` may be an `Err` variant, which should be handled"]
-pub enum Result<T, E> { ... }
-
-// Iterator adaptors
-let v = vec![1, 2, 3];
-v.iter().map(|x| x * 2);  // Warning: iterators are lazy
-```
-
-## See Also
-
-- [api-builder-pattern](./api-builder-pattern.md) - Builder pattern best practices
-- [api-must-use](./api-must-use.md) - General must_use guidelines
-- [err-result-over-panic](./err-result-over-panic.md) - Result types are must_use