agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/type-never-diverge.md

@@ -0,0 +1,146 @@
+# type-never-diverge
+
+> Use `!` (never type) for functions that never return
+
+## Why It Matters
+
+The never type `!` indicates a function will never return normally—it either loops forever, panics, or exits the process. This helps the compiler understand control flow and enables `!` to coerce to any type, making it useful in match arms and expressions.
+
+## Bad
+
+```rust
+// Return type doesn't indicate non-returning
+fn infinite_loop() {
+    loop {
+        process_events();
+    }
+    // Implicit () return type, but never returns
+}
+
+// Using Option when it always panics
+fn unreachable_code() -> Option<()> {
+    panic!("This should never be called");
+}
+```
+
+## Good
+
+```rust
+// ! indicates function never returns
+fn infinite_loop() -> ! {
+    loop {
+        process_events();
+    }
+}
+
+fn abort_with_error(msg: &str) -> ! {
+    eprintln!("Fatal error: {}", msg);
+    std::process::exit(1);
+}
+
+fn panic_handler() -> ! {
+    panic!("Unexpected state");
+}
+```
+
+## Coercion to Any Type
+
+```rust
+// ! coerces to any type
+fn get_value(opt: Option<i32>) -> i32 {
+    match opt {
+        Some(v) => v,
+        None => panic!("No value"),  // panic! returns !, coerces to i32
+    }
+}
+
+// Useful in Result handling
+fn must_get_config() -> Config {
+    match load_config() {
+        Ok(c) => c,
+        Err(e) => {
+            log_error(&e);
+            std::process::exit(1)  // Returns !, coerces to Config
+        }
+    }
+}
+```
+
+## Standard Library Examples
+
+```rust
+// std::process::exit
+pub fn exit(code: i32) -> !
+
+// panic! macro
+// Expands to an expression of type !
+
+// std::hint::unreachable_unchecked
+pub unsafe fn unreachable_unchecked() -> !
+
+// loop {} with no break
+fn forever() -> ! {
+    loop {}
+}
+```
+
+## In Match Expressions
+
+```rust
+enum State {
+    Running,
+    Stopped,
+    Error,
+}
+
+fn get_status(state: &State) -> &str {
+    match state {
+        State::Running => "running",
+        State::Stopped => "stopped",
+        State::Error => unreachable!(),  // ! coerces to &str
+    }
+}
+
+// With Result
+fn process(r: Result<Data, Error>) -> Data {
+    match r {
+        Ok(d) => d,
+        Err(e) => panic!("Unexpected error: {}", e),  // ! coerces to Data
+    }
+}
+```
+
+## Diverging Closures
+
+```rust
+// Closures that never return
+let handler: fn() -> ! = || {
+    panic!("Handler called");
+};
+
+// In thread spawn
+std::thread::spawn(|| -> ! {
+    loop {
+        process_work();
+    }
+});
+```
+
+## Current Limitations (Nightly)
+
+```rust
+// Full ! type is nightly
+#![feature(never_type)]
+
+// Can use ! as type parameter
+type NeverResult = Result<(), !>;  // Can never be Err
+
+// On stable, use std::convert::Infallible
+type StableNeverResult = Result<(), std::convert::Infallible>;
+```
+
+## See Also
+
+- [err-result-over-panic](./err-result-over-panic.md) - When to panic vs return Result
+- [type-result-fallible](./type-result-fallible.md) - Result for errors
+- [opt-cold-unlikely](./opt-cold-unlikely.md) - Marking unlikely paths

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

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

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

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