agy-superpowers 5.2.1 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/test-tokio-async.md

@@ -1,154 +0,0 @@
-# test-tokio-async
-
-> Use `#[tokio::test]` for async tests
-
-## Why It Matters
-
-Async functions can't be called directly—they need a runtime to drive them. `#[tokio::test]` provides a Tokio runtime for your test, handling setup automatically. This is simpler than manually creating a runtime and essential for testing async code.
-
-## Bad
-
-```rust
-// Won't compile - async fn can't be called without runtime
-#[test]
-async fn test_async_function() {  // Error!
-    let result = fetch_data().await;
-    assert!(result.is_ok());
-}
-
-// Manual runtime - verbose and error-prone
-#[test]
-fn test_async_function() {
-    let rt = tokio::runtime::Runtime::new().unwrap();
-    rt.block_on(async {
-        let result = fetch_data().await;
-        assert!(result.is_ok());
-    });
-}
-```
-
-## Good
-
-```rust
-#[tokio::test]
-async fn test_async_function() {
-    let result = fetch_data().await;
-    assert!(result.is_ok());
-}
-
-#[tokio::test]
-async fn test_concurrent_operations() {
-    let (a, b) = tokio::join!(
-        fetch_user(1),
-        fetch_user(2),
-    );
-    assert!(a.is_ok());
-    assert!(b.is_ok());
-}
-```
-
-## Runtime Configuration
-
-```rust
-// Multi-threaded runtime (default)
-#[tokio::test]
-async fn test_default_runtime() {
-    // Uses multi-thread runtime
-}
-
-// Single-threaded (current_thread)
-#[tokio::test(flavor = "current_thread")]
-async fn test_single_threaded() {
-    // Simpler, deterministic
-}
-
-// With specific thread count
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn test_with_workers() {
-    // Exactly 2 worker threads
-}
-
-// With time control
-#[tokio::test(start_paused = true)]
-async fn test_with_time_control() {
-    // Time starts paused for deterministic testing
-    tokio::time::advance(Duration::from_secs(60)).await;
-}
-```
-
-## Testing Timeouts
-
-```rust
-use tokio::time::{timeout, Duration};
-
-#[tokio::test]
-async fn test_operation_completes_in_time() {
-    let result = timeout(
-        Duration::from_secs(5),
-        slow_operation()
-    ).await;
-    
-    assert!(result.is_ok(), "Operation timed out");
-}
-
-#[tokio::test]
-async fn test_timeout_triggers() {
-    let result = timeout(
-        Duration::from_millis(100),
-        never_completes()
-    ).await;
-    
-    assert!(result.is_err(), "Expected timeout");
-}
-```
-
-## Testing Channels
-
-```rust
-use tokio::sync::mpsc;
-
-#[tokio::test]
-async fn test_channel_communication() {
-    let (tx, mut rx) = mpsc::channel(10);
-    
-    tokio::spawn(async move {
-        tx.send("hello").await.unwrap();
-        tx.send("world").await.unwrap();
-    });
-    
-    assert_eq!(rx.recv().await, Some("hello"));
-    assert_eq!(rx.recv().await, Some("world"));
-    assert_eq!(rx.recv().await, None);
-}
-```
-
-## Testing with Mocks
-
-```rust
-use mockall::*;
-
-#[automock]
-#[async_trait::async_trait]
-trait Database {
-    async fn get_user(&self, id: u64) -> Option<User>;
-}
-
-#[tokio::test]
-async fn test_with_mock_database() {
-    let mut mock = MockDatabase::new();
-    mock.expect_get_user()
-        .with(eq(42))
-        .returning(|_| Some(User { id: 42, name: "Alice".into() }));
-    
-    let service = UserService::new(mock);
-    let user = service.find_user(42).await;
-    
-    assert_eq!(user.unwrap().name, "Alice");
-}
-```
-
-## See Also
-
-- [async-tokio-runtime](./async-tokio-runtime.md) - Runtime configuration
-- [test-mock-traits](./test-mock-traits.md) - Mocking async traits
-- [test-fixture-raii](./test-fixture-raii.md) - Async test cleanup

package/template/agent/skills/rust-developer/references/rust-rules/test-use-super.md

@@ -1,127 +0,0 @@
-# test-use-super
-
-> Use `use super::*;` in test modules to access parent module items
-
-## Why It Matters
-
-The test module is a child of the module being tested. `use super::*` imports all items from the parent module, including private ones. This gives tests access to both public API and internal implementation details for thorough testing.
-
-## Bad
-
-```rust
-// Verbose imports
-#[cfg(test)]
-mod tests {
-    use crate::my_module::public_function;
-    use crate::my_module::MyStruct;
-    // Can't access private items this way!
-    
-    #[test]
-    fn test_function() {
-        let result = public_function();
-        // ...
-    }
-}
-```
-
-## Good
-
-```rust
-// src/my_module.rs
-pub struct PublicStruct { ... }
-struct PrivateStruct { ... }  // Private
-
-pub fn public_function() -> i32 { ... }
-fn private_helper() -> i32 { ... }  // Private
-
-#[cfg(test)]
-mod tests {
-    use super::*;  // Imports everything from parent
-    
-    #[test]
-    fn test_public_struct() {
-        let s = PublicStruct::new();
-        // ...
-    }
-    
-    #[test]
-    fn test_private_struct() {
-        let s = PrivateStruct::new();  // Can access private!
-        // ...
-    }
-    
-    #[test]
-    fn test_private_helper() {
-        assert_eq!(private_helper(), 42);  // Can test private!
-    }
-}
-```
-
-## Selective Imports
-
-```rust
-#[cfg(test)]
-mod tests {
-    // When you want to be explicit
-    use super::{parse, ParseError, Token};
-    
-    // Or import all plus test utilities
-    use super::*;
-    use std::fs;
-    use tempfile::TempDir;
-    
-    #[test]
-    fn test_parse() { ... }
-}
-```
-
-## Nested Modules
-
-```rust
-mod outer {
-    pub fn outer_fn() -> i32 { 1 }
-    
-    mod inner {
-        pub fn inner_fn() -> i32 { 2 }
-        
-        #[cfg(test)]
-        mod tests {
-            use super::*;           // Gets inner's items
-            use super::super::*;    // Gets outer's items
-            
-            #[test]
-            fn test_inner() {
-                assert_eq!(inner_fn(), 2);
-                assert_eq!(outer_fn(), 1);
-            }
-        }
-    }
-}
-```
-
-## With External Dependencies
-
-```rust
-#[cfg(test)]
-mod tests {
-    use super::*;
-    
-    // Test-only dependencies
-    use proptest::prelude::*;
-    use mockall::predicate::*;
-    
-    proptest! {
-        #[test]
-        fn test_property(s: String) {
-            let result = process(&s);
-            prop_assert!(result.is_ok());
-        }
-    }
-}
-```
-
-## See Also
-
-- [test-cfg-test-module](./test-cfg-test-module.md) - Test module structure
-- [test-integration-dir](./test-integration-dir.md) - Integration tests
-- [proj-pub-crate-internal](./proj-pub-crate-internal.md) - Visibility modifiers

package/template/agent/skills/rust-developer/references/rust-rules/type-enum-states.md

@@ -1,154 +0,0 @@
-# type-enum-states
-
-> Use enums for mutually exclusive states
-
-## Why It Matters
-
-When a value can be in exactly one of several states, an enum makes invalid states unrepresentable. The compiler ensures all states are handled. Contrast with boolean flags or optional fields that can represent impossible combinations.
-
-## Bad
-
-```rust
-struct Connection {
-    is_connected: bool,
-    is_authenticated: bool,
-    is_disconnected: bool,  // Can all three be true? False?
-    socket: Option<TcpStream>,
-    credentials: Option<Credentials>,
-}
-
-// Possible invalid states:
-// - is_connected && is_disconnected (contradiction)
-// - is_authenticated && !is_connected (impossible)
-// - socket is None but is_connected is true (inconsistent)
-```
-
-## Good
-
-```rust
-enum ConnectionState {
-    Disconnected,
-    Connecting { address: SocketAddr },
-    Connected { socket: TcpStream },
-    Authenticated { socket: TcpStream, session: Session },
-    Failed { error: ConnectionError },
-}
-
-struct Connection {
-    state: ConnectionState,
-}
-
-// Impossible states are unrepresentable
-// Each state has exactly the data it needs
-```
-
-## Pattern Matching Ensures Completeness
-
-```rust
-fn handle_connection(conn: &Connection) {
-    match &conn.state {
-        ConnectionState::Disconnected => {
-            println!("Not connected");
-        }
-        ConnectionState::Connecting { address } => {
-            println!("Connecting to {}", address);
-        }
-        ConnectionState::Connected { socket } => {
-            println!("Connected, not authenticated");
-        }
-        ConnectionState::Authenticated { socket, session } => {
-            println!("Authenticated as {}", session.user);
-        }
-        ConnectionState::Failed { error } => {
-            println!("Failed: {}", error);
-        }
-    }
-    // Compiler error if any state is missing
-}
-```
-
-## State Transitions
-
-```rust
-impl Connection {
-    fn connect(&mut self, addr: SocketAddr) -> Result<(), Error> {
-        match &self.state {
-            ConnectionState::Disconnected => {
-                self.state = ConnectionState::Connecting { address: addr };
-                Ok(())
-            }
-            _ => Err(Error::AlreadyConnected),
-        }
-    }
-    
-    fn on_connected(&mut self, socket: TcpStream) {
-        if let ConnectionState::Connecting { .. } = &self.state {
-            self.state = ConnectionState::Connected { socket };
-        }
-    }
-    
-    fn authenticate(&mut self, creds: Credentials) -> Result<(), Error> {
-        match std::mem::replace(&mut self.state, ConnectionState::Disconnected) {
-            ConnectionState::Connected { socket } => {
-                let session = perform_auth(&socket, creds)?;
-                self.state = ConnectionState::Authenticated { socket, session };
-                Ok(())
-            }
-            other => {
-                self.state = other;
-                Err(Error::NotConnected)
-            }
-        }
-    }
-}
-```
-
-## Result and Option as State Enums
-
-```rust
-// Option<T> is an enum for "might not exist"
-enum Option<T> {
-    Some(T),
-    None,
-}
-
-// Result<T, E> is an enum for "might have failed"
-enum Result<T, E> {
-    Ok(T),
-    Err(E),
-}
-
-// Use these instead of nullable/sentinel values
-fn find_user(id: u64) -> Option<User> { ... }
-fn parse_config(s: &str) -> Result<Config, ParseError> { ... }
-```
-
-## Avoid Boolean Flags
-
-```rust
-// Bad: boolean flags
-struct Task {
-    is_running: bool,
-    is_completed: bool,
-    is_failed: bool,
-    error: Option<Error>,
-}
-
-// Good: enum state
-enum TaskState {
-    Pending,
-    Running { started_at: Instant },
-    Completed { result: Output },
-    Failed { error: Error },
-}
-
-struct Task {
-    state: TaskState,
-}
-```
-
-## See Also
-
-- [api-typestate](./api-typestate.md) - Type-level state machines
-- [api-non-exhaustive](./api-non-exhaustive.md) - Forward-compatible enums
-- [type-option-nullable](./type-option-nullable.md) - Option for optional values

package/template/agent/skills/rust-developer/references/rust-rules/type-generic-bounds.md

@@ -1,142 +0,0 @@
-# type-generic-bounds
-
-> Add trait bounds only where needed, prefer where clauses for readability
-
-## Why It Matters
-
-Trait bounds constrain what types can be used with generic code. Adding unnecessary bounds limits flexibility. Adding bounds in the right place (impl vs function vs where clause) affects usability and readability. Well-placed bounds keep APIs flexible while ensuring type safety.
-
-## Bad
-
-```rust
-// Bounds on struct definition - limits all uses
-struct Container<T: Clone + Debug> {  // Even storage requires Clone?
-    items: Vec<T>,
-}
-
-// Inline bounds make signature hard to read
-fn process<T: Clone + Debug + Send + Sync + 'static, E: Error + Send + Clone>(
-    value: T
-) -> Result<T, E> { ... }
-
-// Redundant bounds
-fn print_twice<T: Clone + Debug>(value: T)
-where
-    T: Clone,  // Already specified above
-{ ... }
-```
-
-## Good
-
-```rust
-// No bounds on struct - store anything
-struct Container<T> {
-    items: Vec<T>,
-}
-
-// Bounds only on impls that need them
-impl<T: Clone> Container<T> {
-    fn duplicate(&self) -> Self {
-        Container { items: self.items.clone() }
-    }
-}
-
-impl<T: Debug> Container<T> {
-    fn debug_print(&self) {
-        println!("{:?}", self.items);
-    }
-}
-
-// Where clause for readability
-fn process<T, E>(value: T) -> Result<T, E>
-where
-    T: Clone + Debug + Send + Sync + 'static,
-    E: Error + Send + Clone,
-{ ... }
-```
-
-## Bound Placement
-
-```rust
-// On struct: affects all uses of the type
-struct MustBeClone<T: Clone> { data: T }  // Rarely needed
-
-// On impl: affects specific functionality
-impl<T: Clone> Container<T> { ... }  // Common pattern
-
-// On function: affects that function only
-fn requires_send<T: Send>(value: T) { ... }
-
-// Recommendation: start with no bounds, add as needed
-```
-
-## Where Clause Benefits
-
-```rust
-// Inline: hard to read
-fn complex<T: Clone + Debug + Send, U: AsRef<str> + Into<String>>(t: T, u: U) { }
-
-// Where clause: clear and scannable
-fn complex<T, U>(t: T, u: U)
-where
-    T: Clone + Debug + Send,
-    U: AsRef<str> + Into<String>,
-{ }
-
-// Essential for complex bounds
-fn foo<T, U>(t: T, u: U)
-where
-    T: Iterator<Item = U>,
-    U: Clone + Into<String>,
-    Vec<U>: Debug,  // Bounds on expressions
-{ }
-```
-
-## Implied Bounds
-
-```rust
-// Supertrait bounds are implied
-trait Foo: Clone + Debug {}
-
-fn process<T: Foo>(value: T) {
-    // T: Clone and T: Debug are implied by T: Foo
-    let cloned = value.clone();
-    println!("{:?}", cloned);
-}
-
-// Associated type bounds
-fn process<I>(iter: I)
-where
-    I: Iterator,
-    I::Item: Clone,  // Bound on associated type
-{ }
-```
-
-## Conditional Trait Implementation
-
-```rust
-struct Wrapper<T>(T);
-
-// Implement Clone only when T: Clone
-impl<T: Clone> Clone for Wrapper<T> {
-    fn clone(&self) -> Self {
-        Wrapper(self.0.clone())
-    }
-}
-
-// Implement Debug only when T: Debug  
-impl<T: Debug> Debug for Wrapper<T> {
-    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
-        f.debug_tuple("Wrapper").field(&self.0).finish()
-    }
-}
-
-// Wrapper<i32> is Clone + Debug
-// Wrapper<NonCloneable> is neither
-```
-
-## See Also
-
-- [api-impl-into](./api-impl-into.md) - Using Into bounds
-- [api-impl-asref](./api-impl-asref.md) - Using AsRef bounds
-- [name-type-param-single](./name-type-param-single.md) - Type parameter naming

package/template/agent/skills/rust-developer/references/rust-rules/type-never-diverge.md

@@ -1,146 +0,0 @@
-# type-never-diverge
-
-> Use `!` (never type) for functions that never return
-
-## Why It Matters
-
-The never type `!` indicates a function will never return normally—it either loops forever, panics, or exits the process. This helps the compiler understand control flow and enables `!` to coerce to any type, making it useful in match arms and expressions.
-
-## Bad
-
-```rust
-// Return type doesn't indicate non-returning
-fn infinite_loop() {
-    loop {
-        process_events();
-    }
-    // Implicit () return type, but never returns
-}
-
-// Using Option when it always panics
-fn unreachable_code() -> Option<()> {
-    panic!("This should never be called");
-}
-```
-
-## Good
-
-```rust
-// ! indicates function never returns
-fn infinite_loop() -> ! {
-    loop {
-        process_events();
-    }
-}
-
-fn abort_with_error(msg: &str) -> ! {
-    eprintln!("Fatal error: {}", msg);
-    std::process::exit(1);
-}
-
-fn panic_handler() -> ! {
-    panic!("Unexpected state");
-}
-```
-
-## Coercion to Any Type
-
-```rust
-// ! coerces to any type
-fn get_value(opt: Option<i32>) -> i32 {
-    match opt {
-        Some(v) => v,
-        None => panic!("No value"),  // panic! returns !, coerces to i32
-    }
-}
-
-// Useful in Result handling
-fn must_get_config() -> Config {
-    match load_config() {
-        Ok(c) => c,
-        Err(e) => {
-            log_error(&e);
-            std::process::exit(1)  // Returns !, coerces to Config
-        }
-    }
-}
-```
-
-## Standard Library Examples
-
-```rust
-// std::process::exit
-pub fn exit(code: i32) -> !
-
-// panic! macro
-// Expands to an expression of type !
-
-// std::hint::unreachable_unchecked
-pub unsafe fn unreachable_unchecked() -> !
-
-// loop {} with no break
-fn forever() -> ! {
-    loop {}
-}
-```
-
-## In Match Expressions
-
-```rust
-enum State {
-    Running,
-    Stopped,
-    Error,
-}
-
-fn get_status(state: &State) -> &str {
-    match state {
-        State::Running => "running",
-        State::Stopped => "stopped",
-        State::Error => unreachable!(),  // ! coerces to &str
-    }
-}
-
-// With Result
-fn process(r: Result<Data, Error>) -> Data {
-    match r {
-        Ok(d) => d,
-        Err(e) => panic!("Unexpected error: {}", e),  // ! coerces to Data
-    }
-}
-```
-
-## Diverging Closures
-
-```rust
-// Closures that never return
-let handler: fn() -> ! = || {
-    panic!("Handler called");
-};
-
-// In thread spawn
-std::thread::spawn(|| -> ! {
-    loop {
-        process_work();
-    }
-});
-```
-
-## Current Limitations (Nightly)
-
-```rust
-// Full ! type is nightly
-#![feature(never_type)]
-
-// Can use ! as type parameter
-type NeverResult = Result<(), !>;  // Can never be Err
-
-// On stable, use std::convert::Infallible
-type StableNeverResult = Result<(), std::convert::Infallible>;
-```
-
-## See Also
-
-- [err-result-over-panic](./err-result-over-panic.md) - When to panic vs return Result
-- [type-result-fallible](./type-result-fallible.md) - Result for errors
-- [opt-cold-unlikely](./opt-cold-unlikely.md) - Marking unlikely paths