agy-superpowers 5.1.4 → 5.1.5

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

package/template/agent/skills/rust-developer/references/rust-rules/name-acronym-word.md

@@ -0,0 +1,99 @@
+# name-acronym-word
+
+> Treat acronyms as words in identifiers: `HttpServer`, not `HTTPServer`
+
+## Why It Matters
+
+When acronyms are written in ALL CAPS within identifiers, word boundaries become unclear: is `HTTPSHandler` "HTTPS Handler" or "HTTP SHandler"? Treating acronyms as words (`HttpsHandler`) maintains clear word boundaries and follows Rust convention. The standard library uses this consistently.
+
+## Bad
+
+```rust
+// ALL CAPS acronyms - unclear word boundaries
+struct HTTPServer { ... }      // HTTP + Server or H + TTP + Server?
+struct TCPIPConnection { ... } // TCP + IP? Or other splits?
+struct JSONParser { ... }
+struct XMLHTTPRequest { ... }  // Very confusing
+
+fn parseJSON(input: &str) { ... }
+fn connectTCP(addr: &str) { ... }
+```
+
+## Good
+
+```rust
+// Acronyms as words - clear boundaries
+struct HttpServer { ... }      // Http + Server
+struct TcpIpConnection { ... } // Tcp + Ip + Connection
+struct JsonParser { ... }
+struct XmlHttpRequest { ... }
+
+fn parse_json(input: &str) { ... }
+fn connect_tcp(addr: &str) { ... }
+
+// More examples
+struct Uuid { ... }            // Not UUID
+struct Uri { ... }             // Not URI
+struct Url { ... }             // Not URL
+struct Html { ... }            // Not HTML
+struct Css { ... }             // Not CSS
+struct Api { ... }             // Not API
+```
+
+## Standard Library Examples
+
+```rust
+// std uses acronyms as words
+std::net::TcpStream            // Not TCPStream
+std::net::TcpListener          // Not TCPListener
+std::net::UdpSocket            // Not UDPSocket
+std::net::IpAddr               // Not IPAddr
+std::io::IoError               // Not IOError (though Io is acceptable too)
+```
+
+## Two-Letter Acronyms
+
+```rust
+// Two-letter acronyms can go either way
+struct Io { ... }    // or IO - both acceptable
+struct Id { ... }    // or ID - both acceptable
+
+// Preference: treat as word for consistency
+struct IoHandler { ... }     // Preferred
+struct IdGenerator { ... }   // Preferred
+```
+
+## In snake_case
+
+```rust
+// Acronyms become lowercase in snake_case
+fn parse_json() { ... }
+fn connect_tcp() { ... }
+fn generate_uuid() { ... }
+fn fetch_http() { ... }
+fn encode_url() { ... }
+
+// Variables
+let json_response = fetch_json();
+let tcp_connection = connect_tcp();
+let user_id = generate_uuid();
+```
+
+## Mixed Cases
+
+```rust
+// When acronym is part of compound
+struct HttpsConnection { ... }   // Https (not HTTPS)
+struct Utf8String { ... }        // Utf8 (not UTF8)
+struct Base64Encoder { ... }     // Base64 as word
+
+// Multiple acronyms
+struct JsonApiClient { ... }     // Json + Api + Client
+struct RestApiHandler { ... }    // Rest + Api + Handler
+```
+
+## See Also
+
+- [name-types-camel](./name-types-camel.md) - Type naming conventions
+- [name-funcs-snake](./name-funcs-snake.md) - Function naming conventions
+- [name-consts-screaming](./name-consts-screaming.md) - Constant naming

package/template/agent/skills/rust-developer/references/rust-rules/name-as-free.md

@@ -0,0 +1,104 @@
+# name-as-free
+
+> `as_` prefix: free reference conversion
+
+## Why It Matters
+
+Consistent naming helps users understand API cost. `as_` prefix signals a free (O(1), no allocation) conversion that returns a reference. This convention is used throughout the standard library.
+
+## The Convention
+
+| Prefix | Cost | Ownership | Example |
+|--------|------|-----------|---------|
+| `as_` | Free | `&T -> &U` | `str::as_bytes()` |
+| `to_` | Expensive | `&T -> U` | `str::to_lowercase()` |
+| `into_` | Variable | `T -> U` | `String::into_bytes()` |
+
+## Examples
+
+```rust
+impl MyString {
+    // as_ - free reference conversion
+    pub fn as_str(&self) -> &str {
+        &self.inner
+    }
+    
+    pub fn as_bytes(&self) -> &[u8] {
+        self.inner.as_bytes()
+    }
+}
+
+impl Wrapper<T> {
+    // as_ - returns reference to inner
+    pub fn as_inner(&self) -> &T {
+        &self.inner
+    }
+    
+    pub fn as_inner_mut(&mut self) -> &mut T {
+        &mut self.inner
+    }
+}
+```
+
+## Standard Library Examples
+
+```rust
+// String
+let s = String::from("hello");
+let bytes: &[u8] = s.as_bytes();    // Free, returns &[u8]
+let str_ref: &str = s.as_str();     // Free, returns &str
+
+// Vec
+let v = vec![1, 2, 3];
+let slice: &[i32] = v.as_slice();   // Free, returns &[i32]
+
+// Path
+let p = PathBuf::from("/home");
+let path: &Path = p.as_path();      // Free, returns &Path
+
+// OsString
+let os = OsString::from("hello");
+let os_str: &OsStr = os.as_os_str(); // Free, returns &OsStr
+```
+
+## Bad
+
+```rust
+impl MyType {
+    // BAD: as_ but allocates
+    pub fn as_string(&self) -> String {
+        format!("{}", self.value)  // Allocates! Should be to_string()
+    }
+    
+    // BAD: as_ but expensive
+    pub fn as_processed(&self) -> &ProcessedData {
+        // Actually does expensive computation
+    }
+}
+```
+
+## Good
+
+```rust
+impl MyType {
+    // GOOD: Free reference
+    pub fn as_str(&self) -> &str {
+        &self.inner
+    }
+    
+    // GOOD: to_ signals allocation
+    pub fn to_string(&self) -> String {
+        format!("{}", self.value)
+    }
+    
+    // GOOD: into_ signals ownership transfer
+    pub fn into_inner(self) -> Inner {
+        self.inner
+    }
+}
+```
+
+## See Also
+
+- [name-to-expensive](name-to-expensive.md) - `to_` prefix for expensive conversions
+- [name-into-ownership](name-into-ownership.md) - `into_` prefix for ownership transfer