agy-superpowers 5.2.2 → 5.2.4

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

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

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

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

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