agy-superpowers 5.1.4 → 5.1.5

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

package/template/agent/skills/rust-developer/references/rust-rules/api-must-use.md

@@ -0,0 +1,125 @@
+# api-must-use
+
+> Mark types and functions with `#[must_use]` when ignoring results is likely a bug
+
+## Why It Matters
+
+Some return values should never be ignored—`Result`, locks, RAII guards, computed values that have no side effects. Without `#[must_use]`, silently discarding these values can introduce subtle bugs that are hard to detect. The attribute generates compiler warnings when the value is unused.
+
+## Bad
+
+```rust
+// Result ignored - error silently dropped
+fn send_email(to: &str, body: &str) -> Result<(), EmailError> { ... }
+
+send_email("user@example.com", "Hello!");  // No warning if Result ignored!
+// Email may have failed, but we don't know
+
+// Computed value ignored - likely a bug
+fn compute_checksum(data: &[u8]) -> u32 { ... }
+
+let data = vec![1, 2, 3, 4];
+compute_checksum(&data);  // Result discarded - pointless call
+```
+
+## Good
+
+```rust
+#[must_use = "this `Result` may be an `Err` that should be handled"]
+fn send_email(to: &str, body: &str) -> Result<(), EmailError> { ... }
+
+send_email("user@example.com", "Hello!");  
+// Warning: unused `Result` that must be used
+
+// Mark pure functions
+#[must_use = "this returns a new value and does not modify the input"]
+fn compute_checksum(data: &[u8]) -> u32 { ... }
+
+compute_checksum(&data);
+// Warning: unused return value of `compute_checksum` that must be used
+```
+
+## Apply to Types
+
+```rust
+// Mark the type itself when it should always be used
+#[must_use = "futures do nothing unless polled"]
+struct MyFuture<T> { ... }
+
+// Mark RAII guards
+#[must_use = "if unused, the lock will be immediately released"]
+struct MutexGuard<'a, T> { ... }
+
+// Mark results/errors
+#[must_use = "errors should be handled"]
+enum AppError { ... }
+```
+
+## Standard Library Examples
+
+```rust
+// Result and Option are #[must_use]
+let v: Vec<i32> = vec![1, 2, 3];
+v.first();  // Warning: unused Option
+
+// Iterator adapters are #[must_use]
+v.iter().map(|x| x * 2);  // Warning: iterators are lazy
+
+// String methods that return new values
+let s = "hello";
+s.to_uppercase();  // Warning: unused String
+```
+
+## When to Apply
+
+```rust
+// ✅ Pure functions (no side effects)
+#[must_use]
+fn add(a: i32, b: i32) -> i32 { a + b }
+
+// ✅ Builder methods returning Self
+#[must_use = "builder methods return a new builder"]
+fn with_timeout(self, t: Duration) -> Self { ... }
+
+// ✅ Fallible operations
+#[must_use]
+fn try_parse(s: &str) -> Result<Data, ParseError> { ... }
+
+// ✅ Iterators and futures (lazy)
+#[must_use = "iterators are lazy and do nothing unless consumed"]
+struct Map<I, F> { ... }
+
+// ❌ Side-effecting functions where result is optional
+fn log(msg: &str) -> Result<(), io::Error> { ... }  // Might be ok to ignore
+
+// ❌ Methods with useful side effects
+fn vec.push(item);  // Mutates vec, no return to use
+```
+
+## Custom Messages
+
+```rust
+#[must_use = "creating a guard does nothing without assignment"]
+struct ScopeGuard { ... }
+
+#[must_use = "this returns the old value"]
+fn replace(&mut self, new: T) -> T { ... }
+
+#[must_use = "use `.await` to execute the future"]
+async fn fetch() -> Data { ... }
+```
+
+## Clippy Lints
+
+```toml
+[lints.clippy]
+must_use_candidate = "warn"      # Suggests where to add #[must_use]
+unused_must_use = "deny"          # Built-in, treat warnings as errors
+double_must_use = "warn"          # Redundant #[must_use]
+```
+
+## See Also
+
+- [api-builder-must-use](./api-builder-must-use.md) - Builder pattern must_use
+- [err-result-over-panic](./err-result-over-panic.md) - Result types require handling
+- [lint-deny-correctness](./lint-deny-correctness.md) - Enabling useful lints