agy-superpowers 5.2.2 → 5.2.4

package/template/agent/skills/rust-developer/references/rust-rules/api-newtype-safety.md

@@ -1,162 +0,0 @@
-# api-newtype-safety
-
-> Use newtypes to prevent mixing semantically different values
-
-## Why It Matters
-
-Raw primitives like `u64` or `String` carry no semantic meaning. A function taking `(u64, u64)` can easily be called with arguments swapped. Newtypes wrap primitives in distinct types, making the compiler catch mistakes at compile time rather than runtime.
-
-## Bad
-
-```rust
-struct User {
-    id: u64,
-    group_id: u64,
-    created_at: u64,  // Unix timestamp
-}
-
-fn add_user_to_group(user_id: u64, group_id: u64) { ... }
-
-// Bug: arguments swapped - compiles fine, fails at runtime
-let user = User { id: 100, group_id: 5, created_at: 1234567890 };
-add_user_to_group(user.group_id, user.id);  // Silent bug!
-
-// Bug: wrong field used - timestamp passed as ID
-add_user_to_group(user.created_at, user.group_id);  // Compiles fine!
-```
-
-## Good
-
-```rust
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-struct UserId(u64);
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-struct GroupId(u64);
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
-struct Timestamp(u64);
-
-struct User {
-    id: UserId,
-    group_id: GroupId,
-    created_at: Timestamp,
-}
-
-fn add_user_to_group(user_id: UserId, group_id: GroupId) { ... }
-
-// Compile error: expected UserId, found GroupId
-let user = User { ... };
-add_user_to_group(user.group_id, user.id);  // Error!
-
-// Compile error: expected UserId, found Timestamp
-add_user_to_group(user.created_at, user.group_id);  // Error!
-```
-
-## Derive Common Traits
-
-```rust
-// Minimal: just enough for your use case
-#[derive(Debug, Clone, Copy)]
-struct MeterId(u32);
-
-// Full ID type: hashable, comparable, displayable
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-struct OrderId(u64);
-
-impl std::fmt::Display for OrderId {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "ORD-{:08}", self.0)
-    }
-}
-
-// With serde for serialization
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
-#[serde(transparent)]  // Serializes as raw u64
-struct ProductId(u64);
-```
-
-## Constructor Patterns
-
-```rust
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-struct Email(String);
-
-impl Email {
-    /// Creates a new Email, validating the format.
-    pub fn new(s: &str) -> Result<Self, EmailError> {
-        if is_valid_email(s) {
-            Ok(Email(s.to_string()))
-        } else {
-            Err(EmailError::InvalidFormat)
-        }
-    }
-    
-    /// Returns the email as a string slice.
-    pub fn as_str(&self) -> &str {
-        &self.0
-    }
-}
-
-// Usage enforces validation
-let email = Email::new("user@example.com")?;  // Must go through validation
-```
-
-## Zero-Cost Abstraction
-
-```rust
-use std::mem::size_of;
-
-#[derive(Clone, Copy)]
-struct Miles(f64);
-
-#[derive(Clone, Copy)]
-struct Kilometers(f64);
-
-// Same size as raw f64
-assert_eq!(size_of::<Miles>(), size_of::<f64>());
-assert_eq!(size_of::<Kilometers>(), size_of::<f64>());
-
-// But can't accidentally mix them
-fn drive(distance: Miles) { ... }
-
-let km = Kilometers(100.0);
-drive(km);  // Error: expected Miles, found Kilometers
-
-// Explicit conversion
-impl From<Kilometers> for Miles {
-    fn from(km: Kilometers) -> Self {
-        Miles(km.0 * 0.621371)
-    }
-}
-
-drive(km.into());  // Explicit, visible conversion
-```
-
-## When Newtypes Help Most
-
-```rust
-// ✅ IDs that could be confused
-fn transfer(from: AccountId, to: AccountId, amount: Money) { ... }
-
-// ✅ Units that shouldn't mix
-struct Celsius(f64);
-struct Fahrenheit(f64);
-
-// ✅ Validated strings
-struct Username(String);  // Validated alphanumeric
-struct Password(String);  // Never logged
-
-// ✅ Different meanings of same type
-struct Milliseconds(u64);
-struct Seconds(u64);
-
-// ❌ Overkill: single use, no confusion possible
-struct X(i32);  // Just use i32
-```
-
-## See Also
-
-- [type-newtype-ids](./type-newtype-ids.md) - Newtype pattern for IDs
-- [api-parse-dont-validate](./api-parse-dont-validate.md) - Type-driven validation
-- [own-copy-small](./own-copy-small.md) - Making newtypes Copy

package/template/agent/skills/rust-developer/references/rust-rules/api-non-exhaustive.md

@@ -1,177 +0,0 @@
-# api-non-exhaustive
-
-> Use `#[non_exhaustive]` on public enums and structs for forward compatibility
-
-## Why It Matters
-
-Adding a variant to a public enum or a field to a public struct is normally a breaking change—downstream code may match exhaustively or use struct literal syntax. `#[non_exhaustive]` forces external code to use wildcards in matches and constructors, allowing you to add variants/fields in minor versions without breaking callers.
-
-## Bad
-
-```rust
-// Public enum - adding variant breaks downstream matches
-pub enum ErrorKind {
-    NotFound,
-    PermissionDenied,
-    TimedOut,
-}
-
-// Downstream code
-match error.kind() {
-    ErrorKind::NotFound => ...,
-    ErrorKind::PermissionDenied => ...,
-    ErrorKind::TimedOut => ...,
-    // No wildcard - will break when you add ErrorKind::Interrupted
-}
-
-// Public struct - adding field breaks downstream construction
-pub struct Config {
-    pub name: String,
-    pub value: i32,
-}
-
-// Downstream code
-let config = Config { name: "test".into(), value: 42 };
-// Will break when you add `pub enabled: bool`
-```
-
-## Good
-
-```rust
-// Can add variants in minor versions
-#[non_exhaustive]
-pub enum ErrorKind {
-    NotFound,
-    PermissionDenied,
-    TimedOut,
-    // Future: can add Interrupted here without breaking changes
-}
-
-// Downstream code MUST have wildcard
-match error.kind() {
-    ErrorKind::NotFound => ...,
-    ErrorKind::PermissionDenied => ...,
-    ErrorKind::TimedOut => ...,
-    _ => ...,  // Required by non_exhaustive
-}
-
-// Can add fields in minor versions
-#[non_exhaustive]
-pub struct Config {
-    pub name: String,
-    pub value: i32,
-}
-
-// Downstream CANNOT use struct literal syntax
-// let config = Config { name: "test".into(), value: 42 };  // Error!
-
-// Must use constructor
-impl Config {
-    pub fn new(name: impl Into<String>, value: i32) -> Self {
-        Config { name: name.into(), value }
-    }
-}
-```
-
-## How It Works
-
-```rust
-#[non_exhaustive]
-pub enum Status {
-    Active,
-    Inactive,
-}
-
-// Inside your crate: exhaustive match is allowed
-fn internal(s: Status) {
-    match s {
-        Status::Active => {},
-        Status::Inactive => {},
-        // No wildcard needed inside defining crate
-    }
-}
-
-// Outside your crate: wildcard required
-fn external(s: my_crate::Status) {
-    match s {
-        my_crate::Status::Active => {},
-        my_crate::Status::Inactive => {},
-        _ => {},  // REQUIRED
-    }
-}
-```
-
-## Struct Usage
-
-```rust
-#[non_exhaustive]
-pub struct Point {
-    pub x: f64,
-    pub y: f64,
-}
-
-impl Point {
-    // Provide constructor
-    pub fn new(x: f64, y: f64) -> Self {
-        Point { x, y }
-    }
-}
-
-// External code can read fields but not construct with literals
-fn external(p: Point) {
-    println!("x: {}, y: {}", p.x, p.y);  // Reading is fine
-    
-    // let p2 = Point { x: 1.0, y: 2.0 };  // Error!
-    let p2 = Point::new(1.0, 2.0);  // Must use constructor
-}
-```
-
-## Non-Exhaustive Variants
-
-```rust
-pub enum Message {
-    // Specific variant is non-exhaustive
-    #[non_exhaustive]
-    Error { code: u32, message: String },
-    
-    Ok(Data),
-}
-
-// Can destructure Ok normally
-// But Error requires `..` to handle future fields
-match msg {
-    Message::Ok(data) => {},
-    Message::Error { code, message, .. } => {},  // `..` required
-}
-```
-
-## When to Use
-
-```rust
-// ✅ Use for public API types that may evolve
-#[non_exhaustive]
-pub enum ApiError { ... }
-
-#[non_exhaustive]
-pub struct Options { ... }
-
-// ✅ Use for error types
-#[non_exhaustive]
-pub enum MyError { ... }
-
-// ❌ Don't use for internal types
-enum InternalState { ... }  // Not public, no concern
-
-// ❌ Don't use for stable, complete types
-pub enum Ordering {  // Less, Equal, Greater is complete
-    Less,
-    Equal,
-    Greater,
-}
-```
-
-## See Also
-
-- [api-sealed-trait](./api-sealed-trait.md) - Controlling trait implementations
-- [err-custom-type](./err-custom-type.md) - Error type design
-- [api-builder-pattern](./api-builder-pattern.md) - Alternative to struct literals

package/template/agent/skills/rust-developer/references/rust-rules/api-parse-dont-validate.md

@@ -1,184 +0,0 @@
-# api-parse-dont-validate
-
-> Parse into validated types at boundaries
-
-## Why It Matters
-
-Instead of validating data and hoping you remember to check everywhere, parse it into a type that can only be constructed from valid data. The type system then guarantees validity - you can't forget to validate because invalid states are unrepresentable.
-
-## Bad
-
-```rust
-// Validation scattered throughout codebase
-fn send_email(email: &str) -> Result<(), Error> {
-    // Did someone validate this already? Who knows!
-    if !is_valid_email(email) {
-        return Err(Error::InvalidEmail);
-    }
-    // Send email...
-}
-
-fn add_to_mailing_list(email: &str) -> Result<(), Error> {
-    // Duplicate validation, or did we forget?
-    if !is_valid_email(email) {
-        return Err(Error::InvalidEmail);
-    }
-    // Add to list...
-}
-
-// Easy to forget validation
-fn process_user_email(email: &str) {
-    // Oops, no validation!
-    database.store_email(email);
-}
-```
-
-## Good
-
-```rust
-/// A validated email address.
-/// Can only be constructed via `Email::parse()`.
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
-pub struct Email(String);
-
-impl Email {
-    /// Parses and validates an email address.
-    pub fn parse(s: impl Into<String>) -> Result<Self, EmailError> {
-        let s = s.into();
-        if Self::is_valid(&s) {
-            Ok(Email(s))
-        } else {
-            Err(EmailError::Invalid)
-        }
-    }
-    
-    fn is_valid(s: &str) -> bool {
-        s.contains('@') && s.len() > 3  // Simplified
-    }
-    
-    pub fn as_str(&self) -> &str {
-        &self.0
-    }
-}
-
-// Now functions can accept Email - guaranteed valid!
-fn send_email(email: &Email) -> Result<(), Error> {
-    // No validation needed - Email is always valid
-    smtp_send(email.as_str())
-}
-
-fn add_to_mailing_list(email: Email) {
-    // No validation needed
-    list.push(email);
-}
-```
-
-## More Examples
-
-```rust
-// Port number (1-65535)
-pub struct Port(u16);
-
-impl Port {
-    pub fn new(n: u16) -> Option<Self> {
-        if n > 0 { Some(Port(n)) } else { None }
-    }
-    
-    pub fn get(&self) -> u16 {
-        self.0
-    }
-}
-
-// Non-empty string
-pub struct NonEmptyString(String);
-
-impl NonEmptyString {
-    pub fn new(s: impl Into<String>) -> Option<Self> {
-        let s = s.into();
-        if s.is_empty() { None } else { Some(Self(s)) }
-    }
-}
-
-// Positive integer
-pub struct PositiveI32(i32);
-
-impl PositiveI32 {
-    pub fn new(n: i32) -> Option<Self> {
-        if n > 0 { Some(Self(n)) } else { None }
-    }
-}
-
-// Bounded value
-pub struct Percentage(u8);
-
-impl Percentage {
-    pub fn new(n: u8) -> Option<Self> {
-        if n <= 100 { Some(Self(n)) } else { None }
-    }
-}
-```
-
-## Parsing at Boundaries
-
-```rust
-// Parse at the system boundary (API, CLI, config file)
-fn handle_request(raw: RawRequest) -> Result<Response, Error> {
-    // Parse ALL inputs upfront
-    let email = Email::parse(&raw.email)?;
-    let age = Age::parse(raw.age)?;
-    let username = Username::parse(&raw.username)?;
-    
-    // Now work with validated types
-    process_user(email, age, username)
-}
-
-fn process_user(email: Email, age: Age, username: Username) {
-    // All inputs guaranteed valid - no checks needed
-}
-```
-
-## Evidence from sqlx
-
-```rust
-// sqlx parses SQL at compile time, ensuring query validity
-// https://github.com/launchbadge/sqlx/blob/master/src/macros/mod.rs
-
-// The query! macro parses and validates SQL
-let user = sqlx::query!("SELECT * FROM users WHERE id = ?", id)
-    .fetch_one(&pool)
-    .await?;
-
-// If SQL is invalid, compilation fails - invalid state unrepresentable
-```
-
-## Combining with Display
-
-```rust
-use std::fmt;
-
-pub struct Email(String);
-
-impl Email {
-    pub fn parse(s: &str) -> Result<Self, EmailError> { ... }
-}
-
-// Implement Display for easy printing
-impl fmt::Display for Email {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "{}", self.0)
-    }
-}
-
-// Implement AsRef for easy borrowing
-impl AsRef<str> for Email {
-    fn as_ref(&self) -> &str {
-        &self.0
-    }
-}
-```
-
-## See Also
-
-- [api-newtype-safety](api-newtype-safety.md) - Use newtypes for type safety
-- [type-newtype-validated](type-newtype-validated.md) - Newtypes for validated data
-- [api-typestate](api-typestate.md) - Compile-time state machines

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

@@ -1,168 +0,0 @@
-# api-sealed-trait
-
-> Use sealed traits to prevent external implementations while allowing use
-
-## Why It Matters
-
-Public traits can be implemented by anyone, which may be undesirable when you need to guarantee behavior or add methods in future versions. A sealed trait can be used by external code but not implemented by it, giving you control over implementations while maintaining a usable API.
-
-## Bad
-
-```rust
-// Anyone can implement this trait
-pub trait DatabaseDriver {
-    fn connect(&self, url: &str) -> Connection;
-    fn execute(&self, query: &str) -> Result<Rows, Error>;
-}
-
-// External crate implements it incorrectly
-impl DatabaseDriver for MyBadDriver {
-    fn connect(&self, url: &str) -> Connection {
-        // Buggy implementation that doesn't handle errors
-        unsafe { force_connect(url) }
-    }
-}
-
-// Later, you want to add a required method - BREAKING CHANGE
-pub trait DatabaseDriver {
-    fn connect(&self, url: &str) -> Connection;
-    fn execute(&self, query: &str) -> Result<Rows, Error>;
-    fn transaction(&self) -> Transaction;  // External impls now broken!
-}
-```
-
-## Good
-
-```rust
-// Create a private module with a private trait
-mod private {
-    pub trait Sealed {}
-}
-
-// Public trait requires the private trait
-pub trait DatabaseDriver: private::Sealed {
-    fn connect(&self, url: &str) -> Connection;
-    fn execute(&self, query: &str) -> Result<Rows, Error>;
-}
-
-// Only your crate can implement Sealed, thus DatabaseDriver
-pub struct PostgresDriver;
-impl private::Sealed for PostgresDriver {}
-impl DatabaseDriver for PostgresDriver {
-    fn connect(&self, url: &str) -> Connection { ... }
-    fn execute(&self, query: &str) -> Result<Rows, Error> { ... }
-}
-
-pub struct MySqlDriver;
-impl private::Sealed for MySqlDriver {}
-impl DatabaseDriver for MySqlDriver {
-    fn connect(&self, url: &str) -> Connection { ... }
-    fn execute(&self, query: &str) -> Result<Rows, Error> { ... }
-}
-
-// External crate cannot implement - private::Sealed is not accessible
-// impl DatabaseDriver for ExternalDriver { }  // Error!
-
-// But external code CAN use the trait
-fn use_driver(driver: &impl DatabaseDriver) {
-    let conn = driver.connect("postgres://localhost");
-}
-```
-
-## Full Pattern
-
-```rust
-pub mod db {
-    mod private {
-        pub trait Sealed {}
-    }
-    
-    /// Database driver trait.
-    /// 
-    /// This trait is sealed and cannot be implemented outside this crate.
-    pub trait Driver: private::Sealed {
-        /// Connects to the database.
-        fn connect(&self, url: &str) -> Result<Connection, Error>;
-        
-        /// Executes a query.
-        fn execute(&self, sql: &str) -> Result<Rows, Error>;
-    }
-    
-    pub struct Postgres;
-    impl private::Sealed for Postgres {}
-    impl Driver for Postgres { ... }
-    
-    pub struct Sqlite;
-    impl private::Sealed for Sqlite {}
-    impl Driver for Sqlite { ... }
-}
-
-// Usage works fine
-use db::{Driver, Postgres};
-
-fn query(driver: &impl Driver) {
-    driver.execute("SELECT 1")?;
-}
-
-query(&Postgres);
-```
-
-## Benefits of Sealing
-
-```rust
-// 1. Add methods without breaking changes
-pub trait Format: private::Sealed {
-    fn format(&self) -> String;
-    
-    // Added later - not breaking because no external impls exist
-    fn format_pretty(&self) -> String {
-        self.format()  // Default implementation
-    }
-}
-
-// 2. Guarantee invariants
-pub trait SafeBuffer: private::Sealed {
-    // You control all implementations, so you know they're all correct
-    fn get(&self, index: usize) -> Option<&u8>;
-}
-
-// 3. Use as marker traits
-pub trait ValidConfig: private::Sealed {}
-// Only validated configs implement this
-```
-
-## Partially Sealed
-
-```rust
-// Allow implementing some methods but not all
-mod private {
-    pub trait SealedCore {}
-}
-
-pub trait Plugin: private::SealedCore {
-    // Sealed - only we implement
-    fn initialize(&self);
-    fn shutdown(&self);
-    
-    // Open - users can override
-    fn name(&self) -> &str { "unnamed" }
-}
-
-// Only we can add new required sealed methods
-// Users can customize open methods
-```
-
-## When to Seal
-
-| Seal When | Don't Seal When |
-|-----------|-----------------|
-| API stability is critical | You want extension points |
-| Implementation correctness is hard | Users need custom implementations |
-| You'll add methods later | Trait is simple and stable |
-| Safety invariants required | Standard patterns (Iterator, etc.) |
-
-## See Also
-
-- [api-non-exhaustive](./api-non-exhaustive.md) - Related pattern for enums/structs
-- [api-extension-trait](./api-extension-trait.md) - Adding methods to external types
-- [api-typestate](./api-typestate.md) - Compile-time state guarantees