agy-superpowers 5.2.2 → 5.2.3

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

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