agy-superpowers 5.2.2 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/doc-safety-section.md

@@ -1,131 +0,0 @@
-# doc-safety-section
-
-> Include `# Safety` section for unsafe functions
-
-## Why It Matters
-
-Unsafe functions require callers to uphold invariants that the compiler cannot verify. The `# Safety` section documents exactly what the caller must guarantee for the function to be sound. Without this, users cannot safely call the function.
-
-This is not optional—it's a requirement for sound unsafe code.
-
-## Bad
-
-```rust
-/// Reads a value from a raw pointer.
-pub unsafe fn read_ptr<T>(ptr: *const T) -> T {
-    // What guarantees must the caller provide? Unknown!
-    ptr.read()
-}
-
-/// Creates a string from raw parts.
-pub unsafe fn string_from_raw(ptr: *mut u8, len: usize, cap: usize) -> String {
-    String::from_raw_parts(ptr, len, cap)
-}
-```
-
-## Good
-
-```rust
-/// Reads a value from a raw pointer.
-///
-/// # Safety
-///
-/// The caller must ensure that:
-/// - `ptr` is valid for reads of `size_of::<T>()` bytes
-/// - `ptr` is properly aligned for type `T`
-/// - `ptr` points to a properly initialized value of type `T`
-/// - The memory referenced by `ptr` is not mutated during this call
-pub unsafe fn read_ptr<T>(ptr: *const T) -> T {
-    ptr.read()
-}
-
-/// Creates a `String` from raw parts.
-///
-/// # Safety
-///
-/// The caller must guarantee that:
-/// - `ptr` was allocated by the same allocator that `String` uses
-/// - `len` is less than or equal to `cap`
-/// - The first `len` bytes at `ptr` are valid UTF-8
-/// - `cap` is the capacity that `ptr` was allocated with
-/// - No other code will use `ptr` after this call (ownership is transferred)
-///
-/// Violating these requirements leads to undefined behavior including
-/// memory corruption, use-after-free, or invalid UTF-8 in strings.
-pub unsafe fn string_from_raw(ptr: *mut u8, len: usize, cap: usize) -> String {
-    String::from_raw_parts(ptr, len, cap)
-}
-```
-
-## Key Elements of Safety Documentation
-
-| Element | Description |
-|---------|-------------|
-| **Preconditions** | What must be true before calling |
-| **Pointer validity** | Alignment, null-ness, lifetime |
-| **Memory ownership** | Who owns what, transfer semantics |
-| **Invariants** | Type invariants that must hold |
-| **Consequences** | What happens if violated |
-
-## Pattern: Unsafe Trait Implementations
-
-```rust
-/// A type that can be safely zeroed.
-///
-/// # Safety
-///
-/// Implementing this trait guarantees that:
-/// - All bit patterns of zeros represent a valid value of this type
-/// - The type has no padding bytes that could leak data
-/// - The type contains no references or pointers
-pub unsafe trait Zeroable {
-    fn zeroed() -> Self;
-}
-
-// SAFETY: u32 is a primitive integer type where all zero bits
-// represent a valid value (0).
-unsafe impl Zeroable for u32 {
-    fn zeroed() -> Self {
-        0
-    }
-}
-```
-
-## Pattern: Unsafe Blocks in Safe Functions
-
-When a safe function contains unsafe blocks, document the invariants:
-
-```rust
-/// Returns a reference to the element at the given index.
-///
-/// Returns `None` if the index is out of bounds.
-pub fn get(&self, index: usize) -> Option<&T> {
-    if index < self.len {
-        // SAFETY: We just verified that index < len, so this
-        // access is within bounds.
-        Some(unsafe { self.data.get_unchecked(index) })
-    } else {
-        None
-    }
-}
-```
-
-## Common Safety Requirements
-
-```rust
-/// # Safety
-///
-/// - Pointer must be non-null
-/// - Pointer must be aligned to `align_of::<T>()`
-/// - Pointer must be valid for reads/writes of `size_of::<T>()` bytes
-/// - Pointer must point to an initialized value of `T`
-/// - The referenced memory must not be accessed through any other pointer
-///   for the duration of the returned reference
-/// - The total size must not exceed `isize::MAX`
-```
-
-## See Also
-
-- [doc-panics-section](./doc-panics-section.md) - Documenting panics
-- [lint-unsafe-doc](./lint-unsafe-doc.md) - Enforcing unsafe documentation
-- [doc-errors-section](./doc-errors-section.md) - Documenting errors

package/template/agent/skills/rust-developer/references/rust-rules/err-anyhow-app.md

@@ -1,179 +0,0 @@
-# err-anyhow-app
-
-> Use `anyhow` for application error handling
-
-## Why It Matters
-
-Applications often don't need typed errors - they just need to report what went wrong with good context. `anyhow` provides easy error handling with context chaining, backtraces, and conversion from any error type.
-
-## Bad
-
-```rust
-// Tedious type management
-fn load_config() -> Result<Config, Box<dyn std::error::Error>> {
-    let path = find_config()?;  // Returns FindError
-    let content = std::fs::read_to_string(&path)?;  // Returns io::Error
-    let config: Config = toml::from_str(&content)?;  // Returns toml::Error
-    validate(&config)?;  // Returns ValidationError
-    Ok(config)
-}
-
-// No context - hard to debug
-fn process() -> Result<(), Box<dyn std::error::Error>> {
-    let data = fetch()?;  // Which fetch failed?
-    transform(data)?;     // What was being transformed?
-    save()?;              // Where was it saving to?
-    Ok(())
-}
-```
-
-## Good
-
-```rust
-use anyhow::{Context, Result};
-
-fn load_config() -> Result<Config> {
-    let path = find_config()
-        .context("failed to locate config file")?;
-    
-    let content = std::fs::read_to_string(&path)
-        .with_context(|| format!("failed to read config from {}", path.display()))?;
-    
-    let config: Config = toml::from_str(&content)
-        .context("failed to parse config as TOML")?;
-    
-    validate(&config)
-        .context("config validation failed")?;
-    
-    Ok(config)
-}
-
-// Error message: "config validation failed: field 'port' must be > 0"
-// Full chain preserved for debugging
-```
-
-## Key Features
-
-```rust
-use anyhow::{anyhow, bail, ensure, Context, Result};
-
-fn example() -> Result<()> {
-    // Create ad-hoc errors
-    let err = anyhow!("something went wrong");
-    
-    // Early return with error
-    bail!("aborting due to {}", reason);
-    
-    // Assert with error
-    ensure!(condition, "condition was false");
-    
-    // Add context to any error
-    risky_operation()
-        .context("risky operation failed")?;
-    
-    // Dynamic context
-    fetch(url)
-        .with_context(|| format!("failed to fetch {}", url))?;
-    
-    Ok(())
-}
-```
-
-## Main Function Pattern
-
-```rust
-use anyhow::Result;
-
-fn main() -> Result<()> {
-    let config = load_config()?;
-    run_app(config)?;
-    Ok(())
-}
-
-// Or with custom exit handling
-fn main() {
-    if let Err(e) = run() {
-        eprintln!("Error: {:#}", e);  // Pretty-print with causes
-        std::process::exit(1);
-    }
-}
-
-fn run() -> Result<()> {
-    // Application logic
-    Ok(())
-}
-```
-
-## Error Display Formats
-
-```rust
-use anyhow::Result;
-
-fn show_error(err: anyhow::Error) {
-    // Just the top-level message
-    println!("{}", err);
-    // "config validation failed"
-    
-    // With cause chain (# alternate format)
-    println!("{:#}", err);
-    // "config validation failed: field 'port' must be > 0"
-    
-    // Debug format with backtrace
-    println!("{:?}", err);
-    // Full backtrace if RUST_BACKTRACE=1
-    
-    // Iterate through cause chain
-    for cause in err.chain() {
-        println!("Caused by: {}", cause);
-    }
-}
-```
-
-## Combining with thiserror
-
-```rust
-// In your library crate - typed errors
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum ApiError {
-    #[error("rate limited")]
-    RateLimited,
-    #[error("not found: {0}")]
-    NotFound(String),
-}
-
-// In your application - anyhow for handling
-use anyhow::{Context, Result};
-
-fn fetch_user(id: u64) -> Result<User> {
-    api::get_user(id)
-        .with_context(|| format!("failed to fetch user {}", id))
-}
-
-// Can still downcast if needed
-fn handle_error(err: anyhow::Error) {
-    if let Some(api_err) = err.downcast_ref::<ApiError>() {
-        match api_err {
-            ApiError::RateLimited => wait_and_retry(),
-            ApiError::NotFound(id) => log_missing(id),
-        }
-    }
-}
-```
-
-## When to Use Which
-
-| Situation | Use |
-|-----------|-----|
-| Library public API | `thiserror` |
-| Application code | `anyhow` |
-| CLI tools | `anyhow` |
-| Internal library code | Either |
-| Need to match error variants | `thiserror` |
-| Just need to report errors | `anyhow` |
-
-## See Also
-
-- [err-thiserror-lib](err-thiserror-lib.md) - Use thiserror for libraries
-- [err-context-chain](err-context-chain.md) - Add context to errors

package/template/agent/skills/rust-developer/references/rust-rules/err-context-chain.md

@@ -1,144 +0,0 @@
-# err-context-chain
-
-> Add context with `.context()` or `.with_context()`
-
-## Why It Matters
-
-Raw errors often lack information about what operation failed. Adding context creates an error chain that tells the full story: what you were trying to do, and why it failed.
-
-## Bad
-
-```rust
-// Raw error - no context
-fn load_user(id: u64) -> Result<User, Error> {
-    let path = format!("users/{}.json", id);
-    let content = std::fs::read_to_string(&path)?;
-    Ok(serde_json::from_str(&content)?)
-}
-
-// Error message: "No such file or directory (os error 2)"
-// Which file? What were we doing?
-```
-
-## Good
-
-```rust
-use anyhow::{Context, Result};
-
-fn load_user(id: u64) -> Result<User> {
-    let path = format!("users/{}.json", id);
-    
-    let content = std::fs::read_to_string(&path)
-        .with_context(|| format!("failed to read user file: {}", path))?;
-    
-    let user: User = serde_json::from_str(&content)
-        .with_context(|| format!("failed to parse user {} JSON", id))?;
-    
-    Ok(user)
-}
-
-// Error: "failed to parse user 42 JSON"
-// Caused by: "expected ':' at line 5 column 12"
-```
-
-## context() vs with_context()
-
-```rust
-// context() - static string (slight allocation)
-fs::read_to_string(path)
-    .context("failed to read config")?;
-
-// with_context() - lazy evaluation (only allocates on error)
-fs::read_to_string(path)
-    .with_context(|| format!("failed to read {}", path))?;
-
-// Use with_context() when:
-// - Message includes runtime data (format!)
-// - Computing the message is expensive
-// - Error path is cold (most of the time)
-```
-
-## Building Context Chains
-
-```rust
-fn process_order(order_id: u64) -> Result<()> {
-    let order = fetch_order(order_id)
-        .with_context(|| format!("failed to fetch order {}", order_id))?;
-    
-    let user = load_user(order.user_id)
-        .with_context(|| format!("failed to load user for order {}", order_id))?;
-    
-    let payment = process_payment(&order, &user)
-        .context("payment processing failed")?;
-    
-    ship_order(&order, &payment)
-        .context("shipping failed")?;
-    
-    Ok(())
-}
-
-// Full error chain:
-// "shipping failed"
-// Caused by: "carrier API returned 503"
-// Caused by: "connection refused"
-```
-
-## Displaying Error Chains
-
-```rust
-fn main() {
-    if let Err(e) = run() {
-        // Just top-level message
-        eprintln!("Error: {}", e);
-        
-        // Full chain with alternate format
-        eprintln!("Error: {:#}", e);
-        
-        // Debug format (includes backtrace if enabled)
-        eprintln!("Error: {:?}", e);
-        
-        // Iterate through chain
-        for (i, cause) in e.chain().enumerate() {
-            eprintln!("  {}: {}", i, cause);
-        }
-    }
-}
-```
-
-## With thiserror
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum AppError {
-    #[error("failed to load config from {path}")]
-    ConfigLoad {
-        path: String,
-        #[source]
-        cause: std::io::Error,
-    },
-    
-    #[error("failed to connect to database")]
-    Database {
-        #[source]
-        cause: sqlx::Error,
-    },
-}
-
-// Usage
-fn load_config(path: &str) -> Result<Config, AppError> {
-    let content = std::fs::read_to_string(path)
-        .map_err(|e| AppError::ConfigLoad {
-            path: path.to_string(),
-            cause: e,
-        })?;
-    // ...
-}
-```
-
-## See Also
-
-- [err-anyhow-app](err-anyhow-app.md) - Use anyhow for applications
-- [err-source-chain](err-source-chain.md) - Use #[source] to chain errors
-- [err-question-mark](err-question-mark.md) - Use ? for propagation

package/template/agent/skills/rust-developer/references/rust-rules/err-custom-type.md

@@ -1,152 +0,0 @@
-# err-custom-type
-
-> Define custom error types for domain-specific failures
-
-## Why It Matters
-
-Generic errors like `String`, `Box<dyn Error>`, or catch-all enums obscure what can actually go wrong. Custom error types document failure modes in the type system, enable pattern matching for specific handling, and provide clear API contracts. They make your code self-documenting and help callers handle errors appropriately.
-
-## Bad
-
-```rust
-// Generic string errors - no structure
-fn validate_user(user: &User) -> Result<(), String> {
-    if user.name.is_empty() {
-        return Err("Name is empty".to_string());
-    }
-    if user.age > 150 {
-        return Err("Age is invalid".to_string());
-    }
-    Ok(())
-}
-
-// Caller can't match on specific errors
-match validate_user(&user) {
-    Ok(()) => save(user),
-    Err(msg) => {
-        // Can only do string comparison - fragile!
-        if msg.contains("Name") {
-            prompt_for_name()
-        }
-    }
-}
-```
-
-## Good
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum ValidationError {
-    #[error("name cannot be empty")]
-    EmptyName,
-    
-    #[error("name exceeds maximum length of {max} characters")]
-    NameTooLong { max: usize, actual: usize },
-    
-    #[error("invalid age {0}: must be between 0 and 150")]
-    InvalidAge(u8),
-    
-    #[error("email format is invalid: {0}")]
-    InvalidEmail(String),
-}
-
-fn validate_user(user: &User) -> Result<(), ValidationError> {
-    if user.name.is_empty() {
-        return Err(ValidationError::EmptyName);
-    }
-    if user.name.len() > 100 {
-        return Err(ValidationError::NameTooLong { 
-            max: 100, 
-            actual: user.name.len() 
-        });
-    }
-    if user.age > 150 {
-        return Err(ValidationError::InvalidAge(user.age));
-    }
-    Ok(())
-}
-
-// Caller can match specifically
-match validate_user(&user) {
-    Ok(()) => save(user),
-    Err(ValidationError::EmptyName) => prompt_for_name(),
-    Err(ValidationError::InvalidAge(age)) => {
-        show_error(&format!("Please enter a valid age (you entered {})", age))
-    }
-    Err(e) => show_error(&e.to_string()),
-}
-```
-
-## Error Type Design Guidelines
-
-```rust
-// 1. Group related errors in domain-specific enums
-#[derive(Error, Debug)]
-pub enum AuthError {
-    #[error("invalid credentials")]
-    InvalidCredentials,
-    #[error("account locked after {attempts} failed attempts")]
-    AccountLocked { attempts: u32 },
-    #[error("token expired")]
-    TokenExpired,
-}
-
-#[derive(Error, Debug)]
-pub enum PaymentError {
-    #[error("insufficient funds: need {required}, have {available}")]
-    InsufficientFunds { required: Decimal, available: Decimal },
-    #[error("card declined: {reason}")]
-    CardDeclined { reason: String },
-}
-
-// 2. Include relevant data for error handling/display
-#[derive(Error, Debug)]
-pub enum FileError {
-    #[error("file not found: {path}")]
-    NotFound { path: PathBuf },
-    #[error("permission denied for {path}")]
-    PermissionDenied { path: PathBuf },
-}
-
-// 3. Consider #[non_exhaustive] for public APIs
-#[derive(Error, Debug)]
-#[non_exhaustive]  // Allows adding variants without breaking changes
-pub enum ApiError {
-    #[error("rate limited")]
-    RateLimited,
-    #[error("not found")]
-    NotFound,
-}
-```
-
-## When to Use What
-
-| Error Pattern | Use Case |
-|---------------|----------|
-| Custom enum | Library with specific failure modes |
-| `thiserror` | Libraries needing `std::error::Error` |
-| `anyhow::Error` | Applications, prototypes |
-| Struct with source | Single error type with wrapped cause |
-
-## Struct-Based Errors
-
-For single error types with rich context:
-
-```rust
-#[derive(Error, Debug)]
-#[error("query failed for table '{table}' with filter '{filter}'")]
-pub struct QueryError {
-    pub table: String,
-    pub filter: String,
-    #[source]
-    pub source: DatabaseError,
-}
-```
-
-## See Also
-
-- [err-thiserror-lib](./err-thiserror-lib.md) - thiserror for error definitions
-- [err-anyhow-app](./err-anyhow-app.md) - When to use anyhow instead
-- [api-non-exhaustive](./api-non-exhaustive.md) - Forward-compatible enums