agy-superpowers 5.2.2 → 5.2.4

package/template/agent/skills/rust-developer/references/rust-rules/lint-missing-docs.md

@@ -1,154 +0,0 @@
-# lint-missing-docs
-
-> Warn on missing documentation for public items
-
-## Why It Matters
-
-The `missing_docs` lint ensures all public API items are documented. For libraries, documentation IS the user interface. Missing docs mean users can't understand your API without reading source code.
-
-## Configuration
-
-```rust
-// In lib.rs
-#![warn(missing_docs)]
-```
-
-Or in `Cargo.toml`:
-
-```toml
-[lints.rust]
-missing_docs = "warn"
-```
-
-For strict enforcement:
-
-```rust
-#![deny(missing_docs)]
-```
-
-## What It Catches
-
-```rust
-#![warn(missing_docs)]
-
-pub struct User {  // WARN: missing documentation for a struct
-    pub name: String,  // WARN: missing documentation for a field
-    pub age: u32,      // WARN: missing documentation for a field
-}
-
-pub fn process() { }  // WARN: missing documentation for a function
-
-pub trait Handler {  // WARN: missing documentation for a trait
-    fn handle(&self);  // WARN: missing documentation for a method
-}
-```
-
-## Good
-
-```rust
-#![warn(missing_docs)]
-
-//! User management module.
-
-/// Represents a registered user in the system.
-pub struct User {
-    /// The user's display name.
-    pub name: String,
-    /// The user's age in years.
-    pub age: u32,
-}
-
-/// Processes pending user requests.
-///
-/// # Examples
-///
-/// ```
-/// process();
-/// ```
-pub fn process() { }
-
-/// Handler trait for request processing.
-pub trait Handler {
-    /// Handle an incoming request.
-    fn handle(&self);
-}
-```
-
-## Private Items
-
-`missing_docs` only applies to `pub` items. Private items don't trigger warnings:
-
-```rust
-#![warn(missing_docs)]
-
-struct Internal { }  // No warning - private
-
-pub struct Public { }  // WARN - public, needs docs
-```
-
-## Allow for Specific Items
-
-```rust
-#![warn(missing_docs)]
-
-/// Documented module.
-pub mod api {
-    /// Documented struct.
-    pub struct Config { }
-    
-    #[allow(missing_docs)]
-    pub mod internal {
-        // Internal API, docs not required
-        pub struct Helper { }
-    }
-}
-```
-
-## Gradual Adoption
-
-For existing codebases, start with `warn` and fix incrementally:
-
-```rust
-// Phase 1: Warn, fix critical items
-#![warn(missing_docs)]
-
-// Phase 2: After cleanup, deny
-#![deny(missing_docs)]
-```
-
-## Combining with doc Attributes
-
-```rust
-#![warn(missing_docs)]
-#![warn(rustdoc::broken_intra_doc_links)]
-#![warn(rustdoc::private_intra_doc_links)]
-```
-
-## Workspace Configuration
-
-```toml
-# In workspace Cargo.toml
-[workspace.lints.rust]
-missing_docs = "warn"
-
-# Member crates inherit
-[lints]
-workspace = true
-```
-
-## What to Document
-
-| Item | Doc Focus |
-|------|-----------|
-| Structs | Purpose, usage example |
-| Struct fields | What it represents |
-| Enums | When to use each variant |
-| Functions | What it does, params, return |
-| Traits | Contract and expectations |
-| Modules | What the module provides |
-
-## See Also
-
-- [doc-all-public](./doc-all-public.md) - Documentation patterns
-- [lint-unsafe-doc](./lint-unsafe-doc.md) - Unsafe documentation
-- [doc-examples-section](./doc-examples-section.md) - Adding examples

package/template/agent/skills/rust-developer/references/rust-rules/lint-pedantic-selective.md

@@ -1,118 +0,0 @@
-# lint-pedantic-selective
-
-> Enable clippy::pedantic selectively
-
-## Why It Matters
-
-The `clippy::pedantic` group contains opinionated lints that aren't universally applicable. Enabling it wholesale produces noise; selectively enabling useful pedantic lints improves code quality without false positives.
-
-## Bad
-
-```rust
-// Too noisy - will fight you constantly
-#![warn(clippy::pedantic)]
-```
-
-## Good
-
-```toml
-# Cargo.toml - cherry-pick useful pedantic lints
-[lints.clippy]
-# Enable pedantic as baseline
-pedantic = "warn"
-
-# Disable noisy ones
-missing_errors_doc = "allow"      # Document errors separately
-missing_panics_doc = "allow"      # Document panics separately
-module_name_repetitions = "allow" # Allow Foo::FooError pattern
-too_many_lines = "allow"          # Function length varies
-must_use_candidate = "allow"      # Too many suggestions
-```
-
-## Recommended Pedantic Lints
-
-| Lint | Why Enable |
-|------|-----------|
-| `doc_markdown` | Catch unmarked code in docs |
-| `match_wildcard_for_single_variants` | Explicit variant matching |
-| `semicolon_if_nothing_returned` | Consistent semicolons |
-| `string_add_assign` | Use `+=` for string concatenation |
-| `unnested_or_patterns` | Simplify match patterns |
-| `unused_self` | Catch methods that should be functions |
-| `used_underscore_binding` | Warn on using `_var` |
-| `wildcard_imports` | Avoid glob imports |
-
-## Often Disabled
-
-| Lint | Why Disable |
-|------|-------------|
-| `missing_errors_doc` | Handle with `#[doc]` policy |
-| `missing_panics_doc` | Handle with `#[doc]` policy |
-| `module_name_repetitions` | Sometimes intentional |
-| `must_use_candidate` | Too aggressive |
-| `too_many_lines` | Arbitrary threshold |
-| `struct_excessive_bools` | Valid for config structs |
-
-## Full Configuration
-
-```toml
-# Cargo.toml
-[lints.clippy]
-# Start with pedantic
-pedantic = "warn"
-
-# Keep these
-doc_markdown = "warn"
-match_wildcard_for_single_variants = "warn"
-semicolon_if_nothing_returned = "warn"
-unused_self = "warn"
-wildcard_imports = "warn"
-
-# Disable these
-missing_errors_doc = "allow"
-missing_panics_doc = "allow"
-module_name_repetitions = "allow"
-must_use_candidate = "allow"
-too_many_lines = "allow"
-similar_names = "allow"
-struct_excessive_bools = "allow"
-```
-
-## Alternative: Explicit Opt-in
-
-```toml
-# Only enable specific lints, not the group
-[lints.clippy]
-# From pedantic, only these:
-doc_markdown = "warn"
-semicolon_if_nothing_returned = "warn"
-unused_self = "warn"
-wildcard_imports = "warn"
-```
-
-## Module-Level Overrides
-
-```rust
-// Allow specific lint for a module
-#![allow(clippy::module_name_repetitions)]
-
-// Or for specific items
-#[allow(clippy::too_many_arguments)]
-fn complex_function(/* many args */) { }
-```
-
-## Team Consensus
-
-Pedantic lints are style choices. Agree as a team:
-
-1. Enable `pedantic` as baseline
-2. Run `cargo clippy` on codebase
-3. Discuss each warning category
-4. Disable ones that don't fit your style
-5. Document decisions in `clippy.toml`
-
-## See Also
-
-- [lint-warn-style](./lint-warn-style.md) - Style warnings
-- [lint-warn-complexity](./lint-warn-complexity.md) - Complexity warnings
-- [lint-deny-correctness](./lint-deny-correctness.md) - Correctness lints

package/template/agent/skills/rust-developer/references/rust-rules/lint-rustfmt-check.md

@@ -1,157 +0,0 @@
-# lint-rustfmt-check
-
-> Run cargo fmt --check in CI
-
-## Why It Matters
-
-Consistent formatting eliminates style debates and makes diffs cleaner. Running `cargo fmt --check` in CI ensures all code follows the same format. This catches formatting issues before merge, not after.
-
-## CI Configuration
-
-### GitHub Actions
-
-```yaml
-name: CI
-
-on: [push, pull_request]
-
-jobs:
-  fmt:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-        with:
-          components: rustfmt
-      - run: cargo fmt --all --check
-```
-
-### GitLab CI
-
-```yaml
-fmt:
-  image: rust:latest
-  script:
-    - rustup component add rustfmt
-    - cargo fmt --all --check
-```
-
-### Pre-commit Hook
-
-```bash
-#!/bin/sh
-# .git/hooks/pre-commit
-cargo fmt --all --check
-```
-
-## Configuration
-
-Create `rustfmt.toml` for custom settings:
-
-```toml
-# rustfmt.toml
-edition = "2021"
-max_width = 100
-use_small_heuristics = "Max"
-imports_granularity = "Module"
-group_imports = "StdExternalCrate"
-reorder_imports = true
-```
-
-## Common Options
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `max_width` | 100 | Maximum line width |
-| `tab_spaces` | 4 | Spaces per indent |
-| `edition` | "2015" | Rust edition |
-| `use_small_heuristics` | "Default" | Layout heuristics |
-| `imports_granularity` | "Preserve" | Import grouping |
-| `group_imports` | "Preserve" | Import ordering |
-
-## Running Locally
-
-```bash
-# Check formatting (doesn't modify files)
-cargo fmt --all --check
-
-# Apply formatting
-cargo fmt --all
-
-# Format specific file
-cargo fmt -- src/main.rs
-
-# Check with verbose output
-cargo fmt --all --check -- --verbose
-```
-
-## Workspace Formatting
-
-```bash
-# Format all workspace members
-cargo fmt --all
-
-# Format specific package
-cargo fmt -p my-package
-```
-
-## Ignoring Files
-
-In `rustfmt.toml`:
-
-```toml
-# Skip generated files
-ignore = [
-    "src/generated/*",
-    "build.rs",
-]
-```
-
-Or in code:
-
-```rust
-#[rustfmt::skip]
-mod generated_code;
-
-#[rustfmt::skip]
-const MATRIX: [[i32; 4]; 4] = [
-    [1, 0, 0, 0],
-    [0, 1, 0, 0],
-    [0, 0, 1, 0],
-    [0, 0, 0, 1],
-];
-```
-
-## Nightly Features
-
-Some options require nightly:
-
-```toml
-# rustfmt.toml (nightly only)
-unstable_features = true
-imports_granularity = "Crate"
-wrap_comments = true
-format_code_in_doc_comments = true
-```
-
-```bash
-# Use nightly rustfmt
-cargo +nightly fmt
-```
-
-## IDE Integration
-
-Most IDEs format on save. Configure to use project `rustfmt.toml`:
-
-```json
-// VS Code settings.json
-{
-  "rust-analyzer.rustfmt.extraArgs": ["--config-path", "./rustfmt.toml"]
-}
-```
-
-## See Also
-
-- [lint-warn-style](./lint-warn-style.md) - Style lints
-- [lint-pedantic-selective](./lint-pedantic-selective.md) - Pedantic lints
-- [name-funcs-snake](./name-funcs-snake.md) - Naming conventions

package/template/agent/skills/rust-developer/references/rust-rules/lint-unsafe-doc.md

@@ -1,133 +0,0 @@
-# lint-unsafe-doc
-
-> Require documentation for unsafe blocks
-
-## Why It Matters
-
-The `undocumented_unsafe_blocks` lint ensures every unsafe block has a `// SAFETY:` comment explaining why the operation is sound. Unsafe code is the source of most memory safety bugs—documenting invariants catches mistakes and helps reviewers.
-
-## Configuration
-
-```rust
-#![warn(clippy::undocumented_unsafe_blocks)]
-```
-
-Or in `Cargo.toml`:
-
-```toml
-[lints.clippy]
-undocumented_unsafe_blocks = "warn"
-```
-
-For strict enforcement:
-
-```toml
-[lints.clippy]
-undocumented_unsafe_blocks = "deny"
-```
-
-## Bad
-
-```rust
-pub fn read_data(ptr: *const u8, len: usize) -> &[u8] {
-    unsafe {
-        std::slice::from_raw_parts(ptr, len)  // WARN: undocumented
-    }
-}
-
-impl Buffer {
-    pub fn get_unchecked(&self, index: usize) -> &u8 {
-        unsafe { self.data.get_unchecked(index) }  // WARN
-    }
-}
-```
-
-## Good
-
-```rust
-pub fn read_data(ptr: *const u8, len: usize) -> &[u8] {
-    // SAFETY: Caller guarantees:
-    // - ptr is valid for reads of len bytes
-    // - ptr is properly aligned for u8
-    // - the memory is initialized
-    // - no mutable references exist to this memory
-    unsafe {
-        std::slice::from_raw_parts(ptr, len)
-    }
-}
-
-impl Buffer {
-    pub fn get_unchecked(&self, index: usize) -> &u8 {
-        debug_assert!(index < self.len(), "index out of bounds");
-        // SAFETY: We verified index < len in debug builds.
-        // Callers must ensure index is within bounds.
-        unsafe { self.data.get_unchecked(index) }
-    }
-}
-```
-
-## SAFETY Comment Format
-
-```rust
-// SAFETY: <explanation of why this is sound>
-unsafe {
-    // ...
-}
-```
-
-The comment should explain:
-1. **What invariants are upheld** - preconditions that make this safe
-2. **Why the invariants hold** - how you know they're satisfied
-3. **What could go wrong** - if invariants are violated
-
-## Examples by Category
-
-### Pointer Operations
-
-```rust
-// SAFETY: ptr was obtained from Box::into_raw, so it's valid
-// and properly aligned. We're taking back ownership.
-let boxed = unsafe { Box::from_raw(ptr) };
-```
-
-### Unchecked Operations
-
-```rust
-// SAFETY: We just checked that i < self.len() above.
-// The bounds check cannot be elided by the optimizer
-// because len() is not inlined.
-unsafe { self.data.get_unchecked(i) }
-```
-
-### FFI Calls
-
-```rust
-// SAFETY: libc::getenv is safe to call with a null-terminated
-// string. We ensure null termination with CString::new.
-// The returned pointer is valid for the lifetime of the environment.
-let value = unsafe { libc::getenv(key.as_ptr()) };
-```
-
-### Trait Implementations
-
-```rust
-// SAFETY: MyType contains no pointers or interior mutability,
-// and all bit patterns are valid MyType values.
-unsafe impl Send for MyType {}
-unsafe impl Sync for MyType {}
-```
-
-## Related Lints
-
-```toml
-[lints.clippy]
-undocumented_unsafe_blocks = "warn"
-# Also consider:
-multiple_unsafe_ops_per_block = "warn"  # One operation per block
-```
-
-## See Also
-
-- [doc-safety-section](./doc-safety-section.md) - `# Safety` in docs
-- [lint-deny-correctness](./lint-deny-correctness.md) - Correctness lints
-- [type-repr-transparent](./type-repr-transparent.md) - FFI safety

package/template/agent/skills/rust-developer/references/rust-rules/lint-warn-complexity.md

@@ -1,131 +0,0 @@
-# lint-warn-complexity
-
-> Enable clippy::complexity for simpler code
-
-## Why It Matters
-
-The `clippy::complexity` lint group identifies unnecessarily complex code that can be simplified. Complex code is harder to read, maintain, and often hides bugs. Clippy suggests cleaner alternatives.
-
-## Configuration
-
-```rust
-// In lib.rs or main.rs
-#![warn(clippy::complexity)]
-```
-
-Or in `Cargo.toml`:
-
-```toml
-[lints.clippy]
-complexity = "warn"
-```
-
-## What It Catches
-
-### Unnecessary Complexity
-
-```rust
-// WARN: Overly complex boolean expression
-if !(x == 0) { }  // Use: if x != 0 { }
-
-// WARN: Manual implementation of Option::map
-match option {
-    Some(x) => Some(x + 1),
-    None => None,
-}  // Use: option.map(|x| x + 1)
-
-// WARN: Unnecessary filter before count
-iter.filter(|x| predicate(x)).count()  // Could simplify if only counting
-```
-
-### Redundant Operations
-
-```rust
-// WARN: Redundant allocation
-let s = format!("literal");  // Use: "literal".to_string() or just "literal"
-
-// WARN: Unnecessarily complicated match
-match result {
-    Ok(ok) => Ok(ok),
-    Err(err) => Err(err),
-}  // Just use: result
-
-// WARN: Box::new in return position
-fn make_error() -> Box<dyn Error> {
-    Box::new(MyError)  // Could use: MyError.into()
-}
-```
-
-### Overly Verbose Code
-
-```rust
-// WARN: bind_instead_of_map
-option.and_then(|x| Some(x + 1))  // Use: option.map(|x| x + 1)
-
-// WARN: clone_on_copy
-let y = x.clone();  // Where x is Copy type, just use: let y = x;
-
-// WARN: useless_let_if_seq
-let result;
-if condition {
-    result = 1;
-} else {
-    result = 2;
-}
-// Use: let result = if condition { 1 } else { 2 };
-```
-
-## Notable Lints in This Group
-
-| Lint | Simplification |
-|------|---------------|
-| `bind_instead_of_map` | Use `map` instead of `and_then(Some(...))` |
-| `bool_comparison` | `if x == true` → `if x` |
-| `clone_on_copy` | Remove `.clone()` for Copy types |
-| `filter_next` | Use `.find()` instead |
-| `option_map_unit_fn` | Use `if let` instead |
-| `search_is_some` | Use `.any()` or `.contains()` |
-| `unnecessary_cast` | Remove redundant casts |
-| `useless_conversion` | Remove `.into()` when types match |
-
-## Examples
-
-```rust
-// Before (complexity warnings)
-fn find_positive(nums: &[i32]) -> Option<i32> {
-    let filtered: Vec<_> = nums.iter()
-        .cloned()
-        .filter(|x| *x > 0)
-        .collect();
-    if filtered.len() == 0 {
-        None
-    } else {
-        Some(filtered[0])
-    }
-}
-
-// After (simplified)
-fn find_positive(nums: &[i32]) -> Option<i32> {
-    nums.iter()
-        .copied()
-        .find(|&x| x > 0)
-}
-```
-
-## Cognitive Load
-
-Complex code isn't just longer—it's harder to understand:
-
-```rust
-// High cognitive load
-let value = if x.is_some() { x.unwrap() } else { y.unwrap_or(z) };
-
-// Lower cognitive load
-let value = x.unwrap_or_else(|| y.unwrap_or(z));
-```
-
-## See Also
-
-- [lint-warn-style](./lint-warn-style.md) - Style warnings
-- [lint-warn-perf](./lint-warn-perf.md) - Performance warnings
-- [lint-pedantic-selective](./lint-pedantic-selective.md) - Pedantic lints