agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/perf-chain-avoid.md

@@ -0,0 +1,136 @@
+# perf-chain-avoid
+
+> Avoid chain in hot loops
+
+## Why It Matters
+
+`Iterator::chain()` adds overhead for checking which iterator is active on every `.next()` call. In hot loops, this branch prediction overhead can impact performance. For performance-critical code, prefer single iterators or pre-combined collections.
+
+## Bad
+
+```rust
+// Chain in hot inner loop
+fn process_hot_path(a: &[i32], b: &[i32]) -> i64 {
+    let mut sum = 0i64;
+    
+    // Called millions of times
+    for _ in 0..1_000_000 {
+        for x in a.iter().chain(b.iter()) {  // Branch every iteration
+            sum += *x as i64;
+        }
+    }
+    sum
+}
+
+// Chaining multiple small slices in tight loop
+fn combine_results(parts: &[&[u8]]) -> Vec<u8> {
+    let mut result = Vec::new();
+    for part in parts {
+        for byte in std::iter::once(&0u8).chain(part.iter()) {
+            result.push(*byte);
+        }
+    }
+    result
+}
+```
+
+## Good
+
+```rust
+// Separate loops - branch-free inner loops
+fn process_hot_path(a: &[i32], b: &[i32]) -> i64 {
+    let mut sum = 0i64;
+    
+    for _ in 0..1_000_000 {
+        for x in a {
+            sum += *x as i64;
+        }
+        for x in b {
+            sum += *x as i64;
+        }
+    }
+    sum
+}
+
+// Pre-combine outside hot loop
+fn combine_results(parts: &[&[u8]]) -> Vec<u8> {
+    let mut result = Vec::new();
+    for part in parts {
+        result.push(0u8);
+        result.extend_from_slice(part);
+    }
+    result
+}
+```
+
+## When Chain Is Fine
+
+Chain is perfectly acceptable when:
+
+```rust
+// One-time iteration, not in hot path
+fn collect_all(a: Vec<i32>, b: Vec<i32>) -> Vec<i32> {
+    a.into_iter().chain(b).collect()
+}
+
+// Lazy evaluation with short-circuit
+fn find_in_either(a: &[Item], b: &[Item], target: i32) -> Option<&Item> {
+    a.iter().chain(b.iter()).find(|x| x.id == target)
+}
+
+// Small number of elements
+fn get_prefixes() -> impl Iterator<Item = &'static str> {
+    ["Mr.", "Mrs.", "Dr."].iter().copied()
+        .chain(["Prof."].iter().copied())
+}
+```
+
+## Alternative Patterns
+
+### Pre-allocate and Extend
+
+```rust
+fn merge_slices(slices: &[&[i32]]) -> Vec<i32> {
+    let total: usize = slices.iter().map(|s| s.len()).sum();
+    let mut result = Vec::with_capacity(total);
+    for slice in slices {
+        result.extend_from_slice(slice);
+    }
+    result
+}
+```
+
+### Use append for Vecs
+
+```rust
+fn combine_vecs(mut a: Vec<i32>, mut b: Vec<i32>) -> Vec<i32> {
+    a.append(&mut b);  // Moves elements, no reallocation if a has capacity
+    a
+}
+```
+
+### Flatten Instead of Chain
+
+```rust
+// Instead of: a.iter().chain(b.iter()).chain(c.iter())
+let all = [a, b, c];
+for item in all.iter().flat_map(|slice| slice.iter()) {
+    process(item);
+}
+```
+
+## Performance Impact
+
+| Pattern | Per-Item Overhead |
+|---------|-------------------|
+| Single iterator | None |
+| `chain(a, b)` | 1 branch per item |
+| `chain(a, b, c)` | 2 branches per item |
+| Nested chains | Compounds |
+| Separate loops | None (but code duplication) |
+
+## See Also
+
+- [perf-iter-over-index](./perf-iter-over-index.md) - Prefer iterators
+- [perf-extend-batch](./perf-extend-batch.md) - Batch insertions
+- [opt-cache-friendly](./opt-cache-friendly.md) - Cache-friendly patterns

package/template/agent/skills/rust-developer/references/rust-rules/perf-collect-into.md

@@ -0,0 +1,133 @@
+# perf-collect-into
+
+> Use collect_into for reusing containers
+
+## Why It Matters
+
+`collect_into()` (stabilized in Rust 1.83) allows collecting iterator results into an existing collection, reusing its allocation. This avoids the allocation that `collect()` would make for a new collection.
+
+## Bad
+
+```rust
+// Allocates new Vec each time
+fn process_batches(batches: Vec<Vec<i32>>) -> Vec<Vec<i32>> {
+    batches.into_iter()
+        .map(|batch| {
+            batch.into_iter()
+                .filter(|x| *x > 0)
+                .collect::<Vec<_>>()  // New allocation per batch
+        })
+        .collect()
+}
+
+// Can't reuse cleared buffer
+fn filter_loop(data: &[Vec<i32>]) {
+    for batch in data {
+        let filtered: Vec<_> = batch.iter()
+            .filter(|&&x| x > 0)
+            .copied()
+            .collect();  // New allocation each iteration
+        process(&filtered);
+    }
+}
+```
+
+## Good
+
+```rust
+// Reuse buffer with collect_into
+fn filter_loop(data: &[Vec<i32>]) {
+    let mut buffer = Vec::new();
+    
+    for batch in data {
+        buffer.clear();  // Keep allocation
+        batch.iter()
+            .filter(|&&x| x > 0)
+            .copied()
+            .collect_into(&mut buffer);
+        process(&buffer);
+    }
+}
+
+// Also works with extend pattern
+fn filter_loop_extend(data: &[Vec<i32>]) {
+    let mut buffer = Vec::new();
+    
+    for batch in data {
+        buffer.clear();
+        buffer.extend(
+            batch.iter()
+                .filter(|&&x| x > 0)
+                .copied()
+        );
+        process(&buffer);
+    }
+}
+```
+
+## Pre-1.83 Alternative: extend
+
+Before `collect_into()` was stabilized, use `extend()`:
+
+```rust
+fn reuse_buffer(data: &[Vec<i32>]) {
+    let mut buffer = Vec::new();
+    
+    for batch in data {
+        buffer.clear();
+        buffer.extend(batch.iter().filter(|&&x| x > 0).copied());
+        process(&buffer);
+    }
+}
+```
+
+## Pattern: Transform and Reuse
+
+```rust
+fn transform_batches(batches: &[Vec<RawData>]) -> Vec<ProcessedData> {
+    let mut temp = Vec::new();
+    let mut all_results = Vec::new();
+    
+    for batch in batches {
+        temp.clear();
+        batch.iter()
+            .map(ProcessedData::from)
+            .collect_into(&mut temp);
+        
+        // Process temp, append to results
+        all_results.extend(temp.drain(..).filter(|p| p.is_valid()));
+    }
+    
+    all_results
+}
+```
+
+## Supported Collections
+
+`collect_into()` works with any type implementing `Extend`:
+
+```rust
+use std::collections::{HashSet, HashMap, VecDeque};
+
+let mut vec = Vec::new();
+let mut set = HashSet::new();
+let mut deque = VecDeque::new();
+
+(0..10).collect_into(&mut vec);
+(0..10).collect_into(&mut set);
+(0..10).collect_into(&mut deque);
+```
+
+## Comparison
+
+| Method | Allocation | Buffer Reuse |
+|--------|------------|--------------|
+| `.collect()` | New each time | No |
+| `.collect_into(&mut buf)` | Reuses buffer | Yes |
+| `buf.extend(iter)` | Reuses buffer | Yes |
+
+## See Also
+
+- [perf-drain-reuse](./perf-drain-reuse.md) - Drain for reuse
+- [mem-reuse-collections](./mem-reuse-collections.md) - Collection reuse
+- [perf-extend-batch](./perf-extend-batch.md) - Batch extensions

package/template/agent/skills/rust-developer/references/rust-rules/perf-collect-once.md

@@ -0,0 +1,120 @@
+# perf-collect-once
+
+> Don't collect intermediate iterators
+
+## Why It Matters
+
+Each `.collect()` allocates a new collection. Chaining multiple operations with intermediate collections wastes memory and CPU cycles. Keep iterator chains lazy and collect only once at the end.
+
+## Bad
+
+```rust
+// Three allocations, three passes
+fn process_users(users: Vec<User>) -> Vec<String> {
+    let active: Vec<_> = users.into_iter()
+        .filter(|u| u.is_active)
+        .collect();
+    
+    let verified: Vec<_> = active.into_iter()
+        .filter(|u| u.is_verified)
+        .collect();
+    
+    verified.into_iter()
+        .map(|u| u.name)
+        .collect()
+}
+
+// Collecting to count
+fn count_valid(items: &[Item]) -> usize {
+    items.iter()
+        .filter(|i| i.is_valid())
+        .collect::<Vec<_>>()  // Unnecessary!
+        .len()
+}
+```
+
+## Good
+
+```rust
+// One allocation, one pass
+fn process_users(users: Vec<User>) -> Vec<String> {
+    users.into_iter()
+        .filter(|u| u.is_active)
+        .filter(|u| u.is_verified)
+        .map(|u| u.name)
+        .collect()
+}
+
+// No allocation needed
+fn count_valid(items: &[Item]) -> usize {
+    items.iter()
+        .filter(|i| i.is_valid())
+        .count()
+}
+```
+
+## Pattern: Deferred Collection
+
+```rust
+// Create the iterator chain
+fn prepare_data(raw: Vec<RawData>) -> impl Iterator<Item = ProcessedData> {
+    raw.into_iter()
+        .filter(|d| d.is_valid())
+        .map(ProcessedData::from)
+}
+
+// Collect only when needed
+let data: Vec<_> = prepare_data(input).collect();
+
+// Or consume without collecting
+prepare_data(input).for_each(|d| process(d));
+```
+
+## When Intermediate Collection Is Needed
+
+```rust
+// Need to iterate multiple times
+let items: Vec<_> = data.iter()
+    .filter(|x| x.is_valid())
+    .collect();
+
+let count = items.len();
+let first = items.first();
+for item in &items {
+    process(item);
+}
+
+// Need to sort (requires concrete collection)
+let mut sorted: Vec<_> = data.iter()
+    .filter(|x| x.is_active)
+    .collect();
+sorted.sort_by_key(|x| x.priority);
+```
+
+## Comparison
+
+| Approach | Allocations | Passes | Memory |
+|----------|-------------|--------|--------|
+| Multiple `.collect()` | N | N | O(N × data) |
+| Single chain + `.collect()` | 1 | 1 | O(data) |
+| No `.collect()` (streaming) | 0 | 1 | O(1) |
+
+## Pattern: Collect with Capacity
+
+When you must collect, pre-allocate:
+
+```rust
+// With estimated capacity
+let mut result = Vec::with_capacity(items.len());
+result.extend(
+    items.iter()
+        .filter(|x| x.is_valid())
+        .map(|x| x.clone())
+);
+```
+
+## See Also
+
+- [perf-iter-lazy](./perf-iter-lazy.md) - Keep iterators lazy
+- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocate collections
+- [anti-collect-intermediate](./anti-collect-intermediate.md) - Anti-pattern

package/template/agent/skills/rust-developer/references/rust-rules/perf-drain-reuse.md

@@ -0,0 +1,137 @@
+# perf-drain-reuse
+
+> Use drain to reuse allocations
+
+## Why It Matters
+
+`drain()` removes elements from a collection while keeping its allocated capacity. This allows reusing the same allocation across iterations, avoiding repeated allocate/deallocate cycles in loops.
+
+## Bad
+
+```rust
+// Allocates new Vec every iteration
+fn process_batches(data: Vec<Item>) {
+    let mut remaining = data;
+    
+    while !remaining.is_empty() {
+        let batch: Vec<_> = remaining.drain(..100.min(remaining.len())).collect();
+        process_batch(batch);
+        // remaining keeps its capacity - good
+        // but batch allocates new every time - bad
+    }
+}
+
+// Clears and reallocates
+fn reuse_buffer() {
+    for _ in 0..1000 {
+        let mut buffer = Vec::new();  // Allocates each iteration
+        fill_buffer(&mut buffer);
+        process(&buffer);
+    }
+}
+```
+
+## Good
+
+```rust
+// Reuses allocation with drain
+fn process_batches(mut data: Vec<Item>) {
+    let mut batch = Vec::with_capacity(100);
+    
+    while !data.is_empty() {
+        batch.extend(data.drain(..100.min(data.len())));
+        process_batch(&batch);
+        batch.clear();  // Keeps capacity
+    }
+}
+
+// Reuses buffer across iterations
+fn reuse_buffer() {
+    let mut buffer = Vec::new();
+    
+    for _ in 0..1000 {
+        buffer.clear();  // Keeps capacity
+        fill_buffer(&mut buffer);
+        process(&buffer);
+    }
+}
+```
+
+## Drain Methods
+
+| Collection | Method | Behavior |
+|------------|--------|----------|
+| `Vec<T>` | `.drain(range)` | Remove range, shift remaining |
+| `Vec<T>` | `.drain(..)` | Remove all (like clear) |
+| `VecDeque<T>` | `.drain(range)` | Remove range |
+| `String` | `.drain(range)` | Remove char range |
+| `HashMap<K,V>` | `.drain()` | Remove all entries |
+| `HashSet<T>` | `.drain()` | Remove all elements |
+
+## Pattern: Batch Processing
+
+```rust
+fn process_in_chunks(mut items: Vec<Item>, chunk_size: usize) {
+    while !items.is_empty() {
+        let chunk: Vec<_> = items.drain(..chunk_size.min(items.len())).collect();
+        process_chunk(chunk);
+    }
+}
+```
+
+## Pattern: Transfer Between Collections
+
+```rust
+// Move all elements without reallocation
+fn transfer_all(src: &mut Vec<Item>, dst: &mut Vec<Item>) {
+    dst.extend(src.drain(..));
+    // src is now empty but keeps capacity
+}
+
+// Move matching elements
+fn transfer_matching(src: &mut Vec<Item>, dst: &mut Vec<Item>, predicate: impl Fn(&Item) -> bool) {
+    let matching: Vec<_> = src.drain(..).filter(predicate).collect();
+    dst.extend(matching);
+}
+```
+
+## Pattern: HashMap Drain
+
+```rust
+use std::collections::HashMap;
+
+fn process_and_clear(map: &mut HashMap<String, Value>) {
+    // Process all entries, clearing the map
+    for (key, value) in map.drain() {
+        process(key, value);
+    }
+    // map is now empty but keeps capacity
+}
+```
+
+## drain vs clear vs take
+
+| Operation | Elements | Capacity | Returns |
+|-----------|----------|----------|---------|
+| `.clear()` | Removed | Kept | Nothing |
+| `.drain(..)` | Removed | Kept | Iterator |
+| `std::mem::take()` | Moved out | Reset to 0 | Owned collection |
+
+```rust
+// clear: just empty
+vec.clear();
+
+// drain: empty and iterate
+for item in vec.drain(..) {
+    process(item);
+}
+
+// take: swap with empty, get ownership
+let old_vec = std::mem::take(&mut vec);
+```
+
+## See Also
+
+- [mem-reuse-collections](./mem-reuse-collections.md) - Reusing collections
+- [perf-extend-batch](./perf-extend-batch.md) - Batch insertions
+- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocation

package/template/agent/skills/rust-developer/references/rust-rules/perf-entry-api.md

@@ -0,0 +1,134 @@
+# perf-entry-api
+
+> Use entry API for map insert-or-update
+
+## Why It Matters
+
+The entry API performs a single lookup for insert-or-update operations. Without it, you lookup twice: once to check existence, once to insert. For `HashMap` and `BTreeMap`, the entry API is both faster and more idiomatic.
+
+## Bad
+
+```rust
+use std::collections::HashMap;
+
+// Double lookup: contains_key + insert
+fn increment(map: &mut HashMap<String, u32>, key: String) {
+    if map.contains_key(&key) {
+        *map.get_mut(&key).unwrap() += 1;
+    } else {
+        map.insert(key, 1);
+    }
+}
+
+// Double lookup with get + insert
+fn get_or_insert(map: &mut HashMap<String, Vec<i32>>, key: String) -> &mut Vec<i32> {
+    if !map.contains_key(&key) {
+        map.insert(key.clone(), Vec::new());
+    }
+    map.get_mut(&key).unwrap()
+}
+
+// Triple lookup pattern
+fn update_or_default(map: &mut HashMap<String, Config>, key: &str, value: i32) {
+    match map.get(key) {
+        Some(config) => {
+            let mut new_config = config.clone();
+            new_config.value = value;
+            map.insert(key.to_string(), new_config);
+        }
+        None => {
+            map.insert(key.to_string(), Config::default());
+        }
+    }
+}
+```
+
+## Good
+
+```rust
+use std::collections::HashMap;
+use std::collections::hash_map::Entry;
+
+// Single lookup with entry
+fn increment(map: &mut HashMap<String, u32>, key: String) {
+    *map.entry(key).or_insert(0) += 1;
+}
+
+// Single lookup, returns mutable reference
+fn get_or_insert(map: &mut HashMap<String, Vec<i32>>, key: String) -> &mut Vec<i32> {
+    map.entry(key).or_insert_with(Vec::new)
+}
+
+// Single lookup with and_modify
+fn update_or_default(map: &mut HashMap<String, Config>, key: String, value: i32) {
+    map.entry(key)
+        .and_modify(|config| config.value = value)
+        .or_insert_with(Config::default);
+}
+```
+
+## Entry API Methods
+
+| Method | Behavior |
+|--------|----------|
+| `.or_insert(val)` | Insert `val` if empty |
+| `.or_insert_with(f)` | Insert `f()` if empty (lazy) |
+| `.or_default()` | Insert `Default::default()` if empty |
+| `.and_modify(f)` | Apply `f` if occupied |
+| `.or_insert_with_key(f)` | Insert `f(&key)` if empty |
+
+## Pattern: Count Occurrences
+
+```rust
+fn word_count(text: &str) -> HashMap<&str, usize> {
+    let mut counts = HashMap::new();
+    for word in text.split_whitespace() {
+        *counts.entry(word).or_insert(0) += 1;
+    }
+    counts
+}
+```
+
+## Pattern: Group By
+
+```rust
+fn group_by_category(items: Vec<Item>) -> HashMap<Category, Vec<Item>> {
+    let mut groups: HashMap<Category, Vec<Item>> = HashMap::new();
+    for item in items {
+        groups.entry(item.category.clone())
+            .or_default()
+            .push(item);
+    }
+    groups
+}
+```
+
+## Pattern: Complex Entry Logic
+
+```rust
+match map.entry(key) {
+    Entry::Occupied(mut entry) => {
+        let value = entry.get_mut();
+        if should_update(value) {
+            *value = new_value;
+        }
+    }
+    Entry::Vacant(entry) => {
+        entry.insert(default_value);
+    }
+}
+```
+
+## Performance
+
+| Pattern | Lookups | Hash Computations |
+|---------|---------|-------------------|
+| `contains_key` + `insert` | 2 | 2 |
+| `get` + `insert` | 2 | 2 |
+| `entry().or_insert()` | 1 | 1 |
+
+## See Also
+
+- [perf-extend-batch](./perf-extend-batch.md) - Batch insertions
+- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocate maps
+- [perf-drain-reuse](./perf-drain-reuse.md) - Reuse map allocations