agy-superpowers 5.1.4 → 5.1.6

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

@@ -0,0 +1,186 @@
+# proj-workspace-deps
+
+> Use workspace dependency inheritance for consistent versions across crates
+
+## Why It Matters
+
+Multi-crate workspaces often have dependency version drift—different crates using different versions of the same dependency. Workspace dependency inheritance (Rust 1.64+) lets you declare dependencies once in the workspace `Cargo.toml` and inherit them in member crates, ensuring consistency.
+
+## Bad
+
+```toml
+# crate-a/Cargo.toml
+[dependencies]
+serde = "1.0.150"
+tokio = "1.25"
+
+# crate-b/Cargo.toml  
+[dependencies]
+serde = "1.0.188"  # Different version!
+tokio = "1.32"     # Different version!
+
+# Version drift leads to:
+# - Larger binaries (multiple versions)
+# - Compilation time increase
+# - Subtle behavior differences
+```
+
+## Good
+
+```toml
+# Root Cargo.toml
+[workspace]
+members = ["crate-a", "crate-b", "crate-c"]
+
+[workspace.dependencies]
+serde = { version = "1.0", features = ["derive"] }
+tokio = { version = "1.32", features = ["full"] }
+thiserror = "1.0"
+anyhow = "1.0"
+tracing = "0.1"
+
+# crate-a/Cargo.toml
+[dependencies]
+serde.workspace = true
+tokio.workspace = true
+
+# crate-b/Cargo.toml
+[dependencies]
+serde.workspace = true
+tokio.workspace = true
+thiserror.workspace = true
+```
+
+## Override Features
+
+```toml
+# Root Cargo.toml
+[workspace.dependencies]
+tokio = { version = "1.32", features = ["rt-multi-thread"] }
+
+# crate-a/Cargo.toml - add extra features
+[dependencies]
+tokio = { workspace = true, features = ["net", "io-util"] }
+# Gets both workspace features AND local features
+
+# crate-b/Cargo.toml - minimal features
+[dependencies]
+tokio = { workspace = true }  # Just workspace features
+```
+
+## Dev and Build Dependencies
+
+```toml
+# Root Cargo.toml
+[workspace.dependencies]
+criterion = "0.5"
+proptest = "1.0"
+trybuild = "1.0"
+cc = "1.0"
+
+# crate-a/Cargo.toml
+[dev-dependencies]
+criterion.workspace = true
+proptest.workspace = true
+
+[build-dependencies]
+cc.workspace = true
+```
+
+## Internal Crate Dependencies
+
+```toml
+# Root Cargo.toml
+[workspace.dependencies]
+# Internal crates
+my-core = { path = "crates/core" }
+my-utils = { path = "crates/utils" }
+my-derive = { path = "crates/derive" }
+
+# External crates
+serde = "1.0"
+
+# crate-a/Cargo.toml
+[dependencies]
+my-core.workspace = true
+my-utils.workspace = true
+serde.workspace = true
+```
+
+## Optional Dependencies
+
+```toml
+# Root Cargo.toml
+[workspace.dependencies]
+serde = { version = "1.0", optional = true }  # Won't work!
+
+# Optional must be set in member, not workspace
+[workspace.dependencies]
+serde = "1.0"
+
+# crate-a/Cargo.toml
+[dependencies]
+serde = { workspace = true, optional = true }
+
+[features]
+serde = ["dep:serde"]
+```
+
+## Complete Workspace Example
+
+```toml
+# Root Cargo.toml
+[workspace]
+members = ["crates/*"]
+resolver = "2"
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/user/repo"
+
+[workspace.dependencies]
+# Internal
+my-core = { path = "crates/core", version = "0.1" }
+
+# Async
+tokio = { version = "1.32", features = ["full"] }
+futures = "0.3"
+
+# Serialization
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+# Error handling
+thiserror = "1.0"
+anyhow = "1.0"
+
+# Logging
+tracing = "0.1"
+tracing-subscriber = "0.3"
+
+# Testing
+proptest = "1.0"
+criterion = { version = "0.5", features = ["html_reports"] }
+
+# crates/core/Cargo.toml
+[package]
+name = "my-core"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+serde.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+proptest.workspace = true
+```
+
+## See Also
+
+- [proj-lib-main-split](./proj-lib-main-split.md) - Workspace structure
+- [api-serde-optional](./api-serde-optional.md) - Optional dependencies
+- [lint-deny-correctness](./lint-deny-correctness.md) - Workspace lints

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