devflow-kit 1.8.3 → 2.0.1

package/shared/skills/rust/SKILL.md

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

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

@@ -1,242 +0,0 @@
-# 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)
-}
-```