agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/err-question-mark.md

@@ -0,0 +1,151 @@
+# err-question-mark
+
+> Use `?` operator for clean propagation
+
+## Why It Matters
+
+The `?` operator is Rust's idiomatic way to propagate errors. It's concise, readable, and automatically converts between compatible error types using `From`. It replaces verbose `match` or `unwrap()` calls.
+
+## Bad
+
+```rust
+// Verbose match-based error handling
+fn load_config() -> Result<Config, Error> {
+    let content = match std::fs::read_to_string("config.toml") {
+        Ok(c) => c,
+        Err(e) => return Err(Error::Io(e)),
+    };
+    
+    let config = match toml::from_str(&content) {
+        Ok(c) => c,
+        Err(e) => return Err(Error::Parse(e)),
+    };
+    
+    Ok(config)
+}
+
+// Or worse - using unwrap
+fn load_config_bad() -> Config {
+    let content = std::fs::read_to_string("config.toml").unwrap();
+    toml::from_str(&content).unwrap()
+}
+```
+
+## Good
+
+```rust
+fn load_config() -> Result<Config, Error> {
+    let content = std::fs::read_to_string("config.toml")?;
+    let config = toml::from_str(&content)?;
+    Ok(config)
+}
+
+// Even more concise
+fn load_config() -> Result<Config, Error> {
+    Ok(toml::from_str(&std::fs::read_to_string("config.toml")?)?)
+}
+```
+
+## How ? Works
+
+```rust
+// This:
+let x = expr?;
+
+// Expands roughly to:
+let x = match expr {
+    Ok(val) => val,
+    Err(err) => return Err(From::from(err)),
+};
+```
+
+## Combining with Context
+
+```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)
+        .context("failed to parse user JSON")?;
+    
+    Ok(user)
+}
+```
+
+## ? with Option
+
+```rust
+fn get_first_word(text: &str) -> Option<&str> {
+    let first_line = text.lines().next()?;
+    let first_word = first_line.split_whitespace().next()?;
+    Some(first_word)
+}
+
+// Convert Option to Result
+fn get_required_config(key: &str) -> Result<String, Error> {
+    config.get(key)
+        .cloned()
+        .ok_or_else(|| Error::MissingConfig(key.to_string()))
+}
+```
+
+## Error Type Conversion
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+enum MyError {
+    #[error("io error")]
+    Io(#[from] std::io::Error),  // Auto From impl
+    
+    #[error("parse error")]
+    Parse(#[from] serde_json::Error),  // Auto From impl
+}
+
+fn process() -> Result<(), MyError> {
+    // ? automatically converts io::Error to MyError via From
+    let content = std::fs::read_to_string("file.txt")?;
+    
+    // ? automatically converts serde_json::Error to MyError
+    let data: Data = serde_json::from_str(&content)?;
+    
+    Ok(())
+}
+```
+
+## In main()
+
+```rust
+// Option 1: Return Result from main
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let config = load_config()?;
+    run_app(config)?;
+    Ok(())
+}
+
+// Option 2: Handle in main, exit on error
+fn main() {
+    if let Err(e) = run() {
+        eprintln!("Error: {:#}", e);
+        std::process::exit(1);
+    }
+}
+
+fn run() -> anyhow::Result<()> {
+    let config = load_config()?;
+    run_app(config)?;
+    Ok(())
+}
+```
+
+## See Also
+
+- [err-context-chain](err-context-chain.md) - Add context with .context()
+- [err-from-impl](err-from-impl.md) - Use #[from] for automatic conversion
+- [err-anyhow-app](err-anyhow-app.md) - Use anyhow for applications

package/template/agent/skills/rust-developer/references/rust-rules/err-result-over-panic.md

@@ -0,0 +1,130 @@
+# err-result-over-panic
+
+> Return `Result<T, E>` instead of panicking for recoverable errors
+
+## Why It Matters
+
+Panics unwind the stack and crash the thread (or program). They're unrecoverable from the caller's perspective. `Result<T, E>` gives callers the ability to decide how to handle errors—retry, fallback, propagate, or log. Libraries should almost never panic; applications should minimize panics to truly unrecoverable situations.
+
+## Bad
+
+```rust
+fn parse_config(path: &str) -> Config {
+    let content = std::fs::read_to_string(path)
+        .expect("Failed to read config");  // Crashes on missing file
+    
+    serde_json::from_str(&content)
+        .expect("Invalid config format")   // Crashes on bad JSON
+}
+
+fn divide(a: i32, b: i32) -> i32 {
+    if b == 0 {
+        panic!("Division by zero!");  // Crashes the program
+    }
+    a / b
+}
+```
+
+Caller has no chance to recover or provide a fallback.
+
+## Good
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+enum ConfigError {
+    #[error("Failed to read config file: {0}")]
+    Io(#[from] std::io::Error),
+    #[error("Invalid config format: {0}")]
+    Parse(#[from] serde_json::Error),
+}
+
+fn parse_config(path: &str) -> Result<Config, ConfigError> {
+    let content = std::fs::read_to_string(path)?;
+    let config = serde_json::from_str(&content)?;
+    Ok(config)
+}
+
+fn divide(a: i32, b: i32) -> Result<i32, &'static str> {
+    if b == 0 {
+        return Err("Division by zero");
+    }
+    Ok(a / b)
+}
+
+// Caller decides how to handle
+match parse_config("app.json") {
+    Ok(config) => run_app(config),
+    Err(e) => {
+        eprintln!("Using default config: {}", e);
+        run_app(Config::default())
+    }
+}
+```
+
+## When Panic IS Appropriate
+
+```rust
+// 1. Bug in the program (invariant violation)
+fn get_cached_value(&self, key: &str) -> &Value {
+    self.cache.get(key).expect("BUG: key was verified to exist")
+}
+
+// 2. Setup/initialization that can't reasonably fail
+fn main() {
+    let config = Config::load().expect("Failed to load required config");
+    // Can't run without config, panic is reasonable
+}
+
+// 3. Tests
+#[test]
+fn test_parse() {
+    let result = parse("valid input").unwrap(); // unwrap OK in tests
+    assert_eq!(result, expected);
+}
+
+// 4. Examples and prototypes
+fn main() {
+    // Quick prototype, panic is fine
+    let data = fetch_data().unwrap();
+}
+```
+
+## Panic vs Result Decision Guide
+
+| Situation | Use |
+|-----------|-----|
+| File not found | `Result` |
+| Network error | `Result` |
+| Invalid user input | `Result` |
+| Parse error | `Result` |
+| Index out of bounds (from user data) | `Result` |
+| Index out of bounds (internal bug) | Panic |
+| Violated internal invariant | Panic |
+| Unimplemented code path | Panic (`unimplemented!()`) |
+| Impossible state reached | Panic (`unreachable!()`) |
+
+## Library vs Application
+
+```rust
+// Library: NEVER panic on user input
+pub fn parse(input: &str) -> Result<Ast, ParseError> {
+    // Always return Result
+}
+
+// Application: Can panic at top level for critical failures
+fn main() {
+    if let Err(e) = run() {
+        eprintln!("Fatal error: {}", e);
+        std::process::exit(1);
+    }
+}
+```
+
+## See Also
+
+- [err-thiserror-lib](./err-thiserror-lib.md) - Define error types for libraries
+- [err-anyhow-app](./err-anyhow-app.md) - Ergonomic errors for applications
+- [err-no-unwrap-prod](./err-no-unwrap-prod.md) - Avoid unwrap in production code
+- [anti-unwrap-abuse](./anti-unwrap-abuse.md) - When unwrap is acceptable

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

@@ -0,0 +1,155 @@
+# err-source-chain
+
+> Preserve error chains with `#[source]` or `source()` method
+
+## Why It Matters
+
+Errors often have underlying causes. Preserving the error chain (via `source()` method) allows logging frameworks and error reporters to show the full context: "config parse failed → JSON syntax error at line 5 → unexpected token". Without chaining, you lose valuable debugging information.
+
+## Bad
+
+```rust
+#[derive(Debug)]
+enum ConfigError {
+    ParseFailed(String),  // Lost the original serde_json::Error
+}
+
+fn load_config(path: &str) -> Result<Config, ConfigError> {
+    let content = std::fs::read_to_string(path)
+        .map_err(|e| ConfigError::ParseFailed(e.to_string()))?;  // Chain lost!
+    
+    serde_json::from_str(&content)
+        .map_err(|e| ConfigError::ParseFailed(e.to_string()))?  // No source
+}
+
+// Error output: "Parse failed: invalid type: ..."
+// Missing: which file? what line? what was the parent error?
+```
+
+## Good
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+enum ConfigError {
+    #[error("Failed to read config file '{path}'")]
+    ReadFailed {
+        path: String,
+        #[source]  // Preserves the error chain
+        source: std::io::Error,
+    },
+    
+    #[error("Failed to parse config file '{path}'")]
+    ParseFailed {
+        path: String,
+        #[source]  // Original parse error preserved
+        source: serde_json::Error,
+    },
+}
+
+fn load_config(path: &str) -> Result<Config, ConfigError> {
+    let content = std::fs::read_to_string(path)
+        .map_err(|source| ConfigError::ReadFailed {
+            path: path.to_string(),
+            source,  // Chain preserved
+        })?;
+    
+    serde_json::from_str(&content)
+        .map_err(|source| ConfigError::ParseFailed {
+            path: path.to_string(),
+            source,
+        })
+}
+```
+
+## Manual source() Implementation
+
+```rust
+use std::error::Error;
+
+#[derive(Debug)]
+struct MyError {
+    message: String,
+    source: Option<Box<dyn Error + Send + Sync>>,
+}
+
+impl std::fmt::Display for MyError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.message)
+    }
+}
+
+impl Error for MyError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        self.source.as_ref().map(|e| e.as_ref() as &(dyn Error + 'static))
+    }
+}
+```
+
+## Walking the Error Chain
+
+```rust
+fn print_error_chain(error: &dyn std::error::Error) {
+    eprintln!("Error: {}", error);
+    
+    let mut source = error.source();
+    while let Some(err) = source {
+        eprintln!("Caused by: {}", err);
+        source = err.source();
+    }
+}
+
+// With anyhow, use {:?} for full chain
+let result: anyhow::Result<()> = do_something();
+if let Err(e) = result {
+    eprintln!("{:?}", e);  // Prints full chain with backtraces
+}
+```
+
+## anyhow Context
+
+```rust
+use anyhow::{Context, Result};
+
+fn load_config(path: &str) -> Result<Config> {
+    let content = std::fs::read_to_string(path)
+        .with_context(|| format!("Failed to read '{}'", path))?;
+    
+    let config: Config = serde_json::from_str(&content)
+        .with_context(|| format!("Failed to parse '{}'", path))?;
+    
+    Ok(config)
+}
+
+// Output:
+// Error: Failed to parse 'config.json'
+// Caused by: expected `:` at line 5 column 10
+```
+
+## #[from] vs #[source]
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+enum MyError {
+    // #[from] = implements From + sets source
+    #[error("IO error")]
+    Io(#[from] std::io::Error),
+    
+    // #[source] = only sets source (no From impl)
+    #[error("Parse error in file '{path}'")]
+    Parse {
+        path: String,
+        #[source]
+        source: serde_json::Error,
+    },
+}
+```
+
+## See Also
+
+- [err-thiserror-lib](./err-thiserror-lib.md) - thiserror for error definitions
+- [err-context-chain](./err-context-chain.md) - Adding context to errors
+- [err-from-impl](./err-from-impl.md) - From implementations for ?

package/template/agent/skills/rust-developer/references/rust-rules/err-thiserror-lib.md

@@ -0,0 +1,171 @@
+# err-thiserror-lib
+
+> Use `thiserror` for library error types
+
+## Why It Matters
+
+Libraries should expose typed, matchable errors so users can handle specific error conditions. `thiserror` generates `Error` trait implementations with minimal boilerplate, creating ergonomic error types that are easy to match against.
+
+## Bad
+
+```rust
+// String errors - not matchable
+fn parse(input: &str) -> Result<Data, String> {
+    Err("parse error".to_string())
+}
+
+// Box<dyn Error> - not matchable
+fn load(path: &Path) -> Result<Data, Box<dyn std::error::Error>> {
+    Err(Box::new(std::io::Error::new(std::io::ErrorKind::NotFound, "file not found")))
+}
+
+// Manual implementation - verbose
+#[derive(Debug)]
+enum MyError {
+    Io(std::io::Error),
+    Parse(String),
+}
+
+impl std::fmt::Display for MyError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            MyError::Io(e) => write!(f, "io error: {}", e),
+            MyError::Parse(s) => write!(f, "parse error: {}", s),
+        }
+    }
+}
+
+impl std::error::Error for MyError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            MyError::Io(e) => Some(e),
+            MyError::Parse(_) => None,
+        }
+    }
+}
+```
+
+## Good
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum ParseError {
+    #[error("invalid syntax at line {line}: {message}")]
+    Syntax { line: usize, message: String },
+    
+    #[error("unexpected end of file")]
+    UnexpectedEof,
+    
+    #[error("invalid utf-8 encoding")]
+    Utf8(#[from] std::str::Utf8Error),
+    
+    #[error("io error reading input")]
+    Io(#[from] std::io::Error),
+}
+
+// Usage
+fn parse(input: &str) -> Result<Ast, ParseError> {
+    if input.is_empty() {
+        return Err(ParseError::UnexpectedEof);
+    }
+    // ...
+}
+
+// Users can match specific errors
+match parse(input) {
+    Ok(ast) => process(ast),
+    Err(ParseError::Syntax { line, message }) => {
+        eprintln!("Syntax error on line {}: {}", line, message);
+    }
+    Err(ParseError::UnexpectedEof) => {
+        eprintln!("File ended unexpectedly");
+    }
+    Err(e) => eprintln!("Error: {}", e),
+}
+```
+
+## Key Attributes
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum MyError {
+    // Simple message
+    #[error("operation failed")]
+    Failed,
+    
+    // Interpolated fields
+    #[error("invalid value: {0}")]
+    InvalidValue(String),
+    
+    // Named fields
+    #[error("connection to {host}:{port} failed")]
+    Connection { host: String, port: u16 },
+    
+    // Automatic From impl with #[from]
+    #[error("database error")]
+    Database(#[from] sqlx::Error),
+    
+    // Source without From (manual conversion needed)
+    #[error("validation failed")]
+    Validation {
+        #[source]
+        cause: ValidationError,
+        field: String,
+    },
+    
+    // Transparent - delegates Display and source to inner
+    #[error(transparent)]
+    Other(#[from] anyhow::Error),
+}
+```
+
+## Error Chaining
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum ConfigError {
+    #[error("failed to read config file")]
+    Read(#[source] std::io::Error),
+    
+    #[error("failed to parse config")]
+    Parse(#[source] toml::de::Error),
+    
+    #[error("invalid config value for '{key}'")]
+    InvalidValue {
+        key: String,
+        #[source]
+        cause: ValueError,
+    },
+}
+
+// Error chain is preserved
+fn load_config(path: &Path) -> Result<Config, ConfigError> {
+    let content = std::fs::read_to_string(path)
+        .map_err(ConfigError::Read)?;
+    
+    let config: Config = toml::from_str(&content)
+        .map_err(ConfigError::Parse)?;
+    
+    Ok(config)
+}
+```
+
+## Library vs Application
+
+| Context | Crate | Why |
+|---------|-------|-----|
+| Library | `thiserror` | Typed errors users can match |
+| Application | `anyhow` | Easy error handling with context |
+| Both | `thiserror` for public API, `anyhow` internally | Best of both |
+
+## See Also
+
+- [err-anyhow-app](err-anyhow-app.md) - Use anyhow for applications
+- [err-from-impl](err-from-impl.md) - Use #[from] for automatic conversion
+- [err-source-chain](err-source-chain.md) - Use #[source] to chain errors