agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/mem-reuse-collections.md

@@ -0,0 +1,174 @@
+# mem-reuse-collections
+
+> Clear and reuse collections instead of creating new ones in loops
+
+## Why It Matters
+
+Creating new `Vec`, `String`, or `HashMap` instances in hot loops generates significant allocator pressure. Clearing a collection and reusing it keeps the existing capacity, avoiding repeated allocation/deallocation cycles. This is especially impactful for frequently-executed code paths.
+
+## Bad
+
+```rust
+fn process_batches(batches: &[Batch]) -> Vec<Result> {
+    let mut results = Vec::new();
+    
+    for batch in batches {
+        let mut temp = Vec::new();  // Allocates every iteration
+        
+        for item in &batch.items {
+            temp.push(transform(item));
+        }
+        
+        results.push(aggregate(&temp));
+        // temp dropped here, deallocation
+    }
+    
+    results
+}
+
+fn format_lines(items: &[Item]) -> String {
+    let mut output = String::new();
+    
+    for item in items {
+        let line = format!("{}: {}", item.name, item.value);  // Allocates
+        output.push_str(&line);
+        output.push('\n');
+    }
+    
+    output
+}
+```
+
+## Good
+
+```rust
+fn process_batches(batches: &[Batch]) -> Vec<Result> {
+    let mut results = Vec::with_capacity(batches.len());
+    let mut temp = Vec::new();  // Allocate once outside loop
+    
+    for batch in batches {
+        temp.clear();  // Reuse allocation, just reset length
+        
+        for item in &batch.items {
+            temp.push(transform(item));
+        }
+        
+        results.push(aggregate(&temp));
+        // temp keeps its capacity for next iteration
+    }
+    
+    results
+}
+
+fn format_lines(items: &[Item]) -> String {
+    use std::fmt::Write;
+    
+    let mut output = String::new();
+    let mut line = String::new();  // Reusable buffer
+    
+    for item in items {
+        line.clear();
+        write!(&mut line, "{}: {}", item.name, item.value).unwrap();
+        output.push_str(&line);
+        output.push('\n');
+    }
+    
+    output
+}
+```
+
+## Clear vs Drain vs New
+
+```rust
+let mut vec = vec![1, 2, 3, 4, 5];
+
+// clear(): keeps capacity, O(n) for Drop types
+vec.clear();
+assert_eq!(vec.len(), 0);
+assert!(vec.capacity() >= 5);
+
+// drain(): returns iterator, clears after iteration
+let drained: Vec<_> = vec.drain(..).collect();
+
+// truncate(): keeps first n elements
+vec.truncate(2);
+
+// Creating new: loses all capacity
+vec = Vec::new();  // Capacity gone
+```
+
+## HashMap Reuse
+
+```rust
+use std::collections::HashMap;
+
+fn count_words_per_line(lines: &[&str]) -> Vec<HashMap<String, usize>> {
+    let mut results = Vec::with_capacity(lines.len());
+    let mut counts = HashMap::new();  // Reuse across iterations
+    
+    for line in lines {
+        counts.clear();  // Keeps bucket allocation
+        
+        for word in line.split_whitespace() {
+            *counts.entry(word.to_string()).or_insert(0) += 1;
+        }
+        
+        results.push(counts.clone());
+    }
+    
+    results
+}
+```
+
+## BufWriter Pattern
+
+```rust
+use std::io::{BufWriter, Write};
+
+fn write_many_records(records: &[Record], mut output: impl Write) -> std::io::Result<()> {
+    // BufWriter reuses its internal buffer
+    let mut writer = BufWriter::with_capacity(8192, &mut output);
+    let mut line = String::with_capacity(256);  // Reusable formatting buffer
+    
+    for record in records {
+        line.clear();
+        format_record(record, &mut line);
+        writer.write_all(line.as_bytes())?;
+        writer.write_all(b"\n")?;
+    }
+    
+    writer.flush()
+}
+```
+
+## When to Create Fresh
+
+```rust
+// When ownership transfer is needed
+fn produce_results() -> Vec<Vec<Item>> {
+    let mut results = Vec::new();
+    
+    for batch in batches {
+        let processed: Vec<Item> = batch.process();  // Ownership transferred
+        results.push(processed);  // Moved into results
+    }
+    
+    results  // Each inner Vec is independent
+}
+
+// When thread safety requires it
+std::thread::scope(|s| {
+    for _ in 0..4 {
+        s.spawn(|| {
+            let local_buffer = Vec::new();  // Thread-local, can't share
+            // ...
+        });
+    }
+});
+```
+
+## See Also
+
+- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocating capacity
+- [mem-clone-from](./mem-clone-from.md) - Reusing allocations when cloning
+- [mem-write-over-format](./mem-write-over-format.md) - Avoiding format! allocations

package/template/agent/skills/rust-developer/references/rust-rules/mem-smaller-integers.md

@@ -0,0 +1,159 @@
+# mem-smaller-integers
+
+> Use appropriately-sized integers to reduce memory footprint
+
+## Why It Matters
+
+Using `i64` when `i16` suffices wastes 6 bytes per value. In arrays, vectors, and structs with millions of instances, this waste compounds dramatically. Choosing the smallest integer type that fits your domain reduces memory usage and improves cache utilization.
+
+## Bad
+
+```rust
+struct Pixel {
+    r: u64,  // Color channels 0-255 = 8 bits needed
+    g: u64,  // Using 64 bits = 8x waste
+    b: u64,
+    a: u64,
+}
+// Size: 32 bytes per pixel
+
+struct HttpStatus {
+    code: i32,      // HTTP codes 100-599 = 10 bits needed
+    version: i32,   // HTTP 1.0, 1.1, 2, 3 = 2 bits needed
+}
+// Size: 8 bytes per status
+
+struct GeoPoint {
+    lat: f64,   // -90 to 90
+    lon: f64,   // -180 to 180
+}
+// Often f32 precision is sufficient for display
+```
+
+## Good
+
+```rust
+struct Pixel {
+    r: u8,
+    g: u8,
+    b: u8,
+    a: u8,
+}
+// Size: 4 bytes per pixel (8x smaller!)
+
+struct HttpStatus {
+    code: u16,      // 100-599 fits in u16
+    version: u8,    // 1, 2, 3 fits in u8
+}
+// Size: 3 bytes (+ 1 padding = 4 bytes)
+
+struct GeoPoint {
+    lat: f32,   // ~7 decimal digits precision
+    lon: f32,   // Sufficient for most geo applications
+}
+// Size: 8 bytes vs 16 bytes
+```
+
+## Integer Size Reference
+
+| Type | Range | Use For |
+|------|-------|---------|
+| `u8` | 0 to 255 | Bytes, small counts, flags |
+| `i8` | -128 to 127 | Small signed values |
+| `u16` | 0 to 65,535 | Port numbers, small indices |
+| `i16` | -32,768 to 32,767 | Audio samples |
+| `u32` | 0 to 4 billion | Array indices, timestamps (seconds) |
+| `i32` | ±2 billion | General integers, file offsets |
+| `u64` | 0 to 18 quintillion | Large counts, nanosecond timestamps |
+| `usize` | Platform-dependent | Array indexing (required by Rust) |
+
+## Struct Packing
+
+```rust
+use std::mem::size_of;
+
+// Poor ordering - 24 bytes due to padding
+struct Wasteful {
+    a: u8,    // 1 byte + 7 padding
+    b: u64,   // 8 bytes
+    c: u8,    // 1 byte + 7 padding
+}
+assert_eq!(size_of::<Wasteful>(), 24);
+
+// Better ordering - 16 bytes
+struct Efficient {
+    b: u64,   // 8 bytes (aligned)
+    a: u8,    // 1 byte
+    c: u8,    // 1 byte + 6 padding
+}
+assert_eq!(size_of::<Efficient>(), 16);
+
+// Even better with smaller types - 10 bytes
+struct Compact {
+    b: u32,   // 4 bytes (if u32 suffices)
+    a: u8,    // 1 byte
+    c: u8,    // 1 byte
+}
+assert_eq!(size_of::<Compact>(), 8);  // With padding
+```
+
+## Conversion Safety
+
+```rust
+// Safe: always succeeds (widening)
+let small: u8 = 42;
+let big: u32 = small.into();
+
+// Fallible: may overflow (narrowing)
+let big: u32 = 1000;
+let small: u8 = big.try_into().expect("value out of range");
+
+// Or use checked conversion
+if let Ok(small) = u8::try_from(big) {
+    use_small(small);
+} else {
+    handle_overflow();
+}
+```
+
+## Bitflags for Boolean Sets
+
+```rust
+use bitflags::bitflags;
+
+// Instead of 8 separate bool fields (8 bytes minimum)
+bitflags! {
+    struct Permissions: u8 {
+        const READ    = 0b0000_0001;
+        const WRITE   = 0b0000_0010;
+        const EXECUTE = 0b0000_0100;
+        const DELETE  = 0b0000_1000;
+    }
+}
+// All 8 flags in 1 byte!
+
+let perms = Permissions::READ | Permissions::WRITE;
+if perms.contains(Permissions::READ) {
+    // ...
+}
+```
+
+## NonZero Types for Option Optimization
+
+```rust
+use std::num::NonZeroU64;
+
+// Option<u64> = 16 bytes (no null pointer optimization)
+assert_eq!(size_of::<Option<u64>>(), 16);
+
+// Option<NonZeroU64> = 8 bytes (0 represents None)
+assert_eq!(size_of::<Option<NonZeroU64>>(), 8);
+
+let id: Option<NonZeroU64> = NonZeroU64::new(42);
+```
+
+## See Also
+
+- [mem-box-large-variant](./mem-box-large-variant.md) - Optimizing enum sizes
+- [mem-assert-type-size](./mem-assert-type-size.md) - Compile-time size checks
+- [type-newtype-ids](./type-newtype-ids.md) - Type safety for integer IDs

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

@@ -0,0 +1,138 @@
+# mem-smallvec
+
+> Use `SmallVec` for usually-small collections
+
+## Why It Matters
+
+`SmallVec<[T; N]>` stores up to N elements inline (on the stack), only allocating on the heap when the size exceeds N. This eliminates heap allocations for the common case while still allowing growth when needed.
+
+## Bad
+
+```rust
+// Always heap-allocates, even for 1-2 elements
+fn get_path_components(path: &str) -> Vec<&str> {
+    path.split('/').collect()  // Usually 2-4 components
+}
+
+// Always heap-allocates for error list
+fn validate(input: &Input) -> Vec<ValidationError> {
+    let mut errors = Vec::new();  // Usually 0-3 errors
+    // validation logic...
+    errors
+}
+```
+
+## Good
+
+```rust
+use smallvec::{smallvec, SmallVec};
+
+// Stack-allocated for typical paths (1-8 components)
+fn get_path_components(path: &str) -> SmallVec<[&str; 8]> {
+    path.split('/').collect()
+}
+
+// Stack-allocated for typical error counts
+fn validate(input: &Input) -> SmallVec<[ValidationError; 4]> {
+    let mut errors = SmallVec::new();
+    // validation logic...
+    errors
+}
+
+// Using smallvec! macro
+let v: SmallVec<[i32; 4]> = smallvec![1, 2, 3];
+```
+
+## Choosing Capacity N
+
+```rust
+// Measure your actual data distribution!
+// Guidelines:
+
+// Path components: 4-8 (most paths are shallow)
+type PathParts<'a> = SmallVec<[&'a str; 8]>;
+
+// Function arguments: 4-8 (most functions have few args)  
+type Args = SmallVec<[Arg; 8]>;
+
+// AST children: 2-4 (binary ops, if/else, etc.)
+type Children = SmallVec<[Node; 4]>;
+
+// Error accumulation: 2-4 (most inputs have few errors)
+type Errors = SmallVec<[Error; 4]>;
+
+// Attribute lists: 4-8 (most items have few attributes)
+type Attrs = SmallVec<[Attribute; 8]>;
+```
+
+## Evidence from rust-analyzer
+
+```rust
+// https://github.com/rust-lang/rust/blob/main/compiler/rustc_expand/src/base.rs
+macro_rules! make_stmts_default {
+    ($me:expr) => {
+        $me.make_expr().map(|e| {
+            smallvec![ast::Stmt {
+                id: ast::DUMMY_NODE_ID,
+                span: e.span,
+                kind: ast::StmtKind::Expr(e),
+            }]
+        })
+    }
+}
+```
+
+## Trade-offs
+
+```rust
+// SmallVec is slightly larger than Vec
+use std::mem::size_of;
+// Vec<i32>: 24 bytes (ptr + len + cap)
+// SmallVec<[i32; 4]>: 32 bytes (inline storage + len + discriminant)
+
+// SmallVec has branching overhead on every operation
+// (must check if inline or heap)
+
+// Profile to verify benefit!
+```
+
+## When to Use SmallVec vs Alternatives
+
+| Situation | Use |
+|-----------|-----|
+| Usually small, sometimes large | `SmallVec<[T; N]>` |
+| Always small, fixed max | `ArrayVec<T, N>` |
+| Rarely grows past initial | `Vec::with_capacity` |
+| No `unsafe` allowed | `TinyVec` |
+| Often empty | `ThinVec` |
+
+## ArrayVec Alternative
+
+```rust
+use arrayvec::ArrayVec;
+
+// Fixed maximum capacity, never heap allocates
+// Panics if you exceed capacity
+fn parse_rgb(s: &str) -> ArrayVec<u8, 3> {
+    let mut components = ArrayVec::new();
+    for part in s.split(',').take(3) {
+        components.push(part.parse().unwrap());
+    }
+    components
+}
+```
+
+## TinyVec (No Unsafe)
+
+```rust
+use tinyvec::{tiny_vec, TinyVec};
+
+// Same concept as SmallVec but 100% safe code
+let v: TinyVec<[i32; 4]> = tiny_vec![1, 2, 3];
+```
+
+## See Also
+
+- [mem-arrayvec](mem-arrayvec.md) - Use ArrayVec for fixed-max collections
+- [mem-with-capacity](mem-with-capacity.md) - Pre-allocate when size is known
+- [mem-thinvec](mem-thinvec.md) - Use ThinVec for often-empty vectors

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

@@ -0,0 +1,142 @@
+# mem-thinvec
+
+> Use `ThinVec<T>` for nullable collections with minimal overhead
+
+## Why It Matters
+
+Standard `Vec<T>` is 24 bytes even when empty. `ThinVec` from Mozilla's `thin_vec` crate uses a single pointer (8 bytes), storing length and capacity inline with the heap allocation. For Option<Vec<T>> patterns or structs with many optional vecs, this significantly reduces memory overhead.
+
+## Bad
+
+```rust
+struct TreeNode {
+    value: i32,
+    // Each node pays 24 bytes for children, even leaves
+    children: Vec<TreeNode>,  // Most nodes are leaves with empty Vec
+}
+
+// Or using Option<Vec<T>>
+struct SparseData {
+    // Option<Vec> = 24 bytes (Vec is never null-pointer optimized)
+    tags: Option<Vec<String>>,
+    metadata: Option<Vec<Metadata>>,
+    // 48 bytes for usually-None fields
+}
+```
+
+## Good
+
+```rust
+use thin_vec::ThinVec;
+
+struct TreeNode {
+    value: i32,
+    // Empty ThinVec is just a null pointer - 8 bytes
+    children: ThinVec<TreeNode>,
+}
+
+struct SparseData {
+    // ThinVec empty = 8 bytes each
+    tags: ThinVec<String>,
+    metadata: ThinVec<Metadata>,
+    // 16 bytes vs 48 bytes
+}
+```
+
+## Memory Layout
+
+```rust
+use std::mem::size_of;
+
+// Standard Vec: always 24 bytes
+assert_eq!(size_of::<Vec<u8>>(), 24);
+assert_eq!(size_of::<Option<Vec<u8>>>(), 24);  // No NPO benefit
+
+// ThinVec: 8 bytes (one pointer)
+use thin_vec::ThinVec;
+assert_eq!(size_of::<ThinVec<u8>>(), 8);
+assert_eq!(size_of::<Option<ThinVec<u8>>>(), 8);  // Option is free!
+```
+
+## ThinVec vs Vec
+
+| Feature | `Vec<T>` | `ThinVec<T>` |
+|---------|----------|--------------|
+| Size (empty) | 24 bytes | 8 bytes |
+| Size (non-empty) | 24 bytes | 8 bytes (header on heap) |
+| Option<T> optimization | No | Yes |
+| Cache locality | Better (len/cap on stack) | Worse (len/cap on heap) |
+| Iteration speed | Faster | Slightly slower |
+| API compatibility | Full | Vec-like |
+
+## When to Use ThinVec
+
+```rust
+// ✅ Good: Many instances, often empty
+struct SparseGraph {
+    nodes: Vec<Node>,
+    // Most edges lists are empty or small
+    edges: Vec<ThinVec<EdgeId>>,  // Saves 16 bytes per node
+}
+
+// ✅ Good: Nullable collection field
+struct Document {
+    content: String,
+    attachments: ThinVec<Attachment>,  // Often empty
+}
+
+// ❌ Avoid: Hot loops, performance-critical iteration
+fn process_hot_path(data: &ThinVec<Item>) {
+    // Every length check goes through pointer indirection
+    for item in data {  // Vec would be faster here
+        process(item);
+    }
+}
+
+// ❌ Avoid: Few instances
+fn main() {
+    let single_vec: ThinVec<i32> = ThinVec::new();
+    // Saving 16 bytes once is meaningless
+}
+```
+
+## API Compatibility
+
+```rust
+use thin_vec::{ThinVec, thin_vec};
+
+// Constructor macro
+let v: ThinVec<i32> = thin_vec![1, 2, 3];
+
+// Familiar Vec-like API
+let mut v = ThinVec::new();
+v.push(1);
+v.push(2);
+v.extend([3, 4, 5]);
+v.pop();
+
+// Iteration
+for item in &v {
+    println!("{}", item);
+}
+
+// Slicing
+let slice: &[i32] = &v[..];
+
+// Conversion
+let vec: Vec<i32> = v.into();
+let thin: ThinVec<i32> = vec.into();
+```
+
+## Cargo.toml
+
+```toml
+[dependencies]
+thin-vec = "0.2"
+```
+
+## See Also
+
+- [mem-smallvec](./mem-smallvec.md) - Stack-allocated small vecs
+- [mem-boxed-slice](./mem-boxed-slice.md) - Fixed-size heap slices
+- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocation strategies