agy-superpowers 5.1.4 → 5.1.5

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

package/template/agent/skills/rust-developer/references/rust-rules/api-extension-trait.md

@@ -0,0 +1,163 @@
+# api-extension-trait
+
+> Use extension traits to add methods to external types
+
+## Why It Matters
+
+Rust's orphan rules prevent implementing external traits on external types. Extension traits provide a workaround: define a new trait with your methods, then implement it for the external type. This pattern is used extensively in the ecosystem (e.g., `itertools::Itertools`, `tokio::AsyncReadExt`).
+
+## Bad
+
+```rust
+// Can't add methods directly to external types
+impl Vec<u8> {
+    fn as_hex(&self) -> String {
+        // Error: cannot define inherent impl for a type outside this crate
+    }
+}
+
+// Can't implement external trait for external type
+impl SomeExternalTrait for Vec<u8> {
+    // Error: orphan rules violation
+}
+```
+
+## Good
+
+```rust
+// Define an extension trait
+pub trait ByteSliceExt {
+    fn as_hex(&self) -> String;
+    fn is_ascii_printable(&self) -> bool;
+}
+
+// Implement for the external type
+impl ByteSliceExt for [u8] {
+    fn as_hex(&self) -> String {
+        self.iter()
+            .map(|b| format!("{:02x}", b))
+            .collect()
+    }
+    
+    fn is_ascii_printable(&self) -> bool {
+        self.iter().all(|b| b.is_ascii_graphic() || b.is_ascii_whitespace())
+    }
+}
+
+// Usage: import the trait to use the methods
+use my_crate::ByteSliceExt;
+
+let data: &[u8] = b"hello";
+println!("{}", data.as_hex());  // "68656c6c6f"
+```
+
+## Convention: Ext Suffix
+
+```rust
+// Standard naming: TypeExt for extending Type
+pub trait OptionExt<T> {
+    fn unwrap_or_log(self, msg: &str) -> Option<T>;
+}
+
+impl<T> OptionExt<T> for Option<T> {
+    fn unwrap_or_log(self, msg: &str) -> Option<T> {
+        if self.is_none() {
+            log::warn!("{}", msg);
+        }
+        self
+    }
+}
+
+// For generic extensions
+pub trait ResultExt<T, E> {
+    fn log_err(self) -> Self;
+}
+
+impl<T, E: std::fmt::Display> ResultExt<T, E> for Result<T, E> {
+    fn log_err(self) -> Self {
+        if let Err(ref e) = self {
+            log::error!("{}", e);
+        }
+        self
+    }
+}
+```
+
+## Ecosystem Examples
+
+```rust
+// itertools::Itertools
+use itertools::Itertools;
+let groups = vec![1, 1, 2, 2, 3].into_iter().group_by(|x| *x);
+
+// futures::StreamExt
+use futures::StreamExt;
+let next = stream.next().await;
+
+// tokio::io::AsyncReadExt
+use tokio::io::AsyncReadExt;
+let mut buf = [0u8; 1024];
+reader.read(&mut buf).await?;
+
+// anyhow::Context
+use anyhow::Context;
+let content = std::fs::read_to_string(path)
+    .with_context(|| format!("failed to read {}", path))?;
+```
+
+## Scoped Extensions
+
+```rust
+// Extension only visible where imported
+mod string_utils {
+    pub trait StringExt {
+        fn truncate_ellipsis(&self, max_len: usize) -> String;
+    }
+    
+    impl StringExt for str {
+        fn truncate_ellipsis(&self, max_len: usize) -> String {
+            if self.len() <= max_len {
+                self.to_string()
+            } else {
+                format!("{}...", &self[..max_len.saturating_sub(3)])
+            }
+        }
+    }
+}
+
+// Only available when explicitly imported
+use string_utils::StringExt;
+let short = "very long string".truncate_ellipsis(10);
+```
+
+## Generic Extensions with Bounds
+
+```rust
+pub trait VecExt<T> {
+    fn push_if_unique(&mut self, item: T)
+    where
+        T: PartialEq;
+}
+
+impl<T> VecExt<T> for Vec<T> {
+    fn push_if_unique(&mut self, item: T)
+    where
+        T: PartialEq,
+    {
+        if !self.contains(&item) {
+            self.push(item);
+        }
+    }
+}
+
+// Works with any T: PartialEq
+let mut v = vec![1, 2, 3];
+v.push_if_unique(2);  // No-op
+v.push_if_unique(4);  // Adds 4
+```
+
+## See Also
+
+- [api-sealed-trait](./api-sealed-trait.md) - Controlling trait implementations
+- [api-impl-into](./api-impl-into.md) - Using standard conversion traits
+- [name-as-free](./name-as-free.md) - Naming conventions for conversions