agy-superpowers 5.2.1 → 5.2.3

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

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

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

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

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