devflow-kit 1.1.0 → 1.2.0

package/shared/skills/python/references/patterns.md

@@ -0,0 +1,226 @@
+# Python Correct Patterns
+
+Extended correct patterns for Python development. Reference from main SKILL.md.
+
+## Dependency Injection
+
+### Constructor Injection
+
+```python
+from typing import Protocol
+
+class EmailSender(Protocol):
+    def send(self, to: str, subject: str, body: str) -> None: ...
+
+class UserService:
+    def __init__(self, repo: UserRepository, emailer: EmailSender) -> None:
+        self._repo = repo
+        self._emailer = emailer
+
+    def create_user(self, request: CreateUserRequest) -> User:
+        user = User(name=request.name, email=request.email)
+        saved = self._repo.save(user)
+        self._emailer.send(user.email, "Welcome", f"Hello {user.name}")
+        return saved
+
+# Easy to test — inject fakes
+service = UserService(repo=FakeUserRepo(), emailer=FakeEmailSender())
+```
+
+### Factory Functions
+
+```python
+def create_app(config: AppConfig) -> Flask:
+    app = Flask(__name__)
+    db = Database(config.database_url)
+    cache = RedisCache(config.redis_url)
+    user_service = UserService(repo=SqlUserRepo(db), emailer=SmtpSender(config.smtp))
+    register_routes(app, user_service)
+    return app
+```
+
+## Decorator Patterns
+
+### Retry Decorator
+
+```python
+import functools
+import time
+from typing import TypeVar, Callable, ParamSpec
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+def retry(
+    max_attempts: int = 3,
+    delay: float = 1.0,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            last_error: Exception | None = None
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_error = e
+                    if attempt < max_attempts - 1:
+                        time.sleep(delay * (2 ** attempt))
+            raise last_error  # type: ignore[misc]
+        return wrapper
+    return decorator
+
+@retry(max_attempts=3, delay=0.5, exceptions=(ConnectionError, TimeoutError))
+def fetch_data(url: str) -> dict[str, Any]:
+    ...
+```
+
+### Validation Decorator
+
+```python
+def validate_input(schema: type[BaseModel]):
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            # Validate first positional arg after self/cls
+            data = args[1] if len(args) > 1 else args[0]
+            schema.model_validate(data)
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
+```
+
+## Context Manager Patterns
+
+### Database Transaction
+
+```python
+from contextlib import contextmanager
+from typing import Generator
+
+@contextmanager
+def transaction(session: Session) -> Generator[Session, None, None]:
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+# Usage
+with transaction(db.session()) as session:
+    session.add(user)
+    session.add(audit_log)
+```
+
+### Temporary Directory
+
+```python
+from contextlib import contextmanager
+from pathlib import Path
+import tempfile
+import shutil
+
+@contextmanager
+def temp_workspace() -> Generator[Path, None, None]:
+    path = Path(tempfile.mkdtemp())
+    try:
+        yield path
+    finally:
+        shutil.rmtree(path, ignore_errors=True)
+```
+
+## Pytest Fixture Patterns
+
+### Service Fixtures with DI
+
+```python
+import pytest
+
+@pytest.fixture
+def fake_repo() -> FakeUserRepo:
+    return FakeUserRepo()
+
+@pytest.fixture
+def fake_emailer() -> FakeEmailSender:
+    return FakeEmailSender()
+
+@pytest.fixture
+def user_service(fake_repo: FakeUserRepo, fake_emailer: FakeEmailSender) -> UserService:
+    return UserService(repo=fake_repo, emailer=fake_emailer)
+
+def test_create_user_sends_welcome_email(
+    user_service: UserService,
+    fake_emailer: FakeEmailSender,
+) -> None:
+    user_service.create_user(CreateUserRequest(name="Alice", email="a@b.com"))
+    assert fake_emailer.sent_count == 1
+    assert fake_emailer.last_to == "a@b.com"
+```
+
+### Parametrized Tests
+
+```python
+@pytest.mark.parametrize(
+    "input_age, expected_valid",
+    [
+        (25, True),
+        (0, True),
+        (150, True),
+        (-1, False),
+        (151, False),
+        (None, False),
+    ],
+)
+def test_age_validation(input_age: int | None, expected_valid: bool) -> None:
+    result = validate_age(input_age)
+    assert result.is_valid == expected_valid
+```
+
+## Structured Logging
+
+```python
+import structlog
+
+logger = structlog.get_logger()
+
+def process_order(order: Order) -> OrderResult:
+    log = logger.bind(order_id=order.id, user_id=order.user_id)
+    log.info("processing_order", item_count=len(order.items))
+
+    try:
+        result = fulfill(order)
+        log.info("order_fulfilled", total=result.total)
+        return result
+    except InsufficientStockError as e:
+        log.warning("order_failed_stock", item_id=e.item_id)
+        raise
+```
+
+## Enum Patterns
+
+```python
+from enum import Enum, auto
+
+class OrderStatus(Enum):
+    PENDING = auto()
+    PROCESSING = auto()
+    SHIPPED = auto()
+    DELIVERED = auto()
+    CANCELLED = auto()
+
+    @property
+    def is_terminal(self) -> bool:
+        return self in (OrderStatus.DELIVERED, OrderStatus.CANCELLED)
+
+    def can_transition_to(self, target: "OrderStatus") -> bool:
+        valid = {
+            OrderStatus.PENDING: {OrderStatus.PROCESSING, OrderStatus.CANCELLED},
+            OrderStatus.PROCESSING: {OrderStatus.SHIPPED, OrderStatus.CANCELLED},
+            OrderStatus.SHIPPED: {OrderStatus.DELIVERED},
+        }
+        return target in valid.get(self, set())
+```

package/shared/skills/python/references/violations.md

@@ -0,0 +1,204 @@
+# Python Violation Examples
+
+Extended violation patterns for Python reviews. Reference from main SKILL.md.
+
+## Type Safety Violations
+
+### Missing Type Hints
+
+```python
+# VIOLATION: No type annotations
+def process(data, config):
+    result = transform(data)
+    return result
+
+# VIOLATION: Partial annotations (inconsistent)
+def save(user: User, db):  # db missing type
+    return db.insert(user)
+
+# VIOLATION: Missing return type
+def calculate_total(items: list[Item]):
+    return sum(item.price for item in items)
+```
+
+### Bare Except Clauses
+
+```python
+# VIOLATION: Catches everything including SystemExit and KeyboardInterrupt
+try:
+    process_data()
+except:
+    pass
+
+# VIOLATION: Catches too broadly and silences
+try:
+    user = fetch_user(user_id)
+except Exception:
+    user = None  # Hides real errors (network, auth, parsing)
+
+# VIOLATION: Bare except with logging but no re-raise
+try:
+    critical_operation()
+except:
+    logger.error("Something failed")
+    # Swallows the error — caller never knows
+```
+
+## Data Modeling Violations
+
+### Raw Dicts Instead of Dataclasses
+
+```python
+# VIOLATION: Untyped dict — no IDE support, no validation
+user = {
+    "name": "Alice",
+    "email": "alice@example.com",
+    "age": 30,
+}
+
+# VIOLATION: Accessing dict keys without safety
+def get_display_name(user: dict) -> str:
+    return f"{user['first_name']} {user['last_name']}"  # KeyError risk
+
+# VIOLATION: Nested untyped dicts
+config = {
+    "database": {
+        "host": "localhost",
+        "port": 5432,
+    },
+    "cache": {
+        "ttl": 300,
+    },
+}
+```
+
+### Mutable Default Arguments
+
+```python
+# VIOLATION: Mutable default shared across calls
+def add_item(item: str, items: list[str] = []) -> list[str]:
+    items.append(item)
+    return items
+
+# VIOLATION: Dict default mutated in place
+def register(name: str, registry: dict[str, bool] = {}) -> None:
+    registry[name] = True
+
+# VIOLATION: Set default
+def collect(value: int, seen: set[int] = set()) -> set[int]:
+    seen.add(value)
+    return seen
+```
+
+## String Formatting Violations
+
+### Percent Formatting
+
+```python
+# VIOLATION: Old-style % formatting
+message = "Hello %s, you have %d messages" % (name, count)
+
+# VIOLATION: % formatting with dict — hard to read, error-prone
+log = "%(timestamp)s - %(level)s - %(message)s" % log_data
+```
+
+### String Concatenation in Loops
+
+```python
+# VIOLATION: O(n^2) string building
+result = ""
+for line in lines:
+    result += line + "\n"
+
+# CORRECT: Use join
+result = "\n".join(lines)
+```
+
+## Global State Violations
+
+### Module-Level Mutable State
+
+```python
+# VIOLATION: Global mutable state
+_cache = {}
+_connections = []
+
+def get_cached(key: str) -> Any:
+    return _cache.get(key)
+
+def add_connection(conn: Connection) -> None:
+    _connections.append(conn)
+
+# VIOLATION: Global variable modified by functions
+current_user = None
+
+def login(username: str) -> None:
+    global current_user
+    current_user = authenticate(username)
+```
+
+### Singleton via Module Import
+
+```python
+# VIOLATION: Hard-to-test singleton
+# db.py
+connection = create_connection(os.environ["DATABASE_URL"])
+
+# service.py
+from db import connection  # Cannot mock or swap for tests
+```
+
+## Import Violations
+
+### Wildcard Imports
+
+```python
+# VIOLATION: Pollutes namespace, hides dependencies
+from os.path import *
+from utils import *
+
+# VIOLATION: Star import in __init__.py
+# mypackage/__init__.py
+from .models import *
+from .services import *
+```
+
+### Circular Imports
+
+```python
+# VIOLATION: Circular dependency
+# models.py
+from services import UserService  # services imports models too
+
+# services.py
+from models import User  # Circular!
+```
+
+## Testing Violations
+
+### Assert in Production Code
+
+```python
+# VIOLATION: assert is stripped with -O flag
+def withdraw(account: Account, amount: float) -> None:
+    assert amount > 0, "Amount must be positive"  # Disabled in production!
+    assert account.balance >= amount, "Insufficient funds"
+    account.balance -= amount
+```
+
+### No pytest Fixtures
+
+```python
+# VIOLATION: Repeated setup in every test
+def test_create_user():
+    db = Database(":memory:")
+    db.create_tables()
+    service = UserService(db)
+    # ... test logic
+
+def test_update_user():
+    db = Database(":memory:")  # Duplicated setup
+    db.create_tables()
+    service = UserService(db)
+    # ... test logic
+```

package/shared/skills/react/SKILL.md

@@ -95,7 +95,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
   const [user, setUser] = useState<User | null>(null);
   const login = async (creds: Credentials) => setUser(await authApi.login(creds));
   const logout = () => { authApi.logout(); setUser(null); };
-  return <AuthContext.Provider value={{ user, login, logout }}>{children}</AuthContext.Provider>;
+  return <AuthContext value={{ user, login, logout }}>{children}</AuthContext>;
 }
 
 export function useAuth() {

package/shared/skills/react/references/patterns.md

@@ -429,9 +429,9 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
   };
 
   return (
-    <AuthContext.Provider value={{ user, login, logout, isLoading }}>
+    <AuthContext value={{ user, login, logout, isLoading }}>
       {children}
-    </AuthContext.Provider>
+    </AuthContext>
   );
 }
 
@@ -590,7 +590,7 @@ function SearchInput() {
 ```tsx
 // CORRECT: Track previous value for comparisons
 function usePrevious<T>(value: T): T | undefined {
-  const ref = useRef<T>();
+  const ref = useRef<T | undefined>(undefined);
 
   useEffect(() => {
     ref.current = value;

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`)