agy-superpowers 5.1.3 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/mem-avoid-format.md

@@ -0,0 +1,147 @@
+# mem-avoid-format
+
+> Avoid `format!()` when string literals work
+
+## Why It Matters
+
+`format!()` always allocates a new String, even for constant text. In hot paths, these allocations add up. Use string literals, `write!()`, or pre-allocated buffers instead.
+
+## Bad
+
+```rust
+// Allocates every time, even for static text
+fn get_error_message() -> String {
+    format!("An error occurred")  // Unnecessary allocation!
+}
+
+// Allocates in a loop
+for item in items {
+    log::info!("{}", format!("Processing item: {}", item));  // Double work!
+}
+
+// format! in hot path
+fn classify(n: i32) -> String {
+    if n > 0 {
+        format!("positive")  // Allocates!
+    } else if n < 0 {
+        format!("negative")  // Allocates!
+    } else {
+        format!("zero")      // Allocates!
+    }
+}
+```
+
+## Good
+
+```rust
+// Return &'static str for constants
+fn get_error_message() -> &'static str {
+    "An error occurred"  // No allocation
+}
+
+// Use format args directly
+for item in items {
+    log::info!("Processing item: {}", item);  // No intermediate String
+}
+
+// Return Cow for mixed static/dynamic
+use std::borrow::Cow;
+
+fn classify(n: i32) -> Cow<'static, str> {
+    if n > 0 {
+        Cow::Borrowed("positive")  // No allocation
+    } else if n < 0 {
+        Cow::Borrowed("negative")  // No allocation
+    } else {
+        Cow::Borrowed("zero")      // No allocation
+    }
+}
+
+// Or just &'static str if always static
+fn classify_str(n: i32) -> &'static str {
+    if n > 0 { "positive" }
+    else if n < 0 { "negative" }
+    else { "zero" }
+}
+```
+
+## Use write!() for Output
+
+```rust
+use std::io::Write;
+
+// Bad: Allocate then write
+fn bad_log(writer: &mut impl Write, msg: &str, code: u32) {
+    let formatted = format!("[ERROR {}] {}", code, msg);  // Allocation!
+    writer.write_all(formatted.as_bytes()).unwrap();
+}
+
+// Good: Write directly
+fn good_log(writer: &mut impl Write, msg: &str, code: u32) {
+    write!(writer, "[ERROR {}] {}", code, msg).unwrap();  // No allocation!
+}
+```
+
+## Pre-allocate for Multiple Appends
+
+```rust
+// Bad: Multiple allocations
+fn build_message(parts: &[&str]) -> String {
+    let mut result = String::new();
+    for part in parts {
+        result = format!("{}{}\n", result, part);  // Allocates each iteration!
+    }
+    result
+}
+
+// Good: Pre-allocate
+fn build_message(parts: &[&str]) -> String {
+    let total_len: usize = parts.iter().map(|p| p.len() + 1).sum();
+    let mut result = String::with_capacity(total_len);
+    for part in parts {
+        result.push_str(part);
+        result.push('\n');
+    }
+    result
+}
+
+// Good: Use join
+fn build_message(parts: &[&str]) -> String {
+    parts.join("\n")
+}
+```
+
+## CompactString for Small Strings
+
+```rust
+use compact_str::CompactString;
+
+// Stack-allocated for strings <= 24 bytes
+fn format_code(code: u32) -> CompactString {
+    compact_str::format_compact!("ERR-{:04}", code)
+    // Stack-allocated if result is small enough
+}
+```
+
+## When format!() Is Fine
+
+```rust
+// Rare/cold paths - clarity over micro-optimization
+fn log_startup_message() {
+    println!("{}", format!("Starting {} v{}", APP_NAME, VERSION));
+}
+
+// When you need an owned String anyway
+fn create_user_greeting(name: &str) -> String {
+    format!("Hello, {}!", name)  // Need owned String
+}
+
+// Error messages (already on error path)
+return Err(format!("Invalid value: {}", value).into());
+```
+
+## See Also
+
+- [mem-write-over-format](mem-write-over-format.md) - Use write!() instead of format!()
+- [mem-with-capacity](mem-with-capacity.md) - Pre-allocate strings
+- [own-cow-conditional](own-cow-conditional.md) - Use Cow for mixed static/dynamic

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