devflow-kit 1.1.0 → 1.2.0

package/plugins/devflow-rust/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/plugins/devflow-rust/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)
+}
+```

package/plugins/devflow-rust/skills/rust/references/patterns.md

@@ -0,0 +1,210 @@
+# Rust Extended Patterns
+
+Extended correct patterns for Rust. Reference from main SKILL.md.
+
+## Typestate Pattern
+
+Encode valid state transitions in the type system so invalid sequences don't compile.
+
+```rust
+// States are zero-sized types — no runtime cost
+struct Draft;
+struct Published;
+struct Archived;
+
+struct Article<State> {
+    title: String,
+    body: String,
+    _state: std::marker::PhantomData<State>,
+}
+
+impl Article<Draft> {
+    pub fn new(title: String, body: String) -> Self {
+        Article { title, body, _state: std::marker::PhantomData }
+    }
+
+    pub fn publish(self) -> Article<Published> {
+        Article { title: self.title, body: self.body, _state: std::marker::PhantomData }
+    }
+}
+
+impl Article<Published> {
+    pub fn archive(self) -> Article<Archived> {
+        Article { title: self.title, body: self.body, _state: std::marker::PhantomData }
+    }
+}
+
+// article.archive() on Draft won't compile — transition enforced at compile time
+```
+
+---
+
+## Error Handling Hierarchy
+
+Layer errors from specific to general using `thiserror` for libraries and `anyhow` for applications.
+
+```rust
+// Library: precise, typed errors
+#[derive(thiserror::Error, Debug)]
+pub enum RepoError {
+    #[error("entity {entity} with id {id} not found")]
+    NotFound { entity: &'static str, id: String },
+    #[error("duplicate key: {0}")]
+    Duplicate(String),
+    #[error("connection failed")]
+    Connection(#[from] sqlx::Error),
+}
+
+// Application: ergonomic error propagation
+use anyhow::{Context, Result};
+
+fn run() -> Result<()> {
+    let config = load_config()
+        .context("failed to load configuration")?;
+    let db = connect_db(&config.database_url)
+        .context("failed to connect to database")?;
+    serve(db, config.port)
+        .context("server exited with error")
+}
+```
+
+---
+
+## Trait Objects vs Generics
+
+### Use Generics for Performance (Monomorphization)
+
+```rust
+fn largest<T: PartialOrd>(list: &[T]) -> Option<&T> {
+    list.iter().reduce(|a, b| if a >= b { a } else { b })
+}
+```
+
+### Use Trait Objects for Heterogeneous Collections
+
+```rust
+trait Handler: Send + Sync {
+    fn handle(&self, request: &Request) -> Response;
+}
+
+struct Router {
+    routes: Vec<Box<dyn Handler>>, // Different concrete types in one Vec
+}
+```
+
+### Decision Guide
+
+| Criteria | Generics | Trait Objects |
+|----------|----------|--------------|
+| Known types at compile time | Yes | No |
+| Heterogeneous collection | No | Yes |
+| Performance-critical | Yes | Acceptable overhead |
+| Binary size concern | Increases | Minimal |
+
+---
+
+## Smart Pointers
+
+### Box — Heap Allocation
+
+```rust
+// Recursive types require indirection
+enum List<T> {
+    Cons(T, Box<List<T>>),
+    Nil,
+}
+```
+
+### Rc/Arc — Shared Ownership
+
+```rust
+use std::sync::Arc;
+
+// Shared read-only config across threads
+let config = Arc::new(load_config()?);
+let config_clone = Arc::clone(&config);
+tokio::spawn(async move {
+    use_config(&config_clone).await;
+});
+```
+
+### When to Use Each
+
+| Pointer | Use Case |
+|---------|----------|
+| `Box<T>` | Single owner, heap allocation, recursive types |
+| `Rc<T>` | Multiple owners, single-threaded |
+| `Arc<T>` | Multiple owners, multi-threaded |
+| `Cow<'a, T>` | Clone-on-write, flexible borrowing |
+
+---
+
+## From/Into Conversions
+
+```rust
+// Implement From for automatic Into
+impl From<CreateUserRequest> for User {
+    fn from(req: CreateUserRequest) -> Self {
+        User {
+            id: Uuid::new_v4(),
+            name: req.name,
+            email: req.email,
+            created_at: Utc::now(),
+        }
+    }
+}
+
+// Callers get Into for free
+fn save_user(user: impl Into<User>) -> Result<(), DbError> {
+    let user: User = user.into();
+    // ...
+    Ok(())
+}
+```
+
+---
+
+## Derive and Trait Best Practices
+
+```rust
+// Derive the standard set for data types
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct UserId(String);
+
+// Derive serde for serialization boundaries
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct ApiResponse<T> {
+    pub data: T,
+    pub metadata: Metadata,
+}
+```
+
+### Trait Implementation Order Convention
+
+1. Standard library traits (`Debug`, `Display`, `Clone`, `PartialEq`)
+2. Conversion traits (`From`, `Into`, `TryFrom`)
+3. Iterator traits (`Iterator`, `IntoIterator`)
+4. Serde traits (`Serialize`, `Deserialize`)
+5. Custom traits (domain-specific)
+
+---
+
+## Module Organization
+
+```
+src/
+├── lib.rs          # Public API re-exports
+├── error.rs        # Crate-level error types
+├── domain/
+│   ├── mod.rs      # Domain re-exports
+│   ├── user.rs     # User entity and logic
+│   └── order.rs    # Order entity and logic
+├── repo/
+│   ├── mod.rs      # Repository trait definitions
+│   └── postgres.rs # Concrete implementation
+└── api/
+    ├── mod.rs      # Route registration
+    └── handlers.rs # HTTP handlers
+```
+
+Keep `lib.rs` thin — re-export only the public API. Internal modules use `pub(crate)`.