agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/test-criterion-bench.md

@@ -0,0 +1,171 @@
+# test-criterion-bench
+
+> Use `criterion` for benchmarking
+
+## Why It Matters
+
+Criterion provides statistically rigorous benchmarking with warmup, multiple iterations, outlier detection, and comparison between runs. It's far more reliable than simple timing with `Instant::now()`.
+
+## Setup
+
+```toml
+# Cargo.toml
+[dev-dependencies]
+criterion = "0.5"
+
+[[bench]]
+name = "my_benchmark"
+harness = false
+```
+
+## Basic Benchmark
+
+```rust
+// benches/my_benchmark.rs
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+
+fn fibonacci(n: u64) -> u64 {
+    match n {
+        0 => 0,
+        1 => 1,
+        n => fibonacci(n - 1) + fibonacci(n - 2),
+    }
+}
+
+fn bench_fibonacci(c: &mut Criterion) {
+    c.bench_function("fib 20", |b| {
+        b.iter(|| fibonacci(black_box(20)))
+    });
+}
+
+criterion_group!(benches, bench_fibonacci);
+criterion_main!(benches);
+```
+
+## black_box is Critical
+
+```rust
+// BAD: Compiler may optimize away the computation
+b.iter(|| fibonacci(20));  // Result unused, might be eliminated
+
+// GOOD: black_box prevents optimization
+b.iter(|| fibonacci(black_box(20)));
+
+// Also wrap the result if needed
+b.iter(|| black_box(fibonacci(black_box(20))));
+```
+
+## Comparing Implementations
+
+```rust
+fn bench_comparison(c: &mut Criterion) {
+    let mut group = c.benchmark_group("String concat");
+    
+    let data = "hello";
+    
+    group.bench_function("format!", |b| {
+        b.iter(|| format!("{}{}", black_box(data), " world"))
+    });
+    
+    group.bench_function("push_str", |b| {
+        b.iter(|| {
+            let mut s = String::from(black_box(data));
+            s.push_str(" world");
+            s
+        })
+    });
+    
+    group.bench_function("concat", |b| {
+        b.iter(|| [black_box(data), " world"].concat())
+    });
+    
+    group.finish();
+}
+```
+
+## Parameterized Benchmarks
+
+```rust
+fn bench_vec_push(c: &mut Criterion) {
+    let mut group = c.benchmark_group("Vec::push");
+    
+    for size in [100, 1000, 10000].iter() {
+        group.bench_with_input(
+            BenchmarkId::from_parameter(size),
+            size,
+            |b, &size| {
+                b.iter(|| {
+                    let mut v = Vec::new();
+                    for i in 0..size {
+                        v.push(black_box(i));
+                    }
+                    v
+                });
+            },
+        );
+    }
+    
+    group.finish();
+}
+```
+
+## Throughput Measurement
+
+```rust
+use criterion::Throughput;
+
+fn bench_parse(c: &mut Criterion) {
+    let input = "a]ong string to parse...";
+    
+    let mut group = c.benchmark_group("Parser");
+    group.throughput(Throughput::Bytes(input.len() as u64));
+    
+    group.bench_function("parse", |b| {
+        b.iter(|| parse(black_box(input)))
+    });
+    
+    group.finish();
+}
+```
+
+## Running Benchmarks
+
+```bash
+# Run all benchmarks
+cargo bench
+
+# Run specific benchmark
+cargo bench -- fib
+
+# Save baseline for comparison
+cargo bench -- --save-baseline main
+
+# Compare against baseline
+cargo bench -- --baseline main
+```
+
+## Evidence from tokio
+
+```rust
+// https://github.com/tokio-rs/tokio/blob/master/benches/sync_mpsc.rs
+use criterion::{criterion_group, criterion_main, Criterion};
+
+fn send_data<T: Default, const SIZE: usize>(
+    g: &mut BenchmarkGroup<WallTime>, 
+    prefix: &str
+) {
+    let rt = rt();
+    g.bench_function(format!("{prefix}_{SIZE}"), |b| {
+        b.iter(|| {
+            let (tx, mut rx) = mpsc::channel::<T>(SIZE);
+            rt.block_on(tx.send(T::default())).unwrap();
+            rt.block_on(rx.recv()).unwrap();
+        })
+    });
+}
+```
+
+## See Also
+
+- [perf-profile-first](perf-profile-first.md) - Profile before optimizing
+- [perf-black-box-bench](perf-black-box-bench.md) - Use black_box in benchmarks

package/template/agent/skills/rust-developer/references/rust-rules/test-descriptive-names.md

@@ -0,0 +1,142 @@
+# test-descriptive-names
+
+> Use descriptive test names that explain what is being tested
+
+## Why It Matters
+
+Test names appear in test output and serve as documentation. A good test name tells you what behavior is being verified without reading the test body. When a test fails, a descriptive name immediately tells you what broke.
+
+## Bad
+
+```rust
+#[test]
+fn test1() { ... }
+
+#[test]
+fn test_parse() { ... }  // Parse what? What behavior?
+
+#[test]
+fn it_works() { ... }
+
+#[test]
+fn test_function() { ... }
+
+// Failure output: "test test_parse ... FAILED"
+// What failed? No idea.
+```
+
+## Good
+
+```rust
+#[test]
+fn parse_returns_error_for_empty_input() { ... }
+
+#[test]
+fn parse_handles_unicode_characters() { ... }
+
+#[test]
+fn user_creation_requires_valid_email() { ... }
+
+#[test]
+fn expired_token_is_rejected() { ... }
+
+// Failure output: "test parse_returns_error_for_empty_input ... FAILED"
+// Immediately know what broke!
+```
+
+## Naming Patterns
+
+```rust
+// Pattern: function_condition_expected_result
+#[test]
+fn parse_valid_json_returns_document() { ... }
+
+#[test]
+fn parse_invalid_json_returns_syntax_error() { ... }
+
+// Pattern: scenario_expectation
+#[test]
+fn empty_cart_has_zero_total() { ... }
+
+#[test]
+fn adding_item_increases_cart_total() { ... }
+
+// Pattern: when_given_then (BDD-style)
+#[test]
+fn when_user_not_found_then_returns_404() { ... }
+```
+
+## Edge Cases
+
+```rust
+#[test]
+fn handles_empty_string() { ... }
+
+#[test]
+fn handles_max_length_input() { ... }
+
+#[test]
+fn handles_unicode_emoji() { ... }
+
+#[test]
+fn handles_null_bytes() { ... }
+
+#[test]
+fn handles_concurrent_access() { ... }
+```
+
+## Error Cases
+
+```rust
+#[test]
+fn rejects_negative_quantity() { ... }
+
+#[test]
+fn returns_error_for_invalid_email_format() { ... }
+
+#[test]
+fn panics_on_double_initialization() { ... }
+
+#[test]
+fn timeout_returns_timeout_error() { ... }
+```
+
+## Module Organization
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    mod parsing {
+        use super::*;
+        
+        #[test]
+        fn accepts_valid_json() { ... }
+        
+        #[test]
+        fn rejects_trailing_comma() { ... }
+    }
+    
+    mod validation {
+        use super::*;
+        
+        #[test]
+        fn requires_name_field() { ... }
+        
+        #[test]
+        fn email_must_contain_at_symbol() { ... }
+    }
+}
+
+// Test output:
+// tests::parsing::accepts_valid_json
+// tests::parsing::rejects_trailing_comma
+// tests::validation::requires_name_field
+```
+
+## See Also
+
+- [test-arrange-act-assert](./test-arrange-act-assert.md) - Test structure
+- [test-cfg-test-module](./test-cfg-test-module.md) - Test module organization
+- [doc-examples-section](./doc-examples-section.md) - Documentation tests

package/template/agent/skills/rust-developer/references/rust-rules/test-doctest-examples.md

@@ -0,0 +1,168 @@
+# test-doctest-examples
+
+> Keep documentation examples as executable doctests
+
+## Why It Matters
+
+Doctests are examples in documentation that are automatically tested. They serve dual purposes: demonstrating usage to readers and verifying the examples compile and work. When your API changes, failing doctests catch outdated documentation.
+
+## Bad
+
+```rust
+/// Parses a number from a string.
+/// 
+/// Example:
+/// let n = parse("42");  // Not tested!
+/// assert_eq!(n, 42);
+pub fn parse(s: &str) -> i32 {
+    s.parse().unwrap()
+}
+
+// Documentation can become outdated:
+/// Adds two numbers.
+/// 
+/// ```
+/// let sum = add(1, 2, 3);  // Wrong number of args - not caught!
+/// ```
+pub fn add(a: i32, b: i32) -> i32 {
+    a + b
+}
+```
+
+## Good
+
+```rust
+/// Parses a number from a string.
+/// 
+/// # Examples
+/// 
+/// ```
+/// use my_crate::parse;
+/// 
+/// let n = parse("42");
+/// assert_eq!(n, 42);
+/// ```
+pub fn parse(s: &str) -> i32 {
+    s.parse().unwrap()
+}
+
+/// Adds two numbers.
+/// 
+/// # Examples
+/// 
+/// ```
+/// use my_crate::add;
+/// 
+/// let sum = add(1, 2);
+/// assert_eq!(sum, 3);
+/// ```
+pub fn add(a: i32, b: i32) -> i32 {
+    a + b
+}
+```
+
+## Hiding Setup Code
+
+```rust
+/// Processes data from a file.
+/// 
+/// # Examples
+/// 
+/// ```
+/// # use std::io::Write;
+/// # let mut file = tempfile::NamedTempFile::new().unwrap();
+/// # writeln!(file, "test data").unwrap();
+/// # let path = file.path();
+/// use my_crate::process_file;
+/// 
+/// let result = process_file(path)?;
+/// assert!(!result.is_empty());
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
+pub fn process_file(path: &Path) -> Result<String, Error> {
+    std::fs::read_to_string(path).map_err(Error::from)
+}
+```
+
+## Showing Error Handling
+
+```rust
+/// Parses and validates an email address.
+/// 
+/// # Examples
+/// 
+/// ```
+/// use my_crate::Email;
+/// 
+/// let email = Email::parse("user@example.com")?;
+/// assert_eq!(email.domain(), "example.com");
+/// # Ok::<(), my_crate::EmailError>(())
+/// ```
+/// 
+/// # Errors
+/// 
+/// Returns error for invalid format:
+/// 
+/// ```
+/// use my_crate::Email;
+/// 
+/// assert!(Email::parse("not-an-email").is_err());
+/// ```
+pub fn parse(s: &str) -> Result<Email, EmailError> {
+    // ...
+}
+```
+
+## no_run and ignore
+
+```rust
+/// Starts the server.
+/// 
+/// ```no_run
+/// use my_crate::Server;
+/// 
+/// // This compiles but doesn't run (would block forever)
+/// Server::new().run();
+/// ```
+pub fn run(&self) { ... }
+
+/// Platform-specific example.
+/// 
+/// ```ignore
+/// // This might not compile on all platforms
+/// use windows_specific::Feature;
+/// ```
+```
+
+## compile_fail
+
+```rust
+/// This type is not Clone.
+/// 
+/// ```compile_fail
+/// use my_crate::UniqueHandle;
+/// 
+/// let a = UniqueHandle::new();
+/// let b = a.clone();  // Error: Clone not implemented
+/// ```
+pub struct UniqueHandle { ... }
+```
+
+## Running Doctests
+
+```bash
+# Run all tests including doctests
+cargo test
+
+# Run only doctests
+cargo test --doc
+
+# Run doctests for specific item
+cargo test --doc my_function
+```
+
+## See Also
+
+- [doc-examples-section](./doc-examples-section.md) - Documentation structure
+- [doc-hidden-setup](./doc-hidden-setup.md) - Hiding setup code
+- [doc-question-mark](./doc-question-mark.md) - Error handling in examples

package/template/agent/skills/rust-developer/references/rust-rules/test-fixture-raii.md

@@ -0,0 +1,151 @@
+# test-fixture-raii
+
+> Use RAII pattern (Drop trait) for automatic test cleanup
+
+## Why It Matters
+
+Tests often need setup and teardown—creating temp files, starting servers, setting environment variables. Using RAII (Resource Acquisition Is Initialization) with Drop ensures cleanup happens automatically, even if the test panics. This prevents test pollution and resource leaks.
+
+## Bad
+
+```rust
+#[test]
+fn test_with_temp_file() {
+    let path = "/tmp/test_file.txt";
+    std::fs::write(path, "test data").unwrap();
+    
+    let result = process_file(path);
+    
+    std::fs::remove_file(path).unwrap();  // Might not run if test panics!
+    assert!(result.is_ok());
+}
+
+#[test]
+fn test_with_env_var() {
+    std::env::set_var("MY_VAR", "test_value");
+    
+    let result = read_config();
+    
+    std::env::remove_var("MY_VAR");  // Might not run if test panics!
+    assert!(result.is_ok());
+}
+```
+
+## Good
+
+```rust
+use tempfile::NamedTempFile;
+
+#[test]
+fn test_with_temp_file() {
+    // Arrange - file deleted automatically when `file` drops
+    let file = NamedTempFile::new().unwrap();
+    std::fs::write(file.path(), "test data").unwrap();
+    
+    // Act
+    let result = process_file(file.path());
+    
+    // Assert - file cleaned up even if assertion panics
+    assert!(result.is_ok());
+}
+
+// Custom RAII guard for environment variables
+struct EnvGuard {
+    key: String,
+    original: Option<String>,
+}
+
+impl EnvGuard {
+    fn set(key: &str, value: &str) -> Self {
+        let original = std::env::var(key).ok();
+        std::env::set_var(key, value);
+        EnvGuard {
+            key: key.to_string(),
+            original,
+        }
+    }
+}
+
+impl Drop for EnvGuard {
+    fn drop(&mut self) {
+        match &self.original {
+            Some(v) => std::env::set_var(&self.key, v),
+            None => std::env::remove_var(&self.key),
+        }
+    }
+}
+
+#[test]
+fn test_with_env_var() {
+    let _guard = EnvGuard::set("MY_VAR", "test_value");
+    
+    let result = read_config();
+    
+    assert!(result.is_ok());
+}  // MY_VAR automatically restored
+```
+
+## Common RAII Patterns
+
+```rust
+// Temporary directory
+use tempfile::TempDir;
+
+#[test]
+fn test_with_temp_dir() {
+    let dir = TempDir::new().unwrap();
+    let file_path = dir.path().join("test.txt");
+    std::fs::write(&file_path, "data").unwrap();
+    
+    // dir and all contents deleted on drop
+}
+
+// Server guard
+struct TestServer {
+    handle: std::thread::JoinHandle<()>,
+    shutdown: std::sync::mpsc::Sender<()>,
+}
+
+impl Drop for TestServer {
+    fn drop(&mut self) {
+        let _ = self.shutdown.send(());
+        // Wait for server to stop
+    }
+}
+
+// Database transaction rollback
+struct TestTransaction<'a> {
+    conn: &'a mut Connection,
+}
+
+impl Drop for TestTransaction<'_> {
+    fn drop(&mut self) {
+        self.conn.execute("ROLLBACK").unwrap();
+    }
+}
+```
+
+## scopeguard Crate
+
+```rust
+use scopeguard::defer;
+
+#[test]
+fn test_with_defer() {
+    let path = "/tmp/test_file.txt";
+    std::fs::write(path, "data").unwrap();
+    
+    defer! {
+        std::fs::remove_file(path).ok();
+    }
+    
+    // Test logic here
+    // File removed when scope exits
+}
+```
+
+## See Also
+
+- [test-arrange-act-assert](./test-arrange-act-assert.md) - Test structure
+- [test-tokio-async](./test-tokio-async.md) - Async test cleanup
+- [test-mock-traits](./test-mock-traits.md) - Mocking with RAII