agy-superpowers 5.1.4 → 5.1.6

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

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

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

@@ -0,0 +1,187 @@
+# api-builder-pattern
+
+> Use Builder pattern for complex construction
+
+## Why It Matters
+
+When a type has many optional parameters or complex initialization, the Builder pattern provides a clear, flexible API. It avoids constructors with many parameters (which are error-prone) and makes the code self-documenting.
+
+## Bad
+
+```rust
+// Constructor with many parameters - hard to read, easy to get wrong
+let client = Client::new(
+    "https://api.example.com",  // Which is which?
+    30,                          // Timeout? Retries?
+    true,                        // What does this mean?
+    None,
+    Some("auth_token"),
+    false,
+);
+
+// Or many Option fields
+struct Client {
+    url: String,
+    timeout: Option<Duration>,
+    retries: Option<u32>,
+    // ... 10 more optional fields
+}
+```
+
+## Good
+
+```rust
+#[derive(Default)]
+#[must_use = "builders do nothing unless you call build()"]
+pub struct ClientBuilder {
+    base_url: Option<String>,
+    timeout: Option<Duration>,
+    max_retries: u32,
+    auth_token: Option<String>,
+}
+
+impl ClientBuilder {
+    pub fn new() -> Self {
+        Self::default()
+    }
+    
+    /// Sets the base URL for all requests.
+    pub fn base_url(mut self, url: impl Into<String>) -> Self {
+        self.base_url = Some(url.into());
+        self
+    }
+    
+    /// Sets the request timeout. Default is 30 seconds.
+    pub fn timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = Some(timeout);
+        self
+    }
+    
+    /// Sets the maximum number of retries. Default is 3.
+    pub fn max_retries(mut self, n: u32) -> Self {
+        self.max_retries = n;
+        self
+    }
+    
+    /// Sets the authentication token.
+    pub fn auth_token(mut self, token: impl Into<String>) -> Self {
+        self.auth_token = Some(token.into());
+        self
+    }
+    
+    /// Builds the client with the configured options.
+    pub fn build(self) -> Result<Client, BuilderError> {
+        let base_url = self.base_url
+            .ok_or(BuilderError::MissingBaseUrl)?;
+        
+        Ok(Client {
+            base_url,
+            timeout: self.timeout.unwrap_or(Duration::from_secs(30)),
+            max_retries: self.max_retries,
+            auth_token: self.auth_token,
+        })
+    }
+}
+
+// Usage - clear and self-documenting
+let client = ClientBuilder::new()
+    .base_url("https://api.example.com")
+    .timeout(Duration::from_secs(10))
+    .max_retries(5)
+    .auth_token("secret")
+    .build()?;
+```
+
+## Builder Variations
+
+```rust
+// 1. Infallible builder (build() returns T, not Result)
+impl WidgetBuilder {
+    pub fn build(self) -> Widget {
+        Widget {
+            color: self.color.unwrap_or(Color::Black),
+            size: self.size.unwrap_or(Size::Medium),
+        }
+    }
+}
+
+// 2. Typestate builder (compile-time required field checking)
+pub struct ClientBuilder<Url> {
+    url: Url,
+    timeout: Option<Duration>,
+}
+
+pub struct NoUrl;
+pub struct HasUrl(String);
+
+impl ClientBuilder<NoUrl> {
+    pub fn new() -> Self {
+        Self { url: NoUrl, timeout: None }
+    }
+    
+    pub fn url(self, url: String) -> ClientBuilder<HasUrl> {
+        ClientBuilder { url: HasUrl(url), timeout: self.timeout }
+    }
+}
+
+impl ClientBuilder<HasUrl> {
+    pub fn build(self) -> Client {
+        // url is guaranteed to be set
+        Client { url: self.url.0, timeout: self.timeout }
+    }
+}
+
+// 3. Consuming vs borrowing (consuming is more common)
+// Consuming (takes self)
+pub fn timeout(mut self, t: Duration) -> Self { ... }
+
+// Borrowing (takes &mut self, allows reuse)
+pub fn timeout(&mut self, t: Duration) -> &mut Self { ... }
+```
+
+## Evidence from reqwest
+
+```rust
+// https://github.com/seanmonstar/reqwest/blob/master/src/async_impl/client.rs
+
+#[must_use]
+pub struct ClientBuilder {
+    config: Config,
+}
+
+impl ClientBuilder {
+    pub fn new() -> ClientBuilder {
+        ClientBuilder {
+            config: Config::default(),
+        }
+    }
+    
+    pub fn timeout(mut self, timeout: Duration) -> ClientBuilder {
+        self.config.timeout = Some(timeout);
+        self
+    }
+    
+    pub fn build(self) -> Result<Client, Error> {
+        // Validation and construction
+    }
+}
+```
+
+## Key Attributes
+
+```rust
+#[derive(Default)]  // Enables MyBuilder::default()
+#[must_use = "builders do nothing unless you call build()"]
+pub struct MyBuilder { ... }
+
+impl MyBuilder {
+    #[must_use]  // Each method should have this
+    pub fn option(mut self, value: T) -> Self { ... }
+}
+```
+
+## See Also
+
+- [api-builder-must-use](api-builder-must-use.md) - Add #[must_use] to builders
+- [api-typestate](api-typestate.md) - Compile-time state machines
+- [api-impl-into](api-impl-into.md) - Accept impl Into for flexibility

package/template/agent/skills/rust-developer/references/rust-rules/api-common-traits.md

@@ -0,0 +1,165 @@
+# api-common-traits
+
+> Implement standard traits (Debug, Clone, PartialEq, etc.) for public types
+
+## Why It Matters
+
+Standard traits make your types interoperable with the Rust ecosystem. `Debug` enables `println!("{:?}")` and error messages. `Clone` allows explicit duplication. `PartialEq` enables `==`. Without these, users can't use your types in common patterns like testing, collections, or debugging.
+
+## Bad
+
+```rust
+// Bare struct - severely limited usability
+pub struct Point {
+    pub x: f64,
+    pub y: f64,
+}
+
+// Can't debug
+println!("{:?}", point);  // Error: Debug not implemented
+
+// Can't compare
+if point1 == point2 { }  // Error: PartialEq not implemented
+
+// Can't use in HashMap
+let mut map: HashMap<Point, Value> = HashMap::new();  // Error: Hash not implemented
+
+// Can't clone
+let copy = point.clone();  // Error: Clone not implemented
+```
+
+## Good
+
+```rust
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Point {
+    pub x: f64,
+    pub y: f64,
+}
+
+// Now everything works
+println!("{:?}", point);
+assert_eq!(point1, point2);
+let copy = point;  // Copy, not just Clone
+
+// For hashable types
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct UserId(u64);
+
+let mut map: HashMap<UserId, User> = HashMap::new();
+```
+
+## Trait Derivation Guide
+
+| Trait | Derive When | Requirements |
+|-------|-------------|--------------|
+| `Debug` | Always for public types | All fields implement Debug |
+| `Clone` | Type can be duplicated | All fields implement Clone |
+| `Copy` | Small, simple types | All fields implement Copy, no Drop |
+| `PartialEq` | Comparison makes sense | All fields implement PartialEq |
+| `Eq` | Total equality | PartialEq, no floating-point fields |
+| `Hash` | Used as HashMap/HashSet key | Eq, consistent with PartialEq |
+| `Default` | Sensible default exists | All fields implement Default |
+| `PartialOrd` | Ordering makes sense | PartialEq, all fields implement PartialOrd |
+| `Ord` | Total ordering | Eq + PartialOrd, no floating-point |
+
+## Common Trait Bundles
+
+```rust
+// ID types
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct EntityId(u64);
+
+// Value types
+#[derive(Debug, Clone, Copy, PartialEq, Default)]
+pub struct Vector2 { x: f32, y: f32 }
+
+// Configuration
+#[derive(Debug, Clone, PartialEq, Default)]
+pub struct Config {
+    name: String,
+    options: HashMap<String, String>,
+}
+
+// Error types
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ParseError {
+    InvalidSyntax(String),
+    UnexpectedToken(Token),
+}
+```
+
+## Manual Implementations
+
+```rust
+// When derive doesn't do what you want
+struct CaseInsensitiveString(String);
+
+impl PartialEq for CaseInsensitiveString {
+    fn eq(&self, other: &Self) -> bool {
+        self.0.to_lowercase() == other.0.to_lowercase()
+    }
+}
+
+impl Eq for CaseInsensitiveString {}
+
+impl Hash for CaseInsensitiveString {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        // Must be consistent with PartialEq
+        self.0.to_lowercase().hash(state);
+    }
+}
+
+// Custom Debug for sensitive data
+struct Password(String);
+
+impl Debug for Password {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "Password([REDACTED])")
+    }
+}
+```
+
+## Serde Traits
+
+```rust
+use serde::{Serialize, Deserialize};
+
+// For serializable types
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ApiResponse {
+    pub status: String,
+    pub data: Vec<Item>,
+}
+
+// With custom serialization
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Config {
+    #[serde(default)]
+    pub verbose: bool,
+    
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub api_key: Option<String>,
+}
+```
+
+## Minimum Recommended
+
+```rust
+// At minimum, public types should have:
+#[derive(Debug, Clone, PartialEq)]
+pub struct MyType { ... }
+
+// Add based on use case:
+// + Eq, Hash       → for HashMap keys
+// + Ord, PartialOrd → for BTreeMap, sorting
+// + Default        → for Option::unwrap_or_default()
+// + Copy           → for small value types
+// + Serialize      → for serialization
+```
+
+## See Also
+
+- [own-copy-small](./own-copy-small.md) - When to implement Copy
+- [api-default-impl](./api-default-impl.md) - Implementing Default
+- [doc-examples-section](./doc-examples-section.md) - Documenting trait implementations

package/template/agent/skills/rust-developer/references/rust-rules/api-default-impl.md

@@ -0,0 +1,177 @@
+# api-default-impl
+
+> Implement `Default` for types with sensible default values
+
+## Why It Matters
+
+`Default` is a standard trait that provides a canonical way to create a default instance. It integrates with many ecosystem patterns: `Option::unwrap_or_default()`, `#[derive(Default)]`, struct update syntax `..Default::default()`, and generic code that requires `T: Default`. Implementing it makes your types more ergonomic.
+
+## Bad
+
+```rust
+struct Config {
+    timeout: Duration,
+    retries: u32,
+    verbose: bool,
+}
+
+impl Config {
+    // Custom constructor - works but non-standard
+    fn new() -> Self {
+        Config {
+            timeout: Duration::from_secs(30),
+            retries: 3,
+            verbose: false,
+        }
+    }
+}
+
+// Can't use with standard patterns
+let config: Config = Default::default();  // Error: Default not implemented
+let timeout = settings.get("timeout").unwrap_or_default();  // Won't work
+```
+
+## Good
+
+```rust
+#[derive(Default)]
+struct Config {
+    #[default = Duration::from_secs(30)]  // Nightly, or implement manually
+    timeout: Duration,
+    retries: u32,     // Defaults to 0 with derive
+    verbose: bool,    // Defaults to false with derive
+}
+
+// Or implement manually for custom defaults
+impl Default for Config {
+    fn default() -> Self {
+        Config {
+            timeout: Duration::from_secs(30),
+            retries: 3,
+            verbose: false,
+        }
+    }
+}
+
+// Now works with all standard patterns
+let config = Config::default();
+let config = Config { retries: 5, ..Default::default() };
+let value = map.get("key").cloned().unwrap_or_default();
+```
+
+## Derive vs Manual
+
+```rust
+// Derive: all fields use their own Default
+#[derive(Default)]
+struct Simple {
+    count: u32,      // 0
+    name: String,    // ""
+    items: Vec<i32>, // []
+}
+
+// Manual: when you need custom defaults
+struct Connection {
+    host: String,
+    port: u16,
+    timeout: Duration,
+}
+
+impl Default for Connection {
+    fn default() -> Self {
+        Connection {
+            host: "localhost".to_string(),
+            port: 8080,
+            timeout: Duration::from_secs(30),
+        }
+    }
+}
+```
+
+## Builder with Default
+
+```rust
+#[derive(Default)]
+struct ServerBuilder {
+    host: String,
+    port: u16,
+    workers: usize,
+}
+
+impl ServerBuilder {
+    fn host(mut self, host: impl Into<String>) -> Self {
+        self.host = host.into();
+        self
+    }
+    
+    fn port(mut self, port: u16) -> Self {
+        self.port = port;
+        self
+    }
+}
+
+// Clean initialization
+let server = ServerBuilder::default()
+    .host("0.0.0.0")
+    .port(3000)
+    .build();
+```
+
+## Default with Required Fields
+
+```rust
+// When some fields have no sensible default, don't implement Default
+struct User {
+    id: UserId,       // No sensible default
+    name: String,     // Could default to ""
+}
+
+// Instead, provide a constructor
+impl User {
+    fn new(id: UserId, name: impl Into<String>) -> Self {
+        User { id, name: name.into() }
+    }
+}
+
+// Or use builder with required fields
+struct UserBuilder {
+    id: Option<UserId>,
+    name: String,
+}
+
+impl Default for UserBuilder {
+    fn default() -> Self {
+        UserBuilder {
+            id: None,
+            name: String::new(),
+        }
+    }
+}
+```
+
+## Generic Default
+
+```rust
+// Require Default in generic bounds when needed
+fn create_or_default<T: Default>(opt: Option<T>) -> T {
+    opt.unwrap_or_default()
+}
+
+// PhantomData is Default regardless of T
+use std::marker::PhantomData;
+struct Wrapper<T> {
+    _marker: PhantomData<T>,
+}
+
+impl<T> Default for Wrapper<T> {
+    fn default() -> Self {
+        Wrapper { _marker: PhantomData }
+    }
+}
+```
+
+## See Also
+
+- [api-builder-pattern](./api-builder-pattern.md) - Building complex types
+- [api-common-traits](./api-common-traits.md) - Other common traits to implement
+- [api-from-not-into](./api-from-not-into.md) - Conversion traits