agy-superpowers 5.1.4 → 5.1.5

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

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

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

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

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

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