agy-superpowers 5.2.1 → 5.2.3

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

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

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

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

package/template/agent/skills/rust-developer/references/rust-rules/lint-cargo-metadata.md

@@ -1,138 +0,0 @@
-# lint-cargo-metadata
-
-> Enable clippy::cargo for published crates
-
-## Why It Matters
-
-The `clippy::cargo` lint group checks Cargo.toml for issues that affect publishing and dependency management. For crates intended for crates.io, these checks help ensure a professional, well-configured package.
-
-## Configuration
-
-```toml
-# Cargo.toml
-[lints.clippy]
-cargo = "warn"
-```
-
-Or in code:
-
-```rust
-#![warn(clippy::cargo)]
-```
-
-## What It Catches
-
-### Missing Metadata
-
-```toml
-# WARN: missing package.description
-# WARN: missing package.license or package.license-file
-# WARN: missing package.repository
-[package]
-name = "my-crate"
-version = "0.1.0"
-```
-
-### Dependency Issues
-
-```toml
-# WARN: feature used but not defined
-# WARN: dependency version not specified
-[dependencies]
-serde = "*"  # Bad: any version
-tokio = { git = "..." }  # WARN for published crates
-```
-
-### Feature Issues
-
-```toml
-# WARN: negative_feature_names
-[features]
-no-std = []  # Should be: std = [] (opt-out vs opt-in)
-
-# WARN: redundant_feature_names
-[features]
-default = ["feature-a"]
-feature-a = []  # Feature name matches crate name
-```
-
-## Notable Lints
-
-| Lint | Issue |
-|------|-------|
-| `cargo_common_metadata` | Missing description/license/repository |
-| `multiple_crate_versions` | Same crate at different versions |
-| `negative_feature_names` | Features like `no-std` instead of `std` |
-| `redundant_feature_names` | Feature same as crate name |
-| `wildcard_dependencies` | Using `*` for version |
-
-## Complete Cargo.toml
-
-```toml
-[package]
-name = "my-crate"
-version = "0.1.0"
-edition = "2021"
-rust-version = "1.70"
-
-# Required for cargo lint satisfaction
-description = "A short description of what this crate does"
-license = "MIT OR Apache-2.0"
-repository = "https://github.com/user/my-crate"
-
-# Recommended
-documentation = "https://docs.rs/my-crate"
-readme = "README.md"
-keywords = ["keyword1", "keyword2"]
-categories = ["category-slug"]
-
-[dependencies]
-# Specific versions, not wildcards
-serde = "1.0"
-tokio = { version = "1.0", features = ["full"] }
-
-[features]
-default = ["std"]
-std = []  # Opt-out, not no-std opt-in
-
-[lints.clippy]
-cargo = "warn"
-```
-
-## Multiple Crate Versions
-
-```
-# WARN: multiple versions of `syn` in dependency tree
-# syn v1.0.109
-# syn v2.0.48
-```
-
-Fix by updating dependencies or using `[patch]`:
-
-```toml
-[patch.crates-io]
-old-dep = { git = "...", branch = "syn-2" }
-```
-
-## When to Disable
-
-For internal/unpublished crates:
-
-```toml
-[lints.clippy]
-cargo = "allow"  # Not publishing, metadata not needed
-```
-
-Or selectively:
-
-```toml
-[lints.clippy]
-cargo = "warn"
-multiple_crate_versions = "allow"  # Acceptable in this project
-```
-
-## See Also
-
-- [doc-cargo-metadata](./doc-cargo-metadata.md) - Cargo.toml metadata
-- [proj-workspace-deps](./proj-workspace-deps.md) - Workspace dependencies
-- [lint-deny-correctness](./lint-deny-correctness.md) - Correctness lints

package/template/agent/skills/rust-developer/references/rust-rules/lint-deny-correctness.md

@@ -1,107 +0,0 @@
-# lint-deny-correctness
-
-> `#![deny(clippy::correctness)]`
-
-## Why It Matters
-
-Clippy's correctness lints catch code that is outright wrong - logic errors, undefined behavior, or code that doesn't do what you think. These should always be errors, not warnings.
-
-## Setup
-
-```rust
-// At the top of lib.rs or main.rs
-#![deny(clippy::correctness)]
-
-// Or in Cargo.toml for workspace-wide
-[lints.clippy]
-correctness = "deny"
-```
-
-## What It Catches
-
-```rust
-// Infinite loop (iter::repeat without take)
-for x in std::iter::repeat(1) {  // ERROR: infinite iterator
-    println!("{}", x);
-}
-
-// Comparison to NaN (always false)
-if x == f64::NAN {  // ERROR: NaN != NaN always
-    // This never executes
-}
-
-// Use after free patterns
-let r;
-{
-    let x = 5;
-    r = &x;  // ERROR: x dropped here
-}
-println!("{}", r);
-
-// Wrong equality check
-if x = 5 {  // ERROR: assignment in condition (should be ==)
-}
-
-// Useless comparisons
-if x >= 0 && x < 0 {  // ERROR: impossible condition
-}
-```
-
-## Important Correctness Lints
-
-```rust
-// approx_constant - using imprecise PI, E values
-let pi = 3.14;  // Use std::f64::consts::PI
-
-// invalid_regex - regex that won't compile
-let re = Regex::new("[");  // Invalid regex
-
-// iter_next_loop - using .next() in for loop incorrectly
-for x in iter.next() {  // Should be: for x in iter
-
-// never_loop - loop that never actually loops
-loop {
-    break;  // Always breaks immediately
-}
-
-// nonsensical_open_options - impossible file options
-File::options().read(false).write(false).open("f");
-
-// unit_cmp - comparing unit type ()
-if foo() == bar() { }  // Both return (), always true
-```
-
-## Full Recommended Lints
-
-```rust
-#![deny(clippy::correctness)]
-#![warn(clippy::suspicious)]
-#![warn(clippy::style)]
-#![warn(clippy::complexity)]
-#![warn(clippy::perf)]
-
-// For published crates
-#![warn(missing_docs)]
-#![warn(clippy::cargo)]
-```
-
-## Running Clippy
-
-```bash
-# Basic check
-cargo clippy
-
-# With all warnings as errors
-cargo clippy -- -D warnings
-
-# Check specific lint category
-cargo clippy -- -W clippy::correctness
-
-# In CI (fail on warnings)
-cargo clippy -- -D warnings -D clippy::correctness
-```
-
-## See Also
-
-- [lint-warn-suspicious](lint-warn-suspicious.md) - Warn on suspicious code
-- [lint-warn-perf](lint-warn-perf.md) - Warn on performance issues