agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/proj-pub-crate-internal.md

@@ -0,0 +1,139 @@
+# proj-pub-crate-internal
+
+> Use pub(crate) for internal APIs
+
+## Why It Matters
+
+`pub(crate)` exposes items within the crate but hides them from external users. This creates clear boundaries between public API and internal implementation, preventing accidental breakage and reducing public API surface.
+
+## Bad
+
+```rust
+// Everything public - users depend on internals
+pub mod internal {
+    pub struct InternalState {
+        pub buffer: Vec<u8>,    // Implementation detail exposed
+        pub dirty: bool,
+    }
+    
+    pub fn process_internal(state: &mut InternalState) {
+        // Users can call this, creating coupling
+    }
+}
+
+pub struct Widget {
+    pub state: internal::InternalState,  // Exposed!
+}
+```
+
+## Good
+
+```rust
+// Internal module with crate visibility
+pub(crate) mod internal {
+    pub(crate) struct InternalState {
+        pub(crate) buffer: Vec<u8>,
+        pub(crate) dirty: bool,
+    }
+    
+    pub(crate) fn process_internal(state: &mut InternalState) {
+        // Only callable within crate
+    }
+}
+
+pub struct Widget {
+    state: internal::InternalState,  // Private field
+}
+
+impl Widget {
+    pub fn new() -> Self {
+        Self {
+            state: internal::InternalState {
+                buffer: Vec::new(),
+                dirty: false,
+            }
+        }
+    }
+    
+    pub fn do_something(&mut self) {
+        internal::process_internal(&mut self.state);
+    }
+}
+```
+
+## Visibility Levels
+
+| Visibility | Accessible From |
+|------------|-----------------|
+| `pub` | Everywhere |
+| `pub(crate)` | Current crate only |
+| `pub(super)` | Parent module only |
+| `pub(in path)` | Specific module path |
+| (private) | Current module only |
+
+## Pattern: Internal Module
+
+```rust
+// src/lib.rs
+mod internal;  // Private module
+pub mod api;   // Public API
+
+// src/internal.rs
+pub(crate) struct Helper;
+pub(crate) fn helper_function() -> Helper { Helper }
+
+// src/api.rs
+use crate::internal::{Helper, helper_function};
+
+pub struct PublicType {
+    helper: Helper,  // Uses internal type, but field is private
+}
+```
+
+## Pattern: Test Visibility
+
+```rust
+pub struct Parser {
+    // Private implementation
+    state: ParserState,
+}
+
+// Expose for testing but not public API
+#[cfg(test)]
+pub(crate) fn debug_state(&self) -> &ParserState {
+    &self.state
+}
+
+// Or use a dedicated test helper
+#[doc(hidden)]
+pub mod __test_helpers {
+    pub use super::ParserState;
+}
+```
+
+## Pattern: Feature Module Internals
+
+```rust
+// src/user/mod.rs
+mod repository;  // Private
+mod service;     // Private
+
+pub use service::UserService;  // Only export the public API
+
+// repository and service are pub(crate) internally
+// so other modules in crate can use them if needed
+```
+
+## Benefits
+
+| Approach | API Stability | Flexibility |
+|----------|---------------|-------------|
+| All `pub` | Any change breaks users | None |
+| `pub(crate)` internals | Only `pub` items matter | Can refactor freely |
+| Private | Maximum encapsulation | Limits crate flexibility |
+
+## See Also
+
+- [proj-pub-super-parent](./proj-pub-super-parent.md) - Parent-only visibility
+- [proj-pub-use-reexport](./proj-pub-use-reexport.md) - Clean re-exports
+- [api-non-exhaustive](./api-non-exhaustive.md) - Future-proof structs

package/template/agent/skills/rust-developer/references/rust-rules/proj-pub-super-parent.md

@@ -0,0 +1,135 @@
+# proj-pub-super-parent
+
+> Use pub(super) for parent-only visibility
+
+## Why It Matters
+
+`pub(super)` exposes items only to the immediate parent module. This is useful for helper functions and types that submodules share but shouldn't be visible to the rest of the crate.
+
+## Bad
+
+```rust
+// src/parser/mod.rs
+pub mod lexer;
+pub mod ast;
+
+// src/parser/lexer.rs
+pub fn internal_helper() {  // Visible to entire crate!
+    // Helper only needed by lexer and ast
+}
+
+pub(crate) struct Token {  // Visible to entire crate
+    // Only parser submodules need this
+}
+```
+
+## Good
+
+```rust
+// src/parser/mod.rs
+pub mod lexer;
+pub mod ast;
+
+// Shared types for parser submodules only
+pub(super) struct Token {
+    pub(super) kind: TokenKind,
+    pub(super) span: Span,
+}
+
+pub(super) fn shared_helper() -> Token {
+    // Only visible in parser/*
+}
+
+// src/parser/lexer.rs
+use super::{Token, shared_helper};
+
+pub fn lex(input: &str) -> Vec<Token> {
+    shared_helper();
+    // ...
+}
+
+// src/parser/ast.rs
+use super::Token;
+
+pub fn parse(tokens: Vec<Token>) -> Ast {
+    // ...
+}
+```
+
+## Visibility Hierarchy
+
+```
+src/
+├── lib.rs           # crate root
+├── parser/
+│   ├── mod.rs       # pub(super) items visible here
+│   ├── lexer.rs     # can use pub(super) from mod.rs
+│   └── ast.rs       # can use pub(super) from mod.rs
+└── codegen.rs       # CANNOT see pub(super) parser items
+```
+
+## Pattern: Layered Visibility
+
+```rust
+// src/database/mod.rs
+mod connection;
+mod query;
+mod pool;
+
+// Only this module's children can see
+pub(super) struct RawConnection { /* ... */ }
+
+// Entire crate can see
+pub(crate) struct Pool { /* ... */ }
+
+// Everyone can see
+pub struct Database { /* ... */ }
+```
+
+## Pattern: Test Helpers
+
+```rust
+// src/parser/mod.rs
+mod lexer;
+mod ast;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    // Test helper visible only to parser module's tests
+    pub(super) fn make_test_token() -> Token {
+        Token { kind: TokenKind::Test, span: Span::dummy() }
+    }
+}
+
+// src/parser/lexer.rs
+#[cfg(test)]
+mod tests {
+    use super::super::tests::make_test_token;
+    // ...
+}
+```
+
+## Comparison
+
+| Visibility | Scope | Use Case |
+|------------|-------|----------|
+| `pub` | Everywhere | Public API |
+| `pub(crate)` | Crate-wide | Internal shared utilities |
+| `pub(super)` | Parent module | Submodule helpers |
+| `pub(in path)` | Specific path | Precise control |
+| (private) | Current module | Implementation details |
+
+## When to Use pub(super)
+
+- Helper functions shared between sibling modules
+- Types used by submodules but not the rest of crate
+- Implementation details of a module group
+- Test utilities for a module tree
+
+## See Also
+
+- [proj-pub-crate-internal](./proj-pub-crate-internal.md) - Crate visibility
+- [proj-pub-use-reexport](./proj-pub-use-reexport.md) - Re-export patterns
+- [proj-mod-by-feature](./proj-mod-by-feature.md) - Feature organization

package/template/agent/skills/rust-developer/references/rust-rules/proj-pub-use-reexport.md

@@ -0,0 +1,162 @@
+# proj-pub-use-reexport
+
+> Use pub use for clean public API
+
+## Why It Matters
+
+`pub use` re-exports items from submodules at the current module level. This creates a flat, ergonomic public API while keeping internal organization flexible. Users import from one place; you can reorganize internals without breaking their code.
+
+## Bad
+
+```rust
+// lib.rs - Deep module paths exposed
+pub mod error;
+pub mod config;
+pub mod client;
+pub mod types;
+
+// Users must write:
+use my_crate::error::MyError;
+use my_crate::config::Config;
+use my_crate::client::http::HttpClient;
+use my_crate::types::request::Request;
+```
+
+## Good
+
+```rust
+// lib.rs - Flat public API
+mod error;
+mod config;
+mod client;
+mod types;
+
+pub use error::MyError;
+pub use config::Config;
+pub use client::http::HttpClient;
+pub use types::request::Request;
+
+// Users write:
+use my_crate::{Config, HttpClient, MyError, Request};
+```
+
+## Pattern: Selective Re-export
+
+```rust
+// src/lib.rs
+mod internal;
+
+// Only re-export what users need
+pub use internal::{
+    PublicStruct,
+    PublicTrait,
+    public_function,
+};
+
+// Keep implementation details hidden
+// internal::helper_function is NOT exported
+```
+
+## Pattern: Rename on Re-export
+
+```rust
+mod v1 {
+    pub struct Client { /* old implementation */ }
+}
+
+mod v2 {
+    pub struct Client { /* new implementation */ }
+}
+
+// Re-export with clear names
+pub use v2::Client;
+pub use v1::Client as LegacyClient;
+```
+
+## Pattern: Prelude Module
+
+```rust
+// src/lib.rs
+pub mod prelude {
+    pub use crate::{
+        Config,
+        Client,
+        Error,
+        Request,
+        Response,
+    };
+}
+
+// Users can glob import common items
+use my_crate::prelude::*;
+```
+
+## Pattern: Feature-Gated Re-exports
+
+```rust
+// src/lib.rs
+mod core;
+mod serde_impl;
+mod async_impl;
+
+pub use core::*;
+
+#[cfg(feature = "serde")]
+pub use serde_impl::*;
+
+#[cfg(feature = "async")]
+pub use async_impl::*;
+```
+
+## Comparison: Module Structure vs Public API
+
+```rust
+// Internal structure (complex)
+src/
+├── transport/
+│   ├── http/
+│   │   └── client.rs    // HttpClient
+│   └── grpc/
+│       └── client.rs    // GrpcClient
+├── auth/
+│   └── token.rs         // Token
+└── lib.rs
+
+// Public API (flat)
+pub use transport::http::client::HttpClient;
+pub use transport::grpc::client::GrpcClient;
+pub use auth::token::Token;
+
+// Users see:
+my_crate::HttpClient
+my_crate::GrpcClient
+my_crate::Token
+```
+
+## Re-export External Types
+
+```rust
+// Re-export dependencies users will need
+pub use bytes::Bytes;
+pub use http::{Method, StatusCode};
+
+// Now users don't need to depend on these crates directly
+```
+
+## Glob Re-exports
+
+Use sparingly:
+
+```rust
+// OK for internal modules
+pub use internal::*;
+
+// Careful with external crates - pollutes namespace
+pub use serde::*;  // Usually too broad
+```
+
+## See Also
+
+- [proj-prelude-module](./proj-prelude-module.md) - Prelude pattern
+- [proj-pub-crate-internal](./proj-pub-crate-internal.md) - Internal visibility
+- [api-non-exhaustive](./api-non-exhaustive.md) - API stability

package/template/agent/skills/rust-developer/references/rust-rules/proj-workspace-deps.md

@@ -0,0 +1,186 @@
+# proj-workspace-deps
+
+> Use workspace dependency inheritance for consistent versions across crates
+
+## Why It Matters
+
+Multi-crate workspaces often have dependency version drift—different crates using different versions of the same dependency. Workspace dependency inheritance (Rust 1.64+) lets you declare dependencies once in the workspace `Cargo.toml` and inherit them in member crates, ensuring consistency.
+
+## Bad
+
+```toml
+# crate-a/Cargo.toml
+[dependencies]
+serde = "1.0.150"
+tokio = "1.25"
+
+# crate-b/Cargo.toml  
+[dependencies]
+serde = "1.0.188"  # Different version!
+tokio = "1.32"     # Different version!
+
+# Version drift leads to:
+# - Larger binaries (multiple versions)
+# - Compilation time increase
+# - Subtle behavior differences
+```
+
+## Good
+
+```toml
+# Root Cargo.toml
+[workspace]
+members = ["crate-a", "crate-b", "crate-c"]
+
+[workspace.dependencies]
+serde = { version = "1.0", features = ["derive"] }
+tokio = { version = "1.32", features = ["full"] }
+thiserror = "1.0"
+anyhow = "1.0"
+tracing = "0.1"
+
+# crate-a/Cargo.toml
+[dependencies]
+serde.workspace = true
+tokio.workspace = true
+
+# crate-b/Cargo.toml
+[dependencies]
+serde.workspace = true
+tokio.workspace = true
+thiserror.workspace = true
+```
+
+## Override Features
+
+```toml
+# Root Cargo.toml
+[workspace.dependencies]
+tokio = { version = "1.32", features = ["rt-multi-thread"] }
+
+# crate-a/Cargo.toml - add extra features
+[dependencies]
+tokio = { workspace = true, features = ["net", "io-util"] }
+# Gets both workspace features AND local features
+
+# crate-b/Cargo.toml - minimal features
+[dependencies]
+tokio = { workspace = true }  # Just workspace features
+```
+
+## Dev and Build Dependencies
+
+```toml
+# Root Cargo.toml
+[workspace.dependencies]
+criterion = "0.5"
+proptest = "1.0"
+trybuild = "1.0"
+cc = "1.0"
+
+# crate-a/Cargo.toml
+[dev-dependencies]
+criterion.workspace = true
+proptest.workspace = true
+
+[build-dependencies]
+cc.workspace = true
+```
+
+## Internal Crate Dependencies
+
+```toml
+# Root Cargo.toml
+[workspace.dependencies]
+# Internal crates
+my-core = { path = "crates/core" }
+my-utils = { path = "crates/utils" }
+my-derive = { path = "crates/derive" }
+
+# External crates
+serde = "1.0"
+
+# crate-a/Cargo.toml
+[dependencies]
+my-core.workspace = true
+my-utils.workspace = true
+serde.workspace = true
+```
+
+## Optional Dependencies
+
+```toml
+# Root Cargo.toml
+[workspace.dependencies]
+serde = { version = "1.0", optional = true }  # Won't work!
+
+# Optional must be set in member, not workspace
+[workspace.dependencies]
+serde = "1.0"
+
+# crate-a/Cargo.toml
+[dependencies]
+serde = { workspace = true, optional = true }
+
+[features]
+serde = ["dep:serde"]
+```
+
+## Complete Workspace Example
+
+```toml
+# Root Cargo.toml
+[workspace]
+members = ["crates/*"]
+resolver = "2"
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/user/repo"
+
+[workspace.dependencies]
+# Internal
+my-core = { path = "crates/core", version = "0.1" }
+
+# Async
+tokio = { version = "1.32", features = ["full"] }
+futures = "0.3"
+
+# Serialization
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+# Error handling
+thiserror = "1.0"
+anyhow = "1.0"
+
+# Logging
+tracing = "0.1"
+tracing-subscriber = "0.3"
+
+# Testing
+proptest = "1.0"
+criterion = { version = "0.5", features = ["html_reports"] }
+
+# crates/core/Cargo.toml
+[package]
+name = "my-core"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+serde.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+proptest.workspace = true
+```
+
+## See Also
+
+- [proj-lib-main-split](./proj-lib-main-split.md) - Workspace structure
+- [api-serde-optional](./api-serde-optional.md) - Optional dependencies
+- [lint-deny-correctness](./lint-deny-correctness.md) - Workspace lints