agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/name-iter-method.md

@@ -0,0 +1,131 @@
+# name-iter-method
+
+> Name iterator methods `iter()`, `iter_mut()`, and `into_iter()` consistently
+
+## Why It Matters
+
+Rust has a strong convention for iterator method names. Following these conventions makes your types work predictably with `for` loops and iterator adapters. Users expect `iter()` for shared references, `iter_mut()` for mutable references, and `into_iter()` for owned iteration.
+
+## Bad
+
+```rust
+struct Collection<T> {
+    items: Vec<T>,
+}
+
+impl<T> Collection<T> {
+    // Non-standard names - confusing
+    fn elements(&self) -> impl Iterator<Item = &T> {
+        self.items.iter()
+    }
+    
+    fn get_iterator(&self) -> impl Iterator<Item = &T> {
+        self.items.iter()
+    }
+    
+    fn to_iter(self) -> impl Iterator<Item = T> {
+        self.items.into_iter()
+    }
+}
+```
+
+## Good
+
+```rust
+struct Collection<T> {
+    items: Vec<T>,
+}
+
+impl<T> Collection<T> {
+    /// Returns an iterator over references.
+    fn iter(&self) -> impl Iterator<Item = &T> {
+        self.items.iter()
+    }
+    
+    /// Returns an iterator over mutable references.
+    fn iter_mut(&mut self) -> impl Iterator<Item = &mut T> {
+        self.items.iter_mut()
+    }
+}
+
+// Implement IntoIterator for for-loop support
+impl<T> IntoIterator for Collection<T> {
+    type Item = T;
+    type IntoIter = std::vec::IntoIter<T>;
+    
+    fn into_iter(self) -> Self::IntoIter {
+        self.items.into_iter()
+    }
+}
+
+impl<'a, T> IntoIterator for &'a Collection<T> {
+    type Item = &'a T;
+    type IntoIter = std::slice::Iter<'a, T>;
+    
+    fn into_iter(self) -> Self::IntoIter {
+        self.items.iter()
+    }
+}
+
+impl<'a, T> IntoIterator for &'a mut Collection<T> {
+    type Item = &'a mut T;
+    type IntoIter = std::slice::IterMut<'a, T>;
+    
+    fn into_iter(self) -> Self::IntoIter {
+        self.items.iter_mut()
+    }
+}
+```
+
+## Iterator Convention Summary
+
+| Method | Receiver | Yields | Use Case |
+|--------|----------|--------|----------|
+| `iter()` | `&self` | `&T` | Read-only iteration |
+| `iter_mut()` | `&mut self` | `&mut T` | In-place modification |
+| `into_iter()` | `self` | `T` | Consuming iteration |
+
+## For Loop Integration
+
+```rust
+let col = Collection { items: vec![1, 2, 3] };
+
+// These all work with proper IntoIterator impls
+for item in &col {           // Calls (&col).into_iter() -> iter()
+    println!("{}", item);    // &i32
+}
+
+for item in &mut col {       // Calls (&mut col).into_iter() -> iter_mut()
+    *item += 1;              // &mut i32
+}
+
+for item in col {            // Calls col.into_iter()
+    process(item);           // i32, consumes col
+}
+```
+
+## Additional Iterator Methods
+
+```rust
+impl<T> Collection<T> {
+    // Domain-specific iterators follow similar patterns
+    
+    /// Iterates over keys (for map-like structures).
+    fn keys(&self) -> impl Iterator<Item = &K> { ... }
+    
+    /// Iterates over values.
+    fn values(&self) -> impl Iterator<Item = &V> { ... }
+    
+    /// Iterates over mutable values.
+    fn values_mut(&mut self) -> impl Iterator<Item = &mut V> { ... }
+    
+    /// Drains elements, leaving container empty.
+    fn drain(&mut self) -> impl Iterator<Item = T> { ... }
+}
+```
+
+## See Also
+
+- [name-as-free](./name-as-free.md) - Conversion naming conventions
+- [api-extension-trait](./api-extension-trait.md) - Iterator extensions
+- [api-common-traits](./api-common-traits.md) - Standard trait implementations

package/template/agent/skills/rust-developer/references/rust-rules/name-iter-type-match.md

@@ -0,0 +1,142 @@
+# name-iter-type-match
+
+> Name iterator types after their source method
+
+## Why It Matters
+
+Iterator types should match the method that creates them. `iter()` returns `Iter`, `into_iter()` returns `IntoIter`, `keys()` returns `Keys`. This naming pattern is established by the standard library and makes types predictable.
+
+## Standard Library Pattern
+
+```rust
+// Vec
+impl<T> Vec<T> {
+    fn iter(&self) -> Iter<'_, T> { }       // Returns Iter
+    fn iter_mut(&mut self) -> IterMut<'_, T> { }  // Returns IterMut
+}
+
+impl<T> IntoIterator for Vec<T> {
+    type IntoIter = IntoIter<T>;  // Returns IntoIter
+}
+
+// HashMap
+impl<K, V> HashMap<K, V> {
+    fn iter(&self) -> Iter<'_, K, V> { }
+    fn keys(&self) -> Keys<'_, K, V> { }    // Returns Keys
+    fn values(&self) -> Values<'_, K, V> { }  // Returns Values
+    fn drain(&mut self) -> Drain<'_, K, V> { }  // Returns Drain
+}
+```
+
+## Implementation
+
+```rust
+mod my_collection {
+    pub struct MyCollection<T> {
+        items: Vec<T>,
+    }
+    
+    // Iterator types in same module
+    pub struct Iter<'a, T> {
+        inner: std::slice::Iter<'a, T>,
+    }
+    
+    pub struct IterMut<'a, T> {
+        inner: std::slice::IterMut<'a, T>,
+    }
+    
+    pub struct IntoIter<T> {
+        inner: std::vec::IntoIter<T>,
+    }
+    
+    impl<T> MyCollection<T> {
+        pub fn iter(&self) -> Iter<'_, T> {
+            Iter { inner: self.items.iter() }
+        }
+        
+        pub fn iter_mut(&mut self) -> IterMut<'_, T> {
+            IterMut { inner: self.items.iter_mut() }
+        }
+    }
+    
+    impl<T> IntoIterator for MyCollection<T> {
+        type Item = T;
+        type IntoIter = IntoIter<T>;
+        
+        fn into_iter(self) -> IntoIter<T> {
+            IntoIter { inner: self.items.into_iter() }
+        }
+    }
+    
+    // Implement Iterator for each type
+    impl<'a, T> Iterator for Iter<'a, T> {
+        type Item = &'a T;
+        fn next(&mut self) -> Option<Self::Item> {
+            self.inner.next()
+        }
+    }
+    
+    impl<'a, T> Iterator for IterMut<'a, T> {
+        type Item = &'a mut T;
+        fn next(&mut self) -> Option<Self::Item> {
+            self.inner.next()
+        }
+    }
+    
+    impl<T> Iterator for IntoIter<T> {
+        type Item = T;
+        fn next(&mut self) -> Option<Self::Item> {
+            self.inner.next()
+        }
+    }
+}
+```
+
+## Naming Convention
+
+| Method | Iterator Type |
+|--------|---------------|
+| `iter()` | `Iter` |
+| `iter_mut()` | `IterMut` |
+| `into_iter()` | `IntoIter` |
+| `keys()` | `Keys` |
+| `values()` | `Values` |
+| `values_mut()` | `ValuesMut` |
+| `drain()` | `Drain` |
+| `chunks()` | `Chunks` |
+| `windows()` | `Windows` |
+
+## Custom Iterator Methods
+
+```rust
+impl Graph {
+    // Method name -> Type name
+    fn nodes(&self) -> Nodes<'_> { }        // Custom: Nodes
+    fn edges(&self) -> Edges<'_> { }        // Custom: Edges
+    fn neighbors(&self, node: NodeId) -> Neighbors<'_> { }  // Custom: Neighbors
+}
+
+pub struct Nodes<'a> { /* ... */ }
+pub struct Edges<'a> { /* ... */ }
+pub struct Neighbors<'a> { /* ... */ }
+```
+
+## Bad
+
+```rust
+// Mismatched names
+impl MyCollection<T> {
+    fn iter(&self) -> MyCollectionIterator<'_, T> { }  // Should be Iter
+    fn keys(&self) -> KeyIterator<'_, K> { }           // Should be Keys
+}
+
+// Generic names that don't match method
+pub struct Iterator<T>;  // Conflicts with std::iter::Iterator
+pub struct I<T>;         // Too cryptic
+```
+
+## See Also
+
+- [name-iter-convention](./name-iter-convention.md) - iter/iter_mut/into_iter
+- [name-iter-method](./name-iter-method.md) - Iterator method names
+- [api-common-traits](./api-common-traits.md) - Implementing common traits

package/template/agent/skills/rust-developer/references/rust-rules/name-lifetime-short.md

@@ -0,0 +1,86 @@
+# name-lifetime-short
+
+> Use short, conventional lifetime names: `'a`, `'b`, `'de`, `'src`
+
+## Why It Matters
+
+Lifetime parameters are ubiquitous in Rust signatures. Short names like `'a` keep signatures readable. For domain-specific lifetimes, descriptive but short names like `'src` or `'de` communicate intent without clutter. The Rust community has established conventions that aid recognition.
+
+## Bad
+
+```rust
+// Overly verbose lifetimes
+fn parse<'input_lifetime, 'output_lifetime>(
+    input: &'input_lifetime str
+) -> Result<&'output_lifetime str, Error> { ... }
+
+// Meaningless long names
+struct Parser<'parser_instance_lifetime> {
+    source: &'parser_instance_lifetime str,
+}
+```
+
+## Good
+
+```rust
+// Standard short lifetimes
+fn parse<'a>(input: &'a str) -> Result<&'a str, Error> { ... }
+
+struct Parser<'a> {
+    source: &'a str,
+}
+
+// Multiple lifetimes: 'a, 'b, 'c
+fn merge<'a, 'b>(first: &'a str, second: &'b str) -> String { ... }
+
+// Descriptive when clarity helps
+fn deserialize<'de>(input: &'de [u8]) -> Result<Value<'de>, Error> { ... }
+```
+
+## Common Lifetime Conventions
+
+| Lifetime | Convention | Example |
+|----------|------------|---------|
+| `'a` | Generic, first lifetime | `fn foo<'a>(x: &'a str)` |
+| `'b` | Generic, second lifetime | `fn bar<'a, 'b>(x: &'a T, y: &'b U)` |
+| `'de` | Deserialization | serde's `Deserialize<'de>` |
+| `'src` | Source code/input | `struct Lexer<'src>` |
+| `'ctx` | Context | `struct Query<'ctx>` |
+| `'input` | Input data | `struct Parser<'input>` |
+| `'static` | Static lifetime | `&'static str` |
+
+## Elision Preferred
+
+```rust
+// Let elision work when possible
+fn first_word(s: &str) -> &str {  // Not fn first_word<'a>(s: &'a str) -> &'a str
+    s.split_whitespace().next().unwrap_or("")
+}
+
+impl User {
+    fn name(&self) -> &str {  // Elision handles this
+        &self.name
+    }
+}
+```
+
+## Serde Convention
+
+```rust
+use serde::{Deserialize, Serialize};
+
+// 'de is the standard serde lifetime for borrowed data
+#[derive(Deserialize)]
+struct Request<'de> {
+    #[serde(borrow)]
+    name: &'de str,
+    #[serde(borrow)]
+    tags: Vec<&'de str>,
+}
+```
+
+## See Also
+
+- [own-lifetime-elision](./own-lifetime-elision.md) - When to omit lifetimes
+- [name-type-param-single](./name-type-param-single.md) - Type parameter naming
+- [own-borrow-over-clone](./own-borrow-over-clone.md) - Borrowing patterns

package/template/agent/skills/rust-developer/references/rust-rules/name-no-get-prefix.md

@@ -0,0 +1,154 @@
+# name-no-get-prefix
+
+> Omit get_ prefix for simple getters
+
+## Why It Matters
+
+Rust convention omits the `get_` prefix for simple field access. Methods like `len()`, `name()`, `value()` are cleaner than `get_len()`, `get_name()`, `get_value()`. This follows the principle of making the common case concise.
+
+The `get` prefix is reserved for methods that DO something beyond simple field access.
+
+## Bad
+
+```rust
+struct User {
+    name: String,
+    age: u32,
+}
+
+impl User {
+    fn get_name(&self) -> &str {      // Verbose
+        &self.name
+    }
+    
+    fn get_age(&self) -> u32 {         // Verbose
+        self.age
+    }
+    
+    fn get_is_adult(&self) -> bool {   // Doubly verbose
+        self.age >= 18
+    }
+}
+
+let name = user.get_name();
+let age = user.get_age();
+```
+
+## Good
+
+```rust
+struct User {
+    name: String,
+    age: u32,
+}
+
+impl User {
+    fn name(&self) -> &str {           // Clean
+        &self.name
+    }
+    
+    fn age(&self) -> u32 {             // Clean
+        self.age
+    }
+    
+    fn is_adult(&self) -> bool {       // Boolean uses is_ prefix
+        self.age >= 18
+    }
+}
+
+let name = user.name();
+let age = user.age();
+```
+
+## When get_ IS Appropriate
+
+Use `get` when the method does more than simple access:
+
+```rust
+impl HashMap<K, V> {
+    // Returns Option - not just field access
+    fn get(&self, key: &K) -> Option<&V> { }
+    
+    // Mutable variant
+    fn get_mut(&mut self, key: &K) -> Option<&mut V> { }
+}
+
+impl Vec<T> {
+    // Returns Option - bounds checked
+    fn get(&self, index: usize) -> Option<&T> { }
+}
+
+impl Context {
+    // Does computation/lookup, not just field access
+    fn get_config(&self) -> Config {
+        self.configs.get(&self.current_env).cloned().unwrap_or_default()
+    }
+}
+```
+
+## Standard Library Examples
+
+```rust
+// No get_ prefix
+String::len()
+Vec::len()
+Vec::capacity()
+Vec::is_empty()
+Path::file_name()
+Option::is_some()
+Result::is_ok()
+
+// With get - returns Option or does lookup
+Vec::get(index)
+HashMap::get(key)
+BTreeMap::get(key)
+```
+
+## Pattern: Getter/Setter Pairs
+
+```rust
+impl Config {
+    // Getter: no prefix
+    fn timeout(&self) -> Duration {
+        self.timeout
+    }
+    
+    // Setter: use set_ prefix
+    fn set_timeout(&mut self, timeout: Duration) {
+        self.timeout = timeout;
+    }
+}
+```
+
+## Pattern: Builder Methods
+
+```rust
+impl ConfigBuilder {
+    // Builder methods: no get_, no set_
+    fn timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
+    
+    fn retries(mut self, retries: u32) -> Self {
+        self.retries = retries;
+        self
+    }
+}
+```
+
+## Decision Guide
+
+| Pattern | Naming |
+|---------|--------|
+| Simple field access | `name()`, `value()`, `len()` |
+| Boolean property | `is_valid()`, `has_items()` |
+| Fallible access | `get()`, `get_mut()` |
+| Setter | `set_name()`, `set_value()` |
+| Builder | `name()`, `value()` (consuming self) |
+
+## See Also
+
+- [name-is-has-bool](./name-is-has-bool.md) - Boolean naming
+- [name-is-has-bool](./name-is-has-bool.md) - Boolean naming
+- [api-builder-pattern](./api-builder-pattern.md) - Builder pattern

package/template/agent/skills/rust-developer/references/rust-rules/name-to-expensive.md

@@ -0,0 +1,118 @@
+# name-to-expensive
+
+> Use `to_` prefix for expensive conversions that allocate or compute
+
+## Why It Matters
+
+The `to_` prefix signals "this conversion has a cost"—typically allocation, cloning, or computation. Callers know to consider caching the result or avoiding repeated calls. This contrasts with `as_` (free reference conversion) and `into_` (ownership transfer).
+
+## Bad
+
+```rust
+impl Name {
+    // Misleading: suggests expensive operation
+    fn as_uppercase(&self) -> String {
+        self.0.to_uppercase()  // Allocates!
+    }
+    
+    // Misleading: suggests cheap reference
+    fn get_string(&self) -> String {
+        self.0.clone()  // Allocates!
+    }
+}
+```
+
+## Good
+
+```rust
+impl Name {
+    // to_ = allocates/computes
+    fn to_uppercase(&self) -> String {
+        self.0.to_uppercase()
+    }
+    
+    // to_ = creates new value
+    fn to_string(&self) -> String {
+        self.0.clone()
+    }
+    
+    // as_ = free reference (cheap)
+    fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+```
+
+## Standard Library Examples
+
+```rust
+// to_ methods - all allocate or compute
+let s: String = slice.to_vec();           // Allocates Vec
+let s: String = "hello".to_string();      // Allocates String
+let s: String = "HELLO".to_lowercase();   // Allocates new String
+let s: String = path.to_string_lossy().into_owned();  // May allocate
+
+// Contrast with as_ methods - all are free
+let slice: &[u8] = s.as_bytes();          // Just reinterpret
+let str_ref: &str = string.as_str();      // Just reference
+let path: &Path = Path::new("foo");       // Just reference
+```
+
+## Conversion Method Prefixes
+
+| Prefix | Cost | Ownership | Example |
+|--------|------|-----------|---------|
+| `as_` | Free (O(1)) | Borrows `&T` | `as_str()`, `as_bytes()` |
+| `to_` | Allocates/Computes | Creates new | `to_string()`, `to_vec()` |
+| `into_` | Usually free | Takes ownership | `into_inner()`, `into_vec()` |
+
+## Custom Types
+
+```rust
+struct Email(String);
+
+impl Email {
+    // Cheap: just returns reference
+    fn as_str(&self) -> &str {
+        &self.0
+    }
+    
+    // Expensive: allocates
+    fn to_lowercase(&self) -> Email {
+        Email(self.0.to_lowercase())
+    }
+    
+    // Expensive: allocates
+    fn to_display_format(&self) -> String {
+        format!("<{}>", self.0)
+    }
+    
+    // Ownership transfer: usually cheap
+    fn into_string(self) -> String {
+        self.0
+    }
+}
+```
+
+## to_owned() Pattern
+
+```rust
+// to_owned() for getting owned version of borrowed data
+let borrowed: &str = "hello";
+let owned: String = borrowed.to_owned();  // Allocates
+
+let borrowed: &[i32] = &[1, 2, 3];
+let owned: Vec<i32> = borrowed.to_owned();  // Allocates
+
+// ToOwned trait
+trait ToOwned {
+    type Owned;
+    fn to_owned(&self) -> Self::Owned;
+}
+```
+
+## See Also
+
+- [name-as-free](./name-as-free.md) - Free reference conversions
+- [name-into-ownership](./name-into-ownership.md) - Ownership transfer
+- [own-cow-conditional](./own-cow-conditional.md) - Avoiding unnecessary allocations