agy-superpowers 5.2.1 → 5.2.3

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

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

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

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

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

package/template/agent/skills/rust-developer/references/rust-rules/perf-extend-batch.md

@@ -1,150 +0,0 @@
-# perf-extend-batch
-
-> Use extend for batch insertions
-
-## Why It Matters
-
-`extend()` can pre-allocate capacity for the incoming elements and insert them in a single operation. Individual `push()` calls may trigger multiple reallocations as the collection grows. For adding multiple elements, `extend()` is both faster and clearer.
-
-## Bad
-
-```rust
-// Multiple potential reallocations
-fn collect_results(sources: Vec<Source>) -> Vec<Result> {
-    let mut results = Vec::new();
-    
-    for source in sources {
-        for result in source.get_results() {
-            results.push(result);  // May reallocate
-        }
-    }
-    results
-}
-
-// Loop with push for known data
-fn build_list() -> Vec<i32> {
-    let mut list = Vec::new();
-    for i in 0..1000 {
-        list.push(i);  // Many reallocations
-    }
-    list
-}
-
-// Appending another collection
-fn combine(mut a: Vec<i32>, b: Vec<i32>) -> Vec<i32> {
-    for item in b {
-        a.push(item);
-    }
-    a
-}
-```
-
-## Good
-
-```rust
-// Single extend with size hint
-fn collect_results(sources: Vec<Source>) -> Vec<Result> {
-    let mut results = Vec::new();
-    
-    for source in sources {
-        results.extend(source.get_results());
-    }
-    results
-}
-
-// Direct collection from iterator
-fn build_list() -> Vec<i32> {
-    (0..1000).collect()
-}
-
-// Extend for combining
-fn combine(mut a: Vec<i32>, b: Vec<i32>) -> Vec<i32> {
-    a.extend(b);
-    a
-}
-```
-
-## Extend with Capacity
-
-For best performance, combine with `reserve()`:
-
-```rust
-fn merge_all(chunks: Vec<Vec<Item>>) -> Vec<Item> {
-    // Calculate total size
-    let total: usize = chunks.iter().map(|c| c.len()).sum();
-    
-    let mut result = Vec::with_capacity(total);
-    for chunk in chunks {
-        result.extend(chunk);
-    }
-    result
-}
-```
-
-## Extend Methods
-
-| Method | Description |
-|--------|-------------|
-| `.extend(iter)` | Add all elements from iterator |
-| `.extend_from_slice(&[T])` | Add from slice (for `Copy` types) |
-| `.append(&mut Vec)` | Move all from another Vec |
-
-## Pattern: Building Strings
-
-```rust
-// Bad: multiple allocations
-fn build_message(parts: &[&str]) -> String {
-    let mut result = String::new();
-    for part in parts {
-        result.push_str(part);  // May reallocate
-    }
-    result
-}
-
-// Good: extend with known parts
-fn build_message(parts: &[&str]) -> String {
-    let total_len: usize = parts.iter().map(|s| s.len()).sum();
-    let mut result = String::with_capacity(total_len);
-    for part in parts {
-        result.push_str(part);
-    }
-    result
-}
-
-// Better: collect/join
-fn build_message(parts: &[&str]) -> String {
-    parts.concat()  // or parts.join("")
-}
-```
-
-## HashMap/HashSet Extend
-
-```rust
-use std::collections::HashMap;
-
-// Extend from iterator of tuples
-fn merge_maps(mut base: HashMap<String, i32>, other: HashMap<String, i32>) -> HashMap<String, i32> {
-    base.extend(other);  // Moves entries from other
-    base
-}
-
-// Extend from iterator
-let mut set = HashSet::new();
-set.extend(items.iter().map(|i| i.id));
-```
-
-## Performance
-
-| Operation | Allocations | Complexity |
-|-----------|-------------|------------|
-| N × `push()` | O(log N) | O(N) amortized |
-| `extend(iter)` | O(1)* | O(N) |
-| `with_capacity` + `extend` | 1 | O(N) |
-
-*When iterator provides accurate `size_hint()`
-
-## See Also
-
-- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocation
-- [perf-drain-reuse](./perf-drain-reuse.md) - Reusing allocations
-- [mem-reuse-collections](./mem-reuse-collections.md) - Collection reuse