agy-superpowers 5.1.4 → 5.1.5

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

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

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

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

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