agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/test-should-panic.md

@@ -0,0 +1,130 @@
+# test-should-panic
+
+> Use `#[should_panic]` to test that code panics as expected
+
+## Why It Matters
+
+Some code should panic on invalid inputs or invariant violations. `#[should_panic]` verifies the panic occurs, optionally checking the panic message. This ensures defensive panics work correctly and documents expected panic conditions.
+
+## Bad
+
+```rust
+#[test]
+fn test_panic() {
+    // Just calling panicking code makes test fail
+    divide(1, 0);  // Test fails with panic
+}
+
+// Using catch_unwind is verbose
+#[test]
+fn test_panic_manual() {
+    let result = std::panic::catch_unwind(|| divide(1, 0));
+    assert!(result.is_err());
+}
+```
+
+## Good
+
+```rust
+#[test]
+#[should_panic]
+fn divide_by_zero_panics() {
+    divide(1, 0);  // Test passes when this panics
+}
+
+// With expected message
+#[test]
+#[should_panic(expected = "division by zero")]
+fn divide_by_zero_panics_with_message() {
+    divide(1, 0);  // Panics with "division by zero"
+}
+
+// Partial message match
+#[test]
+#[should_panic(expected = "index out of bounds")]
+fn index_panic_contains_message() {
+    let v = vec![1, 2, 3];
+    let _ = v[100];  // Message contains "index out of bounds"
+}
+```
+
+## Testing Invariants
+
+```rust
+struct NonEmpty<T>(Vec<T>);
+
+impl<T> NonEmpty<T> {
+    fn new(items: Vec<T>) -> Self {
+        assert!(!items.is_empty(), "NonEmpty cannot be empty");
+        NonEmpty(items)
+    }
+}
+
+#[test]
+#[should_panic(expected = "NonEmpty cannot be empty")]
+fn non_empty_rejects_empty_vec() {
+    NonEmpty::new(Vec::<i32>::new());
+}
+
+#[test]
+fn non_empty_accepts_non_empty_vec() {
+    let ne = NonEmpty::new(vec![1, 2, 3]);
+    assert_eq!(ne.0.len(), 3);
+}
+```
+
+## With expect() Messages
+
+```rust
+fn get_config_value(key: &str) -> String {
+    CONFIG.get(key)
+        .expect(&format!("missing required config: {}", key))
+        .to_string()
+}
+
+#[test]
+#[should_panic(expected = "missing required config: DATABASE_URL")]
+fn missing_config_panics_with_key() {
+    get_config_value("DATABASE_URL");
+}
+```
+
+## When NOT to Use should_panic
+
+```rust
+// ❌ For recoverable errors - use Result
+#[test]
+#[should_panic]  // Wrong: this should return Err, not panic
+fn invalid_input_panics() {
+    parse_config("invalid");  // Should return Err, not panic
+}
+
+// ✅ Return Result and test the error
+#[test]
+fn invalid_input_returns_error() {
+    let result = parse_config("invalid");
+    assert!(result.is_err());
+}
+```
+
+## Combining with Result
+
+```rust
+#[test]
+#[should_panic]
+fn test_panics() -> Result<(), Error> {
+    // Can combine with Result for setup
+    let data = setup_test_data()?;
+    
+    // This should panic
+    process_invalid(&data);
+    
+    Ok(())  // Never reached
+}
+```
+
+## See Also
+
+- [err-result-over-panic](./err-result-over-panic.md) - Panic vs Result
+- [err-expect-bugs-only](./err-expect-bugs-only.md) - When to use expect
+- [test-descriptive-names](./test-descriptive-names.md) - Test naming

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

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

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

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

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