agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/mem-box-large-variant.md

@@ -0,0 +1,158 @@
+# mem-box-large-variant
+
+> Box large enum variants to reduce overall enum size
+
+## Why It Matters
+
+An enum's size is determined by its largest variant. If one variant contains a large struct while others are small, every instance of the enum pays for the largest variant's size. Boxing the large variant puts that data on the heap, keeping the enum itself small. This can significantly reduce memory usage and improve cache performance.
+
+## Bad
+
+```rust
+enum Message {
+    Quit,                              // 0 bytes of data
+    Move { x: i32, y: i32 },          // 8 bytes
+    Text(String),                      // 24 bytes
+    Image { 
+        data: [u8; 1024],             // 1024 bytes - forces entire enum to ~1032 bytes!
+        width: u32, 
+        height: u32 
+    },
+}
+
+// Every Message is ~1032 bytes, even Quit and Move
+let messages: Vec<Message> = vec![
+    Message::Quit,  // Wastes ~1032 bytes
+    Message::Quit,  // Wastes ~1032 bytes
+    Message::Move { x: 0, y: 0 },  // Wastes ~1024 bytes
+];
+```
+
+## Good
+
+```rust
+struct ImageData {
+    data: [u8; 1024],
+    width: u32,
+    height: u32,
+}
+
+enum Message {
+    Quit,
+    Move { x: i32, y: i32 },
+    Text(String),
+    Image(Box<ImageData>),  // Now just 8 bytes (pointer)
+}
+
+// Message is now ~32 bytes (String variant is largest)
+let messages: Vec<Message> = vec![
+    Message::Quit,  // Uses ~32 bytes
+    Message::Quit,  // Uses ~32 bytes  
+    Message::Move { x: 0, y: 0 },  // Uses ~32 bytes
+];
+```
+
+## Check Enum Sizes
+
+```rust
+use std::mem::size_of;
+
+// Before boxing
+enum BadEvent {
+    Click { x: u32, y: u32 },           // 8 bytes
+    KeyPress(char),                      // 4 bytes
+    LargeData([u8; 256]),               // 256 bytes
+}
+println!("BadEvent: {} bytes", size_of::<BadEvent>());  // ~264 bytes
+
+// After boxing
+enum GoodEvent {
+    Click { x: u32, y: u32 },
+    KeyPress(char),
+    LargeData(Box<[u8; 256]>),          // 8 bytes (pointer)
+}
+println!("GoodEvent: {} bytes", size_of::<GoodEvent>());  // ~16 bytes
+```
+
+## Clippy Lint
+
+```toml
+[lints.clippy]
+large_enum_variant = "warn"  # Warns when variants differ significantly
+```
+
+```rust
+// Clippy will suggest:
+// warning: large size difference between variants
+// help: consider boxing the large fields to reduce the total size
+```
+
+## When to Box
+
+| Largest Variant | Other Variants | Action |
+|-----------------|----------------|--------|
+| < 64 bytes | Similar size | Don't box |
+| > 128 bytes | Much smaller | Box the large variant |
+| > 256 bytes | Any | Definitely box |
+
+## Recursive Types Require Boxing
+
+```rust
+// Won't compile - infinite size
+enum List {
+    Cons(i32, List),
+    Nil,
+}
+
+// Must box recursive variant
+enum List {
+    Cons(i32, Box<List>),  // Now finite size
+    Nil,
+}
+
+// Same for ASTs
+enum Expr {
+    Number(i64),
+    BinOp {
+        op: Op,
+        left: Box<Expr>,   // Recursive - must box
+        right: Box<Expr>,
+    },
+}
+```
+
+## Pattern Matching with Boxed Variants
+
+```rust
+enum Event {
+    Small(u32),
+    Large(Box<LargeData>),
+}
+
+fn handle(event: Event) {
+    match event {
+        Event::Small(n) => println!("Small: {}", n),
+        Event::Large(data) => {
+            // data is Box<LargeData>, dereference to access
+            println!("Large: {} bytes", data.size);
+        }
+    }
+}
+
+// Or match on reference
+fn handle_ref(event: &Event) {
+    match event {
+        Event::Small(n) => println!("Small: {}", n),
+        Event::Large(data) => {
+            // data is &Box<LargeData>, auto-derefs
+            println!("Large: {} bytes", data.size);
+        }
+    }
+}
+```
+
+## See Also
+
+- [own-move-large](./own-move-large.md) - Boxing large types for cheap moves
+- [mem-smallvec](./mem-smallvec.md) - Alternative for inline small collections
+- [lint-deny-correctness](./lint-deny-correctness.md) - Enabling clippy lints

package/template/agent/skills/rust-developer/references/rust-rules/mem-boxed-slice.md

@@ -0,0 +1,139 @@
+# mem-boxed-slice
+
+> Use `Box<[T]>` instead of `Vec<T>` for fixed-size heap data
+
+## Why It Matters
+
+`Vec<T>` stores three words: pointer, length, and capacity. When you know a collection won't grow, `Box<[T]>` stores only pointer and length (2 words), saving 8 bytes per instance. More importantly, it communicates intent: "this data is fixed-size." For large numbers of fixed collections, this adds up.
+
+## Bad
+
+```rust
+struct Document {
+    // Vec signals "might grow" but we never push after creation
+    paragraphs: Vec<Paragraph>,  // 24 bytes: ptr + len + capacity
+}
+
+fn load_document(data: &[u8]) -> Document {
+    let paragraphs: Vec<Paragraph> = parse_paragraphs(data);
+    // paragraphs has capacity >= len, wasting the capacity field
+    Document { paragraphs }
+}
+```
+
+## Good
+
+```rust
+struct Document {
+    // Box<[T]> signals "fixed size" - clear intent
+    paragraphs: Box<[Paragraph]>,  // 16 bytes: ptr + len (as fat pointer)
+}
+
+fn load_document(data: &[u8]) -> Document {
+    let paragraphs: Vec<Paragraph> = parse_paragraphs(data);
+    Document { 
+        paragraphs: paragraphs.into_boxed_slice()  // Shrinks + converts
+    }
+}
+```
+
+## Memory Layout
+
+```rust
+use std::mem::size_of;
+
+// Vec: 24 bytes on 64-bit
+assert_eq!(size_of::<Vec<u8>>(), 24);  // ptr(8) + len(8) + cap(8)
+
+// Box<[T]>: 16 bytes (fat pointer)
+assert_eq!(size_of::<Box<[u8]>>(), 16);  // ptr(8) + len(8)
+
+// Savings per instance: 8 bytes
+// For 1 million instances: 8 MB saved
+```
+
+## Conversion Patterns
+
+```rust
+// Vec to Box<[T]>
+let vec: Vec<i32> = vec![1, 2, 3, 4, 5];
+let boxed: Box<[i32]> = vec.into_boxed_slice();
+
+// Box<[T]> back to Vec (if you need to grow)
+let vec_again: Vec<i32> = boxed.into_vec();
+
+// From iterator
+let boxed: Box<[i32]> = (0..100).collect::<Vec<_>>().into_boxed_slice();
+
+// Shrink Vec first if it has excess capacity
+let mut vec = Vec::with_capacity(1000);
+vec.extend(0..10);
+vec.shrink_to_fit();  // Reduce capacity to length
+let boxed = vec.into_boxed_slice();  // Now no wasted allocation
+```
+
+## When to Use What
+
+| Type | Use When |
+|------|----------|
+| `Vec<T>` | Collection may grow/shrink |
+| `Box<[T]>` | Fixed-size, heap-allocated, many instances |
+| `[T; N]` | Fixed-size, stack-allocated, size known at compile time |
+| `&[T]` | Borrowed view, don't need ownership |
+
+## Box<str> for Immutable Strings
+
+Same principle applies to strings:
+
+```rust
+use std::mem::size_of;
+
+// String: 24 bytes (like Vec<u8>)
+assert_eq!(size_of::<String>(), 24);
+
+// Box<str>: 16 bytes
+assert_eq!(size_of::<Box<str>>(), 16);
+
+// For immutable strings
+struct Name {
+    value: Box<str>,  // Saves 8 bytes vs String
+}
+
+impl Name {
+    fn new(s: &str) -> Self {
+        Name { value: s.into() }  // &str -> Box<str>
+    }
+}
+
+// Or from String
+let s = String::from("hello");
+let boxed: Box<str> = s.into_boxed_str();
+```
+
+## Real-World Example
+
+```rust
+// Cache with millions of entries
+struct Cache {
+    // 8 bytes saved per entry adds up
+    entries: HashMap<Key, Box<[u8]>>,
+}
+
+impl Cache {
+    fn insert(&mut self, key: Key, data: Vec<u8>) {
+        // Convert to boxed slice for storage
+        self.entries.insert(key, data.into_boxed_slice());
+    }
+    
+    fn get(&self, key: &Key) -> Option<&[u8]> {
+        // Returns regular slice reference
+        self.entries.get(key).map(|b| b.as_ref())
+    }
+}
+```
+
+## See Also
+
+- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocating when size is known
+- [own-slice-over-vec](./own-slice-over-vec.md) - Using slices in function parameters
+- [mem-compact-string](./mem-compact-string.md) - Compact string alternatives

package/template/agent/skills/rust-developer/references/rust-rules/mem-clone-from.md

@@ -0,0 +1,147 @@
+# mem-clone-from
+
+> Use `clone_from()` to reuse allocations when repeatedly cloning
+
+## Why It Matters
+
+`x = y.clone()` drops x's allocation and creates a new one from y. `x.clone_from(&y)` reuses x's existing allocation if possible, avoiding the allocation overhead. For repeatedly cloning into the same variable (loops, buffers), this can significantly reduce allocator pressure.
+
+## Bad
+
+```rust
+let mut buffer = String::with_capacity(1024);
+
+for source in sources {
+    buffer = source.clone();  // Drops old allocation, allocates new
+    process(&buffer);
+}
+
+// Each iteration:
+// 1. Drops buffer's 1024-byte allocation
+// 2. Allocates new memory for source.clone()
+// Allocator thrashing!
+```
+
+## Good
+
+```rust
+let mut buffer = String::with_capacity(1024);
+
+for source in sources {
+    buffer.clone_from(source);  // Reuses allocation if capacity sufficient
+    process(&buffer);
+}
+
+// If source.len() <= 1024, no allocation happens
+// Just copies bytes into existing buffer
+```
+
+## How clone_from Works
+
+```rust
+impl Clone for String {
+    fn clone(&self) -> Self {
+        // Always allocates new memory
+        String::from(self.as_str())
+    }
+    
+    fn clone_from(&mut self, source: &Self) {
+        // Reuse existing capacity if possible
+        self.clear();
+        self.push_str(source);  // Only reallocates if capacity insufficient
+    }
+}
+```
+
+## Types That Benefit
+
+```rust
+// String - reuses capacity
+let mut s = String::with_capacity(100);
+s.clone_from(&other_string);
+
+// Vec<T> - reuses capacity
+let mut v: Vec<u8> = Vec::with_capacity(1000);
+v.clone_from(&other_vec);
+
+// HashMap - reuses buckets
+let mut map = HashMap::with_capacity(100);
+map.clone_from(&other_map);
+
+// PathBuf - reuses capacity
+let mut path = PathBuf::with_capacity(256);
+path.clone_from(&other_path);
+```
+
+## Benchmarking the Difference
+
+```rust
+use criterion::{black_box, criterion_group, Criterion};
+
+fn bench_clone_patterns(c: &mut Criterion) {
+    let source = "x".repeat(1000);
+    
+    c.bench_function("clone assignment", |b| {
+        let mut buffer = String::new();
+        b.iter(|| {
+            buffer = black_box(&source).clone();
+        });
+    });
+    
+    c.bench_function("clone_from", |b| {
+        let mut buffer = String::with_capacity(1000);
+        b.iter(|| {
+            buffer.clone_from(black_box(&source));
+        });
+    });
+}
+// clone_from is typically 2-3x faster for this pattern
+```
+
+## Custom Implementations
+
+When implementing Clone for your types:
+
+```rust
+#[derive(Debug)]
+struct Buffer {
+    data: Vec<u8>,
+    metadata: Metadata,
+}
+
+impl Clone for Buffer {
+    fn clone(&self) -> Self {
+        Buffer {
+            data: self.data.clone(),
+            metadata: self.metadata.clone(),
+        }
+    }
+    
+    // Optimize clone_from to reuse vec capacity
+    fn clone_from(&mut self, source: &Self) {
+        self.data.clone_from(&source.data);  // Reuses allocation
+        self.metadata = source.metadata.clone();
+    }
+}
+```
+
+## When NOT Needed
+
+```rust
+// Single clone - no benefit
+let copy = original.clone();  // Can't reuse, no prior allocation
+
+// Small Copy types - no allocation anyway
+let x: i32 = y;  // Not even Clone, just Copy
+
+// Immutable context
+fn process(data: &String) {
+    // Can't use clone_from - would need &mut self
+}
+```
+
+## See Also
+
+- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocating capacity
+- [mem-reuse-collections](./mem-reuse-collections.md) - Reusing collection allocations
+- [own-clone-explicit](./own-clone-explicit.md) - When Clone is appropriate

package/template/agent/skills/rust-developer/references/rust-rules/mem-compact-string.md

@@ -0,0 +1,149 @@
+# mem-compact-string
+
+> Use compact string types for memory-constrained string storage
+
+## Why It Matters
+
+Standard `String` is 24 bytes (pointer + length + capacity). For applications storing millions of short strings, this overhead dominates. Compact string libraries like `compact_str`, `smartstring`, or `ecow` store small strings inline (no heap allocation) and use optimized layouts for larger strings.
+
+## Bad
+
+```rust
+struct User {
+    id: u64,
+    // Most usernames are < 24 chars, but String is always 24 bytes + heap
+    username: String,
+    email: String,
+}
+
+// 1 million users = 24 bytes * 2 * 1M = 48MB just for String metadata
+// Plus all the heap allocations for actual content
+```
+
+## Good
+
+```rust
+use compact_str::CompactString;
+
+struct User {
+    id: u64,
+    // CompactString: 24 bytes, but strings ≤ 24 chars are inline (no heap)
+    username: CompactString,
+    email: CompactString,
+}
+
+// Most usernames fit inline = zero heap allocations
+// Same memory footprint as String but way fewer allocations
+```
+
+## Compact String Libraries
+
+### compact_str
+
+```rust
+use compact_str::CompactString;
+
+// Inline storage for strings ≤ 24 bytes
+let small: CompactString = "hello".into();  // No heap allocation
+
+// Automatic heap fallback for larger strings
+let large: CompactString = "x".repeat(100).into();
+
+// String-like API
+let mut s = CompactString::new("hello");
+s.push_str(" world");
+assert_eq!(s.as_str(), "hello world");
+
+// Format macro
+use compact_str::format_compact;
+let s = format_compact!("value: {}", 42);
+```
+
+### smartstring
+
+```rust
+use smartstring::{SmartString, LazyCompact};
+
+// Default is LazyCompact: 24 bytes inline capacity
+let s: SmartString<LazyCompact> = "short string".into();
+
+// Compact mode: 23 bytes inline on 64-bit
+use smartstring::Compact;
+let s: SmartString<Compact> = "hello".into();
+```
+
+### ecow (copy-on-write)
+
+```rust
+use ecow::EcoString;
+
+// Clone is O(1) - shares underlying data
+let s1: EcoString = "shared data".into();
+let s2 = s1.clone();  // Cheap, shares allocation
+
+// Copy-on-write: only allocates on mutation
+let mut s3 = s1.clone();
+s3.push_str(" modified");  // Now allocates
+```
+
+## Memory Comparison
+
+```rust
+use std::mem::size_of;
+
+// All 24 bytes, but different inline capacities
+assert_eq!(size_of::<String>(), 24);
+assert_eq!(size_of::<compact_str::CompactString>(), 24);
+assert_eq!(size_of::<smartstring::SmartString>(), 24);
+assert_eq!(size_of::<ecow::EcoString>(), 16);  // Even smaller!
+```
+
+## Inline Capacity
+
+| Type | Size | Inline Capacity |
+|------|------|-----------------|
+| `String` | 24 | 0 (always heap) |
+| `CompactString` | 24 | 24 bytes |
+| `SmartString<LazyCompact>` | 24 | 23 bytes |
+| `EcoString` | 16 | 15 bytes |
+
+## When to Use
+
+```rust
+// ✅ Good: Many short strings in memory
+struct Dictionary {
+    words: Vec<CompactString>,  // Millions of short words
+}
+
+// ✅ Good: Frequently cloned strings
+struct Template {
+    parts: Vec<EcoString>,  // O(1) clone
+}
+
+// ❌ Don't: Hot path string manipulation
+fn transform(s: &str) -> String {
+    // Standard String is optimized for manipulation
+    s.to_uppercase()
+}
+
+// ❌ Don't: API boundaries (prefer &str or String for interop)
+pub fn public_api(input: CompactString) { }  // Forces dependency
+pub fn public_api(input: impl Into<String>) { }  // Better
+```
+
+## Cargo.toml
+
+```toml
+[dependencies]
+compact_str = "0.7"
+# or
+smartstring = "1.0"
+# or
+ecow = "0.2"
+```
+
+## See Also
+
+- [mem-boxed-slice](./mem-boxed-slice.md) - Box<str> for immutable strings
+- [own-cow-conditional](./own-cow-conditional.md) - Cow<str> for borrow-or-own
+- [mem-smallvec](./mem-smallvec.md) - Similar concept for Vec