agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/own-refcell-interior.md

@@ -0,0 +1,97 @@
+# own-refcell-interior
+
+> Use `RefCell<T>` for interior mutability in single-threaded code
+
+## Why It Matters
+
+Rust's borrow checker enforces rules at compile time, but sometimes you need to mutate data through a shared reference. `RefCell<T>` moves borrow checking to runtime, allowing mutation through `&self`. This is essential for patterns like caches, lazy initialization, and observer patterns where compile-time borrowing is too restrictive.
+
+## Bad
+
+```rust
+struct Cache {
+    // Requires &mut self to update, breaking shared reference patterns
+    data: HashMap<String, String>,
+}
+
+impl Cache {
+    fn get_or_compute(&mut self, key: &str) -> &str {
+        // Caller needs &mut Cache, can't share cache reference
+        if !self.data.contains_key(key) {
+            self.data.insert(key.to_string(), expensive_compute(key));
+        }
+        &self.data[key]
+    }
+}
+```
+
+This forces exclusive access even for logically shared operations.
+
+## Good
+
+```rust
+use std::cell::RefCell;
+use std::collections::HashMap;
+
+struct Cache {
+    data: RefCell<HashMap<String, String>>,
+}
+
+impl Cache {
+    fn get_or_compute(&self, key: &str) -> String {
+        // Can mutate through &self
+        let mut data = self.data.borrow_mut();
+        if !data.contains_key(key) {
+            data.insert(key.to_string(), expensive_compute(key));
+        }
+        data[key].clone()
+    }
+}
+
+// Multiple references can coexist
+let cache = Cache::new();
+let ref1 = &cache;
+let ref2 = &cache;
+ref1.get_or_compute("key1");
+ref2.get_or_compute("key2");
+```
+
+## Common Pattern: Rc<RefCell<T>>
+
+```rust
+use std::rc::Rc;
+use std::cell::RefCell;
+
+// Shared mutable state in single-threaded code
+type SharedState = Rc<RefCell<AppState>>;
+
+fn create_handlers(state: SharedState) -> Vec<Box<dyn Fn()>> {
+    vec![
+        Box::new({
+            let state = state.clone();
+            move || state.borrow_mut().increment()
+        }),
+        Box::new({
+            let state = state.clone();
+            move || state.borrow_mut().decrement()
+        }),
+    ]
+}
+```
+
+## Runtime Panics
+
+`RefCell` panics if you violate borrowing rules at runtime:
+
+```rust
+let cell = RefCell::new(5);
+let borrow1 = cell.borrow();
+let borrow2 = cell.borrow_mut(); // PANIC: already borrowed
+```
+
+Use `try_borrow()` and `try_borrow_mut()` for fallible borrowing.
+
+## See Also
+
+- [own-rc-single-thread](./own-rc-single-thread.md) - Combining with Rc for shared ownership
+- [own-mutex-interior](./own-mutex-interior.md) - Thread-safe alternative

package/template/agent/skills/rust-developer/references/rust-rules/own-rwlock-readers.md

@@ -0,0 +1,122 @@
+# own-rwlock-readers
+
+> Use `RwLock<T>` when reads significantly outnumber writes
+
+## Why It Matters
+
+`Mutex<T>` allows only one thread to access data at a time, even for reads. `RwLock<T>` allows multiple concurrent readers OR one exclusive writer. For read-heavy workloads, this dramatically improves throughput by eliminating unnecessary serialization of read operations.
+
+## Bad
+
+```rust
+use std::sync::{Arc, Mutex};
+
+// Configuration rarely changes but is read constantly
+let config = Arc::new(Mutex::new(Config::load()));
+
+// Every read blocks other reads unnecessarily
+fn get_setting(config: &Mutex<Config>, key: &str) -> String {
+    let guard = config.lock().unwrap();
+    guard.get(key).to_string()
+}
+
+// 100 threads reading = serialized, one at a time
+```
+
+## Good
+
+```rust
+use std::sync::{Arc, RwLock};
+
+// Multiple readers can proceed concurrently
+let config = Arc::new(RwLock::new(Config::load()));
+
+fn get_setting(config: &RwLock<Config>, key: &str) -> String {
+    let guard = config.read().unwrap(); // Multiple threads can hold read lock
+    guard.get(key).to_string()
+}
+
+fn update_setting(config: &RwLock<Config>, key: &str, value: &str) {
+    let mut guard = config.write().unwrap(); // Exclusive access for writes
+    guard.set(key, value);
+}
+
+// 100 threads reading = parallel execution
+```
+
+## parking_lot::RwLock
+
+Prefer `parking_lot::RwLock` for better performance:
+
+```rust
+use parking_lot::RwLock;
+use std::sync::Arc;
+
+let data = Arc::new(RwLock::new(HashMap::new()));
+
+// Read - no unwrap needed
+let value = data.read().get("key").cloned();
+
+// Write
+data.write().insert("key".to_string(), "value".to_string());
+
+// Upgradeable read lock (unique to parking_lot)
+let upgradeable = data.upgradable_read();
+if upgradeable.get("key").is_none() {
+    let mut write = parking_lot::RwLockUpgradableReadGuard::upgrade(upgradeable);
+    write.insert("key".to_string(), "default".to_string());
+}
+```
+
+## When RwLock Hurts
+
+RwLock has overhead for tracking readers. It can be slower than Mutex when:
+
+| Scenario | Better Choice |
+|----------|---------------|
+| Writes are frequent (>20% of operations) | `Mutex` |
+| Lock held very briefly | `Mutex` |
+| Single-threaded | `RefCell` |
+| Reads dominate, lock held longer | `RwLock` |
+
+## Write Starvation
+
+Standard `RwLock` may starve writers if readers are continuous. `parking_lot::RwLock` is fair by default.
+
+```rust
+// parking_lot is writer-fair, preventing starvation
+use parking_lot::RwLock;
+
+// Or use std with explicit fairness (nightly)
+// #![feature(rwlock_downgrade)]
+```
+
+## Real-World Pattern: Cached Computation
+
+```rust
+use parking_lot::RwLock;
+use std::sync::Arc;
+
+struct CachedData {
+    cache: RwLock<Option<ExpensiveResult>>,
+}
+
+impl CachedData {
+    fn get(&self) -> ExpensiveResult {
+        // Fast path: read lock
+        if let Some(cached) = self.cache.read().as_ref() {
+            return cached.clone();
+        }
+        
+        // Slow path: compute and cache
+        let result = compute_expensive();
+        *self.cache.write() = Some(result.clone());
+        result
+    }
+}
+```
+
+## See Also
+
+- [own-mutex-interior](./own-mutex-interior.md) - When writes are frequent
+- [async-no-lock-await](./async-no-lock-await.md) - RwLock in async contexts

package/template/agent/skills/rust-developer/references/rust-rules/own-slice-over-vec.md

@@ -0,0 +1,119 @@
+# own-slice-over-vec
+
+> Accept `&[T]` not `&Vec<T>`, `&str` not `&String`
+
+## Why It Matters
+
+Accepting `&[T]` instead of `&Vec<T>` makes your function more flexible - it can accept slices from arrays, vectors, or other sources. Similarly, `&str` accepts string slices from `String`, `&'static str`, or substrings.
+
+## Bad
+
+```rust
+// Overly restrictive - only accepts &Vec
+fn sum(numbers: &Vec<i32>) -> i32 {
+    numbers.iter().sum()
+}
+
+// Overly restrictive - only accepts &String
+fn greet(name: &String) {
+    println!("Hello, {}", name);
+}
+
+// Can't call with arrays or slices
+let arr = [1, 2, 3];
+// sum(&arr);  // ERROR: expected &Vec<i32>
+
+let literal = "world";
+// greet(&literal);  // ERROR: expected &String
+```
+
+## Good
+
+```rust
+// Flexible - accepts any slice-like thing
+fn sum(numbers: &[i32]) -> i32 {
+    numbers.iter().sum()
+}
+
+// Flexible - accepts any string-like thing
+fn greet(name: &str) {
+    println!("Hello, {}", name);
+}
+
+// Now all of these work:
+let vec = vec![1, 2, 3];
+let arr = [4, 5, 6];
+let slice = &vec[0..2];
+
+sum(&vec);    // Vec coerces to slice
+sum(&arr);    // Array coerces to slice
+sum(slice);   // Slice works directly
+
+let string = String::from("Alice");
+let literal = "Bob";
+
+greet(&string);  // String coerces to &str
+greet(literal);  // &str works directly
+```
+
+## The Deref Coercion Chain
+
+```rust
+// These coercions happen automatically:
+// Vec<T>  -> &[T]   (via Deref)
+// String  -> &str   (via Deref)
+// Box<T>  -> &T     (via Deref)
+// Arc<T>  -> &T     (via Deref)
+
+fn process(data: &[u8]) { /* ... */ }
+
+let vec: Vec<u8> = vec![1, 2, 3];
+let boxed: Box<[u8]> = vec.into_boxed_slice();
+let arc: Arc<[u8]> = Arc::from(&[1, 2, 3][..]);
+
+process(&vec);    // Works
+process(&boxed);  // Works
+process(&arc);    // Works
+```
+
+## Path Types Too
+
+```rust
+// Bad
+fn read_config(path: &PathBuf) -> Config { /* ... */ }
+
+// Good - accepts &Path, &PathBuf, &str, &String
+fn read_config(path: &Path) -> Config { /* ... */ }
+
+// Even better - accept anything path-like
+fn read_config(path: impl AsRef<Path>) -> Config {
+    let path = path.as_ref();
+    // ...
+}
+```
+
+## When to Accept Owned Types
+
+```rust
+// Accept owned when you need to store it
+struct Logger {
+    prefix: String,  // Needs to own the string
+}
+
+impl Logger {
+    // Take ownership - caller decides to clone or move
+    fn new(prefix: String) -> Self {
+        Self { prefix }
+    }
+    
+    // Or use Into for flexibility
+    fn with_prefix(prefix: impl Into<String>) -> Self {
+        Self { prefix: prefix.into() }
+    }
+}
+```
+
+## See Also
+
+- [api-impl-asref](api-impl-asref.md) - Accept `impl AsRef<T>` for maximum flexibility
+- [own-borrow-over-clone](own-borrow-over-clone.md) - Prefer borrowing over cloning

package/template/agent/skills/rust-developer/references/rust-rules/perf-black-box-bench.md

@@ -0,0 +1,153 @@
+# perf-black-box-bench
+
+> Use black_box in benchmarks
+
+## Why It Matters
+
+The compiler aggressively optimizes code, potentially eliminating computations whose results aren't used. In benchmarks, this can lead to measuring nothing instead of the actual code. `std::hint::black_box()` prevents the compiler from optimizing away values, ensuring accurate measurements.
+
+## Bad
+
+```rust
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+
+fn benchmark_bad(c: &mut Criterion) {
+    c.bench_function("compute", |b| {
+        b.iter(|| {
+            let result = expensive_computation(42);
+            // Result unused - compiler may eliminate the call!
+        });
+    });
+}
+
+fn benchmark_also_bad(c: &mut Criterion) {
+    let input = 42;  // Constant - compiler may precompute
+    
+    c.bench_function("compute", |b| {
+        b.iter(|| {
+            expensive_computation(input)
+            // Return value may still be optimized away
+        });
+    });
+}
+```
+
+## Good
+
+```rust
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+
+fn benchmark_good(c: &mut Criterion) {
+    c.bench_function("compute", |b| {
+        b.iter(|| {
+            // black_box on input prevents constant folding
+            let result = expensive_computation(black_box(42));
+            // black_box on output prevents dead code elimination
+            black_box(result)
+        });
+    });
+}
+
+// Or simpler with Criterion's built-in support
+fn benchmark_simpler(c: &mut Criterion) {
+    c.bench_function("compute", |b| {
+        b.iter(|| expensive_computation(black_box(42)))
+    });
+}
+```
+
+## What black_box Does
+
+| Without black_box | With black_box |
+|-------------------|----------------|
+| Input may be constant-folded | Input treated as unknown |
+| Result may be eliminated | Result must be computed |
+| Loops may be optimized away | Each iteration runs |
+| Functions may be inlined | Call semantics preserved |
+
+## Standard Library Usage
+
+```rust
+use std::hint::black_box;
+
+fn main() {
+    // In std since Rust 1.66
+    let result = black_box(compute_something(black_box(input)));
+}
+```
+
+## Criterion's black_box
+
+Criterion re-exports `std::hint::black_box`:
+
+```rust
+use criterion::black_box;
+
+// Equivalent to std::hint::black_box
+```
+
+## Pattern: Benchmark with Setup
+
+```rust
+fn benchmark_with_setup(c: &mut Criterion) {
+    c.bench_function("process_data", |b| {
+        // Setup outside iter - not measured
+        let data = generate_test_data(1000);
+        
+        b.iter(|| {
+            // black_box the input reference
+            let result = process(black_box(&data));
+            black_box(result)
+        });
+    });
+}
+```
+
+## Pattern: Benchmark Multiple Inputs
+
+```rust
+fn benchmark_sizes(c: &mut Criterion) {
+    let mut group = c.benchmark_group("scaling");
+    
+    for size in [100, 1000, 10000] {
+        let data = generate_data(size);
+        
+        group.bench_with_input(
+            BenchmarkId::from_parameter(size),
+            &data,
+            |b, data| {
+                b.iter(|| process(black_box(data)))
+            },
+        );
+    }
+    group.finish();
+}
+```
+
+## Common Mistakes
+
+```rust
+// WRONG: black_box inside loop does nothing useful
+for _ in 0..1000 {
+    black_box(());  // Doesn't help
+    compute();
+}
+
+// RIGHT: black_box the computation result
+for _ in 0..1000 {
+    black_box(compute());
+}
+
+// WRONG: Only blocking output, not input
+let x = 42;  // Constant, may be optimized
+black_box(expensive(x));
+
+// RIGHT: Block both
+black_box(expensive(black_box(42)));
+```
+
+## See Also
+
+- [test-criterion-bench](./test-criterion-bench.md) - Using Criterion
+- [perf-profile-first](./perf-profile-first.md) - Profile before optimize
+- [perf-release-profile](./perf-release-profile.md) - Release settings

package/template/agent/skills/rust-developer/references/rust-rules/perf-chain-avoid.md

@@ -0,0 +1,136 @@
+# perf-chain-avoid
+
+> Avoid chain in hot loops
+
+## Why It Matters
+
+`Iterator::chain()` adds overhead for checking which iterator is active on every `.next()` call. In hot loops, this branch prediction overhead can impact performance. For performance-critical code, prefer single iterators or pre-combined collections.
+
+## Bad
+
+```rust
+// Chain in hot inner loop
+fn process_hot_path(a: &[i32], b: &[i32]) -> i64 {
+    let mut sum = 0i64;
+    
+    // Called millions of times
+    for _ in 0..1_000_000 {
+        for x in a.iter().chain(b.iter()) {  // Branch every iteration
+            sum += *x as i64;
+        }
+    }
+    sum
+}
+
+// Chaining multiple small slices in tight loop
+fn combine_results(parts: &[&[u8]]) -> Vec<u8> {
+    let mut result = Vec::new();
+    for part in parts {
+        for byte in std::iter::once(&0u8).chain(part.iter()) {
+            result.push(*byte);
+        }
+    }
+    result
+}
+```
+
+## Good
+
+```rust
+// Separate loops - branch-free inner loops
+fn process_hot_path(a: &[i32], b: &[i32]) -> i64 {
+    let mut sum = 0i64;
+    
+    for _ in 0..1_000_000 {
+        for x in a {
+            sum += *x as i64;
+        }
+        for x in b {
+            sum += *x as i64;
+        }
+    }
+    sum
+}
+
+// Pre-combine outside hot loop
+fn combine_results(parts: &[&[u8]]) -> Vec<u8> {
+    let mut result = Vec::new();
+    for part in parts {
+        result.push(0u8);
+        result.extend_from_slice(part);
+    }
+    result
+}
+```
+
+## When Chain Is Fine
+
+Chain is perfectly acceptable when:
+
+```rust
+// One-time iteration, not in hot path
+fn collect_all(a: Vec<i32>, b: Vec<i32>) -> Vec<i32> {
+    a.into_iter().chain(b).collect()
+}
+
+// Lazy evaluation with short-circuit
+fn find_in_either(a: &[Item], b: &[Item], target: i32) -> Option<&Item> {
+    a.iter().chain(b.iter()).find(|x| x.id == target)
+}
+
+// Small number of elements
+fn get_prefixes() -> impl Iterator<Item = &'static str> {
+    ["Mr.", "Mrs.", "Dr."].iter().copied()
+        .chain(["Prof."].iter().copied())
+}
+```
+
+## Alternative Patterns
+
+### Pre-allocate and Extend
+
+```rust
+fn merge_slices(slices: &[&[i32]]) -> Vec<i32> {
+    let total: usize = slices.iter().map(|s| s.len()).sum();
+    let mut result = Vec::with_capacity(total);
+    for slice in slices {
+        result.extend_from_slice(slice);
+    }
+    result
+}
+```
+
+### Use append for Vecs
+
+```rust
+fn combine_vecs(mut a: Vec<i32>, mut b: Vec<i32>) -> Vec<i32> {
+    a.append(&mut b);  // Moves elements, no reallocation if a has capacity
+    a
+}
+```
+
+### Flatten Instead of Chain
+
+```rust
+// Instead of: a.iter().chain(b.iter()).chain(c.iter())
+let all = [a, b, c];
+for item in all.iter().flat_map(|slice| slice.iter()) {
+    process(item);
+}
+```
+
+## Performance Impact
+
+| Pattern | Per-Item Overhead |
+|---------|-------------------|
+| Single iterator | None |
+| `chain(a, b)` | 1 branch per item |
+| `chain(a, b, c)` | 2 branches per item |
+| Nested chains | Compounds |
+| Separate loops | None (but code duplication) |
+
+## See Also
+
+- [perf-iter-over-index](./perf-iter-over-index.md) - Prefer iterators
+- [perf-extend-batch](./perf-extend-batch.md) - Batch insertions
+- [opt-cache-friendly](./opt-cache-friendly.md) - Cache-friendly patterns