@coralai/sps-cli 0.41.2 → 0.43.0

package/skills/rust/references/ownership.md

@@ -0,0 +1,263 @@
+# Rust — Ownership
+
+Borrowing, lifetimes, move vs. copy, smart pointers. The part the language is organized around.
+
+## The rules
+
+1. Each value has one owner.
+2. When the owner goes out of scope, the value is dropped.
+3. You can borrow immutably (any number of `&T`) OR mutably (exactly one `&mut T`), never both at once.
+
+Everything else is consequences of these.
+
+## Move vs. copy
+
+```rust
+let s = String::from("hi");
+let t = s;              // move: s is no longer valid
+// println!("{s}")       // ❌ error
+
+let n = 5;
+let m = n;              // copy: n is still valid (i32 is Copy)
+println!("{n} {m}");    // ✅
+```
+
+`Copy` types (primitives, `&T`, arrays of `Copy`) are copied implicitly. Everything else is moved. Add `#[derive(Clone, Copy)]` to your own small value types.
+
+## Borrowing
+
+Prefer borrows over ownership in parameters. The caller chooses.
+
+```rust
+fn length(s: &str) -> usize { s.len() }
+
+let owned = String::from("hi");
+length(&owned);         // caller keeps the String
+length("hello");        // works with a &'static str too
+```
+
+Rule: **accept `&str` / `&[T]` / `&T`, not `String` / `Vec<T>` / `T`**, unless you need ownership (e.g., storing it).
+
+## The borrow checker — common errors and fixes
+
+### "cannot borrow X as mutable because it is also borrowed as immutable"
+
+```rust
+// ❌
+let mut v = vec![1, 2, 3];
+let first = &v[0];      // immutable borrow
+v.push(4);              // mutable borrow while &first alive
+println!("{first}");    // error
+
+// ✅ shorten the immutable borrow
+let first = v[0];       // copy out (if Copy)
+v.push(4);
+println!("{first}");
+
+// ✅ scope it
+{
+    let first = &v[0];
+    println!("{first}");
+}                        // borrow ends here
+v.push(4);
+```
+
+### "use of moved value"
+
+```rust
+// ❌
+let s = String::from("hi");
+takes(s);
+println!("{s}");         // already moved
+
+// ✅ pass by reference
+takes(&s);
+
+// ✅ clone if you really need two owners
+takes(s.clone());
+```
+
+## Lifetimes — usually inferred
+
+Rust figures out most lifetimes. You only annotate when the compiler can't:
+
+```rust
+fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
+    if x.len() > y.len() { x } else { y }
+}
+```
+
+The `'a` says "the returned reference is valid for the shorter of x's and y's lifetimes".
+
+In structs that hold references, you must annotate:
+
+```rust
+struct Parser<'src> {
+    input: &'src str,
+}
+```
+
+Rule of thumb: if you're fighting lifetimes, you might want owned data instead of references. Sometimes a `String` is fine.
+
+## `'static` lifetime
+
+`'static` means "lives for the whole program". Comes up with:
+- String literals (`&'static str`)
+- Bounded trait objects in async / threading (`Send + Sync + 'static`)
+- Global `Mutex<T>` via `OnceLock` / `LazyLock`
+
+A function bound `T: 'static` does NOT mean "must be owned forever" — it means "contains no non-static references". An owned `String` is `'static` because it borrows nothing.
+
+## Smart pointers
+
+| Type | Use |
+|---|---|
+| `Box<T>` | Heap allocate; needed for recursive types, trait objects |
+| `Rc<T>` | Shared ownership, single-threaded; refcount |
+| `Arc<T>` | Shared ownership, thread-safe |
+| `RefCell<T>` | Interior mutability, single-threaded, checked at runtime |
+| `Mutex<T>` / `RwLock<T>` | Interior mutability, thread-safe |
+| `Cow<'a, T>` | Borrow OR own; copy-on-write |
+
+Rule: **start with `&T` / `&mut T`. Reach for smart pointers only when simple borrowing can't model what you need.**
+
+## Interior mutability
+
+When a value is shared (`&T`) but a method needs to mutate it internally (caches, ref counts), use `RefCell` (single-threaded) or `Mutex` (threaded).
+
+```rust
+use std::cell::RefCell;
+
+struct Cache {
+    map: RefCell<HashMap<String, String>>,
+}
+
+impl Cache {
+    fn get(&self, k: &str) -> Option<String> {
+        self.map.borrow().get(k).cloned()
+    }
+    fn put(&self, k: String, v: String) {
+        self.map.borrow_mut().insert(k, v);
+    }
+}
+```
+
+`.borrow_mut()` while another `.borrow()` is live panics at runtime. It trades compile-time for runtime checks — a last resort.
+
+## `Rc<RefCell<T>>` — the single-threaded shared-mutable
+
+Legal, common in tree / graph data structures, single-threaded only.
+
+```rust
+use std::{cell::RefCell, rc::Rc};
+
+type Node = Rc<RefCell<NodeData>>;
+```
+
+If two threads may touch it → `Arc<Mutex<T>>`. If you find yourself writing `Rc<RefCell<...>>` often, reconsider — sometimes ownership flows would be cleaner with a different data layout (`Vec<Node>` + indexes).
+
+## `Cow` — borrow or own, at runtime
+
+```rust
+use std::borrow::Cow;
+
+fn normalize(s: &str) -> Cow<'_, str> {
+    if s.chars().any(|c| c.is_uppercase()) {
+        Cow::Owned(s.to_lowercase())
+    } else {
+        Cow::Borrowed(s)
+    }
+}
+```
+
+Great for "usually don't need to clone, sometimes do" paths. Callers get a `&str` from `.as_ref()`.
+
+## `Drop` — RAII
+
+Values implement `Drop` to release resources (file handles, mutex guards, DB connections).
+
+```rust
+impl Drop for TempFile {
+    fn drop(&mut self) {
+        std::fs::remove_file(&self.path).ok();
+    }
+}
+```
+
+Runs when the value goes out of scope. Don't `mem::forget` something with a `Drop` unless you really know.
+
+Guards (`MutexGuard`, `RefMut`) are `Drop`-based — they release the lock when dropped. Keep them scoped tightly:
+
+```rust
+{
+    let mut g = mu.lock().unwrap();
+    g.push(x);
+}               // lock released HERE
+call_may_block();   // no lock held
+```
+
+## `unsafe` — the escape hatch
+
+Only where the borrow checker can't prove safety (FFI, raw pointers, some `Send`/`Sync` work). Every `unsafe` block needs a `// SAFETY:` comment stating the invariants you've manually verified.
+
+```rust
+// SAFETY: `ptr` is not null (checked above) and `len` is within the allocation.
+let slice = unsafe { std::slice::from_raw_parts(ptr, len) };
+```
+
+If you can do it safely, do it safely. `unsafe` is not a performance knob.
+
+## Common patterns
+
+### Newtype for domain meaning
+
+```rust
+pub struct UserId(pub String);
+pub struct Email(pub String);
+
+fn find_user(id: UserId) -> Option<User> { ... }
+
+// fn call takes UserId, not String → hard to mix with other string IDs
+```
+
+### Builder
+
+```rust
+let req = Request::builder()
+    .url("https://x.com")
+    .timeout(Duration::from_secs(5))
+    .build()?;
+```
+
+For types with many optional fields or construction invariants.
+
+### Typestate — encode state in the type
+
+```rust
+struct Draft;
+struct Published;
+
+struct Post<State> { body: String, _s: PhantomData<State> }
+
+impl Post<Draft> {
+    fn publish(self) -> Post<Published> { ... }
+}
+
+impl Post<Published> {
+    fn url(&self) -> String { ... }
+    // no publish() here — you can't double-publish
+}
+```
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `.clone()` reflex to silence the borrow checker | Understand what ownership you need; clones should be deliberate |
+| `Rc<RefCell<T>>` everywhere | Revisit data layout; many problems want a `Vec<T>` with indexes |
+| Accepting `String` / `Vec<T>` when `&str` / `&[T]` works | Over-constrains callers |
+| Returning references from local functions ("dangling reference") | Return owned data, or rework the lifetime story |
+| `mut` everywhere | Minimize mutation; Rust rewards immutable-by-default |
+| Implementing `Clone` by default | Only for types callers will reasonably clone |
+| Allocating in a hot loop (`format!`, `vec![...]`) | Preallocate; `write!` into a reused buffer |
+| Leaking a `MutexGuard` into an async `.await` | Guard is not `Send`; use `tokio::sync::Mutex` or drop the guard before awaiting |

package/skills/rust/references/testing.md

@@ -0,0 +1,274 @@
+# Rust — Testing
+
+`#[test]`, integration tests, property testing, snapshots. For general TDD, see `coding-standards/references/tdd.md`.
+
+## Unit tests — alongside the code
+
+```rust
+// src/math.rs
+pub fn add(a: i32, b: i32) -> i32 { a + b }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn adds_positives() {
+        assert_eq!(add(2, 3), 5);
+    }
+
+    #[test]
+    #[should_panic(expected = "overflow")]
+    fn panics_on_overflow() {
+        add(i32::MAX, 1);
+    }
+}
+```
+
+Run with `cargo test`. The `#[cfg(test)]` block is compiled only for tests — the test code doesn't ship in release builds.
+
+## Integration tests — `tests/` directory
+
+```
+mycrate/
+├── src/
+│   └── lib.rs
+└── tests/
+    └── api.rs          # one file = one crate, black-box tests
+```
+
+```rust
+// tests/api.rs
+use mycrate::load;
+
+#[test]
+fn loads_from_file() {
+    let cfg = load("tests/fixtures/sample.yaml").unwrap();
+    assert_eq!(cfg.name, "sample");
+}
+```
+
+Integration tests use only the public API. If you need internal access, that's a unit test.
+
+## Assertions
+
+```rust
+assert!(cond);
+assert_eq!(a, b);
+assert_ne!(a, b);
+
+// With custom message
+assert_eq!(got, want, "parsed value mismatch for input {input:?}");
+```
+
+Failures show a nice diff. Stick with `assert_eq!` over manual `if got != want { panic! }`.
+
+## Parameterized tests — table style
+
+```rust
+#[test]
+fn add_cases() {
+    for (a, b, want) in [(1, 2, 3), (0, 0, 0), (-1, 1, 0)] {
+        assert_eq!(add(a, b), want, "add({a}, {b})");
+    }
+}
+```
+
+Or use `rstest` for per-case test names:
+
+```rust
+use rstest::rstest;
+
+#[rstest]
+#[case(1, 2, 3)]
+#[case(0, 0, 0)]
+#[case(-1, 1, 0)]
+fn add(#[case] a: i32, #[case] b: i32, #[case] want: i32) {
+    assert_eq!(crate::add(a, b), want);
+}
+```
+
+`cargo test add::case_1` runs one case.
+
+## Async tests
+
+With tokio:
+
+```rust
+#[tokio::test]
+async fn fetches() {
+    let body = fetch("http://...").await.unwrap();
+    assert!(body.contains("hi"));
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn multi_thread() { ... }
+```
+
+Other runtimes have their own macros (`#[async_std::test]`).
+
+## Property tests — `proptest` / `quickcheck`
+
+Generates random inputs; shrinks failing cases to a minimal counter-example.
+
+```rust
+use proptest::prelude::*;
+
+proptest! {
+    #[test]
+    fn sort_is_idempotent(v in any::<Vec<i32>>()) {
+        let mut s = v.clone();
+        s.sort();
+        let mut s2 = s.clone();
+        s2.sort();
+        prop_assert_eq!(s, s2);
+    }
+
+    #[test]
+    fn roundtrip(s in "\\PC*") {   // arbitrary printable UTF-8
+        let encoded = encode(&s);
+        prop_assert_eq!(decode(&encoded), s);
+    }
+}
+```
+
+Use for: parsers, serializers, invariant checks, anything with a large input space.
+
+## Snapshot tests — `insta`
+
+```rust
+#[test]
+fn render() {
+    insta::assert_snapshot!(render(&input));
+    insta::assert_yaml_snapshot!(serialize(&input));
+}
+```
+
+Run `cargo insta review` to approve / reject. Commit the snapshots under `src/snapshots/`. Review every diff deliberately.
+
+Great for CLI output, parser ASTs, generated config. Weak for flaky fields (timestamps, UUIDs) — redact or inject deterministic values.
+
+## Test doubles
+
+Fakes > mocks in Rust too.
+
+```rust
+// Production
+pub trait UserRepo {
+    fn find(&self, id: &str) -> Option<User>;
+}
+
+// In tests
+struct FakeRepo { users: HashMap<String, User> }
+
+impl UserRepo for FakeRepo {
+    fn find(&self, id: &str) -> Option<User> {
+        self.users.get(id).cloned()
+    }
+}
+```
+
+For mocks, `mockall`:
+
+```rust
+use mockall::automock;
+
+#[automock]
+trait UserRepo {
+    fn find(&self, id: &str) -> Option<User>;
+}
+
+let mut mock = MockUserRepo::new();
+mock.expect_find()
+    .with(eq("u1"))
+    .returning(|_| Some(User::sample()));
+```
+
+Reach for `mockall` when the trait has complex call expectations. Otherwise, fakes are clearer.
+
+## Test filtering
+
+```bash
+cargo test                          # all tests
+cargo test math                     # name contains 'math'
+cargo test --lib                    # unit tests only
+cargo test --test api               # one integration file
+cargo test -- --nocapture           # show println! output
+cargo test -- --test-threads=1      # serial execution (rare)
+```
+
+Add `--quiet` for cleaner CI output.
+
+## Golden files — `testdata/` + `env var`
+
+```rust
+const UPDATE: bool = option_env!("UPDATE_GOLDEN").is_some();
+
+#[test]
+fn render_matches_golden() {
+    let got = render(sample());
+    let path = "testdata/rendered.txt";
+    if UPDATE {
+        std::fs::write(path, &got).unwrap();
+    }
+    let want = std::fs::read_to_string(path).unwrap();
+    assert_eq!(got, want);
+}
+```
+
+Run `UPDATE_GOLDEN=1 cargo test` to regenerate. `insta` does this better in most cases.
+
+## Doc tests — executable examples in docs
+
+```rust
+/// Adds two numbers.
+///
+/// ```
+/// use mycrate::add;
+/// assert_eq!(add(2, 3), 5);
+/// ```
+pub fn add(a: i32, b: i32) -> i32 { a + b }
+```
+
+Run with `cargo test --doc`. Keeps public examples honest — if you change the API, the doc test breaks.
+
+## Benchmarks
+
+Stable Rust: `cargo bench` with `criterion`.
+
+```rust
+// benches/my_bench.rs
+use criterion::{criterion_group, criterion_main, Criterion};
+
+fn bench_parse(c: &mut Criterion) {
+    let input = "...";
+    c.bench_function("parse", |b| b.iter(|| parse(input)));
+}
+
+criterion_group!(benches, bench_parse);
+criterion_main!(benches);
+```
+
+Criterion runs statistical comparisons against previous runs, flags regressions.
+
+## `cargo test` + `cargo llvm-cov` for coverage
+
+```
+cargo install cargo-llvm-cov
+cargo llvm-cov --html
+```
+
+See `coding-standards/references/tdd.md` for target numbers.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `unwrap()` in non-test code copied into tests | Use `?` in `fn test() -> Result<(), Err>` if you want |
+| `std::thread::sleep` in async tests | `tokio::time::sleep` (or pause time for determinism) |
+| Tests that depend on execution order | Each test is independent; don't share globals |
+| Hitting real external services in unit tests | Use fakes / `wiremock` / `httpmock` |
+| Comparing `Debug` strings for equality | Use `assert_eq!` on typed values |
+| Snapshot of time-dependent output without redaction | Inject a clock |
+| Ignoring `#[should_panic]` without `expected = "..."` | Any panic passes; you want the specific one |
+| Test file names that don't match the module under test | `foo.rs` → `foo/tests.rs` or `tests/foo.rs` |