agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/own-clone-explicit.md

@@ -0,0 +1,135 @@
+# own-clone-explicit
+
+> Use explicit `Clone` for types where copying has meaningful cost
+
+## Why It Matters
+
+Unlike `Copy` which is implicit and "free," `Clone` requires an explicit `.clone()` call, signaling that duplication has a cost. This makes heap allocations and deep copies visible in code, helping developers reason about performance. Types with heap data (`String`, `Vec`, `Box`) should implement `Clone` but not `Copy`.
+
+## Bad
+
+```rust
+// Hiding expensive operations
+fn process_data(data: Vec<u32>) -> Vec<u32> {
+    let backup = data; // Moved, not copied - but unclear at call site
+    transform(backup)
+}
+
+let my_data = vec![1, 2, 3, 4, 5];
+let result = process_data(my_data);
+// my_data is moved - surprise if you expected it to still exist
+```
+
+## Good
+
+```rust
+fn process_data(data: Vec<u32>) -> Vec<u32> {
+    let backup = data; 
+    transform(backup)
+}
+
+let my_data = vec![1, 2, 3, 4, 5];
+let result = process_data(my_data.clone()); // Explicit: "I know this allocates"
+// my_data still available
+
+// Or better - take reference if you don't need ownership
+fn process_data_ref(data: &[u32]) -> Vec<u32> {
+    transform(data)
+}
+let result = process_data_ref(&my_data); // No clone needed
+```
+
+## Custom Clone Implementation
+
+For types with mixed cheap/expensive fields, implement `Clone` manually:
+
+```rust
+#[derive(Debug)]
+struct Document {
+    id: u64,              // Cheap to copy
+    content: String,      // Expensive to clone
+    metadata: Metadata,   // Moderate cost
+}
+
+impl Clone for Document {
+    fn clone(&self) -> Self {
+        Self {
+            id: self.id,
+            content: self.content.clone(),
+            metadata: self.metadata.clone(),
+        }
+    }
+    
+    // Optimization: reuse existing allocations
+    fn clone_from(&mut self, source: &Self) {
+        self.id = source.id;
+        self.content.clone_from(&source.content); // Reuses capacity
+        self.metadata.clone_from(&source.metadata);
+    }
+}
+```
+
+## clone_from Optimization
+
+`clone_from` can reuse existing allocations:
+
+```rust
+let mut buffer = String::with_capacity(1000);
+
+// Bad: drops old allocation, creates new one
+buffer = source.clone();
+
+// Good: reuses existing capacity if sufficient
+buffer.clone_from(&source);
+```
+
+## Derive vs Manual Clone
+
+```rust
+// Derive when all fields need cloning
+#[derive(Clone)]
+struct Simple {
+    data: Vec<u8>,
+    name: String,
+}
+
+// Manual when you need special behavior
+struct CachedValue {
+    value: i32,
+    cache: RefCell<Option<ExpensiveComputation>>,
+}
+
+impl Clone for CachedValue {
+    fn clone(&self) -> Self {
+        Self {
+            value: self.value,
+            cache: RefCell::new(None), // Don't clone cache, let it rebuild
+        }
+    }
+}
+```
+
+## When to Avoid Clone
+
+```rust
+// Instead of cloning, consider:
+
+// 1. References
+fn process(data: &MyType) { } // Borrow instead of clone
+
+// 2. Cow for conditional cloning
+fn process(data: Cow<'_, str>) { } // Clone only if mutation needed
+
+// 3. Arc for shared ownership
+let shared = Arc::new(expensive_data);
+let handle = shared.clone(); // Cheap: just increments counter
+
+// 4. Passing by value when caller is done with it
+fn consume(data: MyType) { } // Caller moves, no clone
+```
+
+## See Also
+
+- [own-copy-small](./own-copy-small.md) - When implicit Copy is appropriate
+- [own-cow-conditional](./own-cow-conditional.md) - Avoiding clones with Cow
+- [mem-clone-from](./mem-clone-from.md) - Optimizing repeated clones

package/template/agent/skills/rust-developer/references/rust-rules/own-copy-small.md

@@ -0,0 +1,124 @@
+# own-copy-small
+
+> Implement `Copy` for small, simple types
+
+## Why It Matters
+
+Types that implement `Copy` are implicitly duplicated on assignment instead of moved. This eliminates the need for explicit `.clone()` calls and makes the code more ergonomic. For small types (generally ≤16 bytes), copying is as fast or faster than moving a pointer.
+
+## Bad
+
+```rust
+// Small type without Copy - requires explicit clone
+#[derive(Clone, Debug)]
+struct Point {
+    x: f64,
+    y: f64,
+}
+
+fn distance(p1: Point, p2: Point) -> f64 {
+    ((p2.x - p1.x).powi(2) + (p2.y - p1.y).powi(2)).sqrt()
+}
+
+let origin = Point { x: 0.0, y: 0.0 };
+let target = Point { x: 3.0, y: 4.0 };
+
+let d1 = distance(origin.clone(), target.clone()); // Tedious
+let d2 = distance(origin.clone(), target.clone()); // Every use needs clone
+// origin and target still usable but verbose
+```
+
+## Good
+
+```rust
+// Small type with Copy - implicit duplication
+#[derive(Clone, Copy, Debug)]
+struct Point {
+    x: f64,
+    y: f64,
+}
+
+fn distance(p1: Point, p2: Point) -> f64 {
+    ((p2.x - p1.x).powi(2) + (p2.y - p1.y).powi(2)).sqrt()
+}
+
+let origin = Point { x: 0.0, y: 0.0 };
+let target = Point { x: 3.0, y: 4.0 };
+
+let d1 = distance(origin, target); // Implicitly copied
+let d2 = distance(origin, target); // Still works!
+// origin and target remain valid
+```
+
+## Copy Requirements
+
+A type can implement `Copy` only if:
+1. All fields implement `Copy`
+2. No custom `Drop` implementation
+3. No heap-allocated data (`String`, `Vec`, `Box`, etc.)
+
+```rust
+// ✅ Can be Copy
+#[derive(Clone, Copy)]
+struct Color {
+    r: u8,
+    g: u8,
+    b: u8,
+    a: u8,
+}
+
+// ❌ Cannot be Copy - contains String
+#[derive(Clone)]
+struct Person {
+    name: String,  // String is not Copy
+    age: u32,
+}
+
+// ❌ Cannot be Copy - has Drop
+struct FileHandle {
+    fd: i32,
+}
+impl Drop for FileHandle {
+    fn drop(&mut self) { /* close file */ }
+}
+```
+
+## Size Guidelines
+
+| Size | Recommendation |
+|------|----------------|
+| ≤ 16 bytes | Implement `Copy` |
+| 17-64 bytes | Consider `Copy`, benchmark if critical |
+| > 64 bytes | Probably don't, prefer references |
+
+```rust
+use std::mem::size_of;
+
+#[derive(Clone, Copy)]
+struct SmallId(u64); // 8 bytes ✅
+
+#[derive(Clone, Copy)]
+struct Rect { x: f32, y: f32, w: f32, h: f32 } // 16 bytes ✅
+
+#[derive(Clone)] // No Copy - 72 bytes
+struct Transform {
+    matrix: [[f64; 3]; 3], // 72 bytes, too large
+}
+```
+
+## Common Copy Types
+
+Standard library types that are `Copy`:
+- All primitives: `i32`, `f64`, `bool`, `char`, etc.
+- References: `&T`, `&mut T`
+- Raw pointers: `*const T`, `*mut T`
+- Function pointers: `fn(T) -> U`
+- Tuples of `Copy` types: `(i32, f64)`
+- Arrays of `Copy` types: `[u8; 32]`
+- `Option<T>` where `T: Copy`
+- `PhantomData<T>`
+
+## See Also
+
+- [own-clone-explicit](./own-clone-explicit.md) - When Clone without Copy is appropriate
+- [type-newtype-ids](./type-newtype-ids.md) - Newtype pattern often uses Copy

package/template/agent/skills/rust-developer/references/rust-rules/own-cow-conditional.md

@@ -0,0 +1,135 @@
+# own-cow-conditional
+
+> Use `Cow<'a, T>` for conditional ownership
+
+## Why It Matters
+
+`Cow` (Clone-on-Write) lets you avoid allocations when you *might* need to own data but usually don't. It holds either a borrowed reference or an owned value, cloning only when mutation is needed.
+
+## Bad
+
+```rust
+// Always allocates, even when input doesn't need modification
+fn normalize_path(path: &str) -> String {
+    if path.contains("//") {
+        path.replace("//", "/")  // Allocation needed
+    } else {
+        path.to_string()  // Unnecessary allocation!
+    }
+}
+
+// Always clones the error message
+fn format_error(code: u32) -> String {
+    match code {
+        404 => "Not Found".to_string(),      // Unnecessary!
+        500 => "Internal Error".to_string(), // Unnecessary!
+        _ => format!("Error {}", code),      // This one needs allocation
+    }
+}
+```
+
+## Good
+
+```rust
+use std::borrow::Cow;
+
+// Only allocates when needed
+fn normalize_path(path: &str) -> Cow<'_, str> {
+    if path.contains("//") {
+        Cow::Owned(path.replace("//", "/"))  // Allocate
+    } else {
+        Cow::Borrowed(path)  // Zero-cost borrow
+    }
+}
+
+// Static strings stay borrowed
+fn format_error(code: u32) -> Cow<'static, str> {
+    match code {
+        404 => Cow::Borrowed("Not Found"),      // No allocation
+        500 => Cow::Borrowed("Internal Error"), // No allocation
+        _ => Cow::Owned(format!("Error {}", code)), // Allocate only for unknown
+    }
+}
+```
+
+## Real-World Example from ripgrep
+
+```rust
+// https://github.com/BurntSushi/ripgrep/blob/master/crates/globset/src/pathutil.rs
+pub(crate) fn file_name<'a>(path: &Cow<'a, [u8]>) -> Option<Cow<'a, [u8]>> {
+    let last_slash = path.rfind_byte(b'/').map(|i| i + 1).unwrap_or(0);
+    match *path {
+        Cow::Borrowed(path) => Some(Cow::Borrowed(&path[last_slash..])),
+        Cow::Owned(ref path) => {
+            let mut path = path.clone();
+            path.drain_bytes(..last_slash);
+            Some(Cow::Owned(path))
+        }
+    }
+}
+```
+
+## Clone-on-Write Pattern
+
+```rust
+use std::borrow::Cow;
+
+fn process_text(text: Cow<'_, str>) -> Cow<'_, str> {
+    if text.contains("bad_word") {
+        // to_mut() clones if borrowed, returns &mut if owned
+        let mut owned = text.into_owned();
+        owned = owned.replace("bad_word", "***");
+        Cow::Owned(owned)
+    } else {
+        text  // Pass through unchanged
+    }
+}
+
+// Usage
+let borrowed: Cow<str> = Cow::Borrowed("hello world");
+let result = process_text(borrowed);  // No allocation!
+
+let with_bad: Cow<str> = Cow::Borrowed("hello bad_word");
+let result = process_text(with_bad);  // Allocates only here
+```
+
+## Cow with Collections
+
+```rust
+use std::borrow::Cow;
+
+// Mixed borrowed/owned in a collection
+fn collect_errors<'a>(
+    static_errors: &[&'static str],
+    dynamic_errors: Vec<String>,
+) -> Vec<Cow<'a, str>> {
+    let mut errors: Vec<Cow<str>> = Vec::new();
+    
+    // Static strings - no allocation
+    for &e in static_errors {
+        errors.push(Cow::Borrowed(e));
+    }
+    
+    // Dynamic strings - take ownership
+    for e in dynamic_errors {
+        errors.push(Cow::Owned(e));
+    }
+    
+    errors
+}
+```
+
+## When to Use Cow
+
+| Situation | Use Cow? |
+|-----------|----------|
+| Usually borrow, sometimes own | Yes |
+| Always need owned data | No, just use owned type |
+| Always borrow | No, just use reference |
+| Hot path, avoiding all allocations | Yes |
+| Returning static strings or formatted | Yes |
+
+## See Also
+
+- [own-borrow-over-clone](own-borrow-over-clone.md) - Prefer borrowing over cloning
+- [mem-avoid-format](mem-avoid-format.md) - Avoid format! when possible

package/template/agent/skills/rust-developer/references/rust-rules/own-lifetime-elision.md

@@ -0,0 +1,134 @@
+# own-lifetime-elision
+
+> Rely on lifetime elision rules; add explicit lifetimes only when required
+
+## Why It Matters
+
+Rust's lifetime elision rules handle most common borrowing patterns automatically. Adding explicit lifetimes where they're not needed clutters code without adding clarity. However, understanding when elision applies helps you know when explicit lifetimes are truly necessary.
+
+## Bad
+
+```rust
+// Unnecessary explicit lifetimes - elision handles these
+fn first_word<'a>(s: &'a str) -> &'a str {
+    s.split_whitespace().next().unwrap_or("")
+}
+
+fn get_name<'a>(person: &'a Person) -> &'a str {
+    &person.name
+}
+
+impl<'a> Display for Wrapper<'a> {
+    fn fmt<'b>(&'b self, f: &'b mut Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+```
+
+## Good
+
+```rust
+// Let elision do its job
+fn first_word(s: &str) -> &str {
+    s.split_whitespace().next().unwrap_or("")
+}
+
+fn get_name(person: &Person) -> &str {
+    &person.name
+}
+
+impl Display for Wrapper<'_> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+```
+
+## The Three Elision Rules
+
+1. **Each input reference gets its own lifetime:**
+   ```rust
+   fn foo(x: &str, y: &str) 
+   // becomes
+   fn foo<'a, 'b>(x: &'a str, y: &'b str)
+   ```
+
+2. **One input reference → output gets same lifetime:**
+   ```rust
+   fn foo(x: &str) -> &str
+   // becomes  
+   fn foo<'a>(x: &'a str) -> &'a str
+   ```
+
+3. **Method with `&self`/`&mut self` → output gets self's lifetime:**
+   ```rust
+   fn foo(&self, x: &str) -> &str
+   // becomes
+   fn foo<'a, 'b>(&'a self, x: &'b str) -> &'a str
+   ```
+
+## When Explicit Lifetimes ARE Required
+
+```rust
+// Multiple input references, output could come from either
+fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
+    if x.len() > y.len() { x } else { y }
+}
+
+// Struct holding references
+struct Parser<'input> {
+    source: &'input str,
+    position: usize,
+}
+
+// Multiple distinct lifetimes needed
+struct Context<'s, 'c> {
+    source: &'s str,
+    cache: &'c mut Cache,
+}
+
+// Static lifetime for constants
+fn get_default() -> &'static str {
+    "default"
+}
+```
+
+## Anonymous Lifetime `'_`
+
+Use `'_` to let the compiler infer while being explicit about the presence of a lifetime:
+
+```rust
+// In struct definitions
+impl Iterator for Parser<'_> {
+    type Item = Token;
+    fn next(&mut self) -> Option<Self::Item> { ... }
+}
+
+// In function signatures where it adds clarity
+fn parse(input: &str) -> Result<Ast<'_>, Error> { ... }
+
+// Especially useful in trait bounds
+fn process(data: &impl AsRef<str>) -> Cow<'_, str> { ... }
+```
+
+## Common Patterns
+
+```rust
+// ✅ Elision works
+fn trim(s: &str) -> &str { s.trim() }
+fn first(v: &[i32]) -> Option<&i32> { v.first() }
+fn name(&self) -> &str { &self.name }
+
+// ❌ Elision fails - multiple inputs, ambiguous output
+fn pick(a: &str, b: &str, first: bool) -> &str // Error!
+
+// ✅ Fixed with explicit lifetime
+fn pick<'a>(a: &'a str, b: &'a str, first: bool) -> &'a str {
+    if first { a } else { b }
+}
+```
+
+## See Also
+
+- [own-borrow-over-clone](./own-borrow-over-clone.md) - Prefer borrowing to avoid ownership issues
+- [api-impl-asref](./api-impl-asref.md) - Generic borrowing with AsRef

package/template/agent/skills/rust-developer/references/rust-rules/own-move-large.md

@@ -0,0 +1,134 @@
+# own-move-large
+
+> Move large types instead of copying; use `Box` if moves are expensive
+
+## Why It Matters
+
+In Rust, "moving" a value means copying its bytes to a new location and invalidating the old one. For large types (hundreds of bytes), this memcpy can be expensive. Boxing large types reduces move cost to copying a single pointer (8 bytes), making moves cheap regardless of the actual data size.
+
+## Bad
+
+```rust
+// Large struct moved repeatedly = expensive memcpy each time
+struct GameState {
+    board: [[Cell; 100]; 100],  // 10,000 cells
+    history: [Move; 1000],       // 1,000 moves
+    players: [Player; 4],        // Player data
+    // Total: potentially tens of KB
+}
+
+fn process_state(state: GameState) -> GameState {
+    // Moving ~40KB+ of data
+    let mut new_state = state;  // Memcpy here
+    new_state.apply_rules();
+    new_state  // Memcpy on return
+}
+
+let state = GameState::new();
+let state = process_state(state);  // Two large memcpys
+```
+
+## Good
+
+```rust
+// Box reduces move cost to 8 bytes
+struct GameState {
+    board: Box<[[Cell; 100]; 100]>,  // Pointer to heap
+    history: Vec<Move>,               // Already heap-allocated
+    players: [Player; 4],
+}
+
+fn process_state(mut state: GameState) -> GameState {
+    // Moving just pointers + small inline data
+    state.apply_rules();
+    state  // Cheap move
+}
+
+// Or use Box at call site for one-off cases
+fn process_large(state: Box<LargeStruct>) -> Box<LargeStruct> {
+    // 8-byte move regardless of LargeStruct size
+    state
+}
+```
+
+## When to Box
+
+| Type Size | Move Frequency | Recommendation |
+|-----------|----------------|----------------|
+| < 128 bytes | Any | Don't box |
+| 128-512 bytes | Rare | Probably don't box |
+| 128-512 bytes | Frequent | Consider boxing |
+| > 512 bytes | Any | Box or use references |
+| > 4KB | Any | Definitely box |
+
+## Stack vs Heap Tradeoffs
+
+```rust
+// Stack: fast allocation, limited size, moves copy bytes
+struct StackHeavy {
+    data: [u8; 4096],  // 4KB on stack
+}
+
+// Heap: allocation cost, unlimited size, moves copy pointer
+struct HeapLight {
+    data: Box<[u8; 4096]>,  // 8 bytes on stack, 4KB on heap
+}
+
+// Measure with size_of
+use std::mem::size_of;
+assert_eq!(size_of::<StackHeavy>(), 4096);
+assert_eq!(size_of::<HeapLight>(), 8);
+```
+
+## Alternative: References
+
+When you don't need ownership transfer, use references:
+
+```rust
+// Best: no move at all
+fn analyze_state(state: &GameState) -> Analysis {
+    // Borrows state, no copying
+    compute_analysis(state)
+}
+
+// Mutable borrow for in-place modification
+fn update_state(state: &mut GameState) {
+    state.tick();
+}
+```
+
+## Pattern: Builder Returns Boxed
+
+```rust
+impl LargeConfig {
+    pub fn builder() -> ConfigBuilder {
+        ConfigBuilder::default()
+    }
+}
+
+impl ConfigBuilder {
+    // Return boxed to avoid large move
+    pub fn build(self) -> Box<LargeConfig> {
+        Box::new(LargeConfig {
+            // ... fields from builder
+        })
+    }
+}
+```
+
+## Profile First
+
+Don't prematurely optimize. Use tools to identify if moves are actually a bottleneck:
+
+```rust
+// Check type sizes
+println!("Size of GameState: {}", std::mem::size_of::<GameState>());
+
+// Profile with cargo flamegraph or perf to find hot memcpys
+```
+
+## See Also
+
+- [own-copy-small](./own-copy-small.md) - Cheap types should be Copy
+- [mem-box-large-variant](./mem-box-large-variant.md) - Boxing enum variants
+- [perf-profile-first](./perf-profile-first.md) - Measure before optimizing