agy-superpowers 5.1.4 → 5.1.6

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

@@ -0,0 +1,168 @@
+# api-sealed-trait
+
+> Use sealed traits to prevent external implementations while allowing use
+
+## Why It Matters
+
+Public traits can be implemented by anyone, which may be undesirable when you need to guarantee behavior or add methods in future versions. A sealed trait can be used by external code but not implemented by it, giving you control over implementations while maintaining a usable API.
+
+## Bad
+
+```rust
+// Anyone can implement this trait
+pub trait DatabaseDriver {
+    fn connect(&self, url: &str) -> Connection;
+    fn execute(&self, query: &str) -> Result<Rows, Error>;
+}
+
+// External crate implements it incorrectly
+impl DatabaseDriver for MyBadDriver {
+    fn connect(&self, url: &str) -> Connection {
+        // Buggy implementation that doesn't handle errors
+        unsafe { force_connect(url) }
+    }
+}
+
+// Later, you want to add a required method - BREAKING CHANGE
+pub trait DatabaseDriver {
+    fn connect(&self, url: &str) -> Connection;
+    fn execute(&self, query: &str) -> Result<Rows, Error>;
+    fn transaction(&self) -> Transaction;  // External impls now broken!
+}
+```
+
+## Good
+
+```rust
+// Create a private module with a private trait
+mod private {
+    pub trait Sealed {}
+}
+
+// Public trait requires the private trait
+pub trait DatabaseDriver: private::Sealed {
+    fn connect(&self, url: &str) -> Connection;
+    fn execute(&self, query: &str) -> Result<Rows, Error>;
+}
+
+// Only your crate can implement Sealed, thus DatabaseDriver
+pub struct PostgresDriver;
+impl private::Sealed for PostgresDriver {}
+impl DatabaseDriver for PostgresDriver {
+    fn connect(&self, url: &str) -> Connection { ... }
+    fn execute(&self, query: &str) -> Result<Rows, Error> { ... }
+}
+
+pub struct MySqlDriver;
+impl private::Sealed for MySqlDriver {}
+impl DatabaseDriver for MySqlDriver {
+    fn connect(&self, url: &str) -> Connection { ... }
+    fn execute(&self, query: &str) -> Result<Rows, Error> { ... }
+}
+
+// External crate cannot implement - private::Sealed is not accessible
+// impl DatabaseDriver for ExternalDriver { }  // Error!
+
+// But external code CAN use the trait
+fn use_driver(driver: &impl DatabaseDriver) {
+    let conn = driver.connect("postgres://localhost");
+}
+```
+
+## Full Pattern
+
+```rust
+pub mod db {
+    mod private {
+        pub trait Sealed {}
+    }
+    
+    /// Database driver trait.
+    /// 
+    /// This trait is sealed and cannot be implemented outside this crate.
+    pub trait Driver: private::Sealed {
+        /// Connects to the database.
+        fn connect(&self, url: &str) -> Result<Connection, Error>;
+        
+        /// Executes a query.
+        fn execute(&self, sql: &str) -> Result<Rows, Error>;
+    }
+    
+    pub struct Postgres;
+    impl private::Sealed for Postgres {}
+    impl Driver for Postgres { ... }
+    
+    pub struct Sqlite;
+    impl private::Sealed for Sqlite {}
+    impl Driver for Sqlite { ... }
+}
+
+// Usage works fine
+use db::{Driver, Postgres};
+
+fn query(driver: &impl Driver) {
+    driver.execute("SELECT 1")?;
+}
+
+query(&Postgres);
+```
+
+## Benefits of Sealing
+
+```rust
+// 1. Add methods without breaking changes
+pub trait Format: private::Sealed {
+    fn format(&self) -> String;
+    
+    // Added later - not breaking because no external impls exist
+    fn format_pretty(&self) -> String {
+        self.format()  // Default implementation
+    }
+}
+
+// 2. Guarantee invariants
+pub trait SafeBuffer: private::Sealed {
+    // You control all implementations, so you know they're all correct
+    fn get(&self, index: usize) -> Option<&u8>;
+}
+
+// 3. Use as marker traits
+pub trait ValidConfig: private::Sealed {}
+// Only validated configs implement this
+```
+
+## Partially Sealed
+
+```rust
+// Allow implementing some methods but not all
+mod private {
+    pub trait SealedCore {}
+}
+
+pub trait Plugin: private::SealedCore {
+    // Sealed - only we implement
+    fn initialize(&self);
+    fn shutdown(&self);
+    
+    // Open - users can override
+    fn name(&self) -> &str { "unnamed" }
+}
+
+// Only we can add new required sealed methods
+// Users can customize open methods
+```
+
+## When to Seal
+
+| Seal When | Don't Seal When |
+|-----------|-----------------|
+| API stability is critical | You want extension points |
+| Implementation correctness is hard | Users need custom implementations |
+| You'll add methods later | Trait is simple and stable |
+| Safety invariants required | Standard patterns (Iterator, etc.) |
+
+## See Also
+
+- [api-non-exhaustive](./api-non-exhaustive.md) - Related pattern for enums/structs
+- [api-extension-trait](./api-extension-trait.md) - Adding methods to external types
+- [api-typestate](./api-typestate.md) - Compile-time state guarantees

package/template/agent/skills/rust-developer/references/rust-rules/api-serde-optional.md

@@ -0,0 +1,182 @@
+# api-serde-optional
+
+> Make serde a feature flag, not a hard dependency for library crates
+
+## Why It Matters
+
+Not all users of your library need serialization. Making serde a required dependency adds compile time and binary size for everyone. Feature flags let users opt-in to serde support only when needed, following Rust's philosophy of zero-cost abstractions and minimal dependencies.
+
+## Bad
+
+```rust
+// Cargo.toml
+[dependencies]
+serde = { version = "1.0", features = ["derive"] }
+
+// lib.rs
+use serde::{Serialize, Deserialize};
+
+// Every user pays for serde, even if they don't need it
+#[derive(Serialize, Deserialize)]
+pub struct Config {
+    pub name: String,
+    pub value: i32,
+}
+```
+
+## Good
+
+```rust
+// Cargo.toml
+[dependencies]
+serde = { version = "1.0", features = ["derive"], optional = true }
+
+[features]
+default = []
+serde = ["dep:serde"]
+
+// lib.rs
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Config {
+    pub name: String,
+    pub value: i32,
+}
+
+// Users opt-in:
+// my_crate = { version = "1.0", features = ["serde"] }
+```
+
+## Macro Pattern
+
+```rust
+// Reusable macro for serde derives
+#[cfg(feature = "serde")]
+macro_rules! impl_serde {
+    ($($t:ty),*) => {
+        $(
+            impl serde::Serialize for $t {
+                // ...
+            }
+            impl<'de> serde::Deserialize<'de> for $t {
+                // ...
+            }
+        )*
+    };
+}
+
+#[cfg(not(feature = "serde"))]
+macro_rules! impl_serde {
+    ($($t:ty),*) => {};
+}
+
+// Or use cfg_attr for derived impls
+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub struct Point {
+    pub x: f64,
+    pub y: f64,
+}
+```
+
+## Feature Documentation
+
+```rust
+// lib.rs
+
+//! # Features
+//!
+//! - `serde`: Enables `Serialize` and `Deserialize` implementations for all types.
+//!
+//! # Example with serde
+//!
+//! ```toml
+//! [dependencies]
+//! my_crate = { version = "1.0", features = ["serde"] }
+//! ```
+
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
+/// A configuration type.
+/// 
+/// When the `serde` feature is enabled, this type implements
+/// `Serialize` and `Deserialize`.
+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
+pub struct Config {
+    pub name: String,
+}
+```
+
+## Multiple Optional Dependencies
+
+```rust
+// Cargo.toml
+[dependencies]
+serde = { version = "1.0", features = ["derive"], optional = true }
+rkyv = { version = "0.7", optional = true }
+borsh = { version = "0.10", optional = true }
+
+[features]
+default = []
+serde = ["dep:serde"]
+rkyv = ["dep:rkyv"]
+borsh = ["dep:borsh"]
+
+// lib.rs
+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(feature = "rkyv", derive(rkyv::Archive, rkyv::Serialize, rkyv::Deserialize))]
+#[cfg_attr(feature = "borsh", derive(borsh::BorshSerialize, borsh::BorshDeserialize))]
+pub struct Message {
+    pub id: u64,
+    pub content: String,
+}
+```
+
+## Testing with Features
+
+```bash
+# Test without serde
+cargo test
+
+# Test with serde
+cargo test --features serde
+
+# Test all feature combinations
+cargo test --all-features
+```
+
+```rust
+// Test serde round-trip when feature enabled
+#[cfg(feature = "serde")]
+#[test]
+fn test_serde_roundtrip() {
+    let config = Config { name: "test".into() };
+    let json = serde_json::to_string(&config).unwrap();
+    let parsed: Config = serde_json::from_str(&json).unwrap();
+    assert_eq!(config, parsed);
+}
+```
+
+## When to Make Serde Required
+
+```rust
+// ✅ Required: Library is about serialization
+// (e.g., json-schema, config-file parser)
+[dependencies]
+serde = "1.0"
+
+// ✅ Required: Domain heavily uses serde
+// (e.g., API client, data format library)
+
+// ❌ Optional: General-purpose utility library
+// ❌ Optional: Math/algorithm library
+// ❌ Optional: Most libraries!
+```
+
+## See Also
+
+- [proj-lib-main-split](./proj-lib-main-split.md) - Library structure
+- [api-common-traits](./api-common-traits.md) - Core trait implementations
+- [lint-deny-correctness](./lint-deny-correctness.md) - Feature testing

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

@@ -0,0 +1,199 @@
+# api-typestate
+
+> Use typestate pattern to encode state machine invariants in the type system
+
+## Why It Matters
+
+State machines with runtime state checks ("are we connected?", "is the transaction started?") can have invalid transitions. The typestate pattern uses different types for each state, making invalid state transitions compile errors. The compiler enforces your state machine.
+
+## Bad
+
+```rust
+struct Connection {
+    state: ConnectionState,
+    socket: Option<TcpStream>,
+}
+
+enum ConnectionState {
+    Disconnected,
+    Connected,
+    Authenticated,
+}
+
+impl Connection {
+    fn send(&mut self, data: &[u8]) -> Result<(), Error> {
+        // Runtime check - can fail if called in wrong state
+        if self.state != ConnectionState::Authenticated {
+            return Err(Error::NotAuthenticated);
+        }
+        self.socket.as_mut().unwrap().write_all(data)?;
+        Ok(())
+    }
+    
+    fn authenticate(&mut self, password: &str) -> Result<(), Error> {
+        // Runtime check - can fail
+        if self.state != ConnectionState::Connected {
+            return Err(Error::NotConnected);
+        }
+        // ...
+    }
+}
+
+// Bug: forgot to authenticate
+let mut conn = Connection::new();
+conn.connect()?;
+conn.send(b"data")?;  // Runtime error: NotAuthenticated
+```
+
+## Good
+
+```rust
+// Different types for each state
+struct Disconnected;
+struct Connected { socket: TcpStream }
+struct Authenticated { socket: TcpStream, session: Session }
+
+struct Connection<State> {
+    state: State,
+}
+
+impl Connection<Disconnected> {
+    fn new() -> Self {
+        Connection { state: Disconnected }
+    }
+    
+    fn connect(self, addr: &str) -> Result<Connection<Connected>, Error> {
+        let socket = TcpStream::connect(addr)?;
+        Ok(Connection { state: Connected { socket } })
+    }
+}
+
+impl Connection<Connected> {
+    fn authenticate(self, password: &str) -> Result<Connection<Authenticated>, Error> {
+        let session = do_auth(&self.state.socket, password)?;
+        Ok(Connection {
+            state: Authenticated { socket: self.state.socket, session }
+        })
+    }
+}
+
+impl Connection<Authenticated> {
+    fn send(&mut self, data: &[u8]) -> Result<(), Error> {
+        // No runtime check needed - type guarantees we're authenticated
+        self.state.socket.write_all(data)?;
+        Ok(())
+    }
+}
+
+// Bug: forgot to authenticate
+let conn = Connection::new();
+let conn = conn.connect("server:8080")?;
+conn.send(b"data");  // Compile error! send() not available on Connection<Connected>
+
+// Correct usage
+let conn = Connection::new();
+let conn = conn.connect("server:8080")?;
+let mut conn = conn.authenticate("secret")?;
+conn.send(b"data")?;  // Works - type is Connection<Authenticated>
+```
+
+## Builder Typestate
+
+```rust
+// Enforce required fields via typestate
+struct BuilderNoUrl;
+struct BuilderWithUrl { url: String }
+
+struct RequestBuilder<State> {
+    state: State,
+    timeout: Option<Duration>,
+}
+
+impl RequestBuilder<BuilderNoUrl> {
+    fn new() -> Self {
+        RequestBuilder {
+            state: BuilderNoUrl,
+            timeout: None,
+        }
+    }
+    
+    fn url(self, url: &str) -> RequestBuilder<BuilderWithUrl> {
+        RequestBuilder {
+            state: BuilderWithUrl { url: url.to_string() },
+            timeout: self.timeout,
+        }
+    }
+}
+
+impl RequestBuilder<BuilderWithUrl> {
+    fn timeout(mut self, t: Duration) -> Self {
+        self.timeout = Some(t);
+        self
+    }
+    
+    // Only available once URL is set
+    fn build(self) -> Request {
+        Request {
+            url: self.state.url,
+            timeout: self.timeout,
+        }
+    }
+}
+
+// Compile error: build() not available
+let bad = RequestBuilder::new().build();
+
+// Correct: must set URL first
+let good = RequestBuilder::new()
+    .url("https://example.com")
+    .timeout(Duration::from_secs(30))
+    .build();
+```
+
+## Transaction Example
+
+```rust
+struct NotStarted;
+struct InProgress { tx_id: u64 }
+struct Committed;
+
+struct Transaction<State> {
+    conn: Connection,
+    state: State,
+}
+
+impl Transaction<NotStarted> {
+    fn begin(conn: Connection) -> Result<Transaction<InProgress>, Error> {
+        let tx_id = conn.execute("BEGIN")?;
+        Ok(Transaction {
+            conn,
+            state: InProgress { tx_id },
+        })
+    }
+}
+
+impl Transaction<InProgress> {
+    fn execute(&mut self, sql: &str) -> Result<(), Error> {
+        self.conn.execute(sql)
+    }
+    
+    fn commit(self) -> Result<Transaction<Committed>, Error> {
+        self.conn.execute("COMMIT")?;
+        Ok(Transaction {
+            conn: self.conn,
+            state: Committed,
+        })
+    }
+    
+    fn rollback(self) -> Connection {
+        let _ = self.conn.execute("ROLLBACK");
+        self.conn
+    }
+}
+```
+
+## See Also
+
+- [api-builder-pattern](./api-builder-pattern.md) - Basic builder pattern
+- [api-parse-dont-validate](./api-parse-dont-validate.md) - Type-driven invariants
+- [api-sealed-trait](./api-sealed-trait.md) - Restricting trait implementations