agy-superpowers 5.2.2 → 5.2.4

package/template/agent/skills/rust-developer/references/rust-rules/type-newtype-ids.md

@@ -1,160 +0,0 @@
-# type-newtype-ids
-
-> Wrap IDs in newtypes: `UserId(u64)`
-
-## Why It Matters
-
-Using raw integers for IDs is error-prone. It's easy to accidentally pass a `user_id` where a `post_id` is expected. Newtypes make these mix-ups compile-time errors instead of runtime bugs.
-
-## Bad
-
-```rust
-fn get_user_posts(user_id: u64, post_id: u64) -> Vec<Post> {
-    // Which is which? Easy to swap by accident
-}
-
-// Oops! Arguments swapped - compiles fine, wrong at runtime
-let posts = get_user_posts(post_id, user_id);
-
-// Even worse with multiple IDs
-fn transfer(from: u64, to: u64, amount: u64) {
-    // from/to can easily be swapped
-}
-```
-
-## Good
-
-```rust
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct UserId(pub u64);
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct PostId(pub u64);
-
-fn get_user_posts(user_id: UserId, post_id: PostId) -> Vec<Post> {
-    // Types are distinct
-}
-
-// This won't compile - types don't match
-// let posts = get_user_posts(post_id, user_id);  // ERROR!
-
-// Correct usage
-let posts = get_user_posts(UserId(1), PostId(42));
-```
-
-## Derive Common Traits
-
-```rust
-#[derive(
-    Debug,      // For printing
-    Clone,      // For copying
-    Copy,       // For implicit copies (if small)
-    PartialEq,  // For == comparison
-    Eq,         // For HashMap keys
-    Hash,       // For HashMap keys
-    PartialOrd, // For sorting (optional)
-    Ord,        // For BTreeMap keys (optional)
-)]
-pub struct UserId(pub u64);
-```
-
-## Add Useful Methods
-
-```rust
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct UserId(u64);
-
-impl UserId {
-    pub const fn new(id: u64) -> Self {
-        Self(id)
-    }
-    
-    pub const fn get(self) -> u64 {
-        self.0
-    }
-    
-    // For database queries
-    pub fn as_i64(self) -> i64 {
-        self.0 as i64
-    }
-}
-
-impl From<u64> for UserId {
-    fn from(id: u64) -> Self {
-        Self(id)
-    }
-}
-
-impl std::fmt::Display for UserId {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "user:{}", self.0)
-    }
-}
-```
-
-## With Serde
-
-```rust
-use serde::{Deserialize, Serialize};
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
-#[serde(transparent)]  // Serializes as just the inner value
-pub struct UserId(pub u64);
-
-// JSON: {"user_id": 123} not {"user_id": {"0": 123}}
-```
-
-## String IDs (UUIDs, etc.)
-
-```rust
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
-pub struct SessionId(String);
-
-impl SessionId {
-    pub fn new() -> Self {
-        Self(uuid::Uuid::new_v4().to_string())
-    }
-    
-    pub fn parse(s: &str) -> Result<Self, ParseError> {
-        // Validate format
-        uuid::Uuid::parse_str(s)?;
-        Ok(Self(s.to_string()))
-    }
-    
-    pub fn as_str(&self) -> &str {
-        &self.0
-    }
-}
-```
-
-## Multiple Related IDs
-
-```rust
-// Macro for consistent ID types
-macro_rules! define_id {
-    ($name:ident) => {
-        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-        pub struct $name(pub u64);
-        
-        impl $name {
-            pub const fn new(id: u64) -> Self { Self(id) }
-            pub const fn get(self) -> u64 { self.0 }
-        }
-        
-        impl From<u64> for $name {
-            fn from(id: u64) -> Self { Self(id) }
-        }
-    };
-}
-
-define_id!(UserId);
-define_id!(PostId);
-define_id!(CommentId);
-define_id!(TeamId);
-```
-
-## See Also
-
-- [api-newtype-safety](api-newtype-safety.md) - Newtypes for type safety
-- [type-newtype-validated](type-newtype-validated.md) - Newtypes for validated data
-- [api-parse-dont-validate](api-parse-dont-validate.md) - Parse into validated types

package/template/agent/skills/rust-developer/references/rust-rules/type-newtype-validated.md

@@ -1,159 +0,0 @@
-# type-newtype-validated
-
-> Use newtypes to enforce validation at construction time
-
-## Why It Matters
-
-A validated newtype guarantees its inner value is always valid. Once you have an `Email`, you know it passed validation—no re-checking needed. This "parse, don't validate" pattern catches errors at boundaries and makes invalid states unrepresentable.
-
-## Bad
-
-```rust
-// Validation scattered throughout code
-fn send_email(to: &str, body: &str) -> Result<(), Error> {
-    if !is_valid_email(to) {  // Must check every time
-        return Err(Error::InvalidEmail);
-    }
-    // ...
-}
-
-fn add_recipient(list: &mut Vec<String>, email: &str) -> Result<(), Error> {
-    if !is_valid_email(email) {  // Check again
-        return Err(Error::InvalidEmail);
-    }
-    list.push(email.to_string());
-    Ok(())
-}
-```
-
-## Good
-
-```rust
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
-pub struct Email(String);
-
-impl Email {
-    pub fn new(s: &str) -> Result<Self, EmailError> {
-        if is_valid_email(s) {
-            Ok(Email(s.to_string()))
-        } else {
-            Err(EmailError::Invalid(s.to_string()))
-        }
-    }
-    
-    pub fn as_str(&self) -> &str {
-        &self.0
-    }
-}
-
-// No validation needed - Email is always valid
-fn send_email(to: &Email, body: &str) -> Result<(), Error> {
-    // to is guaranteed valid
-    send_to_address(to.as_str(), body)
-}
-
-fn add_recipient(list: &mut Vec<Email>, email: Email) {
-    // email is guaranteed valid
-    list.push(email);
-}
-```
-
-## Common Validated Types
-
-```rust
-// URLs
-pub struct Url(url::Url);
-
-impl Url {
-    pub fn parse(s: &str) -> Result<Self, UrlError> {
-        url::Url::parse(s)
-            .map(Url)
-            .map_err(UrlError::from)
-    }
-}
-
-// Non-empty strings
-pub struct NonEmptyString(String);
-
-impl NonEmptyString {
-    pub fn new(s: String) -> Option<Self> {
-        if s.is_empty() {
-            None
-        } else {
-            Some(NonEmptyString(s))
-        }
-    }
-}
-
-// Positive numbers
-pub struct PositiveI32(i32);
-
-impl PositiveI32 {
-    pub fn new(n: i32) -> Option<Self> {
-        if n > 0 {
-            Some(PositiveI32(n))
-        } else {
-            None
-        }
-    }
-    
-    pub fn get(&self) -> i32 {
-        self.0
-    }
-}
-
-// Bounded ranges
-pub struct Percentage(f64);
-
-impl Percentage {
-    pub fn new(value: f64) -> Result<Self, RangeError> {
-        if (0.0..=100.0).contains(&value) {
-            Ok(Percentage(value))
-        } else {
-            Err(RangeError::OutOfBounds)
-        }
-    }
-}
-```
-
-## With Serde
-
-```rust
-use serde::{Deserialize, Serialize};
-
-#[derive(Debug, Clone, Serialize)]
-pub struct Email(String);
-
-impl<'de> Deserialize<'de> for Email {
-    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
-    where
-        D: serde::Deserializer<'de>,
-    {
-        let s = String::deserialize(deserializer)?;
-        Email::new(&s).map_err(serde::de::Error::custom)
-    }
-}
-
-// JSON deserialization automatically validates
-let email: Email = serde_json::from_str(r#""user@example.com""#)?;
-```
-
-## Compile-Time Validation
-
-```rust
-// For values known at compile time
-macro_rules! email {
-    ($s:literal) => {{
-        const _: () = assert!(is_valid_email_const($s));
-        Email::new_unchecked($s)
-    }};
-}
-
-let admin = email!("admin@example.com");  // Validated at compile time
-```
-
-## See Also
-
-- [api-parse-dont-validate](./api-parse-dont-validate.md) - Parse at boundaries
-- [api-newtype-safety](./api-newtype-safety.md) - Type-safe distinctions
-- [type-newtype-ids](./type-newtype-ids.md) - ID newtypes

package/template/agent/skills/rust-developer/references/rust-rules/type-no-stringly.md

@@ -1,144 +0,0 @@
-# type-no-stringly
-
-> Avoid stringly-typed APIs; use enums, newtypes, or validated types
-
-## Why It Matters
-
-Strings accept any value—typos, wrong formats, invalid data all compile fine. Enums, newtypes, and validated types catch errors at compile time or construction time, not runtime. They also provide better IDE support, documentation, and make invalid states unrepresentable.
-
-## Bad
-
-```rust
-// Status as string - easy to get wrong
-fn set_status(status: &str) {
-    match status {
-        "pending" => { ... }
-        "active" => { ... }
-        "completed" => { ... }
-        _ => panic!("Unknown status"),  // Runtime error
-    }
-}
-
-// Easy to misuse
-set_status("pending");   // OK
-set_status("Pending");   // Runtime error - wrong case
-set_status("aktive");    // Runtime error - typo
-set_status("done");      // Runtime error - wrong word
-
-// Configuration as strings
-fn configure(key: &str, value: &str) {
-    // No type safety, no validation
-}
-```
-
-## Good
-
-```rust
-// Status as enum - compile-time safety
-enum Status {
-    Pending,
-    Active,
-    Completed,
-}
-
-fn set_status(status: Status) {
-    match status {
-        Status::Pending => { ... }
-        Status::Active => { ... }
-        Status::Completed => { ... }
-    }  // Exhaustive - compiler checks all cases
-}
-
-// Can only pass valid values
-set_status(Status::Pending);  // OK
-set_status(Status::Aktivev);  // Compile error - typo caught!
-
-// Configuration with typed builder
-struct Config {
-    timeout: Duration,
-    retries: u32,
-    mode: Mode,
-}
-
-enum Mode { Fast, Safe, Balanced }
-```
-
-## Parsing at Boundaries
-
-```rust
-use std::str::FromStr;
-
-#[derive(Debug, Clone, Copy)]
-enum Priority {
-    Low,
-    Medium,
-    High,
-}
-
-impl FromStr for Priority {
-    type Err = ParseError;
-    
-    fn from_str(s: &str) -> Result<Self, Self::Err> {
-        match s.to_lowercase().as_str() {
-            "low" => Ok(Priority::Low),
-            "medium" | "med" => Ok(Priority::Medium),
-            "high" => Ok(Priority::High),
-            _ => Err(ParseError::UnknownPriority(s.to_string())),
-        }
-    }
-}
-
-// Parse once at boundary
-fn handle_request(priority_str: &str) -> Result<(), Error> {
-    let priority: Priority = priority_str.parse()?;
-    // From here, priority is type-safe
-    process(priority);
-    Ok(())
-}
-```
-
-## Validated Newtypes
-
-```rust
-// Instead of string for email
-struct Email(String);
-
-impl Email {
-    fn new(s: &str) -> Result<Self, ValidationError> {
-        if is_valid_email(s) {
-            Ok(Email(s.to_string()))
-        } else {
-            Err(ValidationError::InvalidEmail)
-        }
-    }
-}
-
-// Instead of string for UUID
-struct UserId(uuid::Uuid);
-
-// Instead of string for paths
-struct ConfigPath(PathBuf);
-```
-
-## With Serde
-
-```rust
-use serde::{Deserialize, Serialize};
-
-#[derive(Debug, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-enum EventType {
-    UserCreated,
-    UserDeleted,
-    UserUpdated,
-}
-
-// JSON: {"type": "user_created", ...}
-// Automatically validated during deserialization
-```
-
-## See Also
-
-- [anti-stringly-typed](./anti-stringly-typed.md) - Anti-pattern details
-- [type-newtype-validated](./type-newtype-validated.md) - Validated newtypes
-- [type-enum-states](./type-enum-states.md) - Enums for states

package/template/agent/skills/rust-developer/references/rust-rules/type-option-nullable.md

@@ -1,137 +0,0 @@
-# type-option-nullable
-
-> Use `Option<T>` for values that might not exist
-
-## Why It Matters
-
-`Option<T>` explicitly represents "value or nothing" in the type system. Unlike null pointers or sentinel values, you can't accidentally use a missing value—the compiler forces you to handle the `None` case. This eliminates null pointer exceptions at compile time.
-
-## Bad
-
-```rust
-// Sentinel values - easy to forget to check
-fn find_user(id: u64) -> User {
-    // Returns "empty" user if not found - caller might not check
-    users.get(&id).cloned().unwrap_or(User::empty())
-}
-
-// Nullable-style with raw pointers
-fn find_user(id: u64) -> *const User {
-    // Null if not found - unsafe, no compiler help
-}
-
-// Error-prone usage
-let user = find_user(42);
-println!("{}", user.name);  // Might be empty user - silent bug
-```
-
-## Good
-
-```rust
-// Option makes absence explicit
-fn find_user(id: u64) -> Option<User> {
-    users.get(&id).cloned()
-}
-
-// Must handle the None case
-let user = find_user(42);
-match user {
-    Some(u) => println!("{}", u.name),
-    None => println!("User not found"),
-}
-
-// Or use combinators
-let name = find_user(42)
-    .map(|u| u.name)
-    .unwrap_or_else(|| "Unknown".to_string());
-```
-
-## Common Option Patterns
-
-```rust
-// if let for single case
-if let Some(user) = find_user(id) {
-    process(user);
-}
-
-// Chaining with map
-let upper_name = find_user(id)
-    .map(|u| u.name)
-    .map(|n| n.to_uppercase());
-
-// Providing defaults
-let user = find_user(id).unwrap_or_default();
-let user = find_user(id).unwrap_or_else(|| User::guest());
-
-// ? operator for propagation
-fn get_user_email(id: u64) -> Option<String> {
-    let user = find_user(id)?;
-    Some(user.email)
-}
-
-// and_then for chained optionals
-fn get_user_country(id: u64) -> Option<String> {
-    find_user(id)
-        .and_then(|u| u.address)
-        .and_then(|a| a.country)
-}
-```
-
-## Struct Fields
-
-```rust
-struct User {
-    name: String,
-    email: String,
-    phone: Option<String>,        // Optional field
-    avatar_url: Option<Url>,      // Optional field
-}
-
-impl User {
-    fn display_phone(&self) -> &str {
-        self.phone.as_deref().unwrap_or("Not provided")
-    }
-}
-```
-
-## Option vs Result
-
-```rust
-// Option: value might not exist (no error context)
-fn find(key: &str) -> Option<Value> { ... }
-
-// Result: operation might fail (with error context)
-fn parse(input: &str) -> Result<Value, ParseError> { ... }
-
-// Convert Option to Result
-let value = find("key").ok_or(Error::NotFound)?;
-
-// Convert Result to Option
-let value = parse("input").ok();  // Discards error
-```
-
-## Option References
-
-```rust
-// Option<&T> for optional borrows
-fn get(&self, key: &str) -> Option<&Value> {
-    self.map.get(key)
-}
-
-// as_ref() to borrow Option contents
-let opt: Option<String> = Some("hello".to_string());
-let opt_ref: Option<&String> = opt.as_ref();
-let opt_str: Option<&str> = opt.as_deref();
-
-// as_mut() for mutable borrow
-let mut opt = Some(vec![1, 2, 3]);
-if let Some(v) = opt.as_mut() {
-    v.push(4);
-}
-```
-
-## See Also
-
-- [type-result-fallible](./type-result-fallible.md) - Result for errors
-- [type-enum-states](./type-enum-states.md) - Enums for states
-- [err-no-unwrap-prod](./err-no-unwrap-prod.md) - Handling Option safely