@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/rust-patterns/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: rust-patterns
+description: Idiomatic Rust design guide covering ownership and borrowing choices, Result-based errors with thiserror in libraries and anyhow in binaries, traits and generics, iterator chains, async with tokio, rules for unsafe, cargo workspaces and clippy settings. Use when writing new Rust code, shaping a crate's public API, choosing between owned and borrowed types, or setting up a Cargo workspace and lint policy.
+license: MIT
+compatibility: Any Agent Skills host. Needs a Rust toolchain (cargo, rustc, clippy, rustfmt) to check the code it writes.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "cargo"
+  kete-loom/owner: "Kete-org"
+---
+
+# Rust patterns
+
+Write Rust that compiles on the first honest try, says what it owns, and fails with typed errors instead of panics.
+
+## 0. Before you write
+
+1. Read `Cargo.toml` (and the workspace root's, if any): edition, `rust-version`, features, existing error crate, async runtime. Match them; never add a second error crate or runtime.
+2. Read `clippy.toml`, `rustfmt.toml` and any `[lints]` table. They are the house rules.
+3. Find a neighbouring module that does something similar and copy its shape (error type, constructor style, module layout).
+4. If the task needs a new dependency, **stop and ask the user** before adding it, and name the crate and why.
+
+## 1. Ownership and borrowing
+
+Decide per parameter, in this order:
+
+| Need | Take |
+|---|---|
+| Only read it | `&T`, `&str`, `&[T]`, `&Path` (not `&String`, `&Vec<T>`, `&PathBuf`) |
+| Mutate the caller's value | `&mut T` |
+| Store it or move it to another thread | `T` by value (`String`, `Vec<T>`) |
+| Accept owned or borrowed, store it | `impl Into<String>` / `impl Into<PathBuf>` |
+| Return borrowed-or-owned | `Cow<'_, str>` |
+
+- Return owned values from constructors and builders; return references only from accessors (`fn name(&self) -> &str`).
+- When the borrow checker objects, restructure first: shorten the borrow with a block, split the struct into fields borrowed separately, or collect indices before mutating. Use `.clone()` only when the data is small or the copy is the real intent, never just to silence an error.
+- Shared ownership: `Rc<T>` single-threaded, `Arc<T>` across threads. Interior mutability: `Cell`/`RefCell` single-threaded, `Mutex`/`RwLock` or atomics across threads. Reaching for `Rc<RefCell<T>>` everywhere usually means the ownership tree needs redesign; say so.
+- Add explicit lifetimes only when elision can't express the relationship. A struct holding references (`struct Parser<'a>`) is fine for short-lived views; long-lived structs should own their data.
+
+## 2. Errors
+
+- Library crates: one error enum per crate or module with `thiserror`. Wrap sources with `#[from]` or `#[source]` so the chain survives.
+- Binaries and app glue: `anyhow::Result<T>`, adding context at each boundary with `.context("reading config")` / `.with_context(|| format!("opening {path:?}"))`.
+- Propagate with `?`. Convert at module boundaries, not at every call.
+- `unwrap()` and `expect()` belong in tests, examples and provably-impossible cases. For the last, use `expect("reason this cannot fail")`, never bare `unwrap()`.
+- Never return `Result<T, String>` or `Box<dyn Error>` from a public library API; callers can't match on them.
+- `panic!` is for broken invariants (bugs), not for bad input, missing files or network failures.
+
+Patterns and full examples: `references/errors-and-traits.md`.
+
+## 3. Traits and generics
+
+- Prefer generics (`fn f<R: Read>(r: R)` or `impl Read`) for hot paths and when the caller picks one type. Use `dyn Trait` for heterogeneous collections, plugin points and to cut compile time or binary size.
+- Keep trait bounds on `impl` blocks and functions, not on struct definitions.
+- Implement standard traits instead of ad hoc methods: `From`/`TryFrom` for conversions, `Display` for user-facing text, `Default`, `FromStr`, `Iterator`, `AsRef`.
+- Derive `Debug` on every public type. Derive `Clone`, `PartialEq`, `Eq`, `Hash` only when they make sense for the type.
+- Newtypes (`struct UserId(u64)`) for values that must not be mixed up. Enums instead of boolean flags or stringly-typed states.
+- Don't implement `Deref` to fake inheritance.
+
+## 4. Iterators and collections
+
+- Chain `iter()`, `map`, `filter`, `filter_map`, `flat_map`, then `collect()`; collect into `Result<Vec<_>, _>` to stop at the first error.
+- Use a plain `for` loop when the body has side effects, early `return`, or `?` that would make the chain unreadable.
+- Pre-size with `Vec::with_capacity` when the length is known. Use the `entry` API on maps instead of a lookup followed by an insert.
+- Don't `collect()` just to iterate again; pass the iterator on (`impl Iterator<Item = T>`).
+
+## 5. Async with tokio
+
+1. One runtime, created once with `#[tokio::main]` in the binary. Libraries take no runtime dependency they can avoid and never create their own runtime.
+2. Never block inside async code: no `std::thread::sleep`, `std::fs` on hot paths, blocking HTTP clients, or long CPU loops. Use `tokio::time::sleep`, `tokio::fs`, or move the work into `tokio::task::spawn_blocking`.
+3. Never hold a `std::sync::Mutex` guard across `.await`. Drop it before awaiting, or use `tokio::sync::Mutex` when the lock must span an await.
+4. Every `tokio::spawn` gets an owner: keep the `JoinHandle` (or use a `JoinSet`) and handle its result, or the task's panic and error vanish.
+5. Bound concurrency and channels: `tokio::sync::Semaphore`, bounded `mpsc::channel(n)`. Unbounded channels need a written reason.
+6. Add timeouts to network I/O with `tokio::time::timeout`, and support shutdown with a cancellation signal checked in `tokio::select!`.
+7. Spawned futures must be `Send + 'static`: move owned data (or an `Arc`) into them, don't borrow.
+
+## 6. Unsafe
+
+- Don't write `unsafe` unless the task cannot be done in safe Rust (FFI, a measured hot path, a primitive the standard library lacks). If you think you need it, **stop and tell the user why** before writing it.
+- Every `unsafe` block gets a `// SAFETY:` comment naming the invariant that makes it sound, and every `unsafe fn` gets a `# Safety` doc section stating what callers must uphold.
+- Keep the block as small as possible and wrap it in a safe API that enforces the invariant.
+- Run the tests under Miri (`cargo +nightly miri test`) when unsafe code touches pointers or memory layout, if Miri is available.
+
+## 7. Cargo workspaces
+
+- Root `Cargo.toml` with `[workspace]`, `members`, and shared versions in `[workspace.dependencies]`; members use `serde = { workspace = true }`.
+- Put shared lint settings in `[workspace.lints]` and `[lints] workspace = true` in each member.
+- Features are additive: a feature must never remove an API or change behaviour incompatibly. Gate optional dependencies with `dep:name`.
+- Commit `Cargo.lock`. Cargo's current guidance is to commit it for libraries too; follow the project if it has a documented reason not to.
+- Layout and a starter manifest: `references/cargo-and-clippy.md`.
+
+## 8. Finish: format, lint, test
+
+Run, and fix everything before you report:
+
+```sh
+cargo fmt --all
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+```
+
+If the project has mutually exclusive features, `--all-features` fails by design: use the feature flags CI uses instead.
+
+- Fix clippy warnings in the code. Suppress only on the smallest item, with a reason: `#[expect(clippy::lint_name, reason = "...")]` when the project's `rust-version` is 1.81 or newer (it warns once the lint stops firing), otherwise `#[allow(clippy::lint_name)]` plus a comment.
+- If a check fails for reasons outside your change, report it instead of fixing unrelated code.
+
+## Never
+
+- Never add `unwrap()` on user input, I/O, parsing or network results in non-test code.
+- Never silence the borrow checker with `clone()`, `Rc<RefCell<_>>` or `unsafe` without saying why.
+- Never use `std::mem::transmute` to convert between types that have safe conversions.
+- Never add a dependency, a feature flag or `#![allow(...)]` at crate level without asking.
+
+## Report back
+
+End with: files changed, the three commands above and their results, any `unsafe`, `allow` or new dependency introduced and why, and anything left undone.

package/skills/rust-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Should this Rust function take a String or a &str? It just looks up a key in a map",
+    "Set up a thiserror error enum for my parser crate and use anyhow in the CLI binary",
+    "Split my Rust project into a cargo workspace with a core library and a cli crate",
+    "Write an async tokio worker that pulls jobs from a channel and processes them with bounded concurrency",
+    "What's the idiomatic way to design a trait for pluggable storage backends in Rust?"
+  ],
+  "should_not_trigger": [
+    "Add proptest property tests for my Rust base64 encoder",
+    "Review this Rust pull request for unwraps and unsafe blocks before I merge it",
+    "cargo build fails with E0502 cannot borrow as mutable because it is also borrowed as immutable",
+    "Write idiomatic Go error handling with wrapped errors for this HTTP handler",
+    "Design a REST API for the orders service with pagination and versioning"
+  ]
+}

package/skills/rust-patterns/references/cargo-and-clippy.md

@@ -0,0 +1,105 @@
+# Cargo workspaces and clippy policy
+
+Read this when creating or restructuring a workspace, or setting lint policy.
+
+## Layout
+
+```
+my-project/
+├── Cargo.toml          # workspace root, no [package] unless it is also a crate
+├── Cargo.lock
+├── crates/
+│   ├── app-core/       # domain types and logic, no I/O
+│   ├── store/          # persistence, depends on app-core
+│   └── cli/            # binary, depends on app-core and store
+└── clippy.toml         # optional
+```
+
+Keep the dependency graph acyclic and pointing inwards: binaries depend on libraries, never the reverse.
+
+## Root manifest
+
+```toml
+[workspace]
+resolver = "3"          # edition 2024 default; use "2" on edition 2021
+members = ["crates/*"]
+
+[workspace.package]
+edition = "2024"
+license = "MIT"
+
+[workspace.dependencies]
+anyhow = "1"
+thiserror = "2"
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+
+[workspace.lints.rust]
+unsafe_code = "forbid"
+
+[workspace.lints.clippy]
+unwrap_used = "warn"
+expect_used = "warn"
+dbg_macro = "warn"
+todo = "warn"
+```
+
+Match the edition, resolver and dependency major versions already used by the project rather than copying the numbers above; they are placeholders.
+
+`unsafe_code = "forbid"` is a sensible default for crates with no FFI. Relax it per crate (`deny`, then `#[allow(unsafe_code)]` on the one module) only where unsafe is justified.
+
+## Member manifest
+
+```toml
+[package]
+name = "store"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+app-core = { path = "../app-core" }   # don't name a crate `core` or `std`: it shadows the built-in crate
+serde = { workspace = true }
+thiserror = { workspace = true }
+sqlx = { version = "0.8", optional = true }
+
+[features]
+default = []
+postgres = ["dep:sqlx"]
+
+[lints]
+workspace = true
+```
+
+## Useful cargo commands
+
+| Task | Command |
+|---|---|
+| Check fast without codegen | `cargo check --workspace --all-targets` |
+| Build one member | `cargo build -p store` |
+| Why is this crate here? | `cargo tree -i <crate>` |
+| Duplicate versions in the graph | `cargo tree -d` |
+| Features enabled on a crate | `cargo tree -e features -i <crate>` |
+| Update one dependency | `cargo update -p <crate>` |
+| Check every feature combination | `cargo hack check --feature-powerset` (needs `cargo-hack`) |
+
+## Clippy
+
+Baseline for CI:
+
+```sh
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+- `clippy::all` (the default groups) is on already. `clippy::pedantic` is opt-in and noisy; enable it only if the project already does, or the user asks.
+- `unwrap_used` and `expect_used` are restriction lints. Allow them in tests with `#[cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]` at the crate root, or in `clippy.toml` with `allow-unwrap-in-tests = true` and `allow-expect-in-tests = true`.
+- Suppress a lint on the smallest item, with a reason:
+
+```rust
+#[expect(clippy::too_many_arguments, reason = "mirrors the C API one-to-one")] // Rust 1.81+
+fn ffi_call(/* ... */) {}
+```
+
+On an older `rust-version`, use `#[allow(...)]` with a trailing comment instead.
+
+- Don't use `cargo clippy --fix` on a dirty tree without reviewing the diff it produces.

package/skills/rust-patterns/references/errors-and-traits.md

@@ -0,0 +1,97 @@
+# Errors and traits: worked patterns
+
+Read this when designing a crate's error type or a public trait.
+
+## Library error with thiserror
+
+```rust
+use std::path::PathBuf;
+
+#[derive(Debug, thiserror::Error)]
+pub enum ConfigError {
+    #[error("could not read config file {path:?}")]
+    Read {
+        path: PathBuf,
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("invalid config")]
+    Parse(#[from] toml::de::Error),
+    #[error("missing required key `{0}`")]
+    MissingKey(&'static str),
+}
+
+pub fn load(path: &std::path::Path) -> Result<Config, ConfigError> {
+    let text = std::fs::read_to_string(path).map_err(|source| ConfigError::Read {
+        path: path.to_owned(),
+        source,
+    })?;
+    let config: Config = toml::from_str(&text)?; // From<toml::de::Error>
+    Ok(config)
+}
+```
+
+Rules:
+
+- The `#[error]` message describes this layer only. Don't repeat the source's message in it; reporters walk `source()` and print the chain.
+- Use `#[from]` only when the conversion is unambiguous. If two call sites produce the same source type with different meaning, use explicit variants with `#[source]` and `map_err`.
+- Mark public error enums `#[non_exhaustive]` if you expect to add variants without a major version bump.
+
+## Application errors with anyhow
+
+```rust
+use anyhow::{bail, Context, Result};
+
+fn main() -> Result<()> {
+    let path = std::env::args().nth(1).context("usage: tool <config>")?;
+    let config = mylib::load(path.as_ref())
+        .with_context(|| format!("loading config from {path}"))?;
+    if config.workers == 0 {
+        bail!("workers must be at least 1");
+    }
+    Ok(())
+}
+```
+
+- Returning `anyhow::Result<()>` from `main` prints the error chain on failure and exits non-zero.
+- Use `anyhow::Error::downcast_ref::<T>()` only at the top level, when you must branch on a specific cause.
+
+## Option and Result helpers
+
+| Want | Use |
+|---|---|
+| Option to Result | `opt.ok_or(Error::Missing)?` / `opt.ok_or_else(\|\| ...)?` |
+| Default on None | `opt.unwrap_or_default()` / `unwrap_or_else(\|\| ...)` |
+| Transform the success value | `res.map(...)` |
+| Chain fallible steps | `res.and_then(...)` |
+| Log and drop an error deliberately | `if let Err(e) = res { tracing::warn!(error = %e, "..."); }` |
+
+Never use `let _ = fallible();` for a `Result` whose failure matters; handle or log it.
+
+## Trait design
+
+```rust
+pub trait Store {
+    fn get(&self, key: &str) -> Result<Option<Vec<u8>>, StoreError>;
+    fn put(&self, key: &str, value: &[u8]) -> Result<(), StoreError>;
+}
+
+pub struct Cache<S: Store> { inner: S }      // avoid: bound on the struct
+pub struct Cache<S> { inner: S }             // prefer
+impl<S: Store> Cache<S> { /* ... */ }        // bound where it is needed
+```
+
+- Take `&self` in trait methods unless mutation is the point; implementations can use interior mutability.
+- Keep traits small and focused. A trait with ten methods usually wants splitting.
+- To make a trait usable as `dyn Trait`, avoid generic methods and `Self` return types (or gate them with `where Self: Sized`).
+- Sealed traits (a private supertrait) stop downstream crates from implementing a trait you need to extend later.
+
+## Async traits
+
+`async fn` in traits works on stable Rust for static dispatch. For `dyn` use, or when callers need the returned future to be `Send`, check the project's current approach (the `async-trait` crate, or a method returning `Pin<Box<dyn Future<Output = T> + Send + '_>>`) and follow it rather than mixing styles.
+
+## Conversions
+
+- `impl From<A> for B` gives you `Into` for free. Never implement `Into` directly.
+- `TryFrom` for conversions that can fail; its `Error` type should be a real error, not `()` or `String`.
+- `AsRef<str>` / `AsRef<Path>` for functions that only need to look at the data.

package/skills/rust-testing/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: rust-testing
+description: Writing and organising tests for Rust crates with cargo test, covering #[cfg(test)] unit modules, integration tests under tests/, doc tests, trait-based fakes and mockall, property tests with proptest, #[tokio::test] for async code, and the cargo test flags for filtering and output. Use when adding or fixing Rust tests, deciding where a test belongs in a crate, testing async or I/O-bound Rust code, or getting a flaky cargo test run under control.
+license: MIT
+compatibility: Any Agent Skills host. Needs a Rust toolchain with cargo. proptest, mockall and tokio are used only if the project already depends on them or the user agrees to add them.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "cargo"
+  kete-loom/owner: "Kete-org"
+---
+
+# Rust testing
+
+Put each test where it can see exactly what it needs, keep it deterministic, and prove it with a `cargo test` run.
+
+## 0. Before you write a test
+
+1. Read `Cargo.toml` `[dev-dependencies]`: which of `proptest`, `mockall`, `tokio` (with which features), `tempfile`, `insta`, `rstest` are already there. Use those. **Ask the user** before adding a new dev-dependency.
+2. Check how CI runs tests (`.github/workflows/`, `Makefile`, `justfile`): plain `cargo test`, `cargo nextest run`, feature flags, `--workspace`. Use the same command.
+3. Run the existing suite once and record the result. If it already fails, **stop and tell the user** which tests fail before you change anything.
+
+## 1. Choose where the test goes
+
+| Testing | Put it in | Can see |
+|---|---|---|
+| One function or private helper | `#[cfg(test)] mod tests` at the bottom of the same file | Private items via `use super::*;` |
+| The crate's public API, as a user would call it | `tests/<feature>.rs` (each file is its own crate) | Only `pub` items |
+| A usage example in the docs | A fenced code block in the item's `///` doc comment | Only `pub` items |
+| A binary's behaviour end to end | `tests/cli.rs`, running the binary (for example with `assert_cmd` if present) | Process output |
+
+- Binary crates: integration tests can't import `main.rs`. Move logic into `src/lib.rs` and keep `main.rs` thin.
+- Shared integration helpers go in `tests/common/mod.rs` (not `tests/common.rs`, which cargo would run as its own test crate), pulled in with `mod common;`.
+
+## 2. Unit tests
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_port_from_host_string() {
+        assert_eq!(parse_port("localhost:8080"), Ok(8080));
+    }
+
+    #[test]
+    fn rejects_missing_port() {
+        let err = parse_port("localhost").unwrap_err();
+        assert!(matches!(err, ParseError::MissingPort));
+    }
+
+    #[test]
+    fn reads_port_from_config_text() -> Result<(), Box<dyn std::error::Error>> {
+        let config: Config = "port = 8080".parse()?;
+        assert_eq!(config.port, 8080);
+        Ok(())
+    }
+
+    #[test]
+    #[should_panic(expected = "capacity must be non-zero")]
+    fn zero_capacity_panics() {
+        RingBuffer::<u8>::new(0);
+    }
+}
+```
+
+- Name tests after the behaviour (`rejects_missing_port`), not `test1`.
+- Assert on the specific error variant with `matches!` instead of comparing `Debug` strings.
+- Use `#[should_panic(expected = "...")]` only for documented panics; give the expected text so an unrelated panic doesn't pass.
+- Tests may return `Result<(), E>` to use `?`; in tests, `unwrap()` and `expect()` are fine.
+
+## 3. Doc tests
+
+- Every public function with a non-obvious use gets an example. Doc tests compile and run with `cargo test` (`cargo test --doc` for only these).
+- Use `?` in examples by ending with `# Ok::<(), Box<dyn std::error::Error>>(())`; lines starting with `# ` are hidden from the rendered docs.
+- Mark examples `no_run` when they need network or files, `compile_fail` to prove misuse doesn't compile, `ignore` only with a written reason.
+- Doc tests run only for library targets. `cargo nextest` does not run doc tests, so CI that uses nextest needs a separate `cargo test --doc` step.
+
+## 4. Fakes and mocks via traits
+
+Rust has no runtime monkey-patching. Make the boundary a trait and inject it.
+
+1. Define a small trait for the external dependency (clock, HTTP client, repository).
+2. Make the code under test generic over it (`struct Service<R: Repo>`) or take `&dyn Repo` / `Arc<dyn Repo>`.
+3. In tests, prefer a hand-written fake (an in-memory `HashMap` store) for state; use `mockall` (`#[cfg_attr(test, mockall::automock)]` on the trait) when you must assert on calls.
+4. Never mock the type under test, and never mock pure functions you could just call.
+
+Examples for fakes, mockall expectations and time control: `references/fakes-proptest-async.md`.
+
+## 5. Property tests with proptest
+
+Use them for parsers, encoders, data structures and anything with an invariant ("decode(encode(x)) == x", "sorted output is a permutation of input").
+
+```rust
+use proptest::prelude::*;
+
+proptest! {
+    #[test]
+    fn round_trips(s in "\\PC*") {
+        prop_assert_eq!(decode(&encode(&s)).unwrap(), s);
+    }
+}
+```
+
+- Use `prop_assert!` / `prop_assert_eq!` inside `proptest!` so failures shrink.
+- Commit the `proptest-regressions/` files it writes; they replay past failures.
+
+## 6. Async tests
+
+- `#[tokio::test]` runs on a current-thread runtime. Use `#[tokio::test(flavor = "multi_thread", worker_threads = 2)]` only when the code needs real parallelism (for example it calls `block_in_place`).
+- `#[tokio::test]` needs tokio's `macros` and `rt` features for the test target (`[dev-dependencies] tokio = { ..., features = ["macros", "rt"] }`); the `multi_thread` flavor also needs `rt-multi-thread`.
+- Don't sleep for real. With the `test-util` feature, `#[tokio::test(start_paused = true)]` and `tokio::time::advance` make timers instant and deterministic.
+- Wrap anything that could hang in `tokio::time::timeout` so a bug fails the test instead of stalling CI.
+
+## 7. Running tests
+
+| Goal | Command |
+|---|---|
+| Everything in a workspace | `cargo test --workspace --all-features` |
+| Tests whose name contains a string | `cargo test parse_port` |
+| One integration test file | `cargo test --test cli` |
+| Only unit tests in the library | `cargo test --lib` |
+| Only doc tests | `cargo test --doc` |
+| Exact name match (full module path) | `cargo test -- --exact parser::tests::parses_port_from_host_string` |
+| Show `println!` output | `cargo test -- --nocapture` |
+| Run serially (shared global state) | `cargo test -- --test-threads=1` |
+| Run ignored (slow) tests | `cargo test -- --ignored` or `-- --include-ignored` |
+| Keep going after a failing test crate | `cargo test --no-fail-fast` |
+
+Flags before `--` go to cargo; flags after `--` go to the test binary.
+
+## 8. Flaky tests
+
+1. Run the test alone and in a loop to reproduce: `for i in $(seq 50); do cargo test name -- --exact || break; done`.
+2. Common causes: tests sharing a file path, port, env var or global (run in parallel threads); real time; `HashMap` iteration order; unseeded randomness.
+3. Fix the cause: `tempfile::tempdir()` per test, bind port `0`, pass config instead of reading env vars, sort before asserting. `--test-threads=1` is a diagnostic, not a fix.
+
+## Never
+
+- Never delete, `#[ignore]` or weaken an existing test to make the suite pass without the user's agreement.
+- Never let tests touch the real network, the user's home directory or shared databases.
+- Never assert on `format!("{:?}", ...)` output when a structured comparison is possible.
+
+## Report back
+
+End with: tests added or changed (names and files), the exact command you ran, pass/fail counts, and anything not covered.

package/skills/rust-testing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Add unit tests for the tokenizer module in my Rust crate",
+    "How do I mock the HTTP client trait in Rust so my service tests don't hit the network?",
+    "My #[tokio::test] hangs forever when the retry backoff sleeps, how do I test it without waiting?",
+    "Where should integration tests go in a Rust library and how do I share helpers between them?",
+    "Write a proptest that checks my Rust serializer round-trips arbitrary input"
+  ],
+  "should_not_trigger": [
+    "Refactor this Rust module to return thiserror errors instead of String",
+    "My Rust tests don't compile anymore after bumping tokio, error E0277 future is not Send",
+    "Review my Rust diff for blocking calls inside async functions",
+    "Write pytest fixtures for the Django user model",
+    "Set up Playwright end-to-end tests for the checkout flow"
+  ]
+}

package/skills/rust-testing/references/fakes-proptest-async.md

@@ -0,0 +1,113 @@
+# Fakes, mockall, proptest strategies and async time
+
+Read this when a test needs a test double, a custom proptest strategy, or control over time.
+
+## Hand-written fake
+
+```rust
+pub trait Repo {
+    fn get(&self, id: u64) -> Result<Option<User>, RepoError>;
+    fn save(&self, user: &User) -> Result<(), RepoError>;
+}
+
+#[cfg(test)]
+#[derive(Default)]
+struct FakeRepo {
+    users: std::sync::Mutex<std::collections::HashMap<u64, User>>,
+}
+
+#[cfg(test)]
+impl Repo for FakeRepo {
+    fn get(&self, id: u64) -> Result<Option<User>, RepoError> {
+        Ok(self.users.lock().unwrap().get(&id).cloned())
+    }
+    fn save(&self, user: &User) -> Result<(), RepoError> {
+        self.users.lock().unwrap().insert(user.id, user.clone());
+        Ok(())
+    }
+}
+```
+
+A fake keeps real behaviour (what you save, you can read back), so tests check outcomes instead of call sequences. Prefer it over a mock whenever state is involved.
+
+## mockall
+
+```rust
+#[cfg_attr(test, mockall::automock)]
+pub trait Mailer {
+    fn send(&self, to: &str, body: &str) -> Result<(), MailError>;
+}
+
+#[test]
+fn sends_welcome_mail_once() {
+    let mut mailer = MockMailer::new();
+    mailer
+        .expect_send()
+        .withf(|to, _| to == "ama@example.com")
+        .times(1)
+        .returning(|_, _| Ok(()));
+
+    signup(&mailer, "ama@example.com").unwrap();
+}
+```
+
+- Expectations are checked when the mock is dropped; an unmet `times(1)` fails the test.
+- Keep `mockall` in `[dev-dependencies]` and gate `automock` with `cfg_attr(test, ...)` so it never reaches release builds.
+- If a mock needs more than three expectations, the unit is probably doing too much; consider a fake or a smaller seam.
+
+## Injecting time
+
+```rust
+pub trait Clock { fn now(&self) -> std::time::SystemTime; }
+
+struct FixedClock(std::time::SystemTime);
+impl Clock for FixedClock { fn now(&self) -> std::time::SystemTime { self.0 } }
+```
+
+Pass the clock into the code under test rather than calling `SystemTime::now()` inside it.
+
+## proptest strategies
+
+```rust
+use proptest::prelude::*;
+
+fn order() -> impl Strategy<Value = Order> {
+    (1u32..1000, prop::collection::vec("[a-z]{1,8}", 0..10))
+        .prop_map(|(qty, tags)| Order { qty, tags })
+}
+
+proptest! {
+    #![proptest_config(ProptestConfig::with_cases(512))]
+
+    #[test]
+    fn order_round_trips_through_text(o in order()) {
+        prop_assert_eq!(o.to_string().parse::<Order>().unwrap(), o);
+    }
+}
+```
+
+- Derive strategies for your own types with `prop_map` or, if the project uses it, `#[derive(Arbitrary)]` from `proptest-derive`.
+- Use `prop_assume!` sparingly; filtering too many cases makes proptest give up.
+
+## Async time control (tokio `test-util` feature)
+
+```rust
+#[tokio::test(start_paused = true)]
+async fn retries_after_backoff() {
+    let handle = tokio::spawn(fetch_with_retry());
+    tokio::time::advance(std::time::Duration::from_secs(5)).await;
+    assert!(handle.await.unwrap().is_ok());
+}
+```
+
+With time paused, the runtime auto-advances to the next timer when every task is idle, so `sleep`-based code completes instantly and deterministically.
+
+## Temporary files
+
+```rust
+let dir = tempfile::tempdir()?;           // removed when `dir` is dropped
+let path = dir.path().join("config.toml");
+std::fs::write(&path, "port = 8080")?;
+```
+
+Never write test files into the repository tree or a fixed path in `/tmp`.