agy-superpowers 5.2.2 → 5.2.3

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

package/template/agent/skills/rust-developer/references/rust-rules/type-phantom-marker.md

@@ -1,188 +0,0 @@
-# type-phantom-marker
-
-> Use `PhantomData` to express type relationships without runtime cost
-
-## Why It Matters
-
-Sometimes your type needs to be parameterized by a type that doesn't appear in any field—for variance, drop order, or semantic purposes. `PhantomData<T>` tells the compiler your type is "associated with" `T` without storing any `T` data. It has zero runtime cost.
-
-## Bad
-
-```rust
-// Type parameter unused - compiler error
-struct Handle<T> {
-    id: u64,
-    // Error: parameter `T` is never used
-}
-
-// Workaround with unnecessary storage
-struct Handle<T> {
-    id: u64,
-    _type: Option<T>,  // Wastes memory, requires T: Default
-}
-```
-
-## Good
-
-```rust
-use std::marker::PhantomData;
-
-struct Handle<T> {
-    id: u64,
-    _marker: PhantomData<T>,  // Zero-size, tells compiler about T
-}
-
-impl<T> Handle<T> {
-    fn new(id: u64) -> Self {
-        Handle {
-            id,
-            _marker: PhantomData,
-        }
-    }
-}
-
-// Different Handle types are incompatible
-struct User;
-struct Order;
-
-fn process_user(h: Handle<User>) { ... }
-
-let user_handle = Handle::<User>::new(1);
-let order_handle = Handle::<Order>::new(2);
-
-process_user(user_handle);   // OK
-process_user(order_handle);  // Error: expected Handle<User>, found Handle<Order>
-```
-
-## Expressing Ownership
-
-```rust
-use std::marker::PhantomData;
-
-// Owns T conceptually (like Box<T>)
-struct Container<T> {
-    ptr: *mut T,
-    _marker: PhantomData<T>,  // Acts like we own a T
-}
-
-// Drop will be called on T when Container drops
-impl<T> Drop for Container<T> {
-    fn drop(&mut self) {
-        unsafe {
-            std::ptr::drop_in_place(self.ptr);
-        }
-    }
-}
-```
-
-## Expressing Borrowing
-
-```rust
-use std::marker::PhantomData;
-
-// Borrows T for lifetime 'a
-struct Ref<'a, T> {
-    ptr: *const T,
-    _marker: PhantomData<&'a T>,  // Acts like &'a T
-}
-
-// Compiler tracks lifetime correctly
-impl<'a, T> Ref<'a, T> {
-    fn get(&self) -> &'a T {
-        unsafe { &*self.ptr }
-    }
-}
-```
-
-## Type-Level State Machine
-
-```rust
-use std::marker::PhantomData;
-
-// States as zero-size types
-struct Unlocked;
-struct Locked;
-
-struct Door<State> {
-    _state: PhantomData<State>,
-}
-
-impl Door<Unlocked> {
-    fn lock(self) -> Door<Locked> {
-        println!("Locking...");
-        Door { _state: PhantomData }
-    }
-    
-    fn open(&self) {
-        println!("Opening...");
-    }
-}
-
-impl Door<Locked> {
-    fn unlock(self) -> Door<Unlocked> {
-        println!("Unlocking...");
-        Door { _state: PhantomData }
-    }
-    
-    // Can't call open() on Locked door - method doesn't exist
-}
-
-fn example() {
-    let door: Door<Unlocked> = Door { _state: PhantomData };
-    door.open();           // OK
-    let locked = door.lock();
-    // locked.open();      // Error: no method `open` for Door<Locked>
-    let unlocked = locked.unlock();
-    unlocked.open();       // OK
-}
-```
-
-## Variance Control
-
-```rust
-use std::marker::PhantomData;
-
-// Covariant in T (PhantomData<T>)
-struct Producer<T> {
-    _marker: PhantomData<T>,  // Covariant
-}
-
-// Contravariant in T (PhantomData<fn(T)>)
-struct Consumer<T> {
-    _marker: PhantomData<fn(T)>,  // Contravariant
-}
-
-// Invariant in T (PhantomData<fn(T) -> T>)
-struct Both<T> {
-    _marker: PhantomData<fn(T) -> T>,  // Invariant
-}
-```
-
-## Common Uses
-
-```rust
-// 1. FFI handles with type safety
-struct FileHandle<T: FileType> {
-    fd: i32,
-    _marker: PhantomData<T>,
-}
-
-// 2. Generic iterators
-struct Iter<'a, T> {
-    ptr: *const T,
-    end: *const T,
-    _marker: PhantomData<&'a T>,
-}
-
-// 3. Allocator-aware types
-struct Vec<T, A: Allocator = Global> {
-    buf: RawVec<T, A>,
-    len: usize,
-}
-```
-
-## See Also
-
-- [api-typestate](./api-typestate.md) - State machine pattern
-- [api-newtype-safety](./api-newtype-safety.md) - Type-safe wrappers
-- [type-newtype-ids](./type-newtype-ids.md) - ID types

package/template/agent/skills/rust-developer/references/rust-rules/type-repr-transparent.md

@@ -1,143 +0,0 @@
-# type-repr-transparent
-
-> Use `#[repr(transparent)]` for newtypes in FFI contexts
-
-## Why It Matters
-
-`#[repr(transparent)]` guarantees a newtype has the same memory layout as its inner type. This is essential for FFI where you need type safety in Rust but must match C ABI layouts. Without it, the compiler may add padding or change layout.
-
-## Bad
-
-```rust
-// No layout guarantee - might not match inner type in FFI
-struct Handle(u64);
-
-// Passing to C code might fail
-extern "C" {
-    fn process_handle(h: Handle);  // May not work correctly
-}
-
-// Wrapping C type without layout guarantee
-struct SafePointer(*mut c_void);
-```
-
-## Good
-
-```rust
-// Guaranteed same layout as inner type
-#[repr(transparent)]
-struct Handle(u64);
-
-// Safe for FFI
-extern "C" {
-    fn process_handle(h: Handle);  // Works - same layout as u64
-}
-
-// FFI pointer wrapper
-#[repr(transparent)]
-struct SafePointer(*mut c_void);
-
-impl SafePointer {
-    // Safe Rust API around raw pointer
-    pub fn new(ptr: *mut c_void) -> Option<Self> {
-        if ptr.is_null() {
-            None
-        } else {
-            Some(SafePointer(ptr))
-        }
-    }
-}
-```
-
-## What repr(transparent) Guarantees
-
-```rust
-use std::mem::{size_of, align_of};
-
-#[repr(transparent)]
-struct Meters(f64);
-
-// Same size
-assert_eq!(size_of::<Meters>(), size_of::<f64>());
-
-// Same alignment
-assert_eq!(align_of::<Meters>(), align_of::<f64>());
-
-// Same ABI - can pass where f64 expected
-extern "C" fn measure(distance: Meters) { ... }
-```
-
-## With PhantomData
-
-```rust
-use std::marker::PhantomData;
-
-// PhantomData is zero-sized, doesn't affect layout
-#[repr(transparent)]
-struct TypedHandle<T> {
-    raw: u64,
-    _marker: PhantomData<T>,  // Zero-sized, ignored for layout
-}
-
-// Still same layout as u64
-assert_eq!(size_of::<TypedHandle<String>>(), size_of::<u64>());
-```
-
-## NonZero Wrappers
-
-```rust
-use std::num::NonZeroU64;
-
-#[repr(transparent)]
-struct NonZeroHandle(NonZeroU64);
-
-// Inherits null-pointer optimization
-assert_eq!(size_of::<Option<NonZeroHandle>>(), size_of::<u64>());
-```
-
-## FFI Pattern
-
-```rust
-mod ffi {
-    use std::os::raw::c_int;
-    
-    #[repr(transparent)]
-    pub struct FileDescriptor(c_int);
-    
-    extern "C" {
-        pub fn open(path: *const i8, flags: c_int) -> FileDescriptor;
-        pub fn close(fd: FileDescriptor) -> c_int;
-        pub fn read(fd: FileDescriptor, buf: *mut u8, len: usize) -> isize;
-    }
-}
-
-// Safe wrapper
-pub struct File {
-    fd: ffi::FileDescriptor,
-}
-
-impl File {
-    pub fn open(path: &str) -> std::io::Result<Self> {
-        let c_path = std::ffi::CString::new(path)?;
-        let fd = unsafe { ffi::open(c_path.as_ptr(), 0) };
-        // ... error handling
-        Ok(File { fd })
-    }
-}
-```
-
-## When to Use
-
-| Scenario | Use `#[repr(transparent)]`? |
-|----------|----------------------------|
-| FFI newtype wrappers | Yes |
-| Type-safe handles | Yes |
-| NonZero optimization | Yes |
-| Pure Rust newtypes | Optional (doesn't hurt) |
-| Multi-field structs | N/A (only for single-field) |
-
-## See Also
-
-- [type-newtype-ids](./type-newtype-ids.md) - Newtype pattern
-- [type-phantom-marker](./type-phantom-marker.md) - PhantomData usage
-- [api-newtype-safety](./api-newtype-safety.md) - Type-safe newtypes

package/template/agent/skills/rust-developer/references/rust-rules/type-result-fallible.md

@@ -1,131 +0,0 @@
-# type-result-fallible
-
-> Use `Result<T, E>` for operations that can fail
-
-## Why It Matters
-
-`Result<T, E>` makes failure explicit in the type system. Callers must acknowledge and handle potential errors—they can't accidentally ignore failures. The `?` operator makes error propagation ergonomic while maintaining explicit error handling.
-
-## Bad
-
-```rust
-// Returning Option loses error context
-fn read_config(path: &str) -> Option<Config> {
-    let content = std::fs::read_to_string(path).ok()?;  // Why did it fail?
-    toml::from_str(&content).ok()  // Parse error lost
-}
-
-// Panicking on errors
-fn read_config(path: &str) -> Config {
-    let content = std::fs::read_to_string(path).unwrap();  // Crashes
-    toml::from_str(&content).unwrap()  // Crashes
-}
-
-// Sentinel values
-fn divide(a: i32, b: i32) -> i32 {
-    if b == 0 { return -1; }  // Magic value, easy to miss
-    a / b
-}
-```
-
-## Good
-
-```rust
-// Result with clear error type
-fn read_config(path: &str) -> Result<Config, ConfigError> {
-    let content = std::fs::read_to_string(path)
-        .map_err(ConfigError::IoError)?;
-    toml::from_str(&content)
-        .map_err(ConfigError::ParseError)
-}
-
-fn divide(a: i32, b: i32) -> Result<i32, DivisionError> {
-    if b == 0 {
-        return Err(DivisionError::DivideByZero);
-    }
-    Ok(a / b)
-}
-
-// Caller must handle
-match divide(10, 0) {
-    Ok(result) => println!("Result: {}", result),
-    Err(e) => println!("Error: {}", e),
-}
-```
-
-## The ? Operator
-
-```rust
-fn process_file(path: &str) -> Result<ProcessedData, Error> {
-    let content = std::fs::read_to_string(path)?;  // Propagates Err
-    let parsed: RawData = serde_json::from_str(&content)?;
-    let validated = validate(parsed)?;
-    let processed = transform(validated)?;
-    Ok(processed)
-}
-
-// Equivalent to:
-fn process_file(path: &str) -> Result<ProcessedData, Error> {
-    let content = match std::fs::read_to_string(path) {
-        Ok(c) => c,
-        Err(e) => return Err(e.into()),
-    };
-    // ... etc
-}
-```
-
-## Result Combinators
-
-```rust
-let result: Result<i32, Error> = Ok(42);
-
-// map: transform success value
-let doubled = result.map(|n| n * 2);  // Ok(84)
-
-// map_err: transform error
-let with_context = result.map_err(|e| format!("Failed: {}", e));
-
-// and_then: chain fallible operations
-let processed = result.and_then(|n| {
-    if n > 0 { Ok(n * 2) } else { Err(Error::Negative) }
-});
-
-// unwrap_or: provide default on error
-let value = result.unwrap_or(0);
-
-// ok(): convert to Option, discarding error
-let maybe_value: Option<i32> = result.ok();
-```
-
-## Defining Error Types
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum ConfigError {
-    #[error("failed to read file: {0}")]
-    Io(#[from] std::io::Error),
-    
-    #[error("failed to parse config: {0}")]
-    Parse(#[from] toml::de::Error),
-    
-    #[error("missing required field: {0}")]
-    MissingField(String),
-}
-
-fn load_config(path: &str) -> Result<Config, ConfigError> {
-    let content = std::fs::read_to_string(path)?;  // Io error
-    let config: Config = toml::from_str(&content)?;  // Parse error
-    if config.name.is_empty() {
-        return Err(ConfigError::MissingField("name".into()));
-    }
-    Ok(config)
-}
-```
-
-## See Also
-
-- [err-thiserror-lib](./err-thiserror-lib.md) - Defining error types
-- [err-question-mark](./err-question-mark.md) - Using ? operator
-- [type-option-nullable](./type-option-nullable.md) - Option vs Result