agy-superpowers 5.2.2 → 5.2.4

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

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

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

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

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