agy-superpowers 5.1.3 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/api-must-use.md

@@ -0,0 +1,125 @@
+# api-must-use
+
+> Mark types and functions with `#[must_use]` when ignoring results is likely a bug
+
+## Why It Matters
+
+Some return values should never be ignored—`Result`, locks, RAII guards, computed values that have no side effects. Without `#[must_use]`, silently discarding these values can introduce subtle bugs that are hard to detect. The attribute generates compiler warnings when the value is unused.
+
+## Bad
+
+```rust
+// Result ignored - error silently dropped
+fn send_email(to: &str, body: &str) -> Result<(), EmailError> { ... }
+
+send_email("user@example.com", "Hello!");  // No warning if Result ignored!
+// Email may have failed, but we don't know
+
+// Computed value ignored - likely a bug
+fn compute_checksum(data: &[u8]) -> u32 { ... }
+
+let data = vec![1, 2, 3, 4];
+compute_checksum(&data);  // Result discarded - pointless call
+```
+
+## Good
+
+```rust
+#[must_use = "this `Result` may be an `Err` that should be handled"]
+fn send_email(to: &str, body: &str) -> Result<(), EmailError> { ... }
+
+send_email("user@example.com", "Hello!");  
+// Warning: unused `Result` that must be used
+
+// Mark pure functions
+#[must_use = "this returns a new value and does not modify the input"]
+fn compute_checksum(data: &[u8]) -> u32 { ... }
+
+compute_checksum(&data);
+// Warning: unused return value of `compute_checksum` that must be used
+```
+
+## Apply to Types
+
+```rust
+// Mark the type itself when it should always be used
+#[must_use = "futures do nothing unless polled"]
+struct MyFuture<T> { ... }
+
+// Mark RAII guards
+#[must_use = "if unused, the lock will be immediately released"]
+struct MutexGuard<'a, T> { ... }
+
+// Mark results/errors
+#[must_use = "errors should be handled"]
+enum AppError { ... }
+```
+
+## Standard Library Examples
+
+```rust
+// Result and Option are #[must_use]
+let v: Vec<i32> = vec![1, 2, 3];
+v.first();  // Warning: unused Option
+
+// Iterator adapters are #[must_use]
+v.iter().map(|x| x * 2);  // Warning: iterators are lazy
+
+// String methods that return new values
+let s = "hello";
+s.to_uppercase();  // Warning: unused String
+```
+
+## When to Apply
+
+```rust
+// ✅ Pure functions (no side effects)
+#[must_use]
+fn add(a: i32, b: i32) -> i32 { a + b }
+
+// ✅ Builder methods returning Self
+#[must_use = "builder methods return a new builder"]
+fn with_timeout(self, t: Duration) -> Self { ... }
+
+// ✅ Fallible operations
+#[must_use]
+fn try_parse(s: &str) -> Result<Data, ParseError> { ... }
+
+// ✅ Iterators and futures (lazy)
+#[must_use = "iterators are lazy and do nothing unless consumed"]
+struct Map<I, F> { ... }
+
+// ❌ Side-effecting functions where result is optional
+fn log(msg: &str) -> Result<(), io::Error> { ... }  // Might be ok to ignore
+
+// ❌ Methods with useful side effects
+fn vec.push(item);  // Mutates vec, no return to use
+```
+
+## Custom Messages
+
+```rust
+#[must_use = "creating a guard does nothing without assignment"]
+struct ScopeGuard { ... }
+
+#[must_use = "this returns the old value"]
+fn replace(&mut self, new: T) -> T { ... }
+
+#[must_use = "use `.await` to execute the future"]
+async fn fetch() -> Data { ... }
+```
+
+## Clippy Lints
+
+```toml
+[lints.clippy]
+must_use_candidate = "warn"      # Suggests where to add #[must_use]
+unused_must_use = "deny"          # Built-in, treat warnings as errors
+double_must_use = "warn"          # Redundant #[must_use]
+```
+
+## See Also
+
+- [api-builder-must-use](./api-builder-must-use.md) - Builder pattern must_use
+- [err-result-over-panic](./err-result-over-panic.md) - Result types require handling
+- [lint-deny-correctness](./lint-deny-correctness.md) - Enabling useful lints

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