agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/lint-cargo-metadata.md

@@ -0,0 +1,138 @@
+# lint-cargo-metadata
+
+> Enable clippy::cargo for published crates
+
+## Why It Matters
+
+The `clippy::cargo` lint group checks Cargo.toml for issues that affect publishing and dependency management. For crates intended for crates.io, these checks help ensure a professional, well-configured package.
+
+## Configuration
+
+```toml
+# Cargo.toml
+[lints.clippy]
+cargo = "warn"
+```
+
+Or in code:
+
+```rust
+#![warn(clippy::cargo)]
+```
+
+## What It Catches
+
+### Missing Metadata
+
+```toml
+# WARN: missing package.description
+# WARN: missing package.license or package.license-file
+# WARN: missing package.repository
+[package]
+name = "my-crate"
+version = "0.1.0"
+```
+
+### Dependency Issues
+
+```toml
+# WARN: feature used but not defined
+# WARN: dependency version not specified
+[dependencies]
+serde = "*"  # Bad: any version
+tokio = { git = "..." }  # WARN for published crates
+```
+
+### Feature Issues
+
+```toml
+# WARN: negative_feature_names
+[features]
+no-std = []  # Should be: std = [] (opt-out vs opt-in)
+
+# WARN: redundant_feature_names
+[features]
+default = ["feature-a"]
+feature-a = []  # Feature name matches crate name
+```
+
+## Notable Lints
+
+| Lint | Issue |
+|------|-------|
+| `cargo_common_metadata` | Missing description/license/repository |
+| `multiple_crate_versions` | Same crate at different versions |
+| `negative_feature_names` | Features like `no-std` instead of `std` |
+| `redundant_feature_names` | Feature same as crate name |
+| `wildcard_dependencies` | Using `*` for version |
+
+## Complete Cargo.toml
+
+```toml
+[package]
+name = "my-crate"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.70"
+
+# Required for cargo lint satisfaction
+description = "A short description of what this crate does"
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/user/my-crate"
+
+# Recommended
+documentation = "https://docs.rs/my-crate"
+readme = "README.md"
+keywords = ["keyword1", "keyword2"]
+categories = ["category-slug"]
+
+[dependencies]
+# Specific versions, not wildcards
+serde = "1.0"
+tokio = { version = "1.0", features = ["full"] }
+
+[features]
+default = ["std"]
+std = []  # Opt-out, not no-std opt-in
+
+[lints.clippy]
+cargo = "warn"
+```
+
+## Multiple Crate Versions
+
+```
+# WARN: multiple versions of `syn` in dependency tree
+# syn v1.0.109
+# syn v2.0.48
+```
+
+Fix by updating dependencies or using `[patch]`:
+
+```toml
+[patch.crates-io]
+old-dep = { git = "...", branch = "syn-2" }
+```
+
+## When to Disable
+
+For internal/unpublished crates:
+
+```toml
+[lints.clippy]
+cargo = "allow"  # Not publishing, metadata not needed
+```
+
+Or selectively:
+
+```toml
+[lints.clippy]
+cargo = "warn"
+multiple_crate_versions = "allow"  # Acceptable in this project
+```
+
+## See Also
+
+- [doc-cargo-metadata](./doc-cargo-metadata.md) - Cargo.toml metadata
+- [proj-workspace-deps](./proj-workspace-deps.md) - Workspace dependencies
+- [lint-deny-correctness](./lint-deny-correctness.md) - Correctness lints

package/template/agent/skills/rust-developer/references/rust-rules/lint-deny-correctness.md

@@ -0,0 +1,107 @@
+# lint-deny-correctness
+
+> `#![deny(clippy::correctness)]`
+
+## Why It Matters
+
+Clippy's correctness lints catch code that is outright wrong - logic errors, undefined behavior, or code that doesn't do what you think. These should always be errors, not warnings.
+
+## Setup
+
+```rust
+// At the top of lib.rs or main.rs
+#![deny(clippy::correctness)]
+
+// Or in Cargo.toml for workspace-wide
+[lints.clippy]
+correctness = "deny"
+```
+
+## What It Catches
+
+```rust
+// Infinite loop (iter::repeat without take)
+for x in std::iter::repeat(1) {  // ERROR: infinite iterator
+    println!("{}", x);
+}
+
+// Comparison to NaN (always false)
+if x == f64::NAN {  // ERROR: NaN != NaN always
+    // This never executes
+}
+
+// Use after free patterns
+let r;
+{
+    let x = 5;
+    r = &x;  // ERROR: x dropped here
+}
+println!("{}", r);
+
+// Wrong equality check
+if x = 5 {  // ERROR: assignment in condition (should be ==)
+}
+
+// Useless comparisons
+if x >= 0 && x < 0 {  // ERROR: impossible condition
+}
+```
+
+## Important Correctness Lints
+
+```rust
+// approx_constant - using imprecise PI, E values
+let pi = 3.14;  // Use std::f64::consts::PI
+
+// invalid_regex - regex that won't compile
+let re = Regex::new("[");  // Invalid regex
+
+// iter_next_loop - using .next() in for loop incorrectly
+for x in iter.next() {  // Should be: for x in iter
+
+// never_loop - loop that never actually loops
+loop {
+    break;  // Always breaks immediately
+}
+
+// nonsensical_open_options - impossible file options
+File::options().read(false).write(false).open("f");
+
+// unit_cmp - comparing unit type ()
+if foo() == bar() { }  // Both return (), always true
+```
+
+## Full Recommended Lints
+
+```rust
+#![deny(clippy::correctness)]
+#![warn(clippy::suspicious)]
+#![warn(clippy::style)]
+#![warn(clippy::complexity)]
+#![warn(clippy::perf)]
+
+// For published crates
+#![warn(missing_docs)]
+#![warn(clippy::cargo)]
+```
+
+## Running Clippy
+
+```bash
+# Basic check
+cargo clippy
+
+# With all warnings as errors
+cargo clippy -- -D warnings
+
+# Check specific lint category
+cargo clippy -- -W clippy::correctness
+
+# In CI (fail on warnings)
+cargo clippy -- -D warnings -D clippy::correctness
+```
+
+## See Also
+
+- [lint-warn-suspicious](lint-warn-suspicious.md) - Warn on suspicious code
+- [lint-warn-perf](lint-warn-perf.md) - Warn on performance issues

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