devflow-kit 1.8.2 → 2.0.0

package/src/assets/skills/java/references/violations.md

@@ -0,0 +1,257 @@
+# Common Java Violations
+
+Extended violation patterns for Java reviews with literature citations. Reference from main SKILL.md.
+
+---
+
+## Null Returns [1, Item 22]
+
+Returning `null` forces callers to null-check — easy to forget, causes NPE at
+unpredictable call sites. Use `Optional` to encode absence in the type. [1, Item 22][25]
+
+### Returning null Instead of Optional
+
+```java
+// VIOLATION: Null return forces callers to null-check [1, Item 22]
+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 [1, Item 54]
+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 [1, Item 26][3]
+
+Raw types bypass the generic type system entirely. Use of raw `List`, `Map`, or
+`Comparable` generates unchecked warnings and enables runtime `ClassCastException`. [1, Item 26]
+
+### Unparameterized Generics
+
+```java
+// VIOLATION: Raw List — no type safety [1, Item 26]
+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 [1, Item 26]
+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 [1]
+
+Broad `throws Exception` declarations hide what can actually go wrong. Callers can't
+catch specific failures and must either re-throw or swallow. Swallowing silently is
+the worst outcome. [1]
+
+### Broad Throws Declarations
+
+```java
+// VIOLATION: throws Exception — hides what can actually go wrong [1]
+public User createUser(String name) throws Exception {
+    // Callers must catch Exception, can't handle specific failures
+}
+
+// VIOLATION: Wrapping everything in checked exceptions [1]
+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 — resource leak hidden [1]
+try {
+    connection.close();
+} catch (SQLException e) {
+    // silently ignored
+}
+
+// VIOLATION: Catching and logging only [1]
+try {
+    processPayment(order);
+} catch (PaymentException e) {
+    logger.error("Payment failed", e);
+    // Continues as if nothing happened — order in inconsistent state
+}
+```
+
+---
+
+## Mutable Data Objects [1, Item 17][4]
+
+JavaBean-style mutation breaks encapsulation: any caller, anywhere, at any time,
+can change state. Records enforce immutability structurally. [1, Item 17][4][9]
+
+### JavaBean-Style Mutability
+
+```java
+// VIOLATION: Mutable DTO with setters [1, Item 17]
+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 [1, Item 50]
+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 [1, Item 18][14]
+
+Inheritance for code reuse creates a fragile base class problem: changes to any
+ancestor break all descendants without warning. Prefer composition. [1, Item 18]
+
+### Fragile Base Class
+
+```java
+// VIOLATION: Deep hierarchy creates tight coupling [1, Item 18]
+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 [1, Item 18]
+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 [1, Item 18]
+```
+
+---
+
+## Concurrency Violations [2][12]
+
+Shared mutable state accessed from multiple threads without synchronization causes
+data races. The Java Memory Model does not guarantee visibility without
+`volatile` or `synchronized`. — Java Concurrency in Practice [2]
+
+### Shared Mutable State Without Synchronization
+
+```java
+// VIOLATION: HashMap accessed from multiple threads [2, Ch. 2]
+private Map<String, Session> sessions = new HashMap<>();
+
+public void addSession(String id, Session s) {
+    sessions.put(id, s); // Not thread-safe — use ConcurrentHashMap [2, Ch. 5]
+}
+```
+
+### Double-Checked Locking Done Wrong [2, Ch. 16][12]
+
+Missing `volatile` allows the JVM to publish a partially-constructed object due to
+instruction reordering. — JSR-133 Cookbook [12]
+
+```java
+// VIOLATION: Missing volatile on lazily-initialized field [2, Ch. 16][12]
+private ExpensiveObject instance;
+
+public ExpensiveObject getInstance() {
+    if (instance == null) {
+        synchronized (this) {
+            if (instance == null) {
+                instance = new ExpensiveObject(); // Partially constructed object visible
+            }
+        }
+    }
+    return instance;
+}
+
+// CORRECT: volatile ensures happens-before [12]
+private volatile ExpensiveObject instance;
+```
+
+---
+
+## Stream Anti-Patterns [10][26]
+
+Streams with side effects in `forEach` and nested streams are hard to reason about.
+Prefer explicit for-loops for side effects and collect for transformation. [10]
+
+```java
+// VIOLATION: forEach with side effects — prefer for-loop [1, Item 46]
+users.stream().forEach(u -> externalService.notify(u));
+
+// VIOLATION: collect(Collectors.toList()) is verbose since Java 16 [26]
+List<String> names = users.stream().map(User::name).collect(Collectors.toList());
+
+// CORRECT: .toList() returns unmodifiable list [26]
+List<String> names = users.stream().map(User::name).toList();
+```

package/src/assets/skills/patterns/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: patterns
+description: This skill should be used when the user asks to "create an API endpoint", "add CRUD operations", "implement event handlers", "set up logging", "add configuration", or builds features involving database operations, REST/GraphQL APIs, pub/sub patterns, or service configuration. Provides implementation patterns that follow existing codebase conventions.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Implementation Patterns
+
+Reference for common implementation patterns. Use these patterns to write consistent, maintainable code.
+
+## Iron Law
+
+> **FOLLOW EXISTING PATTERNS**
+>
+> Match the codebase style, don't invent new conventions. If the project uses Result types,
+> use Result types. If it uses exceptions, use exceptions. Consistency trumps personal
+> preference. The best pattern is the one already in use.
+
+## When This Skill Activates
+
+- Implementing CRUD operations
+- Creating API endpoints
+- Writing event handlers
+- Setting up configuration
+- Adding logging
+- Database operations
+
+---
+
+## Pattern Categories
+
+### CRUD Operations
+
+Create, Read, Update, Delete with Result types and proper error handling.
+
+**Core pattern**: Validate -> Transform -> Persist -> Return
+
+```typescript
+async function createUser(input: CreateUserInput): Promise<Result<User, CreateError>> {
+  const validated = validateCreateUser(input);
+  if (!validated.ok) return Err({ type: 'validation', details: validated.error });
+
+  const user: User = { id: generateId(), ...validated.value, createdAt: new Date() };
+  const saved = await userRepository.save(user);
+  if (!saved.ok) return Err({ type: 'persistence', details: saved.error });
+
+  return Ok(saved.value);
+}
+```
+
+### API Endpoints
+
+REST endpoint structure with auth, validation, and error mapping.
+
+**Core pattern**: Parse request -> Validate auth -> Execute -> Format response
+
+```typescript
+export async function handleGetUser(req: Request): Promise<Response> {
+  const id = parsePathParam(req, 'id');
+  if (!id.ok) return errorResponse(400, 'Invalid user ID');
+
+  const auth = await authenticate(req);
+  if (!auth.ok) return errorResponse(401, 'Unauthorized');
+
+  const result = await getUser(id.value);
+  if (!result.ok) return handleError(result.error);
+
+  return jsonResponse(200, result.value);
+}
+```
+
+### Event Handlers
+
+Async event processing with idempotency and error recovery.
+
+**Core pattern**: Validate event -> Process -> Handle errors -> Acknowledge
+
+```typescript
+async function handleUserCreated(event: UserCreatedEvent): Promise<void> {
+  const validated = validateEvent(event);
+  if (!validated.ok) { logger.warn('Invalid event'); return; }
+
+  await sendWelcomeEmail(event.userId);
+  await createDefaultSettings(event.userId);
+  logger.info('Event processed successfully');
+}
+```
+
+### Configuration
+
+Environment config with schema validation and feature flags.
+
+**Core pattern**: Define schema -> Load from env -> Validate -> Export frozen
+
+```typescript
+const ConfigSchema = z.object({
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+});
+
+export const config = Object.freeze(ConfigSchema.parse(process.env));
+```
+
+### Logging
+
+Structured logging with context propagation and operation tracking.
+
+**Core pattern**: Context -> Level -> Message -> Data
+
+```typescript
+const logger = createLogger({ requestId: req.id, userId: user.id });
+logger.info('Processing order', { orderId: order.id, items: order.items.length });
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Fix |
+|--------------|---------|-----|
+| God functions | 500-line functions doing everything | Compose small, focused functions |
+| Implicit dependencies | Using global state (`db.query(...)`) | Inject dependencies explicitly |
+| Swallowing errors | Empty catch blocks | Handle or propagate with Result types |
+| Magic values | Unexplained numbers/strings | Extract to named constants |
+
+---
+
+## Build Optimization
+
+Production builds must exclude test files, debug artifacts, and sourcemaps.
+
+```json
+// tsconfig.prod.json
+{
+  "exclude": ["**/*.test.ts", "**/*.spec.ts", "**/tests/**"]
+}
+```
+
+---
+
+## Implementation Checklist
+
+Before implementing, verify:
+
+- [ ] Using Result types for operations that can fail
+- [ ] Validating input at system boundaries
+- [ ] Logging with context (requestId, userId, operation)
+- [ ] Handling all error cases explicitly
+- [ ] Making operations idempotent where possible
+- [ ] Using transactions for multi-step operations
+- [ ] No hardcoded values (use config)
+- [ ] Following existing codebase patterns
+
+---
+
+## Extended References
+
+For full implementation examples:
+- `references/violations.md` - Extended violation examples (CRUD, API, Events, Config, Logging)
+- `references/patterns.md` - Extended correct patterns (CRUD, API, Events, Config, Logging)

package/src/assets/skills/performance/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: performance
+description: This skill should be used when reviewing code for N+1 queries, memory leaks, or I/O bottlenecks.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Performance Patterns
+
+Domain expertise for performance optimization and bottleneck detection. Use alongside `devflow:review-methodology` for complete performance reviews.
+
+## Iron Law
+
+> **MEASURE BEFORE OPTIMIZING**
+>
+> Profile first, optimize second. Every performance claim requires benchmarks. Brendan
+> Gregg's USE Method [1] (Utilization, Saturation, Errors) and Tom Wilkie's RED Method [2]
+> (Rate, Errors, Duration) are the systematic starting points — not guesswork.
+> Gil Tene's coordinated omission warning [8]: averages lie — monitor P99, not mean latency.
+
+---
+
+## Measurement Foundation [1][2][7][8][9]
+
+| Method | For | Measures |
+|--------|-----|---------|
+| USE Method [1] | System resources | Utilization, Saturation, Errors per resource |
+| RED Method [2] | Services | Rate, Errors, Duration per endpoint |
+| Flame Graphs [9] | CPU hot paths | Widest frames = hottest code — optimize those |
+| HDR Histogram [8] | Latency | Full distribution without coordinated omission |
+
+**Latency hierarchy** [7]: L1 cache ~1ns · L2 ~4ns · L3 ~40ns · RAM ~100ns · SSD ~100µs · Network (DC) ~500µs · HDD ~10ms. Knowing these prevents optimizing the wrong layer [4].
+
+---
+
+## Performance Categories
+
+### 1. Algorithmic Issues [5][12]
+
+**N+1 Query Problem** — database query inside a loop. O(n) round-trips [5].
+
+```typescript
+// VIOLATION: 1 + N queries — O(n) round-trips [5]
+for (const user of users) {
+  user.orders = await db.orders.findByUserId(user.id);
+}
+
+// CORRECT: Batch query with Map lookup — O(1) per access [5]
+const orders = await db.orders.findAll({ where: { userId: userIds } });
+const ordersByUser = new Map(groupBy(orders, 'userId'));
+users.forEach(u => u.orders = ordersByUser.get(u.id) || []);
+```
+
+**O(n²) Patterns** — linear search inside a loop [12].
+
+```typescript
+// VIOLATION: Array.includes is O(n), called n times → O(n²) [12]
+items.filter(item => selected.includes(item.id));
+
+// CORRECT: Set lookup is O(1) → total O(n) [12]
+const selectedSet = new Set(selected);
+items.filter(item => selectedSet.has(item.id));
+```
+
+### 2. Memory Issues [4][10]
+
+**Memory Leaks** — resources not cleaned up. Hidden by GC until OOM [4].
+**Cache line false sharing** — hot fields on the same 64-byte line cause inter-core invalidation in high-throughput code [4][10].
+**Unbounded caches** — collections that grow forever. Use LRU with a `max` limit [4].
+
+### 3. I/O Issues [3][16]
+
+**Blocking Operations** — synchronous I/O in request path blocks the event loop [3][16].
+
+```typescript
+const config = fs.readFileSync('./config.json');           // VIOLATION [3]
+const config = await fs.promises.readFile('./config.json'); // CORRECT [16]
+```
+
+**Sequential When Parallel Possible** — independent operations run serially [5].
+
+```typescript
+// VIOLATION: total = sum of all [5]
+const user = await getUser(id); const orders = await getOrders(id);
+// CORRECT: total = max of all
+const [user, orders] = await Promise.all([getUser(id), getOrders(id)]);
+```
+
+### 4. Database Issues [20]
+
+Missing indexes, SELECT *, OFFSET pagination on large tables, LIKE with leading wildcard. See `references/violations.md`.
+
+### 5. Frontend / Web Vitals [6][17][21]
+
+| Metric | Good | Poor | Measures |
+|--------|------|------|---------|
+| LCP [6] | < 2.5s | > 4s | Largest element load |
+| INP [21] | < 200ms | > 500ms | Input responsiveness |
+| CLS [6] | < 0.1 | > 0.25 | Layout stability |
+
+Unnecessary re-renders, missing virtualization, missing code splitting. See `references/violations.md`.
+
+---
+
+## Extended References
+
+| Reference | Content |
+|-----------|---------|
+| `references/sources.md` | Full bibliography (25 sources) |
+| `references/violations.md` | Extended violations with citations [n] |
+| `references/patterns.md` | Correct patterns with citations [n] |
+| `references/detection.md` | Grep commands, profiling, CI integration |
+
+---
+
+## Severity Guidelines
+
+| Severity | Examples |
+|----------|----------|
+| **CRITICAL** | N+1 with unbounded data [5], memory leaks [4], blocking I/O in handlers [3] |
+| **HIGH** | Sequential async [5], SELECT * [20], unbounded caches [4], LCP > 4s [6] |
+| **MEDIUM** | Suboptimal algorithm on small data [12], missing memoization, INP > 200ms [21] |
+| **LOW** | Micro-optimizations, premature optimization candidates [1] |
+
+---
+
+## Quick Detection
+
+```bash
+grep -rn "for.*await\|\.forEach.*async" --include="*.ts"  # N+1
+grep -rn "readFileSync\|writeFileSync" --include="*.ts"   # Sync I/O
+grep -rn "SELECT \*" --include="*.ts" --include="*.sql"   # SELECT *
+```
+
+See `references/detection.md` for comprehensive detection patterns.