agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/proj-workspace-large.md

@@ -0,0 +1,162 @@
+# proj-workspace-large
+
+> Use workspaces for large projects
+
+## Why It Matters
+
+Cargo workspaces manage multiple related crates under one repository. They share a single `Cargo.lock`, build cache, and can be versioned together. For large projects, workspaces improve build times, enforce modularity, and simplify dependency management.
+
+## Bad
+
+```
+# Separate repositories for each crate
+my-app-core/
+my-app-cli/
+my-app-server/
+my-app-common/
+
+# Each has its own Cargo.lock
+# Dependencies may drift
+# Cross-crate development is painful
+```
+
+## Good
+
+```
+my-app/
+├── Cargo.toml          # Workspace root
+├── Cargo.lock          # Shared lock file
+├── crates/
+│   ├── core/
+│   │   ├── Cargo.toml
+│   │   └── src/
+│   ├── cli/
+│   │   ├── Cargo.toml
+│   │   └── src/
+│   ├── server/
+│   │   ├── Cargo.toml
+│   │   └── src/
+│   └── common/
+│       ├── Cargo.toml
+│       └── src/
+└── README.md
+```
+
+## Workspace Cargo.toml
+
+```toml
+# Root Cargo.toml
+[workspace]
+resolver = "2"  # Use the new resolver
+members = [
+    "crates/core",
+    "crates/cli",
+    "crates/server",
+    "crates/common",
+]
+
+# Shared dependencies - all crates use same versions
+[workspace.dependencies]
+tokio = { version = "1.0", features = ["full"] }
+serde = { version = "1.0", features = ["derive"] }
+tracing = "0.1"
+anyhow = "1.0"
+
+# Shared lints
+[workspace.lints.rust]
+unsafe_code = "forbid"
+
+[workspace.lints.clippy]
+all = "warn"
+```
+
+## Member Crate Cargo.toml
+
+```toml
+# crates/core/Cargo.toml
+[package]
+name = "my-app-core"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+# Inherit from workspace
+tokio = { workspace = true }
+serde = { workspace = true }
+
+# Crate-specific dependencies
+uuid = "1.0"
+
+# Internal dependency
+my-app-common = { path = "../common" }
+
+[lints]
+workspace = true  # Inherit workspace lints
+```
+
+## When to Use Workspaces
+
+| Scenario | Recommendation |
+|----------|----------------|
+| Single binary/library | No workspace needed |
+| Library + CLI | Maybe, depends on size |
+| Multiple related crates | Yes |
+| Shared internal libraries | Yes |
+| Microservices mono-repo | Yes |
+| Plugin architecture | Yes |
+
+## Benefits
+
+| Aspect | Single Crate | Workspace |
+|--------|--------------|-----------|
+| Build cache | Crate only | Shared across all |
+| Dependency versions | Per-crate | Synchronized |
+| Compile times | Full rebuild | Incremental |
+| Modularity | Files/modules | Crate boundaries |
+| Publishing | Single crate | Independent |
+
+## Commands
+
+```bash
+# Build all crates
+cargo build --workspace
+
+# Build specific crate
+cargo build -p my-app-core
+
+# Test all crates
+cargo test --workspace
+
+# Run specific binary
+cargo run -p my-app-cli
+
+# Check all
+cargo check --workspace
+```
+
+## Pattern: Virtual Workspace
+
+Root Cargo.toml is workspace-only (no `[package]`):
+
+```toml
+[workspace]
+members = ["crates/*"]
+
+[workspace.dependencies]
+# ...
+```
+
+## Pattern: Crate Interdependencies
+
+```toml
+# crates/server/Cargo.toml
+[dependencies]
+my-app-core = { path = "../core" }
+my-app-common = { path = "../common" }
+```
+
+## See Also
+
+- [proj-workspace-deps](./proj-workspace-deps.md) - Workspace dependencies
+- [proj-bin-dir](./proj-bin-dir.md) - Multiple binaries
+- [proj-lib-main-split](./proj-lib-main-split.md) - Lib/main separation

package/template/agent/skills/rust-developer/references/rust-rules/test-arrange-act-assert.md

@@ -0,0 +1,160 @@
+# test-arrange-act-assert
+
+> Structure tests with clear Arrange, Act, Assert sections
+
+## Why It Matters
+
+The AAA pattern makes tests readable and maintainable. Each section has a clear purpose: set up test data, execute the code under test, verify the results. This structure helps identify what's being tested and makes tests easier to debug when they fail.
+
+## Bad
+
+```rust
+#[test]
+fn test_user() {
+    assert_eq!(User::new("alice", "alice@example.com").unwrap().name(), "alice");
+    assert!(User::new("", "email@example.com").is_err());
+    let u = User::new("bob", "bob@example.com").unwrap();
+    assert!(u.validate());
+    assert_eq!(u.email(), "bob@example.com");
+}
+// Multiple concerns, hard to understand, hard to debug
+```
+
+## Good
+
+```rust
+#[test]
+fn new_user_has_correct_name() {
+    // Arrange
+    let name = "alice";
+    let email = "alice@example.com";
+    
+    // Act
+    let user = User::new(name, email).unwrap();
+    
+    // Assert
+    assert_eq!(user.name(), "alice");
+}
+
+#[test]
+fn user_creation_fails_with_empty_name() {
+    // Arrange
+    let name = "";
+    let email = "email@example.com";
+    
+    // Act
+    let result = User::new(name, email);
+    
+    // Assert
+    assert!(result.is_err());
+    assert!(matches!(result, Err(UserError::EmptyName)));
+}
+```
+
+## With Comments
+
+```rust
+#[test]
+fn order_total_includes_tax() {
+    // Arrange
+    let mut order = Order::new();
+    order.add_item(Item::new("Widget", 100.00));
+    order.add_item(Item::new("Gadget", 50.00));
+    let tax_rate = 0.10;
+    
+    // Act
+    let total = order.calculate_total(tax_rate);
+    
+    // Assert
+    let expected = (100.00 + 50.00) * 1.10;
+    assert_eq!(total, expected);
+}
+```
+
+## Complex Arrange
+
+```rust
+#[test]
+fn search_returns_matching_documents() {
+    // Arrange
+    let mut index = SearchIndex::new();
+    index.add_document(Document::new(1, "rust programming"));
+    index.add_document(Document::new(2, "python programming"));
+    index.add_document(Document::new(3, "rust web development"));
+    
+    let query = Query::new("rust");
+    
+    // Act
+    let results = index.search(&query);
+    
+    // Assert
+    assert_eq!(results.len(), 2);
+    assert!(results.iter().any(|d| d.id == 1));
+    assert!(results.iter().any(|d| d.id == 3));
+}
+```
+
+## Async Tests
+
+```rust
+#[tokio::test]
+async fn fetch_user_returns_user_data() {
+    // Arrange
+    let client = TestClient::new();
+    let user_id = 42;
+    
+    // Act
+    let result = client.fetch_user(user_id).await;
+    
+    // Assert
+    assert!(result.is_ok());
+    let user = result.unwrap();
+    assert_eq!(user.id, user_id);
+}
+```
+
+## Helper Functions
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    // Arrange helpers
+    fn create_test_user() -> User {
+        User::new("test", "test@example.com").unwrap()
+    }
+    
+    fn create_order_with_items(items: &[(&str, f64)]) -> Order {
+        let mut order = Order::new();
+        for (name, price) in items {
+            order.add_item(Item::new(name, *price));
+        }
+        order
+    }
+    
+    // Assert helpers
+    fn assert_order_total(order: &Order, expected: f64) {
+        let total = order.calculate_total(0.0);
+        assert!((total - expected).abs() < 0.01);
+    }
+    
+    #[test]
+    fn order_total_sums_items() {
+        // Arrange
+        let order = create_order_with_items(&[
+            ("A", 10.0),
+            ("B", 20.0),
+        ]);
+        
+        // Act & Assert
+        assert_order_total(&order, 30.0);
+    }
+}
+```
+
+## See Also
+
+- [test-descriptive-names](./test-descriptive-names.md) - Test naming
+- [test-fixture-raii](./test-fixture-raii.md) - Test setup/teardown
+- [test-mock-traits](./test-mock-traits.md) - Mocking dependencies

package/template/agent/skills/rust-developer/references/rust-rules/test-cfg-test-module.md

@@ -0,0 +1,151 @@
+# test-cfg-test-module
+
+> Put unit tests in `#[cfg(test)] mod tests { }` within each module
+
+## Why It Matters
+
+The `#[cfg(test)]` attribute ensures test code is only compiled during `cargo test`, not in release builds. Placing tests in a `tests` submodule within the same file keeps tests close to the code they test while maintaining separation. This is Rust's idiomatic unit test pattern.
+
+## Bad
+
+```rust
+// Tests without cfg(test) - compiled into release binary
+mod tests {
+    #[test]
+    fn test_something() { ... }  // Included in release build!
+}
+
+// Tests in separate file without access to private items
+// src/my_module.rs
+fn private_helper() { ... }
+
+// tests/my_module_test.rs
+// Can't access private_helper!
+```
+
+## Good
+
+```rust
+// src/my_module.rs
+
+fn public_api() -> i32 {
+    private_helper() * 2
+}
+
+fn private_helper() -> i32 {
+    21
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;  // Access to private items
+    
+    #[test]
+    fn test_public_api() {
+        assert_eq!(public_api(), 42);
+    }
+    
+    #[test]
+    fn test_private_helper() {
+        assert_eq!(private_helper(), 21);  // Can test private!
+    }
+}
+```
+
+## Module Structure
+
+```rust
+// src/lib.rs
+mod parser;
+mod lexer;
+mod ast;
+
+// src/parser.rs
+pub fn parse(input: &str) -> Result<Ast, Error> {
+    let tokens = tokenize(input)?;
+    build_ast(tokens)
+}
+
+fn tokenize(input: &str) -> Result<Vec<Token>, Error> { ... }
+fn build_ast(tokens: Vec<Token>) -> Result<Ast, Error> { ... }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    #[test]
+    fn test_parse_simple() {
+        let ast = parse("1 + 2").unwrap();
+        assert_eq!(ast.evaluate(), 3);
+    }
+    
+    #[test]
+    fn test_tokenize() {
+        let tokens = tokenize("1 + 2").unwrap();
+        assert_eq!(tokens.len(), 3);
+    }
+}
+```
+
+## Test Helpers
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    // Test-only helpers
+    fn create_test_data() -> Data {
+        Data {
+            id: 1,
+            name: "test".into(),
+            values: vec![1, 2, 3],
+        }
+    }
+    
+    fn assert_valid(data: &Data) {
+        assert!(data.id > 0);
+        assert!(!data.name.is_empty());
+    }
+    
+    #[test]
+    fn test_processing() {
+        let data = create_test_data();
+        let result = process(&data);
+        assert_valid(&result);
+    }
+}
+```
+
+## Multiple Test Modules
+
+```rust
+// For larger test suites, use submodules
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    mod parsing {
+        use super::*;
+        
+        #[test]
+        fn test_parse_number() { ... }
+        
+        #[test]
+        fn test_parse_string() { ... }
+    }
+    
+    mod validation {
+        use super::*;
+        
+        #[test]
+        fn test_validate_range() { ... }
+    }
+}
+```
+
+## See Also
+
+- [test-use-super](./test-use-super.md) - Importing from parent module
+- [test-integration-dir](./test-integration-dir.md) - Integration tests
+- [test-descriptive-names](./test-descriptive-names.md) - Test naming

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