agy-superpowers 5.1.4 → 5.1.5

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

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

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

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