agy-superpowers 5.2.2 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/proj-prelude-module.md

@@ -1,155 +0,0 @@
-# proj-prelude-module
-
-> Create prelude module for common imports
-
-## Why It Matters
-
-A `prelude` module collects the most commonly used types and traits for glob import. Users write `use my_crate::prelude::*` instead of many individual imports. This follows the pattern established by `std::prelude`.
-
-## Bad
-
-```rust
-// Users must import everything individually
-use my_crate::Client;
-use my_crate::Config;
-use my_crate::Error;
-use my_crate::Request;
-use my_crate::Response;
-use my_crate::traits::Handler;
-use my_crate::traits::Middleware;
-use my_crate::types::Method;
-```
-
-## Good
-
-```rust
-// src/lib.rs
-pub mod prelude {
-    pub use crate::{
-        Client,
-        Config,
-        Error,
-        Request,
-        Response,
-    };
-    pub use crate::traits::{Handler, Middleware};
-    pub use crate::types::Method;
-}
-
-// Users write:
-use my_crate::prelude::*;
-```
-
-## What to Include
-
-| Include | Don't Include |
-|---------|---------------|
-| Core types users always need | Rarely-used types |
-| Common traits | Implementation details |
-| Error types | Internal helpers |
-| Extension traits | Feature-gated items (usually) |
-| Type aliases | Everything |
-
-## Example: Web Framework Prelude
-
-```rust
-pub mod prelude {
-    // Core request/response
-    pub use crate::{Request, Response, Body};
-    
-    // Error handling
-    pub use crate::Error;
-    
-    // Common traits
-    pub use crate::traits::{FromRequest, IntoResponse};
-    
-    // Routing
-    pub use crate::Router;
-    
-    // HTTP types
-    pub use crate::http::{Method, StatusCode};
-}
-```
-
-## Example: Database Library Prelude
-
-```rust
-pub mod prelude {
-    // Connection and pool
-    pub use crate::{Connection, Pool};
-    
-    // Query building
-    pub use crate::query::{Query, Select, Insert, Update, Delete};
-    
-    // Traits for custom types
-    pub use crate::traits::{FromRow, ToSql};
-    
-    // Error type
-    pub use crate::Error;
-}
-```
-
-## Pattern: Tiered Preludes
-
-```rust
-// Minimal prelude
-pub mod prelude {
-    pub use crate::{Client, Config, Error};
-}
-
-// Full prelude for power users
-pub mod full_prelude {
-    pub use crate::prelude::*;
-    pub use crate::advanced::*;
-    pub use crate::extensions::*;
-}
-```
-
-## Pattern: Feature-Gated Prelude Items
-
-```rust
-pub mod prelude {
-    pub use crate::{Client, Error};
-    
-    #[cfg(feature = "async")]
-    pub use crate::async_client::AsyncClient;
-    
-    #[cfg(feature = "serde")]
-    pub use crate::serde::{Serialize, Deserialize};
-}
-```
-
-## Guidelines
-
-1. **Be conservative** - Only include truly common items
-2. **Avoid conflicts** - Don't include names that might clash (e.g., `Error`)
-3. **Document it** - List what's included in module docs
-4. **Stay stable** - Removing items is breaking change
-
-## Documenting the Prelude
-
-```rust
-//! Common imports for convenient glob importing.
-//!
-//! # Usage
-//!
-//! ```
-//! use my_crate::prelude::*;
-//! ```
-//!
-//! # Contents
-//!
-//! This prelude re-exports:
-//! - [`Client`] - The main API client
-//! - [`Config`] - Client configuration
-//! - [`Error`] - Error type
-pub mod prelude {
-    // ...
-}
-```
-
-## See Also
-
-- [proj-pub-use-reexport](./proj-pub-use-reexport.md) - Re-export patterns
-- [api-extension-trait](./api-extension-trait.md) - Extension traits
-- [doc-module-inner](./doc-module-inner.md) - Module documentation

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