agy-superpowers 5.2.2 → 5.2.3

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

@@ -1,149 +0,0 @@
-# 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

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

@@ -1,174 +0,0 @@
-# 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

@@ -1,159 +0,0 @@
-# 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

@@ -1,138 +0,0 @@
-# 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