devflow-kit 1.1.0 → 1.3.0

package/shared/skills/rust/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: rust
+description: This skill should be used when the user works with Rust files (.rs), asks about "ownership", "borrowing", "lifetimes", "Result/Option", "traits", or discusses memory safety and type-driven design. Provides patterns for ownership, error handling, type system usage, and safe concurrency.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.rs"
+  exclude:
+    - "**/target/**"
+---
+
+# Rust Patterns
+
+Reference for Rust-specific patterns, ownership model, and type-driven design.
+
+## Iron Law
+
+> **MAKE ILLEGAL STATES UNREPRESENTABLE**
+>
+> Encode invariants in the type system. If a function can fail, return `Result`. If a value
+> might be absent, return `Option`. If a state transition is invalid, make it uncompilable.
+> Runtime checks are a fallback, not a strategy.
+
+## When This Skill Activates
+
+- Working with Rust codebases
+- Designing type-safe APIs
+- Managing ownership and borrowing
+- Implementing error handling
+- Writing concurrent code
+
+---
+
+## Ownership & Borrowing
+
+### Prefer Borrowing Over Cloning
+
+```rust
+// BAD: fn process(data: String) — takes ownership unnecessarily
+// GOOD: fn process(data: &str) — borrows, caller keeps ownership
+
+fn process(data: &str) -> usize {
+    data.len()
+}
+```
+
+### Lifetime Annotations When Needed
+
+```rust
+// Return reference tied to input lifetime
+fn first_word(s: &str) -> &str {
+    s.split_whitespace().next().unwrap_or("")
+}
+
+// Explicit when compiler can't infer
+struct Excerpt<'a> {
+    text: &'a str,
+}
+```
+
+---
+
+## Error Handling
+
+### Use Result and the ? Operator
+
+```rust
+use std::fs;
+use std::io;
+
+fn read_config(path: &str) -> Result<Config, AppError> {
+    let content = fs::read_to_string(path)
+        .map_err(|e| AppError::Io { path: path.into(), source: e })?;
+    let config: Config = toml::from_str(&content)
+        .map_err(|e| AppError::Parse { source: e })?;
+    Ok(config)
+}
+```
+
+### Custom Error Types with thiserror
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum AppError {
+    #[error("IO error reading {path}")]
+    Io { path: String, #[source] source: io::Error },
+    #[error("parse error")]
+    Parse { #[from] source: toml::de::Error },
+    #[error("{entity} with id {id} not found")]
+    NotFound { entity: String, id: String },
+}
+```
+
+---
+
+## Type System
+
+### Newtype Pattern
+
+```rust
+// Prevent mixing up IDs
+struct UserId(String);
+struct OrderId(String);
+
+fn get_order(user_id: &UserId, order_id: &OrderId) -> Result<Order, AppError> {
+    // Can't accidentally swap parameters
+    todo!()
+}
+```
+
+### Enums for State Machines
+
+```rust
+enum Connection {
+    Disconnected,
+    Connecting { attempt: u32 },
+    Connected { session: Session },
+}
+
+// Each state carries only its relevant data
+// Invalid transitions are uncompilable
+```
+
+---
+
+## Patterns
+
+### Builder Pattern
+
+```rust
+pub struct ServerBuilder {
+    port: u16,
+    host: String,
+}
+
+impl ServerBuilder {
+    pub fn new() -> Self { Self { port: 8080, host: "localhost".into() } }
+    pub fn port(mut self, port: u16) -> Self { self.port = port; self }
+    pub fn host(mut self, host: impl Into<String>) -> Self { self.host = host.into(); self }
+    pub fn build(self) -> Server { Server { port: self.port, host: self.host } }
+}
+```
+
+### Iterator Chains Over Loops
+
+```rust
+// BAD: manual loop with push
+// GOOD:
+let active_names: Vec<&str> = users.iter()
+    .filter(|u| u.is_active)
+    .map(|u| u.name.as_str())
+    .collect();
+```
+
+---
+
+## Anti-Patterns
+
+| Pattern | Bad | Good |
+|---------|-----|------|
+| Unwrap in library | `.unwrap()` | `?` operator or `.ok_or()` |
+| Clone to satisfy borrow checker | `.clone()` everywhere | Restructure ownership |
+| String for everything | `HashMap<String, String>` | Typed structs and enums |
+| Ignoring Result | `let _ = write(...)` | Handle or propagate error |
+| Mutex<Vec> for message passing | Shared mutable state | Channels (`mpsc`) |
+
+---
+
+## Extended References
+
+For additional patterns and examples:
+- `references/violations.md` - Common Rust violations
+- `references/patterns.md` - Extended Rust patterns
+- `references/detection.md` - Detection patterns for Rust issues
+- `references/ownership.md` - Advanced ownership and lifetime patterns
+
+---
+
+## Checklist
+
+- [ ] No `.unwrap()` in library/application code (ok in tests)
+- [ ] Custom error types with `thiserror`
+- [ ] `?` operator for error propagation
+- [ ] Borrow instead of clone where possible
+- [ ] Newtype pattern for type-safe IDs
+- [ ] Enums for state machines
+- [ ] Iterator chains over manual loops
+- [ ] `#[must_use]` on Result-returning functions
+- [ ] No `unsafe` without safety comment
+- [ ] Clippy clean (`cargo clippy -- -D warnings`)

package/shared/skills/rust/references/detection.md

@@ -0,0 +1,131 @@
+# Rust Detection Patterns
+
+Grep and regex patterns for finding common Rust issues. Use with `Grep` tool.
+
+## Unwrap and Expect
+
+```bash
+# Find .unwrap() calls (exclude tests)
+grep -rn '\.unwrap()' --include='*.rs' --exclude-dir=tests --exclude='*_test.rs'
+
+# Find .expect() without descriptive message
+grep -rn '\.expect("")' --include='*.rs'
+
+# Find unwrap_or_default hiding errors
+grep -rn '\.unwrap_or_default()' --include='*.rs'
+```
+
+**Pattern**: `\.unwrap\(\)` — matches any `.unwrap()` call
+**Pattern**: `\.expect\("` — matches `.expect("` to review message quality
+
+---
+
+## Clone Abuse
+
+```bash
+# Find .clone() calls — review each for necessity
+grep -rn '\.clone()' --include='*.rs'
+
+# Find clone in loop bodies (likely hot-path waste)
+grep -rn -A2 'for.*in' --include='*.rs' | grep '\.clone()'
+
+# Find to_string() where &str would work
+grep -rn '\.to_string()' --include='*.rs'
+```
+
+**Pattern**: `\.clone\(\)` — all clone calls for manual review
+**Pattern**: `\.to_owned\(\)` — ownership transfer that may be unnecessary
+
+---
+
+## Unsafe Blocks
+
+```bash
+# Find all unsafe blocks
+grep -rn 'unsafe\s*{' --include='*.rs'
+
+# Find unsafe without SAFETY comment
+grep -rn -B2 'unsafe\s*{' --include='*.rs' | grep -v 'SAFETY'
+
+# Find unsafe functions
+grep -rn 'unsafe fn' --include='*.rs'
+```
+
+**Pattern**: `unsafe\s*\{` — unsafe blocks
+**Pattern**: `unsafe fn` — unsafe function declarations
+
+---
+
+## Incomplete Code
+
+```bash
+# Find todo! and unimplemented! macros
+grep -rn 'todo!\|unimplemented!' --include='*.rs'
+
+# Find unreachable! that may hide bugs
+grep -rn 'unreachable!' --include='*.rs'
+
+# Find panic! in non-test code
+grep -rn 'panic!' --include='*.rs' --exclude-dir=tests --exclude='*_test.rs'
+```
+
+**Pattern**: `todo!\(\)` — placeholder code
+**Pattern**: `unimplemented!\(\)` — unfinished implementations
+**Pattern**: `panic!\(` — explicit panics outside tests
+
+---
+
+## Error Handling Issues
+
+```bash
+# Find ignored Results (let _ = expr that returns Result)
+grep -rn 'let _ =' --include='*.rs'
+
+# Find empty match arms that may swallow errors
+grep -rn '=> {}' --include='*.rs'
+
+# Find catch-all match arms hiding missing cases
+grep -rn '_ =>' --include='*.rs'
+```
+
+**Pattern**: `let _ =` — potentially ignored Result or important value
+**Pattern**: `=> \{\}` — empty match arm (may swallow error)
+
+---
+
+## Concurrency Red Flags
+
+```bash
+# Find static mut (almost always wrong)
+grep -rn 'static mut' --include='*.rs'
+
+# Find blocking calls in async functions
+grep -rn 'std::fs::' --include='*.rs' | grep -v 'test'
+grep -rn 'std::thread::sleep' --include='*.rs'
+
+# Find Mutex without Arc in multi-threaded context
+grep -rn 'Mutex::new' --include='*.rs'
+```
+
+**Pattern**: `static mut` — mutable global state (data race risk)
+**Pattern**: `std::fs::` — blocking I/O that may appear in async context
+**Pattern**: `std::thread::sleep` — blocking sleep (use `tokio::time::sleep` in async)
+
+---
+
+## Clippy Lints
+
+Run Clippy for automated detection of many patterns above:
+
+```bash
+cargo clippy -- -D warnings
+cargo clippy -- -W clippy::pedantic
+cargo clippy -- -W clippy::nursery
+```
+
+Key Clippy lints that catch issues:
+- `clippy::unwrap_used` — flags unwrap calls
+- `clippy::clone_on_ref_ptr` — unnecessary Arc/Rc clone
+- `clippy::needless_pass_by_value` — should borrow instead
+- `clippy::missing_errors_doc` — public Result fn without doc
+- `clippy::wildcard_enum_match_arm` — catch-all hiding cases

package/shared/skills/rust/references/ownership.md

@@ -0,0 +1,242 @@
+# Rust Ownership Deep Dive
+
+Advanced ownership patterns, lifetime elision, interior mutability, and pinning.
+
+## Lifetime Elision Rules
+
+The compiler applies three rules to infer lifetimes. When they don't resolve, annotate manually.
+
+### Rule 1: Each Reference Parameter Gets Its Own Lifetime
+
+```rust
+// Compiler sees: fn first(s: &str) -> &str
+// Compiler infers: fn first<'a>(s: &'a str) -> &'a str
+fn first(s: &str) -> &str {
+    &s[..1]
+}
+```
+
+### Rule 2: Single Input Lifetime Applies to All Outputs
+
+```rust
+// One input reference — output borrows from it
+fn trim(s: &str) -> &str {
+    s.trim()
+}
+```
+
+### Rule 3: &self Lifetime Applies to All Outputs in Methods
+
+```rust
+impl Config {
+    // &self lifetime flows to return
+    fn database_url(&self) -> &str {
+        &self.db_url
+    }
+}
+```
+
+### When Elision Fails
+
+```rust
+// Two input lifetimes — compiler can't decide which output borrows from
+// Must annotate: output borrows from `a`, not `b`
+fn longest<'a>(a: &'a str, b: &str) -> &'a str {
+    if a.len() >= b.len() { a } else { a }
+}
+```
+
+---
+
+## Interior Mutability
+
+Mutate data behind a shared reference when ownership rules are too strict.
+
+### Cell — Copy Types Only
+
+```rust
+use std::cell::Cell;
+
+struct Counter {
+    count: Cell<u32>, // Mutate through &self
+}
+
+impl Counter {
+    fn increment(&self) {
+        self.count.set(self.count.get() + 1);
+    }
+}
+```
+
+### RefCell — Runtime Borrow Checking
+
+```rust
+use std::cell::RefCell;
+
+struct Cache {
+    data: RefCell<HashMap<String, String>>,
+}
+
+impl Cache {
+    fn get_or_insert(&self, key: &str, value: &str) -> String {
+        let mut data = self.data.borrow_mut(); // Panics if already borrowed
+        data.entry(key.to_string())
+            .or_insert_with(|| value.to_string())
+            .clone()
+    }
+}
+```
+
+### Mutex — Thread-Safe Interior Mutability
+
+```rust
+use std::sync::Mutex;
+
+struct SharedState {
+    data: Mutex<Vec<String>>,
+}
+
+impl SharedState {
+    fn push(&self, item: String) -> Result<(), AppError> {
+        let mut data = self.data.lock()
+            .map_err(|_| AppError::LockPoisoned)?;
+        data.push(item);
+        Ok(())
+    }
+}
+```
+
+### Decision Guide
+
+| Type | Thread-Safe | Cost | Use Case |
+|------|-------------|------|----------|
+| `Cell<T>` | No | Zero | Copy types, single-threaded |
+| `RefCell<T>` | No | Runtime borrow check | Non-Copy, single-threaded |
+| `Mutex<T>` | Yes | Lock overhead | Multi-threaded mutation |
+| `RwLock<T>` | Yes | Lock overhead | Multi-threaded, read-heavy |
+| `Atomic*` | Yes | Hardware atomic | Counters, flags |
+
+---
+
+## Cow — Clone on Write
+
+Defer cloning until mutation is actually needed.
+
+```rust
+use std::borrow::Cow;
+
+// Returns borrowed if no processing needed, owned if modified
+fn normalize_path(path: &str) -> Cow<'_, str> {
+    if path.contains("//") {
+        Cow::Owned(path.replace("//", "/"))
+    } else {
+        Cow::Borrowed(path)
+    }
+}
+
+// Function accepts both owned and borrowed transparently
+fn process(input: Cow<'_, str>) {
+    println!("{}", input); // No allocation if already borrowed
+}
+```
+
+### Cow in APIs
+
+```rust
+// Accept Cow for flexible ownership — caller decides allocation
+pub fn log_message(msg: Cow<'_, str>) {
+    eprintln!("[LOG] {}", msg);
+}
+
+// Caller with borrowed data — zero-copy
+log_message(Cow::Borrowed("static message"));
+
+// Caller with owned data — no extra clone
+log_message(Cow::Owned(format!("dynamic: {}", value)));
+```
+
+---
+
+## Pin for Async and Self-Referential Types
+
+### Why Pin Exists
+
+Self-referential structs break if moved in memory. `Pin` guarantees the value won't move.
+
+```rust
+use std::pin::Pin;
+use std::future::Future;
+
+// Async functions return self-referential futures
+// Pin ensures the future stays in place while polled
+fn fetch_data(url: &str) -> Pin<Box<dyn Future<Output = Result<Data, Error>> + '_>> {
+    Box::pin(async move {
+        let response = reqwest::get(url).await?;
+        let data = response.json::<Data>().await?;
+        Ok(data)
+    })
+}
+```
+
+### Pin in Practice
+
+```rust
+use tokio::pin;
+
+async fn process_stream(stream: impl Stream<Item = Data>) {
+    // pin! macro pins the stream to the stack
+    pin!(stream);
+
+    while let Some(item) = stream.next().await {
+        handle(item).await;
+    }
+}
+```
+
+### When You Need Pin
+
+| Scenario | Need Pin? |
+|----------|-----------|
+| Returning `async` blocks as trait objects | Yes |
+| Implementing `Future` manually | Yes |
+| Using `tokio::select!` on futures | Yes (automatically handled) |
+| Normal async/await | No (compiler handles it) |
+| Storing futures in collections | Yes (`Pin<Box<dyn Future>>`) |
+
+---
+
+## Ownership Transfer Patterns
+
+### Take Pattern — Move Out of Option
+
+```rust
+struct Connection {
+    session: Option<Session>,
+}
+
+impl Connection {
+    fn close(&mut self) -> Option<Session> {
+        self.session.take() // Moves out, leaves None
+    }
+}
+```
+
+### Swap Pattern — Replace In Place
+
+```rust
+use std::mem;
+
+fn rotate_buffer(current: &mut Vec<u8>, new_data: Vec<u8>) -> Vec<u8> {
+    mem::replace(current, new_data) // Returns old, installs new
+}
+```
+
+### Entry Pattern — Conditional Insertion
+
+```rust
+use std::collections::HashMap;
+
+fn get_or_create(map: &mut HashMap<String, Vec<Item>>, key: &str) -> &mut Vec<Item> {
+    map.entry(key.to_string()).or_insert_with(Vec::new)
+}
+```