agy-superpowers 5.2.2 → 5.2.4

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

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

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

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

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