devflow-kit 1.0.0 → 1.2.0

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

@@ -0,0 +1,213 @@
+# Common Java Violations
+
+Extended violation patterns for Java reviews. Reference from main SKILL.md.
+
+---
+
+## Null Returns
+
+### Returning null Instead of Optional
+
+```java
+// VIOLATION: Null return forces callers to null-check
+public User findById(String id) {
+    return userMap.get(id); // Returns null if absent
+}
+
+// Callers must remember to check:
+User user = findById(id);
+user.getName(); // NullPointerException if not found
+```
+
+### Nullable Collections
+
+```java
+// VIOLATION: Returning null instead of empty collection
+public List<Order> getOrders(String userId) {
+    List<Order> orders = orderMap.get(userId);
+    return orders; // null if user has no orders
+}
+
+// Callers iterate without checking:
+for (Order o : getOrders(userId)) { // NullPointerException
+    process(o);
+}
+```
+
+---
+
+## Raw Types
+
+### Unparameterized Generics
+
+```java
+// VIOLATION: Raw List - no type safety
+List users = new ArrayList();
+users.add("not a user"); // No compile error
+users.add(42);           // No compile error
+User first = (User) users.get(0); // ClassCastException at runtime
+
+// VIOLATION: Raw Map
+Map cache = new HashMap();
+cache.put(123, "value");
+String val = (String) cache.get(123); // Unsafe cast
+```
+
+### Raw Type in Method Signatures
+
+```java
+// VIOLATION: Raw Comparable
+public class Price implements Comparable {
+    public int compareTo(Object other) {
+        return Double.compare(this.amount, ((Price) other).amount); // Unsafe cast
+    }
+}
+
+// VIOLATION: Raw Iterator
+Iterator it = collection.iterator();
+while (it.hasNext()) {
+    String s = (String) it.next(); // Unsafe cast
+}
+```
+
+---
+
+## Checked Exception Abuse
+
+### Broad Throws Declarations
+
+```java
+// VIOLATION: throws Exception - hides what can actually go wrong
+public User createUser(String name) throws Exception {
+    // Callers must catch Exception, can't handle specific failures
+}
+
+// VIOLATION: Wrapping everything in checked exceptions
+public void process(String data) throws ProcessingException {
+    try {
+        Integer.parseInt(data);
+    } catch (NumberFormatException e) {
+        throw new ProcessingException("Failed", e); // Unnecessary wrapping
+    }
+}
+```
+
+### Swallowed Exceptions
+
+```java
+// VIOLATION: Empty catch block
+try {
+    connection.close();
+} catch (SQLException e) {
+    // silently ignored - resource leak hidden
+}
+
+// VIOLATION: Catching and logging only
+try {
+    processPayment(order);
+} catch (PaymentException e) {
+    logger.error("Payment failed", e);
+    // Continues as if nothing happened - order in inconsistent state
+}
+```
+
+---
+
+## Mutable Data Objects
+
+### JavaBean-Style Mutability
+
+```java
+// VIOLATION: Mutable DTO with setters
+public class UserDTO {
+    private String name;
+    private String email;
+
+    public void setName(String name) { this.name = name; }
+    public void setEmail(String email) { this.email = email; }
+    public String getName() { return name; }
+    public String getEmail() { return email; }
+}
+
+// Anyone can modify at any time:
+dto.setName("changed"); // No control over when/where mutation happens
+```
+
+### Exposing Internal Mutable State
+
+```java
+// VIOLATION: Getter returns mutable internal list
+public class Team {
+    private List<String> members = new ArrayList<>();
+
+    public List<String> getMembers() {
+        return members; // Caller can modify internal state
+    }
+}
+
+// External code breaks encapsulation:
+team.getMembers().clear(); // Empties the team's internal list
+```
+
+---
+
+## Deep Inheritance
+
+### Fragile Base Class
+
+```java
+// VIOLATION: Deep hierarchy creates tight coupling
+public abstract class AbstractEntity { ... }
+public abstract class AbstractAuditableEntity extends AbstractEntity { ... }
+public abstract class AbstractVersionedEntity extends AbstractAuditableEntity { ... }
+public class User extends AbstractVersionedEntity { ... }
+
+// Changing any base class ripples through all descendants
+// Testing requires understanding 4 levels of behavior
+```
+
+### Inheritance for Code Reuse
+
+```java
+// VIOLATION: Extending just to reuse utility methods
+public class OrderService extends BaseService {
+    // Only extends BaseService to get logAndAudit() method
+    public void processOrder(Order order) {
+        logAndAudit("processing", order.getId()); // Inherited utility
+    }
+}
+// Should be: inject a LogAuditService instead
+```
+
+---
+
+## Concurrency Violations
+
+### Shared Mutable State Without Synchronization
+
+```java
+// VIOLATION: HashMap accessed from multiple threads
+private Map<String, Session> sessions = new HashMap<>();
+
+public void addSession(String id, Session s) {
+    sessions.put(id, s); // Not thread-safe
+}
+```
+
+### Double-Checked Locking Done Wrong
+
+```java
+// VIOLATION: Missing volatile on lazily-initialized field
+private ExpensiveObject instance;
+
+public ExpensiveObject getInstance() {
+    if (instance == null) {
+        synchronized (this) {
+            if (instance == null) {
+                instance = new ExpensiveObject(); // Partially constructed object visible
+            }
+        }
+    }
+    return instance;
+}
+```

package/shared/skills/python/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: python
+description: This skill should be used when the user works with Python files (.py), asks about "type hints", "protocols", "dataclasses", "async/await", "decorators", or discusses Pythonic patterns and data modeling. Provides patterns for type safety, error handling, data modeling, and async programming.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.py"
+  exclude:
+    - "venv/**"
+    - ".venv/**"
+    - "**/__pycache__/**"
+---
+
+# Python Patterns
+
+Reference for Python-specific patterns, type safety, and idioms.
+
+## Iron Law
+
+> **EXPLICIT IS BETTER THAN IMPLICIT**
+>
+> Type-hint every function signature. Name every exception. Use dataclasses over raw dicts.
+> Python's flexibility is a strength only when boundaries are explicit. Implicit behavior
+> causes debugging nightmares and makes codebases hostile to newcomers.
+
+## When This Skill Activates
+
+- Working with Python codebases
+- Designing typed APIs with type hints
+- Modeling data with dataclasses or Pydantic
+- Implementing async code
+- Structuring Python packages
+
+---
+
+## Type Safety
+
+### Type Hint Everything
+
+```python
+# BAD: def process(data, config): ...
+# GOOD:
+def process(data: list[dict[str, Any]], config: AppConfig) -> ProcessResult:
+    ...
+```
+
+### Use Protocols for Structural Typing
+
+```python
+from typing import Protocol
+
+class Repository(Protocol):
+    def find_by_id(self, id: str) -> User | None: ...
+    def save(self, entity: User) -> User: ...
+
+# Any class with these methods satisfies Repository — no inheritance needed
+```
+
+### Strict Optional Handling
+
+```python
+# BAD: def get_name(user): return user.name
+# GOOD:
+def get_name(user: User | None) -> str:
+    if user is None:
+        return "Anonymous"
+    return user.name
+```
+
+---
+
+## Error Handling
+
+### Custom Exception Hierarchies
+
+```python
+class AppError(Exception):
+    """Base application error."""
+
+class NotFoundError(AppError):
+    def __init__(self, entity: str, id: str) -> None:
+        super().__init__(f"{entity} {id} not found")
+        self.entity = entity
+        self.id = id
+
+class ValidationError(AppError):
+    def __init__(self, field: str, message: str) -> None:
+        super().__init__(f"Validation failed for {field}: {message}")
+```
+
+### Context Managers for Resources
+
+```python
+from contextlib import contextmanager
+
+@contextmanager
+def database_transaction(conn: Connection):
+    try:
+        yield conn
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        raise
+```
+
+---
+
+## Data Modeling
+
+### Dataclasses Over Raw Dicts
+
+```python
+# BAD: user = {"name": "Alice", "email": "alice@example.com"}
+# GOOD:
+@dataclass(frozen=True)
+class User:
+    name: str
+    email: str
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+```
+
+### Pydantic for Validation at Boundaries
+
+```python
+from pydantic import BaseModel, EmailStr
+
+class CreateUserRequest(BaseModel):
+    name: str
+    email: EmailStr
+    age: int = Field(ge=0, le=150)
+```
+
+---
+
+## Pythonic Patterns
+
+```python
+# Comprehensions over loops for transforms
+names = [user.name for user in users if user.active]
+
+# Enumerate over manual index tracking
+for i, item in enumerate(items):
+    process(i, item)
+
+# EAFP: Easier to Ask Forgiveness than Permission
+try:
+    value = mapping[key]
+except KeyError:
+    value = default
+```
+
+---
+
+## Anti-Patterns
+
+| Pattern | Bad | Good |
+|---------|-----|------|
+| Bare except | `except:` | `except (ValueError, KeyError):` |
+| Mutable default | `def fn(items=[])` | `def fn(items: list | None = None)` |
+| No type hints | `def process(data)` | `def process(data: DataFrame) -> Result` |
+| String typing | `x: "MyClass"` (without reason) | `from __future__ import annotations` |
+| God class | `class App` with 50 methods | Compose smaller focused classes |
+
+---
+
+## Extended References
+
+For additional patterns and examples:
+- `references/violations.md` - Common Python violations
+- `references/patterns.md` - Extended Python patterns
+- `references/detection.md` - Detection patterns for Python issues
+- `references/async.md` - Async Python patterns
+
+---
+
+## Checklist
+
+- [ ] All functions have type hints (params + return)
+- [ ] Custom exceptions with meaningful messages
+- [ ] Dataclasses or Pydantic for structured data
+- [ ] No bare `except:` clauses
+- [ ] No mutable default arguments
+- [ ] Context managers for resource management
+- [ ] `from __future__ import annotations` for forward refs
+- [ ] Protocols for structural typing (not ABC unless needed)
+- [ ] Comprehensions for simple transforms
+- [ ] Tests use pytest with fixtures

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

@@ -0,0 +1,220 @@
+# Async Python Patterns
+
+Deep-dive on async Python programming. Reference from main SKILL.md.
+
+## Core asyncio Patterns
+
+### Basic Async Function
+
+```python
+import asyncio
+from typing import Any
+
+async def fetch_user(user_id: str) -> User:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(f"/api/users/{user_id}") as response:
+            data = await response.json()
+            return User.model_validate(data)
+```
+
+### Concurrent Execution with gather
+
+```python
+async def load_dashboard(user_id: str) -> Dashboard:
+    # Independent fetches run concurrently
+    user, orders, preferences = await asyncio.gather(
+        fetch_user(user_id),
+        fetch_orders(user_id),
+        fetch_preferences(user_id),
+    )
+    return Dashboard(user=user, orders=orders, preferences=preferences)
+```
+
+## Structured Concurrency with TaskGroup
+
+### TaskGroup for Safe Concurrency (Python 3.11+)
+
+```python
+async def process_batch(items: list[Item]) -> list[Result]:
+    results: list[Result] = []
+
+    async with asyncio.TaskGroup() as tg:
+        for item in items:
+            tg.create_task(process_and_collect(item, results))
+
+    return results
+
+async def process_and_collect(item: Item, results: list[Result]) -> None:
+    result = await process_item(item)
+    results.append(result)
+```
+
+### Error Handling with TaskGroup
+
+```python
+async def resilient_batch(items: list[Item]) -> tuple[list[Result], list[Error]]:
+    results: list[Result] = []
+    errors: list[Error] = []
+
+    # TaskGroup cancels all tasks if one raises — wrap individual tasks
+    async def safe_process(item: Item) -> None:
+        try:
+            result = await process_item(item)
+            results.append(result)
+        except ProcessingError as e:
+            errors.append(Error(item_id=item.id, message=str(e)))
+
+    async with asyncio.TaskGroup() as tg:
+        for item in items:
+            tg.create_task(safe_process(item))
+
+    return results, errors
+```
+
+## Async Generators
+
+### Streaming Results
+
+```python
+from typing import AsyncGenerator
+
+async def stream_results(query: str, params: tuple = ()) -> AsyncGenerator[Record, None]:
+    async with get_connection() as conn:
+        cursor = await conn.execute(query, params)
+        async for row in cursor:
+            yield Record.from_row(row)
+
+# Usage
+async for record in stream_results("SELECT * FROM events WHERE type = ?", ("click",)):
+    await process(record)
+```
+
+### Async Generator with Cleanup
+
+```python
+async def paginated_fetch(url: str, page_size: int = 100) -> AsyncGenerator[Item, None]:
+    page = 0
+    while True:
+        response = await fetch_page(url, page=page, size=page_size)
+        if not response.items:
+            break
+        for item in response.items:
+            yield item
+        page += 1
+```
+
+## Semaphore for Rate Limiting
+
+### Bounded Concurrency
+
+```python
+async def fetch_all(urls: list[str], max_concurrent: int = 10) -> list[Response]:
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def bounded_fetch(url: str) -> Response:
+        async with semaphore:
+            return await fetch(url)
+
+    return await asyncio.gather(*[bounded_fetch(url) for url in urls])
+```
+
+## aiohttp Patterns
+
+### Client Session Management
+
+```python
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+@asynccontextmanager
+async def api_client(base_url: str) -> AsyncGenerator[aiohttp.ClientSession, None]:
+    timeout = aiohttp.ClientTimeout(total=30)
+    async with aiohttp.ClientSession(base_url, timeout=timeout) as session:
+        yield session
+
+# Usage — session reused for multiple requests
+async def sync_users(user_ids: list[str]) -> list[User]:
+    async with api_client("https://api.example.com") as client:
+        tasks = [fetch_user_with_session(client, uid) for uid in user_ids]
+        return await asyncio.gather(*tasks)
+
+async def fetch_user_with_session(
+    client: aiohttp.ClientSession, user_id: str
+) -> User:
+    async with client.get(f"/users/{user_id}") as response:
+        response.raise_for_status()
+        data = await response.json()
+        return User.model_validate(data)
+```
+
+## Timeout Patterns
+
+### Per-Operation Timeout
+
+```python
+async def fetch_with_timeout(url: str, timeout_seconds: float = 5.0) -> dict[str, Any]:
+    try:
+        async with asyncio.timeout(timeout_seconds):
+            return await fetch(url)
+    except TimeoutError:
+        raise OperationTimeout(f"Request to {url} timed out after {timeout_seconds}s")
+```
+
+## Anti-Patterns
+
+### Blocking Calls in Async Code
+
+```python
+# VIOLATION: Blocks the event loop
+async def bad_fetch(url: str) -> str:
+    import requests
+    return requests.get(url).text  # Blocks entire event loop!
+
+# CORRECT: Use async library or run in executor
+async def good_fetch(url: str) -> str:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            return await response.text()
+
+# CORRECT: Offload blocking call to thread pool
+async def run_blocking(func: Callable[..., R], *args: Any) -> R:
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, func, *args)
+```
+
+### Fire-and-Forget Without Error Handling
+
+```python
+# VIOLATION: Exception silently lost
+async def bad_handler(event: Event) -> None:
+    asyncio.create_task(send_notification(event))  # Error vanishes
+
+# CORRECT: Track the task and handle errors
+async def good_handler(event: Event) -> None:
+    task = asyncio.create_task(send_notification(event))
+    task.add_done_callback(handle_task_exception)
+
+def handle_task_exception(task: asyncio.Task[Any]) -> None:
+    if not task.cancelled() and task.exception() is not None:
+        logger.error("Background task failed", exc_info=task.exception())
+```
+
+### Sequential When Parallel Is Safe
+
+```python
+# VIOLATION: Unnecessarily sequential — 3x slower
+async def slow_load(user_id: str) -> Dashboard:
+    user = await fetch_user(user_id)
+    orders = await fetch_orders(user_id)
+    prefs = await fetch_preferences(user_id)
+    return Dashboard(user=user, orders=orders, preferences=prefs)
+
+# CORRECT: Concurrent — ~1x latency
+async def fast_load(user_id: str) -> Dashboard:
+    user, orders, prefs = await asyncio.gather(
+        fetch_user(user_id),
+        fetch_orders(user_id),
+        fetch_preferences(user_id),
+    )
+    return Dashboard(user=user, orders=orders, preferences=prefs)
+```