agy-superpowers 5.1.4 → 5.1.6

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

package/template/agent/skills/rust-developer/references/rust-rules/mem-arena-allocator.md

@@ -0,0 +1,168 @@
+# mem-arena-allocator
+
+> Use arena allocators for batch allocations
+
+## Why It Matters
+
+Arena allocators (bump allocators) allocate memory from a contiguous region, making allocation extremely fast (just bump a pointer). All allocations are freed at once when the arena is dropped. Perfect for request-scoped or parse-tree allocations.
+
+## Bad
+
+```rust
+// Many small allocations during parsing
+fn parse(input: &str) -> Vec<Node> {
+    let mut nodes = Vec::new();
+    for token in tokenize(input) {
+        nodes.push(Box::new(Node::new(token)));  // Heap alloc per node!
+    }
+    nodes
+}
+
+// Per-request allocations add up
+fn handle_request(req: Request) -> Response {
+    let headers = parse_headers(&req);      // Allocates
+    let body = parse_body(&req);            // Allocates
+    let response = generate_response();     // Allocates
+    // All freed individually at end
+    response
+}
+```
+
+## Good
+
+```rust
+use bumpalo::Bump;
+
+// All nodes allocated from same arena
+fn parse<'a>(input: &str, arena: &'a Bump) -> Vec<&'a Node> {
+    let mut nodes = Vec::new();
+    for token in tokenize(input) {
+        let node = arena.alloc(Node::new(token));  // Fast bump!
+        nodes.push(node);
+    }
+    nodes
+}  // Arena freed all at once
+
+// Per-request arena
+fn handle_request(req: Request) -> Response {
+    let arena = Bump::new();
+    
+    let headers = parse_headers(&req, &arena);
+    let body = parse_body(&req, &arena);
+    let response = generate_response(&arena);
+    
+    // Convert to owned response before arena drops
+    response.to_owned()
+}  // All request memory freed instantly
+```
+
+## Thread-Local Scratch Arena Pattern
+
+```rust
+use bumpalo::Bump;
+use std::cell::RefCell;
+
+thread_local! {
+    static SCRATCH: RefCell<Bump> = RefCell::new(Bump::with_capacity(4 * 1024));
+}
+
+fn with_scratch<T>(f: impl FnOnce(&Bump) -> T) -> T {
+    SCRATCH.with(|scratch| {
+        let arena = scratch.borrow();
+        let result = f(&arena);
+        result
+    })
+}
+
+fn reset_scratch() {
+    SCRATCH.with(|scratch| {
+        scratch.borrow_mut().reset();
+    });
+}
+
+// Usage
+fn process_batch(items: &[Item]) -> Vec<Output> {
+    with_scratch(|arena| {
+        let temp_data: Vec<&TempData> = items
+            .iter()
+            .map(|item| arena.alloc(compute_temp(item)))
+            .collect();
+        
+        // Use temp_data...
+        let result = finalize(&temp_data);
+        
+        reset_scratch();  // Reuse arena memory
+        result
+    })
+}
+```
+
+## Evidence from ROC Compiler
+
+```rust
+// https://github.com/roc-lang/roc/blob/main/crates/compiler/solve/src/to_var.rs
+std::thread_local! {
+    static SCRATCHPAD: RefCell<Option<bumpalo::Bump>> = 
+        RefCell::new(Some(bumpalo::Bump::with_capacity(4 * 1024)));
+}
+
+fn take_scratchpad() -> bumpalo::Bump {
+    SCRATCHPAD.with(|f| f.take().unwrap())
+}
+
+fn put_scratchpad(scratchpad: bumpalo::Bump) {
+    SCRATCHPAD.with(|f| {
+        f.replace(Some(scratchpad));
+    });
+}
+```
+
+## Bumpalo Collections
+
+```rust
+use bumpalo::Bump;
+use bumpalo::collections::{Vec, String};
+
+fn process<'a>(arena: &'a Bump, input: &str) -> Vec<'a, String<'a>> {
+    let mut results = Vec::new_in(arena);
+    
+    for word in input.split_whitespace() {
+        let mut s = String::new_in(arena);
+        s.push_str(word);
+        s.push_str("_processed");
+        results.push(s);
+    }
+    
+    results  // All allocated in arena
+}
+```
+
+## When to Use Arenas
+
+| Situation | Use Arena? |
+|-----------|-----------|
+| Parsing (AST nodes) | Yes |
+| Request handling | Yes |
+| Batch processing | Yes |
+| Long-lived data | No |
+| Data escaping scope | No (or copy out) |
+| Simple programs | Overkill |
+
+## Performance Impact
+
+```rust
+// Benchmarks from production systems:
+// - Individual allocations: ~25-50ns each
+// - Arena bump: ~1-2ns each (20-50x faster)
+// - Arena reset: O(1) regardless of allocation count
+
+// Memory overhead:
+// - Arena wastes some memory (unused capacity)
+// - But eliminates per-allocation metadata overhead
+```
+
+## See Also
+
+- [mem-with-capacity](mem-with-capacity.md) - Pre-allocate when size is known
+- [mem-reuse-collections](mem-reuse-collections.md) - Reuse collections with clear()
+- [opt-profile-first](perf-profile-first.md) - Profile to verify benefit

package/template/agent/skills/rust-developer/references/rust-rules/mem-arrayvec.md

@@ -0,0 +1,142 @@
+# mem-arrayvec
+
+> Use `ArrayVec<T, N>` for fixed-capacity collections that never heap-allocate
+
+## Why It Matters
+
+`ArrayVec` from the `arrayvec` crate provides Vec-like API with a compile-time maximum capacity, storing all elements inline on the stack. Unlike `SmallVec` which can spill to heap, `ArrayVec` guarantees no heap allocation—if you exceed capacity, it returns an error or panics. This is ideal for embedded systems, real-time code, or when you have a hard upper bound.
+
+## Bad
+
+```rust
+// Vec always heap-allocates, even for small collections
+fn parse_options(input: &str) -> Vec<Option> {
+    let mut options = Vec::new();  // Heap allocation
+    for part in input.split(',').take(8) {  // Know we never exceed 8
+        options.push(parse_option(part));
+    }
+    options
+}
+
+// Or SmallVec when you truly can't exceed capacity
+use smallvec::SmallVec;
+fn get_flags() -> SmallVec<[Flag; 4]> {
+    // SmallVec CAN heap-allocate if pushed beyond 4
+    // That might be unexpected in no-alloc contexts
+}
+```
+
+## Good
+
+```rust
+use arrayvec::ArrayVec;
+
+// Guaranteed no heap allocation
+fn parse_options(input: &str) -> ArrayVec<Option, 8> {
+    let mut options = ArrayVec::new();
+    for part in input.split(',') {
+        if options.try_push(parse_option(part)).is_err() {
+            break;  // Capacity reached, stop
+        }
+    }
+    options
+}
+
+// For embedded/no_std contexts
+#[no_std]
+fn collect_readings() -> ArrayVec<SensorReading, 16> {
+    let mut readings = ArrayVec::new();
+    for sensor in SENSORS.iter() {
+        readings.push(sensor.read());  // Panics if > 16
+    }
+    readings
+}
+```
+
+## ArrayVec vs SmallVec vs Vec
+
+| Type | Stack | Heap | Use When |
+|------|-------|------|----------|
+| `Vec<T>` | Never | Always | Unknown size, may grow indefinitely |
+| `SmallVec<[T; N]>` | Up to N | Beyond N | Usually small, occasionally large |
+| `ArrayVec<T, N>` | Always | Never | Hard limit, no heap allowed |
+
+## API Patterns
+
+```rust
+use arrayvec::ArrayVec;
+
+let mut arr: ArrayVec<i32, 4> = ArrayVec::new();
+
+// Push with potential panic (like Vec)
+arr.push(1);
+arr.push(2);
+
+// Safe push - returns Err if full
+match arr.try_push(3) {
+    Ok(()) => println!("Added"),
+    Err(err) => println!("Full, couldn't add {}", err.element()),
+}
+
+// Check capacity
+assert!(arr.len() < arr.capacity());
+
+// Remaining capacity
+let remaining = arr.remaining_capacity();
+
+// Is it full?
+if arr.is_full() {
+    arr.pop();
+}
+
+// From iterator with limit
+let arr: ArrayVec<_, 10> = (0..100)
+    .filter(|x| x % 2 == 0)
+    .take(10)  // Important: don't exceed capacity
+    .collect();
+```
+
+## ArrayString for Stack Strings
+
+```rust
+use arrayvec::ArrayString;
+
+// Stack-allocated string with max capacity
+let mut s: ArrayString<64> = ArrayString::new();
+s.push_str("Hello, ");
+s.push_str("world!");
+
+// No heap allocation for small strings
+fn format_code(code: u32) -> ArrayString<16> {
+    let mut s = ArrayString::new();
+    write!(&mut s, "CODE-{:04}", code).unwrap();
+    s
+}
+```
+
+## When NOT to Use ArrayVec
+
+```rust
+// ❌ When size varies widely
+fn parse_json_array(json: &str) -> ArrayVec<Value, ???> {
+    // What capacity? JSON arrays can be any size
+}
+
+// ❌ When capacity is very large
+let big: ArrayVec<u8, 1_000_000> = ArrayVec::new();  // 1MB on stack = bad
+
+// ✅ Use SmallVec or Vec instead for these cases
+```
+
+## Cargo.toml
+
+```toml
+[dependencies]
+arrayvec = "0.7"
+```
+
+## See Also
+
+- [mem-smallvec](./mem-smallvec.md) - When heap fallback is acceptable
+- [mem-with-capacity](./mem-with-capacity.md) - Pre-allocating Vec capacity
+- [own-move-large](./own-move-large.md) - Large stack types considerations

package/template/agent/skills/rust-developer/references/rust-rules/mem-assert-type-size.md

@@ -0,0 +1,168 @@
+# mem-assert-type-size
+
+> Use static assertions to guard against accidental type size growth
+
+## Why It Matters
+
+Adding a field to a frequently-instantiated struct can silently bloat memory usage. Static size assertions catch this at compile time, making size changes intentional rather than accidental. This is especially important for types stored in large collections or passed frequently by value.
+
+## Bad
+
+```rust
+struct Event {
+    timestamp: u64,
+    kind: EventKind,
+    payload: [u8; 32],
+}
+
+// Later, someone adds a field without realizing the impact
+struct Event {
+    timestamp: u64,
+    kind: EventKind,
+    payload: [u8; 32],
+    metadata: String,  // Silently adds 24 bytes!
+}
+
+// 10 million events now use 240MB more memory
+// No warning, no review trigger
+```
+
+## Good
+
+```rust
+struct Event {
+    timestamp: u64,
+    kind: EventKind,
+    payload: [u8; 32],
+}
+
+// Static assertion - breaks compile if size changes
+const _: () = assert!(std::mem::size_of::<Event>() == 48);
+
+// Or with static_assertions crate
+use static_assertions::assert_eq_size;
+assert_eq_size!(Event, [u8; 48]);
+
+// Now adding metadata triggers compile error:
+// error: assertion failed: std::mem::size_of::<Event>() == 48
+```
+
+## static_assertions Crate
+
+```rust
+use static_assertions::{assert_eq_size, const_assert};
+
+struct Critical {
+    id: u64,
+    flags: u32,
+    data: [u8; 16],
+}
+
+// Exact size assertion
+assert_eq_size!(Critical, [u8; 32]);
+
+// Maximum size assertion
+const_assert!(std::mem::size_of::<Critical>() <= 64);
+
+// Alignment assertion
+const_assert!(std::mem::align_of::<Critical>() == 8);
+
+// Compare sizes
+assert_eq_size!(Critical, [u64; 4]);
+```
+
+## Built-in Const Assertions
+
+```rust
+// No external crate needed (Rust 1.57+)
+struct Packet {
+    header: u32,
+    payload: [u8; 60],
+}
+
+const _: () = assert!(
+    std::mem::size_of::<Packet>() == 64,
+    "Packet must be exactly 64 bytes for protocol compliance"
+);
+
+// Compile error shows custom message if assertion fails
+```
+
+## Documenting Size Constraints
+
+```rust
+/// Network protocol packet header.
+/// 
+/// # Size
+/// 
+/// This struct is guaranteed to be exactly 32 bytes to match
+/// the network protocol specification. Any changes to fields
+/// must maintain this size constraint.
+#[repr(C)]  // Predictable layout for FFI
+struct Header {
+    version: u16,
+    flags: u16,
+    length: u32,
+    checksum: u64,
+    reserved: [u8; 16],
+}
+
+const _: () = assert!(std::mem::size_of::<Header>() == 32);
+```
+
+## Testing Size Stability
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    #[test]
+    fn critical_types_have_expected_sizes() {
+        // Document expected sizes in tests too
+        assert_eq!(std::mem::size_of::<Event>(), 48);
+        assert_eq!(std::mem::size_of::<Message>(), 64);
+        assert_eq!(std::mem::size_of::<Header>(), 32);
+    }
+    
+    #[test]
+    fn cache_line_aligned() {
+        // Verify cache-friendly sizing
+        assert!(std::mem::size_of::<HotData>() <= 64);
+    }
+}
+```
+
+## When to Assert
+
+```rust
+// ✅ Types stored in large collections
+struct Node { /* ... */ }
+const _: () = assert!(std::mem::size_of::<Node>() <= 64);
+
+// ✅ Types used in FFI / binary protocols
+#[repr(C)]
+struct WireFormat { /* ... */ }
+const _: () = assert!(std::mem::size_of::<WireFormat>() == 256);
+
+// ✅ Performance-critical types
+struct HotPath { /* ... */ }
+const _: () = assert!(std::mem::size_of::<HotPath>() <= 128);
+
+// ❌ Skip for rarely-instantiated types
+struct AppConfig { /* many fields */ }
+// Size doesn't matter, only one instance
+```
+
+## Cargo.toml
+
+```toml
+[dependencies]
+static_assertions = "1.1"
+```
+
+## See Also
+
+- [mem-smaller-integers](./mem-smaller-integers.md) - Choosing appropriate integer sizes
+- [mem-box-large-variant](./mem-box-large-variant.md) - Managing enum variant sizes
+- [opt-cache-friendly](./opt-cache-friendly.md) - Cache line considerations