agy-superpowers 5.1.4 → 5.1.5

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

@@ -0,0 +1,168 @@
+# mem-arena-allocator
+
+> Use arena allocators for batch allocations
+
+## Why It Matters
+
+Arena allocators (bump allocators) allocate memory from a contiguous region, making allocation extremely fast (just bump a pointer). All allocations are freed at once when the arena is dropped. Perfect for request-scoped or parse-tree allocations.
+
+## Bad
+
+```rust
+// Many small allocations during parsing
+fn parse(input: &str) -> Vec<Node> {
+    let mut nodes = Vec::new();
+    for token in tokenize(input) {
+        nodes.push(Box::new(Node::new(token)));  // Heap alloc per node!
+    }
+    nodes
+}
+
+// Per-request allocations add up
+fn handle_request(req: Request) -> Response {
+    let headers = parse_headers(&req);      // Allocates
+    let body = parse_body(&req);            // Allocates
+    let response = generate_response();     // Allocates
+    // All freed individually at end
+    response
+}
+```
+
+## Good
+
+```rust
+use bumpalo::Bump;
+
+// All nodes allocated from same arena
+fn parse<'a>(input: &str, arena: &'a Bump) -> Vec<&'a Node> {
+    let mut nodes = Vec::new();
+    for token in tokenize(input) {
+        let node = arena.alloc(Node::new(token));  // Fast bump!
+        nodes.push(node);
+    }
+    nodes
+}  // Arena freed all at once
+
+// Per-request arena
+fn handle_request(req: Request) -> Response {
+    let arena = Bump::new();
+    
+    let headers = parse_headers(&req, &arena);
+    let body = parse_body(&req, &arena);
+    let response = generate_response(&arena);
+    
+    // Convert to owned response before arena drops
+    response.to_owned()
+}  // All request memory freed instantly
+```
+
+## Thread-Local Scratch Arena Pattern
+
+```rust
+use bumpalo::Bump;
+use std::cell::RefCell;
+
+thread_local! {
+    static SCRATCH: RefCell<Bump> = RefCell::new(Bump::with_capacity(4 * 1024));
+}
+
+fn with_scratch<T>(f: impl FnOnce(&Bump) -> T) -> T {
+    SCRATCH.with(|scratch| {
+        let arena = scratch.borrow();
+        let result = f(&arena);
+        result
+    })
+}
+
+fn reset_scratch() {
+    SCRATCH.with(|scratch| {
+        scratch.borrow_mut().reset();
+    });
+}
+
+// Usage
+fn process_batch(items: &[Item]) -> Vec<Output> {
+    with_scratch(|arena| {
+        let temp_data: Vec<&TempData> = items
+            .iter()
+            .map(|item| arena.alloc(compute_temp(item)))
+            .collect();
+        
+        // Use temp_data...
+        let result = finalize(&temp_data);
+        
+        reset_scratch();  // Reuse arena memory
+        result
+    })
+}
+```
+
+## Evidence from ROC Compiler
+
+```rust
+// https://github.com/roc-lang/roc/blob/main/crates/compiler/solve/src/to_var.rs
+std::thread_local! {
+    static SCRATCHPAD: RefCell<Option<bumpalo::Bump>> = 
+        RefCell::new(Some(bumpalo::Bump::with_capacity(4 * 1024)));
+}
+
+fn take_scratchpad() -> bumpalo::Bump {
+    SCRATCHPAD.with(|f| f.take().unwrap())
+}
+
+fn put_scratchpad(scratchpad: bumpalo::Bump) {
+    SCRATCHPAD.with(|f| {
+        f.replace(Some(scratchpad));
+    });
+}
+```
+
+## Bumpalo Collections
+
+```rust
+use bumpalo::Bump;
+use bumpalo::collections::{Vec, String};
+
+fn process<'a>(arena: &'a Bump, input: &str) -> Vec<'a, String<'a>> {
+    let mut results = Vec::new_in(arena);
+    
+    for word in input.split_whitespace() {
+        let mut s = String::new_in(arena);
+        s.push_str(word);
+        s.push_str("_processed");
+        results.push(s);
+    }
+    
+    results  // All allocated in arena
+}
+```
+
+## When to Use Arenas
+
+| Situation | Use Arena? |
+|-----------|-----------|
+| Parsing (AST nodes) | Yes |
+| Request handling | Yes |
+| Batch processing | Yes |
+| Long-lived data | No |
+| Data escaping scope | No (or copy out) |
+| Simple programs | Overkill |
+
+## Performance Impact
+
+```rust
+// Benchmarks from production systems:
+// - Individual allocations: ~25-50ns each
+// - Arena bump: ~1-2ns each (20-50x faster)
+// - Arena reset: O(1) regardless of allocation count
+
+// Memory overhead:
+// - Arena wastes some memory (unused capacity)
+// - But eliminates per-allocation metadata overhead
+```
+
+## See Also
+
+- [mem-with-capacity](mem-with-capacity.md) - Pre-allocate when size is known
+- [mem-reuse-collections](mem-reuse-collections.md) - Reuse collections with clear()
+- [opt-profile-first](perf-profile-first.md) - Profile to verify benefit

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

@@ -0,0 +1,142 @@
+# mem-arrayvec
+
+> Use `ArrayVec<T, N>` for fixed-capacity collections that never heap-allocate
+
+## Why It Matters
+
+`ArrayVec` from the `arrayvec` crate provides Vec-like API with a compile-time maximum capacity, storing all elements inline on the stack. Unlike `SmallVec` which can spill to heap, `ArrayVec` guarantees no heap allocation—if you exceed capacity, it returns an error or panics. This is ideal for embedded systems, real-time code, or when you have a hard upper bound.
+
+## Bad
+
+```rust
+// Vec always heap-allocates, even for small collections
+fn parse_options(input: &str) -> Vec<Option> {
+    let mut options = Vec::new();  // Heap allocation
+    for part in input.split(',').take(8) {  // Know we never exceed 8
+        options.push(parse_option(part));
+    }
+    options
+}
+
+// Or SmallVec when you truly can't exceed capacity
+use smallvec::SmallVec;
+fn get_flags() -> SmallVec<[Flag; 4]> {
+    // SmallVec CAN heap-allocate if pushed beyond 4
+    // That might be unexpected in no-alloc contexts
+}
+```
+
+## Good
+
+```rust
+use arrayvec::ArrayVec;
+
+// Guaranteed no heap allocation
+fn parse_options(input: &str) -> ArrayVec<Option, 8> {
+    let mut options = ArrayVec::new();
+    for part in input.split(',') {
+        if options.try_push(parse_option(part)).is_err() {
+            break;  // Capacity reached, stop
+        }
+    }
+    options
+}
+
+// For embedded/no_std contexts
+#[no_std]
+fn collect_readings() -> ArrayVec<SensorReading, 16> {
+    let mut readings = ArrayVec::new();
+    for sensor in SENSORS.iter() {
+        readings.push(sensor.read());  // Panics if > 16
+    }
+    readings
+}
+```
+
+## ArrayVec vs SmallVec vs Vec
+
+| Type | Stack | Heap | Use When |
+|------|-------|------|----------|
+| `Vec<T>` | Never | Always | Unknown size, may grow indefinitely |
+| `SmallVec<[T; N]>` | Up to N | Beyond N | Usually small, occasionally large |
+| `ArrayVec<T, N>` | Always | Never | Hard limit, no heap allowed |
+
+## API Patterns
+
+```rust
+use arrayvec::ArrayVec;
+
+let mut arr: ArrayVec<i32, 4> = ArrayVec::new();
+
+// Push with potential panic (like Vec)
+arr.push(1);
+arr.push(2);
+
+// Safe push - returns Err if full
+match arr.try_push(3) {
+    Ok(()) => println!("Added"),
+    Err(err) => println!("Full, couldn't add {}", err.element()),
+}
+
+// Check capacity
+assert!(arr.len() < arr.capacity());
+
+// Remaining capacity
+let remaining = arr.remaining_capacity();
+
+// Is it full?
+if arr.is_full() {
+    arr.pop();
+}
+
+// From iterator with limit
+let arr: ArrayVec<_, 10> = (0..100)
+    .filter(|x| x % 2 == 0)
+    .take(10)  // Important: don't exceed capacity
+    .collect();
+```
+
+## ArrayString for Stack Strings
+
+```rust
+use arrayvec::ArrayString;
+
+// Stack-allocated string with max capacity
+let mut s: ArrayString<64> = ArrayString::new();
+s.push_str("Hello, ");
+s.push_str("world!");
+
+// No heap allocation for small strings
+fn format_code(code: u32) -> ArrayString<16> {
+    let mut s = ArrayString::new();
+    write!(&mut s, "CODE-{:04}", code).unwrap();
+    s
+}
+```
+
+## When NOT to Use ArrayVec
+
+```rust
+// ❌ When size varies widely
+fn parse_json_array(json: &str) -> ArrayVec<Value, ???> {
+    // What capacity? JSON arrays can be any size
+}
+
+// ❌ When capacity is very large
+let big: ArrayVec<u8, 1_000_000> = ArrayVec::new();  // 1MB on stack = bad
+
+// ✅ Use SmallVec or Vec instead for these cases
+```
+
+## Cargo.toml
+
+```toml
+[dependencies]
+arrayvec = "0.7"
+```
+
+## See Also
+
+- [mem-smallvec](./mem-smallvec.md) - When heap fallback is acceptable
+- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocating Vec capacity
+- [own-move-large](./own-move-large.md) - Large stack types considerations

package/template/agent/skills/rust-developer/references/rust-rules/mem-assert-type-size.md

@@ -0,0 +1,168 @@
+# mem-assert-type-size
+
+> Use static assertions to guard against accidental type size growth
+
+## Why It Matters
+
+Adding a field to a frequently-instantiated struct can silently bloat memory usage. Static size assertions catch this at compile time, making size changes intentional rather than accidental. This is especially important for types stored in large collections or passed frequently by value.
+
+## Bad
+
+```rust
+struct Event {
+    timestamp: u64,
+    kind: EventKind,
+    payload: [u8; 32],
+}
+
+// Later, someone adds a field without realizing the impact
+struct Event {
+    timestamp: u64,
+    kind: EventKind,
+    payload: [u8; 32],
+    metadata: String,  // Silently adds 24 bytes!
+}
+
+// 10 million events now use 240MB more memory
+// No warning, no review trigger
+```
+
+## Good
+
+```rust
+struct Event {
+    timestamp: u64,
+    kind: EventKind,
+    payload: [u8; 32],
+}
+
+// Static assertion - breaks compile if size changes
+const _: () = assert!(std::mem::size_of::<Event>() == 48);
+
+// Or with static_assertions crate
+use static_assertions::assert_eq_size;
+assert_eq_size!(Event, [u8; 48]);
+
+// Now adding metadata triggers compile error:
+// error: assertion failed: std::mem::size_of::<Event>() == 48
+```
+
+## static_assertions Crate
+
+```rust
+use static_assertions::{assert_eq_size, const_assert};
+
+struct Critical {
+    id: u64,
+    flags: u32,
+    data: [u8; 16],
+}
+
+// Exact size assertion
+assert_eq_size!(Critical, [u8; 32]);
+
+// Maximum size assertion
+const_assert!(std::mem::size_of::<Critical>() <= 64);
+
+// Alignment assertion
+const_assert!(std::mem::align_of::<Critical>() == 8);
+
+// Compare sizes
+assert_eq_size!(Critical, [u64; 4]);
+```
+
+## Built-in Const Assertions
+
+```rust
+// No external crate needed (Rust 1.57+)
+struct Packet {
+    header: u32,
+    payload: [u8; 60],
+}
+
+const _: () = assert!(
+    std::mem::size_of::<Packet>() == 64,
+    "Packet must be exactly 64 bytes for protocol compliance"
+);
+
+// Compile error shows custom message if assertion fails
+```
+
+## Documenting Size Constraints
+
+```rust
+/// Network protocol packet header.
+/// 
+/// # Size
+/// 
+/// This struct is guaranteed to be exactly 32 bytes to match
+/// the network protocol specification. Any changes to fields
+/// must maintain this size constraint.
+#[repr(C)]  // Predictable layout for FFI
+struct Header {
+    version: u16,
+    flags: u16,
+    length: u32,
+    checksum: u64,
+    reserved: [u8; 16],
+}
+
+const _: () = assert!(std::mem::size_of::<Header>() == 32);
+```
+
+## Testing Size Stability
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    #[test]
+    fn critical_types_have_expected_sizes() {
+        // Document expected sizes in tests too
+        assert_eq!(std::mem::size_of::<Event>(), 48);
+        assert_eq!(std::mem::size_of::<Message>(), 64);
+        assert_eq!(std::mem::size_of::<Header>(), 32);
+    }
+    
+    #[test]
+    fn cache_line_aligned() {
+        // Verify cache-friendly sizing
+        assert!(std::mem::size_of::<HotData>() <= 64);
+    }
+}
+```
+
+## When to Assert
+
+```rust
+// ✅ Types stored in large collections
+struct Node { /* ... */ }
+const _: () = assert!(std::mem::size_of::<Node>() <= 64);
+
+// ✅ Types used in FFI / binary protocols
+#[repr(C)]
+struct WireFormat { /* ... */ }
+const _: () = assert!(std::mem::size_of::<WireFormat>() == 256);
+
+// ✅ Performance-critical types
+struct HotPath { /* ... */ }
+const _: () = assert!(std::mem::size_of::<HotPath>() <= 128);
+
+// ❌ Skip for rarely-instantiated types
+struct AppConfig { /* many fields */ }
+// Size doesn't matter, only one instance
+```
+
+## Cargo.toml
+
+```toml
+[dependencies]
+static_assertions = "1.1"
+```
+
+## See Also
+
+- [mem-smaller-integers](./mem-smaller-integers.md) - Choosing appropriate integer sizes
+- [mem-box-large-variant](./mem-box-large-variant.md) - Managing enum variant sizes
+- [opt-cache-friendly](./opt-cache-friendly.md) - Cache line considerations

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