agentic-team-templates 0.9.2 → 0.11.0

package/templates/rust-expert/.cursorrules/testing.md

@@ -0,0 +1,300 @@
+# Rust Testing
+
+Rust has testing built into the language and toolchain. `cargo test` runs unit tests, integration tests, and doc tests in one command.
+
+## Unit Tests
+
+### Module-Level Tests
+
+```rust
+// Tests live in the same file as the code they test
+pub fn celsius_to_fahrenheit(c: f64) -> f64 {
+    c * 9.0 / 5.0 + 32.0
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn freezing_point() {
+        assert!((celsius_to_fahrenheit(0.0) - 32.0).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn boiling_point() {
+        assert!((celsius_to_fahrenheit(100.0) - 212.0).abs() < f64::EPSILON);
+    }
+
+    #[test]
+    fn negative_temperature() {
+        assert!((celsius_to_fahrenheit(-40.0) - -40.0).abs() < f64::EPSILON);
+    }
+}
+```
+
+### Testing Error Cases
+
+```rust
+#[test]
+fn parse_invalid_input_returns_error() {
+    let result = parse_config("not valid toml");
+    assert!(result.is_err());
+
+    let err = result.unwrap_err();
+    assert!(err.to_string().contains("expected"));
+}
+
+#[test]
+fn empty_name_fails_validation() {
+    let input = CreateUserInput { name: "".into(), email: "a@b.com".into() };
+    let result = validate_user(&input);
+
+    assert!(matches!(result, Err(ValidationError::EmptyField { field }) if field == "name"));
+}
+
+// Testing that something panics
+#[test]
+#[should_panic(expected = "index out of bounds")]
+fn panics_on_out_of_bounds() {
+    let v = vec![1, 2, 3];
+    let _ = v[10];
+}
+```
+
+### Test Organization
+
+```rust
+// #[cfg(test)] ensures test code is never compiled into release builds
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Shared test fixtures
+    fn sample_user() -> User {
+        User {
+            id: UserId::new("test-123"),
+            name: "Alice".into(),
+            email: "alice@example.com".into(),
+        }
+    }
+
+    // Group related tests with nested modules
+    mod validation {
+        use super::*;
+
+        #[test]
+        fn rejects_empty_name() { ... }
+
+        #[test]
+        fn rejects_invalid_email() { ... }
+    }
+
+    mod serialization {
+        use super::*;
+
+        #[test]
+        fn round_trips_through_json() { ... }
+    }
+}
+```
+
+## Integration Tests
+
+```rust
+// tests/api_test.rs — separate compilation unit, tests public API only
+use my_crate::{Config, Server};
+
+#[test]
+fn server_responds_to_health_check() {
+    let config = Config::default();
+    let server = Server::new(config);
+
+    let response = server.handle_request("/healthz");
+
+    assert_eq!(response.status(), 200);
+    assert_eq!(response.body(), r#"{"status":"ok"}"#);
+}
+```
+
+## Async Tests
+
+```rust
+#[tokio::test]
+async fn fetches_user_by_id() {
+    let db = setup_test_db().await;
+    let repo = UserRepo::new(db);
+
+    let user = repo.find_by_id("123").await.unwrap();
+
+    assert_eq!(user.name, "Alice");
+}
+
+// With custom runtime config
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn concurrent_operations() {
+    // ...
+}
+```
+
+## Property-Based Testing
+
+```rust
+use proptest::prelude::*;
+
+proptest! {
+    #[test]
+    fn parse_never_panics(s in "\\PC*") {
+        // Whatever string we throw at parse, it must not panic
+        let _ = parse_input(&s);
+    }
+
+    #[test]
+    fn serialization_round_trips(
+        name in "[a-zA-Z]{1,50}",
+        age in 0u32..150,
+    ) {
+        let user = User { name, age };
+        let json = serde_json::to_string(&user).unwrap();
+        let decoded: User = serde_json::from_str(&json).unwrap();
+        assert_eq!(user, decoded);
+    }
+}
+```
+
+## Doc Tests
+
+```rust
+/// Adds two numbers together.
+///
+/// # Examples
+///
+/// ```
+/// use my_crate::add;
+///
+/// assert_eq!(add(2, 3), 5);
+/// assert_eq!(add(-1, 1), 0);
+/// ```
+///
+/// # Panics
+///
+/// Panics if the result overflows.
+///
+/// ```should_panic
+/// use my_crate::add;
+///
+/// add(i64::MAX, 1); // Overflow!
+/// ```
+pub fn add(a: i64, b: i64) -> i64 {
+    a.checked_add(b).expect("overflow")
+}
+
+// Doc tests are compiled and run — they're both documentation AND tests.
+// They verify your examples actually work.
+```
+
+## Mocking and Test Doubles
+
+```rust
+// Prefer trait-based dependency injection over mocking frameworks
+
+// Define trait at the consumer
+trait Clock {
+    fn now(&self) -> DateTime<Utc>;
+}
+
+// Production implementation
+struct SystemClock;
+impl Clock for SystemClock {
+    fn now(&self) -> DateTime<Utc> { Utc::now() }
+}
+
+// Test implementation — deterministic
+struct FakeClock(DateTime<Utc>);
+impl Clock for FakeClock {
+    fn now(&self) -> DateTime<Utc> { self.0 }
+}
+
+#[test]
+fn token_expires_after_one_hour() {
+    let fixed_time = Utc.with_ymd_and_hms(2025, 1, 1, 12, 0, 0).unwrap();
+    let clock = FakeClock(fixed_time);
+    let token = generate_token(&clock);
+
+    let check_time = fixed_time + Duration::hours(2);
+    assert!(token.is_expired_at(check_time));
+}
+
+// When you do need a mocking library: mockall
+#[automock]
+trait Database {
+    fn get(&self, key: &str) -> Option<String>;
+}
+
+#[test]
+fn returns_cached_value() {
+    let mut mock = MockDatabase::new();
+    mock.expect_get()
+        .with(eq("user:123"))
+        .returning(|_| Some("Alice".into()));
+
+    let service = Service::new(mock);
+    assert_eq!(service.get_user("123"), Some("Alice".into()));
+}
+```
+
+## Benchmarks
+
+```rust
+// Using criterion (de facto standard)
+// benches/my_benchmark.rs
+use criterion::{criterion_group, criterion_main, Criterion, black_box};
+
+fn bench_parse(c: &mut Criterion) {
+    let input = include_str!("../testdata/large_input.txt");
+
+    c.bench_function("parse_large_input", |b| {
+        b.iter(|| parse(black_box(input)))
+    });
+}
+
+fn bench_comparison(c: &mut Criterion) {
+    let mut group = c.benchmark_group("serialization");
+    let data = generate_test_data();
+
+    group.bench_function("json", |b| {
+        b.iter(|| serde_json::to_vec(black_box(&data)))
+    });
+
+    group.bench_function("bincode", |b| {
+        b.iter(|| bincode::serialize(black_box(&data)))
+    });
+
+    group.finish();
+}
+
+criterion_group!(benches, bench_parse, bench_comparison);
+criterion_main!(benches);
+```
+
+## Test Anti-Patterns
+
+```rust
+// Never: Tests that depend on execution order
+// Each test runs in its own thread — no shared mutable state
+
+// Never: Ignoring tests instead of fixing them
+#[ignore] // Why? For how long? File an issue.
+
+// Never: Testing private internals through hacks
+// If you can't test it through the public API, the design needs work
+
+// Never: Assertions without messages in complex tests
+assert!(result.is_ok()); // What was the input? What was the error?
+// Better:
+assert!(result.is_ok(), "expected Ok for input {input:?}, got {result:?}");
+
+// Never: Flaky tests
+// Flaky = broken. Fix the race condition or the timing dependency.
+// Use deterministic clocks, seeded RNGs, and proper synchronization.
+```

package/templates/rust-expert/.cursorrules/traits-and-generics.md

@@ -0,0 +1,236 @@
+# Rust Traits and Generics
+
+Traits are Rust's mechanism for abstraction, polymorphism, and code reuse. Combined with generics, they enable zero-cost abstractions that rival hand-written specialized code.
+
+## Trait Design
+
+### Small, Focused Traits
+
+```rust
+// Good: Single-purpose traits
+pub trait Validate {
+    fn validate(&self) -> Result<(), ValidationError>;
+}
+
+pub trait Serialize {
+    fn serialize(&self, writer: &mut dyn Write) -> Result<(), SerializeError>;
+}
+
+// Bad: God trait
+pub trait Entity {
+    fn validate(&self) -> Result<(), Error>;
+    fn serialize(&self) -> Vec<u8>;
+    fn save(&self, db: &Database) -> Result<(), Error>;
+    fn render(&self) -> Html;
+    // Too many responsibilities — split by concern
+}
+```
+
+### Extension Traits
+
+```rust
+// Add methods to existing types via extension traits
+pub trait StrExt {
+    fn is_blank(&self) -> bool;
+    fn truncate_to(&self, max_len: usize) -> &str;
+}
+
+impl StrExt for str {
+    fn is_blank(&self) -> bool {
+        self.trim().is_empty()
+    }
+
+    fn truncate_to(&self, max_len: usize) -> &str {
+        if self.len() <= max_len {
+            self
+        } else {
+            // Find a char boundary to avoid panic
+            let mut end = max_len;
+            while !self.is_char_boundary(end) {
+                end -= 1;
+            }
+            &self[..end]
+        }
+    }
+}
+```
+
+### Sealed Traits
+
+```rust
+// Prevent external implementations when your trait is part of an internal contract
+mod private {
+    pub trait Sealed {}
+}
+
+pub trait Backend: private::Sealed {
+    fn execute(&self, query: &str) -> Result<Rows>;
+}
+
+// Only types in your crate can implement Sealed, so only they can implement Backend
+impl private::Sealed for PostgresBackend {}
+impl Backend for PostgresBackend { ... }
+```
+
+### The Newtype Pattern
+
+```rust
+// Implement foreign traits on foreign types via newtype
+struct Meters(f64);
+struct Seconds(f64);
+
+impl fmt::Display for Meters {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{:.2}m", self.0)
+    }
+}
+
+// Also prevents mixing units at compile time
+fn speed(distance: Meters, time: Seconds) -> f64 {
+    distance.0 / time.0
+}
+// speed(Seconds(1.0), Meters(5.0)) — compile error! Arguments are swapped.
+```
+
+## Generics
+
+### Trait Bounds
+
+```rust
+// Prefer impl Trait for simple cases
+fn print_all(items: &[impl Display]) {
+    for item in items {
+        println!("{item}");
+    }
+}
+
+// Use where clauses for complex bounds
+fn merge<T, U>(left: T, right: U) -> Merged
+where
+    T: IntoIterator<Item = Record>,
+    U: IntoIterator<Item = Record>,
+    T::IntoIter: ExactSizeIterator,
+{
+    // ...
+}
+
+// Use explicit generic parameters when the caller needs to specify the type
+fn parse<T: FromStr>(input: &str) -> Result<T, T::Err> {
+    input.parse()
+}
+let n: i32 = parse("42")?;
+let f: f64 = parse("3.14")?;
+```
+
+### Associated Types vs Generic Parameters
+
+```rust
+// Associated types: one implementation per type
+trait Iterator {
+    type Item; // Each iterator has exactly one Item type
+    fn next(&mut self) -> Option<Self::Item>;
+}
+
+// Generic parameters: multiple implementations per type
+trait Convert<T> {
+    fn convert(&self) -> T;
+}
+// A single type can implement Convert<String>, Convert<i32>, etc.
+
+// Rule of thumb: If there should be only one implementation
+// for a given Self type, use an associated type.
+```
+
+### Phantom Types
+
+```rust
+use std::marker::PhantomData;
+
+// Type-state pattern: encode state in the type system
+struct Validated;
+struct Unvalidated;
+
+struct Form<State> {
+    data: FormData,
+    _state: PhantomData<State>,
+}
+
+impl Form<Unvalidated> {
+    fn new(data: FormData) -> Self {
+        Form { data, _state: PhantomData }
+    }
+
+    fn validate(self) -> Result<Form<Validated>, ValidationError> {
+        // validation logic...
+        Ok(Form { data: self.data, _state: PhantomData })
+    }
+}
+
+impl Form<Validated> {
+    fn submit(self) -> Result<(), SubmitError> {
+        // Only validated forms can be submitted
+        send(self.data)
+    }
+}
+
+// Form::new(data).submit() — compile error! Must validate first.
+```
+
+## Dynamic Dispatch
+
+```rust
+// Static dispatch (monomorphization) — zero cost, larger binary
+fn process(handler: impl Handler) { handler.handle(); }
+
+// Dynamic dispatch (trait objects) — vtable indirection, smaller binary
+fn process(handler: &dyn Handler) { handler.handle(); }
+
+// Use trait objects when:
+// - You need a heterogeneous collection
+// - You want to reduce binary size (e.g., embedded)
+// - The type is determined at runtime
+
+// Trait object safety: a trait is object-safe if:
+// - No methods return Self
+// - No methods have generic type parameters
+// - No associated functions (no &self receiver)
+```
+
+## Derive and Common Traits
+
+```rust
+// Derive what you can — it's correct and free
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct UserId(String);
+
+// Standard trait hierarchy to consider:
+// Debug         — always derive, essential for diagnostics
+// Clone         — when values need to be duplicated
+// PartialEq/Eq  — when values need comparison
+// Hash          — when used as map keys (requires Eq)
+// Default       — when a meaningful zero value exists
+// Display       — for user-facing output (implement manually)
+// Serialize/Deserialize — for serde (derive with feature flag)
+
+// Don't derive Copy unless the type is truly trivially copyable
+// and you want implicit copies. Copy types can't have Drop.
+```
+
+## Anti-Patterns
+
+```rust
+// Never: Trait objects everywhere when generics would work
+// Box<dyn Fn()> is fine for callbacks stored in structs
+// impl Fn() is better for function parameters
+
+// Never: Overusing generics for types that will only ever have one concrete type
+fn process<T: Into<String>>(name: T) { } // Just take String or &str
+
+// Never: Unused type parameters
+struct Wrapper<T> { // T is not used — won't compile without PhantomData
+    data: Vec<u8>,
+}
+
+// Never: Implementing traits for types you don't own without a newtype
+// Orphan rule prevents this anyway — respect it
+```