agy-superpowers 5.1.4 → 5.1.6

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

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

@@ -0,0 +1,156 @@
+# mem-with-capacity
+
+> Use `with_capacity()` when size is known
+
+## Why It Matters
+
+When you know (or can estimate) the final size of a collection, pre-allocating avoids multiple reallocations as it grows. Each reallocation copies all existing elements, so avoiding them can dramatically improve performance.
+
+## Bad
+
+```rust
+// Vec starts at capacity 0, reallocates at 4, 8, 16, 32...
+let mut results = Vec::new();
+for i in 0..1000 {
+    results.push(process(i));  // ~10 reallocations!
+}
+
+// String grows similarly
+let mut output = String::new();
+for word in words {
+    output.push_str(word);
+    output.push(' ');
+}
+
+// HashMap default capacity is small
+let mut map = HashMap::new();
+for (k, v) in pairs {  // Many reallocations
+    map.insert(k, v);
+}
+```
+
+## Good
+
+```rust
+// Pre-allocate exact size
+let mut results = Vec::with_capacity(1000);
+for i in 0..1000 {
+    results.push(process(i));  // Zero reallocations!
+}
+
+// Or use collect with size hint (iterator provides capacity)
+let results: Vec<_> = (0..1000).map(process).collect();
+
+// Pre-allocate string
+let estimated_len = words.iter().map(|w| w.len() + 1).sum();
+let mut output = String::with_capacity(estimated_len);
+for word in words {
+    output.push_str(word);
+    output.push(' ');
+}
+
+// Pre-allocate HashMap
+let mut map = HashMap::with_capacity(pairs.len());
+for (k, v) in pairs {
+    map.insert(k, v);
+}
+```
+
+## Collection Capacity Methods
+
+```rust
+// Vec
+let mut v = Vec::with_capacity(100);
+v.reserve(50);        // Ensure at least 50 more slots
+v.reserve_exact(50);  // Ensure exactly 50 more (no extra)
+v.shrink_to_fit();    // Release unused capacity
+
+// String
+let mut s = String::with_capacity(100);
+s.reserve(50);
+
+// HashMap / HashSet
+let mut m = HashMap::with_capacity(100);
+m.reserve(50);
+
+// VecDeque
+let mut d = VecDeque::with_capacity(100);
+```
+
+## Estimating Capacity
+
+```rust
+// From iterator length
+fn collect_results(items: &[Item]) -> Vec<Output> {
+    let mut results = Vec::with_capacity(items.len());
+    for item in items {
+        results.push(process(item));
+    }
+    results
+}
+
+// From filter estimate (if ~10% pass filter)
+fn filter_valid(items: &[Item]) -> Vec<&Item> {
+    let mut valid = Vec::with_capacity(items.len() / 10);
+    for item in items {
+        if item.is_valid() {
+            valid.push(item);
+        }
+    }
+    valid
+}
+
+// String from parts
+fn join_with_sep(parts: &[&str], sep: &str) -> String {
+    let total_len: usize = parts.iter().map(|p| p.len()).sum();
+    let sep_len = if parts.is_empty() { 0 } else { sep.len() * (parts.len() - 1) };
+    
+    let mut result = String::with_capacity(total_len + sep_len);
+    for (i, part) in parts.iter().enumerate() {
+        if i > 0 {
+            result.push_str(sep);
+        }
+        result.push_str(part);
+    }
+    result
+}
+```
+
+## Evidence from Production Code
+
+From fd (file finder):
+```rust
+// https://github.com/sharkdp/fd/blob/master/src/walk.rs
+struct ReceiverBuffer<'a, W> {
+    buffer: Vec<DirEntry>,
+    // ...
+}
+
+impl<'a, W: Write> ReceiverBuffer<'a, W> {
+    fn new(...) -> Self {
+        Self {
+            buffer: Vec::with_capacity(MAX_BUFFER_LENGTH),
+            // ...
+        }
+    }
+}
+```
+
+## When to Skip
+
+```rust
+// Unknown size, small expected
+let mut small: Vec<i32> = Vec::new();  // OK for small collections
+
+// Using collect() with good size_hint
+let v: Vec<_> = iter.collect();  // collect() uses size_hint
+
+// Capacity overhead exceeds benefit
+let mut rarely_used = Vec::new();  // OK if rarely grown
+```
+
+## See Also
+
+- [mem-reuse-collections](mem-reuse-collections.md) - Reuse collections with clear()
+- [mem-smallvec](mem-smallvec.md) - Use SmallVec for usually-small collections
+- [perf-extend-batch](perf-extend-batch.md) - Use extend() for batch insertions

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

@@ -0,0 +1,172 @@
+# mem-write-over-format
+
+> Use `write!()` into existing buffers instead of `format!()` allocations
+
+## Why It Matters
+
+`format!()` always allocates a new `String`. In hot paths or loops, these allocations add up. `write!()` writes directly into an existing buffer, reusing its capacity. For high-frequency formatting operations, this can eliminate significant allocator overhead.
+
+## Bad
+
+```rust
+fn log_event(event: &Event, output: &mut Vec<u8>) {
+    // format! allocates a new String every call
+    let line = format!(
+        "[{}] {}: {}\n",
+        event.timestamp,
+        event.level,
+        event.message
+    );
+    output.extend_from_slice(line.as_bytes());
+}
+
+fn build_response(items: &[Item]) -> String {
+    let mut result = String::new();
+    
+    for item in items {
+        // format! allocates for each item
+        result.push_str(&format!("{}: {}\n", item.name, item.value));
+    }
+    
+    result
+}
+```
+
+## Good
+
+```rust
+use std::fmt::Write;
+
+fn log_event(event: &Event, output: &mut Vec<u8>) {
+    use std::io::Write;
+    // write! to Vec<u8> directly, no intermediate allocation
+    write!(
+        output,
+        "[{}] {}: {}\n",
+        event.timestamp,
+        event.level,
+        event.message
+    ).unwrap();
+}
+
+fn build_response(items: &[Item]) -> String {
+    use std::fmt::Write;
+    
+    let mut result = String::with_capacity(items.len() * 64);
+    
+    for item in items {
+        // write! into existing String, reuses capacity
+        write!(&mut result, "{}: {}\n", item.name, item.value).unwrap();
+    }
+    
+    result
+}
+```
+
+## Write Trait Varieties
+
+```rust
+// std::fmt::Write - for String, &mut String
+use std::fmt::Write as FmtWrite;
+let mut s = String::new();
+write!(&mut s, "Hello {}", 42).unwrap();
+
+// std::io::Write - for Vec<u8>, File, TcpStream, etc.
+use std::io::Write as IoWrite;
+let mut v: Vec<u8> = Vec::new();
+write!(&mut v, "Hello {}", 42).unwrap();
+
+// Both can fail in principle, but String/Vec never fail
+// Still need .unwrap() due to Result return type
+```
+
+## Reusable Formatting Buffer
+
+```rust
+use std::fmt::Write;
+
+struct Formatter {
+    buffer: String,
+}
+
+impl Formatter {
+    fn new() -> Self {
+        Self { buffer: String::with_capacity(1024) }
+    }
+    
+    fn format_event(&mut self, event: &Event) -> &str {
+        self.buffer.clear();  // Reuse allocation
+        write!(
+            &mut self.buffer, 
+            "[{}] {}",
+            event.timestamp, 
+            event.message
+        ).unwrap();
+        &self.buffer
+    }
+}
+
+// Usage
+let mut formatter = Formatter::new();
+for event in events {
+    let formatted = formatter.format_event(event);
+    send_log(formatted);
+}
+```
+
+## writeln! for Lines
+
+```rust
+use std::fmt::Write;
+
+let mut output = String::new();
+
+// writeln! adds newline automatically
+writeln!(&mut output, "Line 1: {}", value1).unwrap();
+writeln!(&mut output, "Line 2: {}", value2).unwrap();
+
+// Equivalent to
+write!(&mut output, "Line 1: {}\n", value1).unwrap();
+```
+
+## When format! Is Fine
+
+```rust
+// One-time formatting, not in loop
+let message = format!("Starting server on port {}", port);
+log::info!("{}", message);
+
+// Return value (can't return reference to local buffer)
+fn describe(item: &Item) -> String {
+    format!("{}: {}", item.name, item.value)  // Must allocate
+}
+
+// Debug/error paths (not hot)
+if condition {
+    panic!("Unexpected: {}", format!("details: {:?}", debug_info));
+}
+```
+
+## Benchmark Difference
+
+```rust
+// format! in loop: ~500ns per iteration (allocation heavy)
+for i in 0..1000 {
+    let s = format!("item-{}", i);
+    process(&s);
+}
+
+// write! with reuse: ~50ns per iteration (no allocation)
+let mut buf = String::with_capacity(32);
+for i in 0..1000 {
+    buf.clear();
+    write!(&mut buf, "item-{}", i).unwrap();
+    process(&buf);
+}
+```
+
+## See Also
+
+- [mem-avoid-format](./mem-avoid-format.md) - General format! avoidance patterns
+- [mem-reuse-collections](./mem-reuse-collections.md) - Reusing buffers in loops
+- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocating string capacity

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

@@ -0,0 +1,164 @@
+# mem-zero-copy
+
+> Use zero-copy patterns with slices and `Bytes`
+
+## Why It Matters
+
+Zero-copy means working with data without copying it. Instead of allocating new memory and copying bytes, you work with references to the original data. This dramatically reduces memory usage and improves performance, especially for large data.
+
+## Bad
+
+```rust
+// Copies every line into a new String
+fn get_lines(data: &str) -> Vec<String> {
+    data.lines()
+        .map(|line| line.to_string())  // Allocates!
+        .collect()
+}
+
+// Copies the entire buffer
+fn process_packet(buffer: &[u8]) -> Vec<u8> {
+    let header = buffer[0..16].to_vec();  // Copy!
+    let body = buffer[16..].to_vec();      // Copy!
+    // Process...
+    [header, body].concat()  // Another copy!
+}
+```
+
+## Good
+
+```rust
+// Zero-copy: returns references to original data
+fn get_lines(data: &str) -> Vec<&str> {
+    data.lines().collect()  // Just pointers!
+}
+
+// Zero-copy with slices
+fn process_packet(buffer: &[u8]) -> (&[u8], &[u8]) {
+    let header = &buffer[0..16];  // Just a pointer + length
+    let body = &buffer[16..];     // Just a pointer + length
+    (header, body)
+}
+```
+
+## Using bytes::Bytes
+
+```rust
+use bytes::Bytes;
+
+// Bytes provides zero-copy slicing with reference counting
+let data = Bytes::from("hello world");
+
+// Slicing doesn't copy - just increments refcount
+let hello = data.slice(0..5);   // Zero-copy!
+let world = data.slice(6..11); // Zero-copy!
+
+// Both hello and world share the underlying allocation
+// Memory is freed when all references are dropped
+```
+
+## Real-World Pattern from Deno
+
+```rust
+// https://github.com/denoland/deno/blob/main/ext/http/lib.rs
+fn method_to_cow(method: &http::Method) -> Cow<'static, str> {
+    match *method {
+        Method::GET => Cow::Borrowed("GET"),      // Zero-copy
+        Method::POST => Cow::Borrowed("POST"),    // Zero-copy
+        Method::PUT => Cow::Borrowed("PUT"),      // Zero-copy
+        _ => Cow::Owned(method.to_string()),      // Only copies for rare methods
+    }
+}
+```
+
+## Zero-Copy Parsing
+
+```rust
+// Bad: Copies each parsed field
+struct ParsedBad {
+    name: String,
+    value: String,
+}
+
+fn parse_bad(input: &str) -> ParsedBad {
+    let (name, value) = input.split_once('=').unwrap();
+    ParsedBad {
+        name: name.to_string(),   // Copy!
+        value: value.to_string(), // Copy!
+    }
+}
+
+// Good: References into original string
+struct Parsed<'a> {
+    name: &'a str,
+    value: &'a str,
+}
+
+fn parse_good(input: &str) -> Parsed<'_> {
+    let (name, value) = input.split_once('=').unwrap();
+    Parsed { name, value }  // Zero-copy!
+}
+```
+
+## Combining with Cow
+
+```rust
+use std::borrow::Cow;
+
+// Zero-copy when possible, copy when needed
+fn normalize<'a>(input: &'a str) -> Cow<'a, str> {
+    if input.contains('\t') {
+        // Must copy to modify
+        Cow::Owned(input.replace('\t', "    "))
+    } else {
+        // Zero-copy reference
+        Cow::Borrowed(input)
+    }
+}
+```
+
+## memchr for Fast Searching
+
+```rust
+use memchr::memchr;
+
+// Fast byte search using SIMD
+fn find_newline(data: &[u8]) -> Option<usize> {
+    memchr(b'\n', data)  // SIMD-accelerated, no allocation
+}
+
+// Find all occurrences
+use memchr::memchr_iter;
+
+fn count_newlines(data: &[u8]) -> usize {
+    memchr_iter(b'\n', data).count()
+}
+```
+
+## When Zero-Copy Isn't Possible
+
+```rust
+// Need to modify data - must copy
+fn uppercase(s: &str) -> String {
+    s.to_uppercase()  // Creates new String
+}
+
+// Need data to outlive source
+fn store_for_later(s: &str) -> String {
+    s.to_string()  // Must copy for ownership
+}
+
+// Cross-thread transfer (without Arc)
+fn send_to_thread(data: &[u8]) {
+    let owned = data.to_vec();  // Must copy
+    std::thread::spawn(move || {
+        process(&owned);
+    });
+}
+```
+
+## See Also
+
+- [own-cow-conditional](own-cow-conditional.md) - Use Cow for conditional ownership
+- [own-borrow-over-clone](own-borrow-over-clone.md) - Prefer borrowing over cloning
+- [mem-arena-allocator](mem-arena-allocator.md) - Arena allocators for batch operations