agy-superpowers 5.1.4 → 5.1.5

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

@@ -0,0 +1,136 @@
+# lint-warn-perf
+
+> Enable clippy::perf for performance improvements
+
+## Why It Matters
+
+The `clippy::perf` lint group catches performance anti-patterns—inefficient allocations, unnecessary copies, suboptimal API usage. While not all performance issues are critical, avoiding obvious inefficiencies is good practice.
+
+## Configuration
+
+```rust
+// In lib.rs or main.rs
+#![warn(clippy::perf)]
+```
+
+Or in `Cargo.toml`:
+
+```toml
+[lints.clippy]
+perf = "warn"
+```
+
+## What It Catches
+
+### Unnecessary Allocations
+
+```rust
+// WARN: Unnecessary to_string before into
+fn take_string(s: impl Into<String>) { }
+take_string("hello".to_string());  // Just use: "hello"
+
+// WARN: Box::new in return with deref coercion
+fn make_trait() -> Box<dyn Trait> {
+    Box::new(concrete)  // Could use Into
+}
+
+// WARN: Unnecessary vec! for iteration
+for x in vec![1, 2, 3] { }  // Use array: [1, 2, 3]
+```
+
+### Inefficient Operations
+
+```rust
+// WARN: Single-character string patterns
+s.starts_with("x")  // Use char: 'x'
+s.contains("a")     // Use char: 'a'
+
+// WARN: iter().nth(0) instead of first()
+iter.nth(0)  // Use: iter.first() or iter.next()
+
+// WARN: Manual saturating arithmetic
+if x > i32::MAX - y { i32::MAX } else { x + y }
+// Use: x.saturating_add(y)
+```
+
+### Collection Inefficiencies
+
+```rust
+// WARN: extend with a single element
+vec.extend(std::iter::once(item));  // Use: vec.push(item)
+
+// WARN: Inefficient to_vec
+slice.iter().cloned().collect::<Vec<_>>()  // Use: slice.to_vec()
+
+// WARN: Manual string concatenation
+let s = format!("{}{}", a, b);  // When both are &str, use: a.to_owned() + b
+```
+
+## Notable Lints in This Group
+
+| Lint | Improvement |
+|------|-------------|
+| `box_collection` | Use `Vec<T>` not `Box<Vec<T>>` |
+| `iter_nth` | Use `.get(n)` or `.next()` |
+| `large_enum_variant` | Box large variants |
+| `manual_memcpy` | Use slice copy methods |
+| `redundant_allocation` | Remove double boxing |
+| `single_char_pattern` | Use `char` not `&str` |
+| `slow_vector_initialization` | Use `vec![0; n]` |
+| `unnecessary_to_owned` | Remove redundant `.to_owned()` |
+
+## Examples
+
+```rust
+// Before (perf warnings)
+fn process(input: &str) -> String {
+    let parts: Vec<_> = input.split(",").collect();
+    let mut result = String::new();
+    for part in parts.iter() {
+        if part.starts_with(" ") {
+            result = result + &part.trim().to_string();
+        }
+    }
+    result
+}
+
+// After (optimized)
+fn process(input: &str) -> String {
+    input.split(',')
+        .filter(|part| part.starts_with(' '))
+        .map(str::trim)
+        .collect()
+}
+```
+
+## Allocation Patterns
+
+```rust
+// Unnecessary allocation
+let vec: Vec<i32> = vec![];  // Creates capacity
+let vec: Vec<i32> = Vec::new();  // No allocation
+
+// Pre-allocation
+let mut vec = Vec::with_capacity(100);  // One allocation
+for i in 0..100 {
+    vec.push(i);  // No reallocation
+}
+```
+
+## String Patterns
+
+```rust
+// Slow: str pattern
+s.contains("x");
+s.find("y");
+
+// Fast: char pattern
+s.contains('x');
+s.find('y');
+```
+
+## See Also
+
+- [lint-warn-complexity](./lint-warn-complexity.md) - Complexity warnings
+- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocation
+- [perf-profile-first](./perf-profile-first.md) - Profile before optimizing

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

@@ -0,0 +1,135 @@
+# lint-warn-style
+
+> Enable clippy::style for idiomatic code
+
+## Why It Matters
+
+The `clippy::style` lint group enforces idiomatic Rust patterns. While not bugs, style violations make code harder to read and maintain. Consistent style helps teams work together and makes code easier to review.
+
+## Configuration
+
+```rust
+// In lib.rs or main.rs
+#![warn(clippy::style)]
+```
+
+Or in `Cargo.toml`:
+
+```toml
+[lints.clippy]
+style = "warn"
+```
+
+## What It Catches
+
+### Redundant Code
+
+```rust
+// WARN: Redundant clone on Copy type
+let x = 5;
+let y = x.clone();  // Just use: let y = x;
+
+// WARN: Redundant closure
+iter.map(|x| foo(x))  // Just use: iter.map(foo)
+
+// WARN: Redundant pattern matching
+match result {
+    Ok(x) => Ok(x),
+    Err(e) => Err(e),
+}  // Just return result
+```
+
+### Non-Idiomatic Patterns
+
+```rust
+// WARN: Should use if let
+match option {
+    Some(x) => do_something(x),
+    None => {},
+}
+// Better: if let Some(x) = option { do_something(x) }
+
+// WARN: Should use or_else
+let value = if option.is_some() {
+    option.unwrap()
+} else {
+    default()
+};
+// Better: option.unwrap_or_else(default)
+
+// WARN: Collapsible if statements
+if condition1 {
+    if condition2 {
+        do_something();
+    }
+}
+// Better: if condition1 && condition2 { do_something() }
+```
+
+### Naming Issues
+
+```rust
+// WARN: Function should not start with 'is_' returning non-bool
+fn is_valid() -> i32 { 0 }  // Misleading name
+
+// WARN: Method should not be named 'new' without returning Self
+impl Foo {
+    fn new() -> Bar { Bar }  // Confusing
+}
+```
+
+## Notable Lints in This Group
+
+| Lint | Better Pattern |
+|------|---------------|
+| `len_zero` | Use `is_empty()` instead of `len() == 0` |
+| `redundant_field_names` | Use shorthand `{ x }` not `{ x: x }` |
+| `unused_unit` | Remove `-> ()` and trailing `()` |
+| `collapsible_if` | Combine nested ifs with `&&` |
+| `single_match` | Use `if let` instead |
+| `match_like_matches_macro` | Use `matches!()` macro |
+| `needless_return` | Remove explicit `return` at end |
+| `question_mark` | Use `?` instead of `match` |
+
+## Examples
+
+```rust
+// Before (style warnings)
+fn process(data: Vec<i32>) -> Option<i32> {
+    if data.len() == 0 {
+        return None;
+    }
+    let first = match data.first() {
+        Some(x) => x,
+        None => return None,
+    };
+    return Some(*first);
+}
+
+// After (idiomatic)
+fn process(data: Vec<i32>) -> Option<i32> {
+    if data.is_empty() {
+        return None;
+    }
+    let first = data.first()?;
+    Some(*first)
+}
+```
+
+## Selective Allowance
+
+Some style lints may conflict with team preferences:
+
+```rust
+// If your team prefers explicit returns
+#[allow(clippy::needless_return)]
+fn explicit_return() -> i32 {
+    return 42;
+}
+```
+
+## See Also
+
+- [lint-warn-suspicious](./lint-warn-suspicious.md) - Suspicious patterns
+- [lint-warn-complexity](./lint-warn-complexity.md) - Complexity warnings
+- [lint-rustfmt-check](./lint-rustfmt-check.md) - Formatting checks

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

@@ -0,0 +1,122 @@
+# lint-warn-suspicious
+
+> Enable clippy::suspicious for likely bugs
+
+## Why It Matters
+
+The `clippy::suspicious` lint group catches code patterns that are syntactically valid but almost always wrong. These are potential bugs that deserve investigation. Enabling this group as a warning helps catch mistakes early.
+
+## Configuration
+
+```rust
+// In lib.rs or main.rs
+#![warn(clippy::suspicious)]
+```
+
+Or in `Cargo.toml`:
+
+```toml
+[lints.clippy]
+suspicious = "warn"
+```
+
+Or in `clippy.toml`:
+
+```toml
+warn = ["clippy::suspicious"]
+```
+
+## What It Catches
+
+### Suspicious Arithmetic
+
+```rust
+// WARN: Suspicious use of + in a << expression
+let bits = 1 << 4 + 1;  // Probably meant (1 << 4) + 1 or 1 << (4 + 1)
+
+// WARN: Suspicious use of | in a + expression
+let value = x | 1 + y;  // Probably meant (x | 1) + y or x | (1 + y)
+```
+
+### Suspicious Comparisons
+
+```rust
+// WARN: Almost swapped operands in a comparison
+if 5 < x && x < 3 { }  // Impossible condition
+
+// WARN: Suspicious assignment in a condition
+if (x = 5) { }  // Probably meant x == 5
+```
+
+### Suspicious Method Calls
+
+```rust
+// WARN: Suspicious map usage
+let _: Vec<_> = vec.iter().map(|x| { 
+    println!("{}", x);  // Side effect in map
+    x
+}).collect();  // Use for_each instead
+
+// WARN: Suspicious string formatting
+let s = format!("{}", format!("{}", x));  // Redundant nested format
+```
+
+### Suspicious Casts
+
+```rust
+// WARN: Suspicious use of not on a bool
+let inverted = !x as i32;  // Did you mean (!x) as i32 or !(x as i32)?
+
+// WARN: Cast of float to int may lose precision
+let n = 3.14_f64 as i32;  // May want .round() first
+```
+
+## Notable Lints in This Group
+
+| Lint | Description |
+|------|-------------|
+| `suspicious_arithmetic_impl` | Unusual operator in arithmetic trait |
+| `suspicious_assignment_formatting` | Looks like typo in assignment |
+| `suspicious_else_formatting` | Else on wrong line |
+| `suspicious_map` | Map with side effects |
+| `suspicious_op_assign_impl` | Unusual op-assign implementation |
+| `suspicious_splitn` | splitn that can't produce n parts |
+| `suspicious_unary_op_formatting` | Confusing unary operator spacing |
+
+## Example Catches
+
+```rust
+// Caught: Suspicious double negation
+let value = --x;  // In Rust, this is -(-x), not pre-decrement
+
+// Caught: Suspicious modulo
+let remainder = x % 1;  // Always 0 for integers
+
+// Caught: Suspicious else formatting
+if condition {
+    do_something();
+}
+else {  // Weird formatting, might be a mistake
+    do_other();
+}
+```
+
+## When to Allow
+
+Rarely. If you need to suppress, document why:
+
+```rust
+#[allow(clippy::suspicious_arithmetic_impl)]
+impl Mul for Matrix {
+    // Custom matrix multiplication using + for reduction step
+    fn mul(self, rhs: Self) -> Self::Output {
+        // ...
+    }
+}
+```
+
+## See Also
+
+- [lint-deny-correctness](./lint-deny-correctness.md) - Deny definite bugs
+- [lint-warn-style](./lint-warn-style.md) - Style warnings
+- [lint-warn-complexity](./lint-warn-complexity.md) - Complexity warnings

package/template/agent/skills/rust-developer/references/rust-rules/lint-workspace-lints.md

@@ -0,0 +1,172 @@
+# lint-workspace-lints
+
+> Configure lints at workspace level for consistent enforcement
+
+## Why It Matters
+
+Without centralized lint configuration, each crate develops its own standards (or none). Workspace-level lints (Rust 1.74+) ensure consistent code quality across all crates. Denied lints catch issues in CI before they reach production.
+
+## Bad
+
+```toml
+# crate-a/Cargo.toml - strict
+[lints.clippy]
+unwrap_used = "deny"
+
+# crate-b/Cargo.toml - lenient
+# No lint config
+
+# crate-c/Cargo.toml - different
+[lints.clippy]
+unwrap_used = "warn"
+
+# Inconsistent enforcement, some issues slip through
+```
+
+## Good
+
+```toml
+# Root Cargo.toml
+[workspace.lints.rust]
+unsafe_code = "deny"
+missing_docs = "warn"
+
+[workspace.lints.clippy]
+# Correctness
+unwrap_used = "deny"
+expect_used = "warn"
+panic = "deny"
+
+# Style
+needless_pass_by_value = "warn"
+redundant_clone = "warn"
+
+# Complexity
+cognitive_complexity = "warn"
+
+[workspace.lints.rustdoc]
+broken_intra_doc_links = "deny"
+
+# crate-a/Cargo.toml
+[lints]
+workspace = true
+
+# crate-b/Cargo.toml
+[lints]
+workspace = true
+```
+
+## Recommended Lint Configuration
+
+```toml
+# Root Cargo.toml
+[workspace.lints.rust]
+# Safety
+unsafe_code = "deny"
+missing_debug_implementations = "warn"
+
+# Quality
+unused_results = "warn"
+unused_qualifications = "warn"
+
+[workspace.lints.clippy]
+# === Correctness (deny) ===
+correctness = { level = "deny", priority = -1 }
+
+# === Suspicious (deny) ===
+suspicious = { level = "deny", priority = -1 }
+
+# === Style (warn) ===
+style = { level = "warn", priority = -1 }
+
+# === Complexity (warn) ===
+complexity = { level = "warn", priority = -1 }
+
+# === Perf (warn) ===
+perf = { level = "warn", priority = -1 }
+
+# === Pedantic (selective) ===
+# Not all pedantic lints are useful
+doc_markdown = "warn"
+needless_pass_by_value = "warn"
+redundant_closure_for_method_calls = "warn"
+semicolon_if_nothing_returned = "warn"
+
+# === Nursery (selective) ===
+cognitive_complexity = "warn"
+useless_let_if_seq = "warn"
+
+# === Restriction (selective) ===
+unwrap_used = "deny"
+expect_used = "warn"
+dbg_macro = "warn"
+print_stdout = "warn"  # Use logging instead
+todo = "warn"
+
+[workspace.lints.rustdoc]
+broken_intra_doc_links = "deny"
+private_intra_doc_links = "warn"
+```
+
+## Per-Crate Overrides
+
+```toml
+# crate-with-binary/Cargo.toml
+[lints]
+workspace = true
+
+# Binary entry point can use unwrap
+[lints.clippy]
+unwrap_used = "allow"
+
+# test-utils/Cargo.toml
+[lints]
+workspace = true
+
+# Test utilities can print
+[lints.clippy]
+print_stdout = "allow"
+```
+
+## CI Integration
+
+```yaml
+# .github/workflows/ci.yml
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      
+      - name: Clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+      
+      - name: Rustdoc
+        run: RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps
+```
+
+## Lint Categories
+
+```toml
+# Category-level configuration
+[workspace.lints.clippy]
+# All lints in category at once
+correctness = { level = "deny", priority = -1 }
+suspicious = { level = "deny", priority = -1 }
+style = { level = "warn", priority = -1 }
+complexity = { level = "warn", priority = -1 }
+perf = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+
+# Then override specific lints (higher priority)
+missing_errors_doc = "allow"  # Override pedantic
+```
+
+## See Also
+
+- [lint-deny-correctness](./lint-deny-correctness.md) - Critical lints
+- [proj-workspace-deps](./proj-workspace-deps.md) - Workspace configuration
+- [anti-unwrap-abuse](./anti-unwrap-abuse.md) - unwrap lints