agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/api-extension-trait.md

@@ -0,0 +1,163 @@
+# api-extension-trait
+
+> Use extension traits to add methods to external types
+
+## Why It Matters
+
+Rust's orphan rules prevent implementing external traits on external types. Extension traits provide a workaround: define a new trait with your methods, then implement it for the external type. This pattern is used extensively in the ecosystem (e.g., `itertools::Itertools`, `tokio::AsyncReadExt`).
+
+## Bad
+
+```rust
+// Can't add methods directly to external types
+impl Vec<u8> {
+    fn as_hex(&self) -> String {
+        // Error: cannot define inherent impl for a type outside this crate
+    }
+}
+
+// Can't implement external trait for external type
+impl SomeExternalTrait for Vec<u8> {
+    // Error: orphan rules violation
+}
+```
+
+## Good
+
+```rust
+// Define an extension trait
+pub trait ByteSliceExt {
+    fn as_hex(&self) -> String;
+    fn is_ascii_printable(&self) -> bool;
+}
+
+// Implement for the external type
+impl ByteSliceExt for [u8] {
+    fn as_hex(&self) -> String {
+        self.iter()
+            .map(|b| format!("{:02x}", b))
+            .collect()
+    }
+    
+    fn is_ascii_printable(&self) -> bool {
+        self.iter().all(|b| b.is_ascii_graphic() || b.is_ascii_whitespace())
+    }
+}
+
+// Usage: import the trait to use the methods
+use my_crate::ByteSliceExt;
+
+let data: &[u8] = b"hello";
+println!("{}", data.as_hex());  // "68656c6c6f"
+```
+
+## Convention: Ext Suffix
+
+```rust
+// Standard naming: TypeExt for extending Type
+pub trait OptionExt<T> {
+    fn unwrap_or_log(self, msg: &str) -> Option<T>;
+}
+
+impl<T> OptionExt<T> for Option<T> {
+    fn unwrap_or_log(self, msg: &str) -> Option<T> {
+        if self.is_none() {
+            log::warn!("{}", msg);
+        }
+        self
+    }
+}
+
+// For generic extensions
+pub trait ResultExt<T, E> {
+    fn log_err(self) -> Self;
+}
+
+impl<T, E: std::fmt::Display> ResultExt<T, E> for Result<T, E> {
+    fn log_err(self) -> Self {
+        if let Err(ref e) = self {
+            log::error!("{}", e);
+        }
+        self
+    }
+}
+```
+
+## Ecosystem Examples
+
+```rust
+// itertools::Itertools
+use itertools::Itertools;
+let groups = vec![1, 1, 2, 2, 3].into_iter().group_by(|x| *x);
+
+// futures::StreamExt
+use futures::StreamExt;
+let next = stream.next().await;
+
+// tokio::io::AsyncReadExt
+use tokio::io::AsyncReadExt;
+let mut buf = [0u8; 1024];
+reader.read(&mut buf).await?;
+
+// anyhow::Context
+use anyhow::Context;
+let content = std::fs::read_to_string(path)
+    .with_context(|| format!("failed to read {}", path))?;
+```
+
+## Scoped Extensions
+
+```rust
+// Extension only visible where imported
+mod string_utils {
+    pub trait StringExt {
+        fn truncate_ellipsis(&self, max_len: usize) -> String;
+    }
+    
+    impl StringExt for str {
+        fn truncate_ellipsis(&self, max_len: usize) -> String {
+            if self.len() <= max_len {
+                self.to_string()
+            } else {
+                format!("{}...", &self[..max_len.saturating_sub(3)])
+            }
+        }
+    }
+}
+
+// Only available when explicitly imported
+use string_utils::StringExt;
+let short = "very long string".truncate_ellipsis(10);
+```
+
+## Generic Extensions with Bounds
+
+```rust
+pub trait VecExt<T> {
+    fn push_if_unique(&mut self, item: T)
+    where
+        T: PartialEq;
+}
+
+impl<T> VecExt<T> for Vec<T> {
+    fn push_if_unique(&mut self, item: T)
+    where
+        T: PartialEq,
+    {
+        if !self.contains(&item) {
+            self.push(item);
+        }
+    }
+}
+
+// Works with any T: PartialEq
+let mut v = vec![1, 2, 3];
+v.push_if_unique(2);  // No-op
+v.push_if_unique(4);  // Adds 4
+```
+
+## See Also
+
+- [api-sealed-trait](./api-sealed-trait.md) - Controlling trait implementations
+- [api-impl-into](./api-impl-into.md) - Using standard conversion traits
+- [name-as-free](./name-as-free.md) - Naming conventions for conversions

package/template/agent/skills/rust-developer/references/rust-rules/api-from-not-into.md

@@ -0,0 +1,146 @@
+# api-from-not-into
+
+> Implement `From<T>`, not `Into<U>` - From gives you Into for free
+
+## Why It Matters
+
+The standard library has a blanket implementation: `impl<T, U> Into<U> for T where U: From<T>`. This means implementing `From<T> for U` automatically gives you `Into<U> for T`. Implementing `Into` directly bypasses this and is considered non-idiomatic. Always implement `From`.
+
+## Bad
+
+```rust
+struct UserId(u64);
+
+// Non-idiomatic: implementing Into directly
+impl Into<UserId> for u64 {
+    fn into(self) -> UserId {
+        UserId(self)
+    }
+}
+
+// Works, but now you can't use From syntax
+let id = UserId::from(42);  // Error: From not implemented
+let id: UserId = 42.into(); // Works, but limited
+```
+
+## Good
+
+```rust
+struct UserId(u64);
+
+// Idiomatic: implement From
+impl From<u64> for UserId {
+    fn from(id: u64) -> Self {
+        UserId(id)
+    }
+}
+
+// Now both work automatically
+let id = UserId::from(42);   // From syntax
+let id: UserId = 42.into();  // Into syntax (via blanket impl)
+
+// And Into bound works in generics
+fn process(id: impl Into<UserId>) {
+    let id: UserId = id.into();
+}
+process(42u64);  // Works!
+```
+
+## Blanket Implementation
+
+```rust
+// This is in std, you don't write it
+impl<T, U> Into<U> for T
+where
+    U: From<T>,
+{
+    fn into(self) -> U {
+        U::from(self)
+    }
+}
+
+// So when you implement From:
+impl From<String> for MyType { ... }
+
+// You automatically get:
+// impl Into<MyType> for String { ... }
+```
+
+## Multiple From Implementations
+
+```rust
+struct Email(String);
+
+impl From<String> for Email {
+    fn from(s: String) -> Self {
+        Email(s)
+    }
+}
+
+impl From<&str> for Email {
+    fn from(s: &str) -> Self {
+        Email(s.to_string())
+    }
+}
+
+// All of these work
+let e1 = Email::from("test@example.com");
+let e2 = Email::from(String::from("test@example.com"));
+let e3: Email = "test@example.com".into();
+let e4: Email = String::from("test@example.com").into();
+```
+
+## TryFrom for Fallible Conversions
+
+```rust
+use std::convert::TryFrom;
+
+struct PositiveInt(u32);
+
+// Fallible conversion
+impl TryFrom<i32> for PositiveInt {
+    type Error = &'static str;
+    
+    fn try_from(value: i32) -> Result<Self, Self::Error> {
+        if value > 0 {
+            Ok(PositiveInt(value as u32))
+        } else {
+            Err("value must be positive")
+        }
+    }
+}
+
+// Usage
+let pos = PositiveInt::try_from(42)?;   // From-style
+let pos: PositiveInt = 42.try_into()?;  // Into-style (via blanket)
+```
+
+## Clippy Lint
+
+```toml
+[lints.clippy]
+from_over_into = "warn"  # Warns when implementing Into instead of From
+```
+
+```rust
+// Clippy will warn:
+impl Into<Bar> for Foo {  // Warning: prefer From
+    fn into(self) -> Bar { ... }
+}
+```
+
+## When Into IS Needed (Rare)
+
+```rust
+// Only when implementing for external types in specific trait bounds
+// This is very rare and usually indicates a design issue
+
+// Example: you can't implement From<ExternalA> for ExternalB
+// because of orphan rules. But you usually shouldn't need to.
+```
+
+## See Also
+
+- [api-impl-into](./api-impl-into.md) - Using Into in function parameters
+- [err-from-impl](./err-from-impl.md) - From for error types
+- [api-newtype-safety](./api-newtype-safety.md) - Newtype conversions

package/template/agent/skills/rust-developer/references/rust-rules/api-impl-asref.md

@@ -0,0 +1,142 @@
+# api-impl-asref
+
+> Use `AsRef<T>` when you only need to borrow the inner data
+
+## Why It Matters
+
+`AsRef<T>` provides a cheap borrowed view of data without taking ownership or copying. Functions accepting `impl AsRef<T>` can work with multiple types that contain or represent `T`, making APIs flexible while avoiding unnecessary allocations. Use `AsRef` when you only need to read, `Into` when you need to own.
+
+## Bad
+
+```rust
+// Forces callers to provide exact types
+fn process_text(text: &str) { ... }
+fn read_file(path: &Path) { ... }
+
+// Can't call directly with owned types
+let s = String::from("hello");
+process_text(&s);  // Works but verbose
+
+let p = PathBuf::from("/file");
+read_file(&p);  // Works but verbose
+read_file("/file");  // Error! &str != &Path
+```
+
+## Good
+
+```rust
+// Accept anything that can be viewed as the target type
+fn process_text(text: impl AsRef<str>) {
+    let s: &str = text.as_ref();
+    println!("{}", s);
+}
+
+fn read_file(path: impl AsRef<Path>) -> io::Result<Vec<u8>> {
+    std::fs::read(path.as_ref())
+}
+
+// All of these work:
+process_text("literal");        // &str
+process_text(String::from("owned"));  // String
+process_text(Cow::from("cow")); // Cow<str>
+
+read_file("/path/to/file");     // &str  
+read_file(Path::new("/path"));  // &Path
+read_file(PathBuf::from("/path")); // PathBuf
+read_file(OsStr::new("/path")); // &OsStr
+```
+
+## AsRef vs Into vs Borrow
+
+```rust
+// AsRef<T>: cheap borrow, no ownership transfer
+fn read(p: impl AsRef<Path>) {
+    let path: &Path = p.as_ref();
+}
+
+// Into<T>: ownership transfer, may allocate
+fn store(p: impl Into<PathBuf>) {
+    let owned: PathBuf = p.into();
+}
+
+// Borrow<T>: like AsRef but with Eq/Hash consistency guarantee
+use std::borrow::Borrow;
+fn lookup<Q: ?Sized>(map: &HashMap<String, V>, key: &Q) -> Option<&V>
+where
+    String: Borrow<Q>,
+    Q: Hash + Eq,
+{
+    map.get(key)
+}
+```
+
+## Implement AsRef for Custom Types
+
+```rust
+struct Name(String);
+
+impl AsRef<str> for Name {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl AsRef<[u8]> for Name {
+    fn as_ref(&self) -> &[u8] {
+        self.0.as_bytes()
+    }
+}
+
+// Now Name works with functions expecting AsRef<str>
+fn greet(name: impl AsRef<str>) {
+    println!("Hello, {}!", name.as_ref());
+}
+
+greet(Name("Alice".into()));
+```
+
+## Common AsRef Implementations
+
+```rust
+// Standard library provides many
+impl AsRef<str> for String { ... }
+impl AsRef<str> for str { ... }
+impl AsRef<[u8]> for str { ... }
+impl AsRef<[u8]> for String { ... }
+impl AsRef<[u8]> for Vec<u8> { ... }
+impl AsRef<Path> for str { ... }
+impl AsRef<Path> for String { ... }
+impl AsRef<Path> for PathBuf { ... }
+impl AsRef<Path> for OsStr { ... }
+impl AsRef<OsStr> for str { ... }
+```
+
+## When to Use Which
+
+| Trait | Use When |
+|-------|----------|
+| `&T` | Single type, simple API |
+| `AsRef<T>` | Read-only access, multiple input types |
+| `Into<T>` | Need to store/own the value |
+| `Borrow<T>` | HashMap/HashSet keys, Eq/Hash needed |
+| `Deref<Target=T>` | Smart pointer semantics |
+
+## Pattern: Optional AsRef Bound
+
+```rust
+// When T itself might be passed
+fn process<T: AsRef<U>, U>(value: T) {
+    let inner: &U = value.as_ref();
+}
+
+// More flexible: accept T or &T
+fn process<T: AsRef<U> + ?Sized, U: ?Sized>(value: &T) {
+    let inner: &U = value.as_ref();
+}
+```
+
+## See Also
+
+- [api-impl-into](./api-impl-into.md) - When to use Into instead
+- [own-slice-over-vec](./own-slice-over-vec.md) - Using slices for flexibility
+- [own-borrow-over-clone](./own-borrow-over-clone.md) - Preferring borrows

package/template/agent/skills/rust-developer/references/rust-rules/api-impl-into.md

@@ -0,0 +1,160 @@
+# api-impl-into
+
+> Accept `impl Into<T>` for flexible APIs, implement `From<T>` for conversions
+
+## Why It Matters
+
+APIs that accept `impl Into<T>` are ergonomic—callers can pass the target type directly or any type that converts to it. This reduces boilerplate `.into()` calls at call sites. Implement `From<T>` rather than `Into<T>` because `From` implies `Into` through a blanket implementation.
+
+## Bad
+
+```rust
+// Requires exact type - forces callers to convert
+fn process_path(path: PathBuf) { ... }
+fn set_name(name: String) { ... }
+
+// Caller must convert explicitly
+process_path(PathBuf::from("/path/to/file"));
+process_path("/path/to/file".to_path_buf());  // Verbose
+process_path("/path/to/file".into());          // Explicit
+
+set_name(String::from("Alice"));
+set_name("Alice".to_string());  // Verbose
+```
+
+## Good
+
+```rust
+// Accept anything that converts to the target type
+fn process_path(path: impl Into<PathBuf>) {
+    let path = path.into();  // Convert once inside
+    // ...
+}
+
+fn set_name(name: impl Into<String>) {
+    let name = name.into();
+    // ...
+}
+
+// Callers are ergonomic
+process_path("/path/to/file");    // &str converts automatically
+process_path(PathBuf::from(".")); // PathBuf works too
+
+set_name("Alice");                // &str
+set_name(String::from("Alice"));  // String
+set_name(format!("User-{}", id)); // String from format!
+```
+
+## Implement From, Not Into
+
+```rust
+struct UserId(u64);
+
+// ✅ Implement From
+impl From<u64> for UserId {
+    fn from(id: u64) -> Self {
+        UserId(id)
+    }
+}
+
+// Into is automatically provided by blanket impl
+let id: UserId = 42u64.into();  // Works!
+
+// ❌ Don't implement Into directly
+impl Into<UserId> for u64 {
+    fn into(self) -> UserId {
+        UserId(self)  // This works but is non-idiomatic
+    }
+}
+```
+
+## Common Conversions
+
+```rust
+// String-like types
+fn log_message(msg: impl Into<String>) { ... }
+log_message("literal");           // &str
+log_message(String::from("own")); // String
+log_message(Cow::from("cow"));    // Cow<str>
+
+// Path-like types  
+fn read_file(path: impl AsRef<Path>) { ... }  // AsRef for borrowed access
+fn write_file(path: impl Into<PathBuf>) { ... }  // Into when storing
+
+// Duration
+fn set_timeout(duration: impl Into<Duration>) { ... }
+set_timeout(Duration::from_secs(5));
+// Note: no blanket impl for integers, would need custom wrapper
+```
+
+## AsRef vs Into
+
+```rust
+// AsRef<T>: borrow as &T, no conversion cost
+fn count_bytes(data: impl AsRef<[u8]>) -> usize {
+    data.as_ref().len()  // Just borrows, no allocation
+}
+count_bytes("hello");  // &str -> &[u8]
+count_bytes(b"hello"); // &[u8] -> &[u8]
+count_bytes(vec![1, 2, 3]);  // &Vec<u8> -> &[u8]
+
+// Into<T>: convert to owned T, may allocate
+fn store_data(data: impl Into<Vec<u8>>) {
+    let owned: Vec<u8> = data.into();  // Takes ownership
+    // ...
+}
+```
+
+## When NOT to Use impl Into
+
+```rust
+// ❌ Trait objects need Sized
+fn process(handler: impl Into<Box<dyn Handler>>) { }
+// Better: just take Box<dyn Handler> directly
+
+// ❌ Recursive types
+struct Node {
+    children: Vec<impl Into<Node>>,  // Error: impl Trait not allowed here
+}
+
+// ❌ Performance-critical hot paths (minor overhead of trait dispatch)
+fn hot_path(value: impl Into<u64>) {
+    // Consider taking u64 directly if called billions of times
+}
+
+// ❌ When you need to name the type
+fn returns_impl() -> impl Into<String> { }  // Opaque, hard to use
+```
+
+## Builder Pattern with Into
+
+```rust
+struct Config {
+    name: String,
+    path: PathBuf,
+}
+
+impl Config {
+    fn new(name: impl Into<String>) -> Self {
+        Config {
+            name: name.into(),
+            path: PathBuf::new(),
+        }
+    }
+    
+    fn path(mut self, path: impl Into<PathBuf>) -> Self {
+        self.path = path.into();
+        self
+    }
+}
+
+// Clean builder calls
+let config = Config::new("myapp")
+    .path("/etc/myapp");
+```
+
+## See Also
+
+- [api-impl-asref](./api-impl-asref.md) - When to use AsRef instead
+- [api-from-not-into](./api-from-not-into.md) - Why From is preferred
+- [err-from-impl](./err-from-impl.md) - From for error conversion