agy-superpowers 5.2.1 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/doc-link-types.md

@@ -1,169 +0,0 @@
-# doc-link-types
-
-> Use intra-doc links to connect related types and functions
-
-## Why It Matters
-
-Intra-doc links (`[`TypeName`]`) create clickable references in generated documentation. They enable navigation between related items, verify that referenced items exist at compile time, and update automatically when items are renamed. Plain text references become stale and unclickable.
-
-## Bad
-
-```rust
-/// Parses input and returns a ParseResult.
-/// 
-/// See also: ParseError for error types.
-/// Uses the Tokenizer internally.
-pub fn parse(input: &str) -> ParseResult {
-    // "ParseResult", "ParseError", "Tokenizer" are not clickable
-    // No verification they exist
-}
-```
-
-## Good
-
-```rust
-/// Parses input and returns a [`ParseResult`].
-///
-/// # Errors
-///
-/// Returns [`ParseError::InvalidSyntax`] if the input contains invalid tokens.
-/// Returns [`ParseError::UnexpectedEof`] if the input ends prematurely.
-///
-/// # Related
-///
-/// - [`Tokenizer`] - The underlying tokenizer used by this parser
-/// - [`parse_file`] - Convenience function for parsing files
-/// - [`ParseOptions`] - Configuration options for parsing
-pub fn parse(input: &str) -> ParseResult {
-    // All links are clickable and verified
-}
-```
-
-## Link Syntax
-
-```rust
-/// Basic link to type in same module
-/// See [`MyType`] for details.
-
-/// Link to method
-/// Use [`MyType::new`] to create instances.
-
-/// Link to associated type
-/// Returns [`Iterator::Item`].
-
-/// Link to module
-/// See the [`parser`] module.
-
-/// Link to external crate type
-/// Works with [`std::collections::HashMap`].
-
-/// Link with custom text
-/// See [the parser][`parse`] for details.
-
-/// Link to module item
-/// See [`crate::utils::helper`].
-
-/// Link to parent module item
-/// See [`super::Parent`].
-```
-
-## Common Patterns
-
-```rust
-/// A configuration builder.
-///
-/// # Example
-///
-/// ```
-/// use my_crate::Config;
-///
-/// let config = Config::builder()
-///     .timeout(30)
-///     .build()?;
-/// ```
-///
-/// # Methods
-///
-/// - [`Config::builder`] - Create a new builder
-/// - [`Config::default`] - Create with defaults
-///
-/// # Related Types
-///
-/// - [`ConfigBuilder`] - The builder returned by [`Config::builder`]
-/// - [`ConfigError`] - Errors that can occur when building
-pub struct Config { ... }
-
-impl Config {
-    /// Creates a new [`ConfigBuilder`].
-    ///
-    /// This is equivalent to [`ConfigBuilder::new`].
-    pub fn builder() -> ConfigBuilder { ... }
-}
-```
-
-## Linking to Trait Items
-
-```rust
-/// Implements [`Iterator`] for lazy evaluation.
-///
-/// The [`Iterator::next`] method advances the cursor.
-/// 
-/// For parallel iteration, see [`rayon::ParallelIterator`].
-pub struct MyIterator { ... }
-
-impl Iterator for MyIterator {
-    /// Advances and returns the next value.
-    ///
-    /// See also [`Iterator::nth`] for skipping elements.
-    fn next(&mut self) -> Option<Self::Item> { ... }
-}
-```
-
-## Broken Link Detection
-
-```bash
-# Catch broken intra-doc links
-RUSTDOCFLAGS="-D warnings" cargo doc
-
-# Or in CI
-cargo doc --no-deps 2>&1 | grep "warning: unresolved link"
-```
-
-```toml
-# Cargo.toml - deny broken links
-[lints.rustdoc]
-broken_intra_doc_links = "deny"
-```
-
-## Module-Level Documentation
-
-```rust
-//! # Parser Module
-//!
-//! This module provides parsing utilities.
-//!
-//! ## Main Types
-//!
-//! - [`Parser`] - The main parser struct
-//! - [`Token`] - Tokens produced by tokenization
-//! - [`Ast`] - The abstract syntax tree
-//!
-//! ## Functions
-//!
-//! - [`parse`] - Parse a string
-//! - [`parse_file`] - Parse a file
-//!
-//! ## Errors
-//!
-//! All functions return [`ParseError`] on failure.
-
-pub struct Parser { ... }
-pub enum Token { ... }
-pub struct Ast { ... }
-```
-
-## See Also
-
-- [doc-examples-section](./doc-examples-section.md) - Code examples in docs
-- [err-doc-errors](./err-doc-errors.md) - Documenting errors
-- [lint-deny-correctness](./lint-deny-correctness.md) - Lint settings

package/template/agent/skills/rust-developer/references/rust-rules/doc-module-inner.md

@@ -1,116 +0,0 @@
-# doc-module-inner
-
-> Use `//!` for module-level documentation
-
-## Why It Matters
-
-Inner doc comments (`//!`) document the module itself, not the next item. They appear at the top of module files and describe the module's purpose, contents, and usage patterns. This helps users understand what a module provides before diving into individual items.
-
-Module docs are the first thing users see in `cargo doc` when navigating to a module.
-
-## Bad
-
-```rust
-// This module handles authentication
-// It provides JWT and session-based auth
-
-mod auth;
-
-pub use auth::*;
-```
-
-```rust
-// auth.rs
-/// Authentication utilities  // Wrong: this documents nothing useful
-use std::collections::HashMap;
-
-pub struct Session { /* ... */ }
-```
-
-## Good
-
-```rust
-//! Authentication and authorization utilities.
-//!
-//! This module provides multiple authentication strategies:
-//!
-//! - [`JwtAuth`] - JSON Web Token based authentication
-//! - [`SessionAuth`] - Cookie-based session authentication
-//! - [`ApiKeyAuth`] - API key authentication for services
-//!
-//! # Examples
-//!
-//! ```
-//! use my_crate::auth::{JwtAuth, Authenticator};
-//!
-//! let auth = JwtAuth::new("secret-key");
-//! let token = auth.generate_token(&user)?;
-//! ```
-//!
-//! # Feature Flags
-//!
-//! - `jwt` - Enables JWT authentication (enabled by default)
-//! - `sessions` - Enables session-based authentication
-
-use std::collections::HashMap;
-
-pub struct Session { /* ... */ }
-```
-
-## Where to Use Inner Docs
-
-| Location | Purpose |
-|----------|---------|
-| `lib.rs` | Crate-level documentation (appears on crate root) |
-| `mod.rs` | Module documentation for directory modules |
-| `module.rs` | Module documentation for single-file modules |
-
-## Crate Root Example
-
-```rust
-//! # My Awesome Crate
-//!
-//! `my_crate` provides utilities for handling complex workflows.
-//!
-//! ## Quick Start
-//!
-//! ```rust
-//! use my_crate::prelude::*;
-//!
-//! let workflow = Workflow::builder()
-//!     .add_step(Step::new("fetch"))
-//!     .add_step(Step::new("process"))
-//!     .build();
-//! ```
-//!
-//! ## Modules
-//!
-//! - [`workflow`] - Core workflow engine
-//! - [`steps`] - Built-in workflow steps
-//! - [`prelude`] - Common imports
-//!
-//! ## Feature Flags
-//!
-//! | Feature | Description |
-//! |---------|-------------|
-//! | `async` | Async workflow execution |
-//! | `serde` | Serialization support |
-
-pub mod workflow;
-pub mod steps;
-pub mod prelude;
-```
-
-## Key Sections for Module Docs
-
-1. **Brief description** - One-line summary
-2. **Overview** - What the module provides
-3. **Examples** - How to use it
-4. **Feature flags** - Optional functionality
-5. **See Also** - Related modules
-
-## See Also
-
-- [doc-all-public](./doc-all-public.md) - Documenting public items
-- [doc-examples-section](./doc-examples-section.md) - Adding examples
-- [doc-cargo-metadata](./doc-cargo-metadata.md) - Crate metadata

package/template/agent/skills/rust-developer/references/rust-rules/doc-panics-section.md

@@ -1,128 +0,0 @@
-# doc-panics-section
-
-> Include `# Panics` section for functions that can panic
-
-## Why It Matters
-
-Panics are exceptional conditions that crash the program (or unwind the stack). Users need to know when a function might panic so they can ensure preconditions are met or avoid the function in contexts where panics are unacceptable (e.g., `no_std`, embedded, FFI).
-
-If a function can panic, document exactly when.
-
-## Bad
-
-```rust
-/// Returns the element at the given index.
-pub fn get(index: usize) -> &T {
-    &self.data[index]  // Panics if out of bounds - not documented!
-}
-
-/// Divides two numbers.
-pub fn divide(a: i32, b: i32) -> i32 {
-    a / b  // Panics on division by zero - not documented!
-}
-```
-
-## Good
-
-```rust
-/// Returns the element at the given index.
-///
-/// # Panics
-///
-/// Panics if `index` is out of bounds (i.e., `index >= self.len()`).
-///
-/// # Examples
-///
-/// ```
-/// let v = vec![1, 2, 3];
-/// assert_eq!(v.get(1), &2);
-/// ```
-pub fn get(&self, index: usize) -> &T {
-    &self.data[index]
-}
-
-/// Divides two numbers.
-///
-/// # Panics
-///
-/// Panics if `divisor` is zero.
-///
-/// For a non-panicking version, use [`checked_divide`].
-pub fn divide(dividend: i32, divisor: i32) -> i32 {
-    dividend / divisor
-}
-
-/// Divides two numbers, returning `None` if the divisor is zero.
-pub fn checked_divide(dividend: i32, divisor: i32) -> Option<i32> {
-    if divisor == 0 {
-        None
-    } else {
-        Some(dividend / divisor)
-    }
-}
-```
-
-## Common Panic Conditions
-
-| Operation | Panic Condition |
-|-----------|-----------------|
-| Index access `[i]` | Index out of bounds |
-| Division `/`, `%` | Division by zero |
-| `.unwrap()` | `None` or `Err` value |
-| `.expect()` | `None` or `Err` value |
-| `slice::split_at(mid)` | `mid > len` |
-| `Vec::remove(i)` | `i >= len` |
-| Overflow (debug) | Integer overflow |
-
-## Pattern: Panic vs Return Error
-
-Document why you chose to panic vs return `Result`:
-
-```rust
-/// Creates a new buffer with the given capacity.
-///
-/// # Panics
-///
-/// Panics if `capacity` is zero. A buffer must have at least
-/// one byte of capacity.
-///
-/// This panics rather than returning an error because a zero-capacity
-/// buffer represents a programming error, not a runtime condition.
-pub fn new(capacity: usize) -> Self {
-    assert!(capacity > 0, "capacity must be non-zero");
-    // ...
-}
-```
-
-## Pattern: Debug-Only Panics
-
-```rust
-/// Adds an item to the collection.
-///
-/// # Panics
-///
-/// In debug builds, panics if the collection is at capacity.
-/// In release builds, this is a no-op when at capacity.
-pub fn push(&mut self, item: T) {
-    debug_assert!(self.len < self.capacity, "collection at capacity");
-    // ...
-}
-```
-
-## Provide Non-Panicking Alternatives
-
-When documenting a panicking function, point to safe alternatives:
-
-```rust
-/// # Panics
-///
-/// Panics if the index is out of bounds.
-///
-/// For a non-panicking version, use [`get`] which returns `Option<&T>`.
-```
-
-## See Also
-
-- [doc-errors-section](./doc-errors-section.md) - Documenting errors
-- [doc-safety-section](./doc-safety-section.md) - Documenting unsafe
-- [err-result-over-panic](./err-result-over-panic.md) - Preferring Result

package/template/agent/skills/rust-developer/references/rust-rules/doc-question-mark.md

@@ -1,136 +0,0 @@
-# doc-question-mark
-
-> Use `?` in examples, not `.unwrap()`
-
-## Why It Matters
-
-Doc examples should model best practices. Using `.unwrap()` teaches users to ignore errors, while `?` demonstrates proper error propagation. Examples with `?` also fail the doctest if an error occurs, catching bugs in documentation.
-
-Rust doctests wrap examples in a function that returns `Result<(), E>` by default when you use `?`, making this pattern easy to adopt.
-
-## Bad
-
-```rust
-/// Reads a configuration file.
-///
-/// # Examples
-///
-/// ```
-/// let config = Config::from_file("config.toml").unwrap();
-/// println!("{:?}", config.database_url);
-/// ```
-pub fn from_file(path: &str) -> Result<Config, Error> {
-    // ...
-}
-
-/// Fetches data from the API.
-///
-/// # Examples
-///
-/// ```
-/// let client = Client::new();
-/// let response = client.get("https://api.example.com").unwrap();
-/// let data: Data = response.json().unwrap();
-/// ```
-pub async fn get(&self, url: &str) -> Result<Response, Error> {
-    // ...
-}
-```
-
-## Good
-
-```rust
-/// Reads a configuration file.
-///
-/// # Examples
-///
-/// ```
-/// # use my_crate::{Config, Error};
-/// # fn main() -> Result<(), Error> {
-/// let config = Config::from_file("config.toml")?;
-/// println!("{:?}", config.database_url);
-/// # Ok(())
-/// # }
-/// ```
-pub fn from_file(path: &str) -> Result<Config, Error> {
-    // ...
-}
-
-/// Fetches data from the API.
-///
-/// # Examples
-///
-/// ```no_run
-/// # use my_crate::{Client, Data, Error};
-/// # async fn example() -> Result<(), Error> {
-/// let client = Client::new();
-/// let response = client.get("https://api.example.com").await?;
-/// let data: Data = response.json().await?;
-/// # Ok(())
-/// # }
-/// ```
-pub async fn get(&self, url: &str) -> Result<Response, Error> {
-    // ...
-}
-```
-
-## Doctest Wrapper Pattern
-
-Rust wraps doc examples in a function. You can make this explicit:
-
-```rust
-/// # Examples
-///
-/// ```
-/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
-/// let value = parse_config("key=value")?;
-/// assert_eq!(value.key, "value");
-/// # Ok(())
-/// # }
-/// ```
-```
-
-Or use the implicit wrapper (Rust 2021+):
-
-```rust
-/// # Examples
-///
-/// ```
-/// # use my_crate::parse_config;
-/// let value = parse_config("key=value")?;
-/// assert_eq!(value.key, "value");
-/// # Ok::<(), my_crate::Error>(())
-/// ```
-```
-
-## When to Use `.unwrap()`
-
-There are specific cases where `.unwrap()` is acceptable in examples:
-
-```rust
-/// # Examples
-///
-/// ```
-/// // Static regex that is known at compile time to be valid
-/// let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
-///
-/// // Parsing a literal that cannot fail
-/// let n: i32 = "42".parse().unwrap();
-/// ```
-```
-
-But still prefer `?` when demonstrating error handling patterns.
-
-## Comparison
-
-| Pattern | Behavior on Error | Teaches |
-|---------|-------------------|---------|
-| `.unwrap()` | Panics with generic message | Bad habits |
-| `.expect()` | Panics with custom message | Slightly better |
-| `?` | Propagates error, test fails | Best practices |
-
-## See Also
-
-- [doc-examples-section](./doc-examples-section.md) - Writing examples
-- [doc-hidden-setup](./doc-hidden-setup.md) - Hiding setup code
-- [err-question-mark](./err-question-mark.md) - Error propagation

package/template/agent/skills/rust-developer/references/rust-rules/doc-safety-section.md

@@ -1,131 +0,0 @@
-# doc-safety-section
-
-> Include `# Safety` section for unsafe functions
-
-## Why It Matters
-
-Unsafe functions require callers to uphold invariants that the compiler cannot verify. The `# Safety` section documents exactly what the caller must guarantee for the function to be sound. Without this, users cannot safely call the function.
-
-This is not optional—it's a requirement for sound unsafe code.
-
-## Bad
-
-```rust
-/// Reads a value from a raw pointer.
-pub unsafe fn read_ptr<T>(ptr: *const T) -> T {
-    // What guarantees must the caller provide? Unknown!
-    ptr.read()
-}
-
-/// Creates a string from raw parts.
-pub unsafe fn string_from_raw(ptr: *mut u8, len: usize, cap: usize) -> String {
-    String::from_raw_parts(ptr, len, cap)
-}
-```
-
-## Good
-
-```rust
-/// Reads a value from a raw pointer.
-///
-/// # Safety
-///
-/// The caller must ensure that:
-/// - `ptr` is valid for reads of `size_of::<T>()` bytes
-/// - `ptr` is properly aligned for type `T`
-/// - `ptr` points to a properly initialized value of type `T`
-/// - The memory referenced by `ptr` is not mutated during this call
-pub unsafe fn read_ptr<T>(ptr: *const T) -> T {
-    ptr.read()
-}
-
-/// Creates a `String` from raw parts.
-///
-/// # Safety
-///
-/// The caller must guarantee that:
-/// - `ptr` was allocated by the same allocator that `String` uses
-/// - `len` is less than or equal to `cap`
-/// - The first `len` bytes at `ptr` are valid UTF-8
-/// - `cap` is the capacity that `ptr` was allocated with
-/// - No other code will use `ptr` after this call (ownership is transferred)
-///
-/// Violating these requirements leads to undefined behavior including
-/// memory corruption, use-after-free, or invalid UTF-8 in strings.
-pub unsafe fn string_from_raw(ptr: *mut u8, len: usize, cap: usize) -> String {
-    String::from_raw_parts(ptr, len, cap)
-}
-```
-
-## Key Elements of Safety Documentation
-
-| Element | Description |
-|---------|-------------|
-| **Preconditions** | What must be true before calling |
-| **Pointer validity** | Alignment, null-ness, lifetime |
-| **Memory ownership** | Who owns what, transfer semantics |
-| **Invariants** | Type invariants that must hold |
-| **Consequences** | What happens if violated |
-
-## Pattern: Unsafe Trait Implementations
-
-```rust
-/// A type that can be safely zeroed.
-///
-/// # Safety
-///
-/// Implementing this trait guarantees that:
-/// - All bit patterns of zeros represent a valid value of this type
-/// - The type has no padding bytes that could leak data
-/// - The type contains no references or pointers
-pub unsafe trait Zeroable {
-    fn zeroed() -> Self;
-}
-
-// SAFETY: u32 is a primitive integer type where all zero bits
-// represent a valid value (0).
-unsafe impl Zeroable for u32 {
-    fn zeroed() -> Self {
-        0
-    }
-}
-```
-
-## Pattern: Unsafe Blocks in Safe Functions
-
-When a safe function contains unsafe blocks, document the invariants:
-
-```rust
-/// Returns a reference to the element at the given index.
-///
-/// Returns `None` if the index is out of bounds.
-pub fn get(&self, index: usize) -> Option<&T> {
-    if index < self.len {
-        // SAFETY: We just verified that index < len, so this
-        // access is within bounds.
-        Some(unsafe { self.data.get_unchecked(index) })
-    } else {
-        None
-    }
-}
-```
-
-## Common Safety Requirements
-
-```rust
-/// # Safety
-///
-/// - Pointer must be non-null
-/// - Pointer must be aligned to `align_of::<T>()`
-/// - Pointer must be valid for reads/writes of `size_of::<T>()` bytes
-/// - Pointer must point to an initialized value of `T`
-/// - The referenced memory must not be accessed through any other pointer
-///   for the duration of the returned reference
-/// - The total size must not exceed `isize::MAX`
-```
-
-## See Also
-
-- [doc-panics-section](./doc-panics-section.md) - Documenting panics
-- [lint-unsafe-doc](./lint-unsafe-doc.md) - Enforcing unsafe documentation
-- [doc-errors-section](./doc-errors-section.md) - Documenting errors