devflow-kit 0.8.1 → 1.0.0

package/shared/skills/core-patterns/references/violations.md

@@ -0,0 +1,369 @@
+# Extended Violation Examples
+
+Additional code smell patterns and violations beyond the core examples in SKILL.md.
+
+---
+
+## Result Types - Extended Violations
+
+### Try/Catch in Business Logic
+
+```typescript
+// VIOLATION: Try/catch in business logic
+function calculate(items: Item[]): number {
+  try {
+    return items.reduce((sum, i) => sum + i.price, 0);
+  } catch {
+    return 0;  // Silent failure - BAD
+  }
+}
+
+// VIOLATION: Nested try/catch
+async function processOrder(id: string): Promise<Order> {
+  try {
+    const order = await fetchOrder(id);
+    try {
+      await validateOrder(order);
+    } catch {
+      // Swallowed validation error
+    }
+    return order;
+  } catch {
+    return null;  // Silent failure
+  }
+}
+
+// VIOLATION: Error type erasure
+function parseConfig(raw: string): Config {
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error('Parse failed');  // Lost original error context
+  }
+}
+```
+
+### Implicit Error States
+
+```typescript
+// VIOLATION: Using null/undefined for errors
+function findUser(id: string): User | null {
+  // Caller can't distinguish "not found" from "error occurred"
+  return null;
+}
+
+// VIOLATION: Using sentinel values
+function calculateDiscount(userId: string): number {
+  // Returns -1 for errors - magic value
+  if (!userId) return -1;
+  return computeDiscount(userId);
+}
+
+// VIOLATION: Throwing in async without Result
+async function fetchData(url: string): Promise<Data> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error('Fetch failed');  // Should return Result
+  }
+  return response.json();
+}
+```
+
+---
+
+## Dependency Injection - Extended Violations
+
+### Hidden Dependencies
+
+```typescript
+// VIOLATION: Hidden dependencies via imports
+import { config } from './config';  // Global config
+import { analytics } from './analytics';  // Global analytics
+
+class UserService {
+  createUser(data: UserData) {
+    // Uses global config - can't test with different config
+    if (config.features.requireEmailVerification) {
+      // ...
+    }
+    // Uses global analytics - can't mock in tests
+    analytics.track('user_created', data);
+  }
+}
+
+// VIOLATION: Static method dependencies
+class OrderService {
+  processOrder(order: Order) {
+    // Can't mock static methods
+    const tax = TaxCalculator.calculate(order.total);
+    const shipping = ShippingService.getRate(order.address);
+  }
+}
+
+// VIOLATION: Service locator anti-pattern
+class PaymentService {
+  process(payment: Payment) {
+    // Runtime dependency resolution - untestable
+    const gateway = ServiceLocator.resolve<PaymentGateway>('paymentGateway');
+    return gateway.charge(payment);
+  }
+}
+```
+
+### Partial Injection
+
+```typescript
+// VIOLATION: Some dependencies injected, others not
+class ReportService {
+  constructor(private db: Database) {}  // Injected
+
+  generate(reportId: string) {
+    const data = this.db.query(reportId);
+    // But logger is global
+    logger.info('Report generated');  // BAD
+    // And config is imported
+    if (config.features.pdfExport) {  // BAD
+      // ...
+    }
+  }
+}
+```
+
+---
+
+## Immutability - Extended Violations
+
+### Array Mutations
+
+```typescript
+// VIOLATION: In-place array modifications
+function processItems(items: Item[]): Item[] {
+  items.push({ id: 'new' });  // BAD - mutates input
+  items.splice(0, 1);  // BAD - mutates input
+  items.reverse();  // BAD - mutates in place
+  items.fill({ id: 'default' });  // BAD - mutates in place
+  return items;
+}
+
+// VIOLATION: Sorting without copy
+function getSortedUsers(users: User[]): User[] {
+  return users.sort((a, b) => a.name.localeCompare(b.name));  // Mutates original!
+}
+
+// VIOLATION: Using forEach for transformation
+function transformItems(items: Item[]): Item[] {
+  items.forEach(item => {
+    item.processed = true;  // BAD - mutation
+  });
+  return items;
+}
+```
+
+### Object Mutations
+
+```typescript
+// VIOLATION: Nested object mutation
+function updateAddress(user: User, city: string): User {
+  user.address.city = city;  // BAD - nested mutation
+  return user;
+}
+
+// VIOLATION: Object.assign mutating first argument
+function mergeConfig(base: Config, overrides: Partial<Config>): Config {
+  return Object.assign(base, overrides);  // BAD - mutates base
+}
+
+// VIOLATION: Deleting properties
+function removeField(obj: Record<string, unknown>, field: string) {
+  delete obj[field];  // BAD - mutation
+  return obj;
+}
+```
+
+---
+
+## Pure Functions - Extended Violations
+
+### Side Effect Patterns
+
+```typescript
+// VIOLATION: Accessing global state
+let counter = 0;
+function getNextId(): string {
+  return `id-${counter++}`;  // BAD - global state modification
+}
+
+// VIOLATION: Date/time dependency
+function isExpired(expiry: Date): boolean {
+  return new Date() > expiry;  // BAD - depends on current time
+}
+
+// VIOLATION: Random values
+function generateToken(): string {
+  return Math.random().toString(36);  // BAD - non-deterministic
+}
+
+// VIOLATION: Environment access
+function getApiUrl(): string {
+  return process.env.API_URL || 'http://localhost';  // BAD - env dependency
+}
+```
+
+### Hidden I/O
+
+```typescript
+// VIOLATION: Caching with side effects
+const cache = new Map();
+function expensiveCalculation(input: string): number {
+  if (cache.has(input)) return cache.get(input);  // BAD - reads global state
+  const result = compute(input);
+  cache.set(input, result);  // BAD - writes global state
+  return result;
+}
+
+// VIOLATION: Lazy initialization
+let initialized = false;
+function ensureInitialized(): void {
+  if (!initialized) {
+    performSetup();  // BAD - side effect
+    initialized = true;  // BAD - global state
+  }
+}
+```
+
+---
+
+## Type Safety - Extended Violations
+
+### Type Assertions Abuse
+
+```typescript
+// VIOLATION: Unsafe type assertion
+const user = data as User;  // No runtime check
+
+// VIOLATION: Non-null assertion
+const name = user!.profile!.name!;  // Assumes non-null
+
+// VIOLATION: Any escape hatch
+function process(data: unknown) {
+  return (data as any).property.nested;  // BAD
+}
+
+// VIOLATION: Type assertion to bypass checks
+const items: Item[] = response.data as Item[];  // No validation
+```
+
+### Incomplete Discrimination
+
+```typescript
+// VIOLATION: Default case hiding missing patterns
+function handleEvent(event: Event): void {
+  switch (event.type) {
+    case 'click':
+      handleClick(event);
+      break;
+    default:
+      // Silently ignores new event types
+      break;
+  }
+}
+
+// VIOLATION: Using if/else instead of exhaustive switch
+function getLabel(status: Status): string {
+  if (status === 'pending') return 'Waiting';
+  if (status === 'active') return 'Running';
+  return 'Unknown';  // BAD - misses new status types
+}
+```
+
+---
+
+## Resource Cleanup - Extended Violations
+
+### Connection Leaks
+
+```typescript
+// VIOLATION: Connection not released on error
+async function queryDatabase(sql: string) {
+  const conn = await pool.getConnection();
+  const result = await conn.query(sql);  // If this throws, connection leaks
+  conn.release();
+  return result;
+}
+
+// VIOLATION: Stream not closed
+function readFile(path: string) {
+  const stream = fs.createReadStream(path);
+  stream.on('data', chunk => process(chunk));
+  // No close handler - stream never closed on error
+}
+
+// VIOLATION: Subscription not unsubscribed
+function setupListener(emitter: EventEmitter) {
+  emitter.on('event', handler);
+  // No cleanup - memory leak
+}
+```
+
+### Timer Leaks
+
+```typescript
+// VIOLATION: Interval not cleared
+function startPolling() {
+  setInterval(() => {
+    fetchData();
+  }, 1000);
+  // No way to stop polling
+}
+
+// VIOLATION: Timeout not cleared on early exit
+async function withTimeout(promise: Promise<unknown>, ms: number) {
+  const timeout = setTimeout(() => { throw new Error('Timeout'); }, ms);
+  const result = await promise;  // If this resolves, timeout still pending
+  return result;
+}
+```
+
+---
+
+## API Consistency - Extended Violations
+
+### Mixed Error Handling
+
+```typescript
+// VIOLATION: Mixed error handling in same module
+class UserRepository {
+  // Returns null for not found
+  findById(id: string): User | null { ... }
+
+  // Throws for not found
+  getById(id: string): User {
+    const user = this.findById(id);
+    if (!user) throw new NotFoundError();  // Inconsistent!
+    return user;
+  }
+
+  // Returns Result
+  findByEmail(email: string): Result<User, Error> { ... }  // Third pattern!
+}
+```
+
+### Mixed Async Patterns
+
+```typescript
+// VIOLATION: Mixing callbacks and promises
+function fetchUser(id: string, callback?: (err: Error, user: User) => void): Promise<User> {
+  const promise = api.get(`/users/${id}`);
+  if (callback) {
+    promise.then(user => callback(null, user)).catch(err => callback(err, null));
+  }
+  return promise;
+}
+
+// VIOLATION: Fire-and-forget async
+async function processOrder(order: Order) {
+  saveOrder(order);  // Missing await - fire and forget
+  await sendEmail(order.email);  // This one awaits
+  logAnalytics(order);  // Missing await again
+}
+```

package/shared/skills/database-patterns/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: database-patterns
+description: Database analysis patterns for code review. Detects missing indexes, slow queries, unsafe migrations, schema design issues, and connection pool misuse. Loaded by Reviewer agent when focus=database.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Database Patterns
+
+Domain expertise for database design and optimization. Use alongside `review-methodology` for complete database reviews.
+
+## Iron Law
+
+> **EVERY QUERY MUST HAVE AN EXECUTION PLAN**
+>
+> Never deploy a query without understanding its execution plan. Every WHERE clause needs
+> an index analysis. Every JOIN needs cardinality consideration. "It works in dev" is not
+> validation. Production data volumes will expose every missing index and inefficient join.
+
+## Database Categories
+
+### 1. Schema Design Issues
+
+| Issue | Problem | Solution |
+|-------|---------|----------|
+| Missing Foreign Keys | No referential integrity, orphaned records | Add FK with ON DELETE action |
+| Denormalization | Unnecessary duplication, update anomalies | Normalize unless performance requires |
+| Poor Data Types | VARCHAR for everything, lost precision | Use appropriate types (DECIMAL, BOOLEAN, TIMESTAMP) |
+| Missing Constraints | No data validation at DB level | Add NOT NULL, CHECK, UNIQUE constraints |
+
+**Example - Missing Constraints:**
+```sql
+-- VIOLATION
+CREATE TABLE products (id SERIAL, name VARCHAR(100), price DECIMAL);
+
+-- CORRECT
+CREATE TABLE products (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(100) NOT NULL CHECK (LENGTH(TRIM(name)) > 0),
+  price DECIMAL(10, 2) NOT NULL CHECK (price >= 0)
+);
+```
+
+### 2. Query Optimization Issues
+
+| Issue | Problem | Solution |
+|-------|---------|----------|
+| N+1 Queries | Query per iteration, O(n) round trips | JOIN or batch with IN/ANY |
+| Missing Indexes | Full table scans on large tables | Add indexes for WHERE/JOIN columns |
+| Full Table Scans | Functions prevent index use | Functional indexes or query rewrite |
+| Inefficient JOINs | Joining before filtering | Filter early, select specific columns |
+
+**Example - N+1 Query:**
+```typescript
+// VIOLATION: 101 queries for 100 users
+for (const user of users) {
+  user.orders = await db.query('SELECT * FROM orders WHERE user_id = ?', [user.id]);
+}
+
+// CORRECT: 2 queries total
+const orders = await db.query('SELECT * FROM orders WHERE user_id = ANY($1)', [userIds]);
+```
+
+### 3. Migration Issues
+
+| Issue | Problem | Solution |
+|-------|---------|----------|
+| Breaking Changes | Data loss, no recovery path | Phased approach with backups |
+| Data Loss Risk | Type changes truncate data | Validate before changing types |
+| Missing Rollback | Cannot undo migration | Always implement down() method |
+| Performance Impact | Table locks during migration | Add columns nullable, backfill in batches |
+
+**Example - Safe Column Addition:**
+```sql
+-- Step 1: Add nullable (instant)
+ALTER TABLE users ADD COLUMN phone VARCHAR(20);
+-- Step 2: Backfill in batches
+UPDATE users SET phone = 'UNKNOWN' WHERE phone IS NULL AND id BETWEEN 1 AND 10000;
+-- Step 3: Add constraint after backfill
+ALTER TABLE users ALTER COLUMN phone SET NOT NULL;
+```
+
+### 4. Security Issues
+
+| Issue | Problem | Solution |
+|-------|---------|----------|
+| SQL Injection | String interpolation in queries | Parameterized queries only |
+| Excessive Privileges | App has GRANT ALL | Minimum required privileges |
+
+**Example - SQL Injection:**
+```typescript
+// VULNERABLE
+const query = `SELECT * FROM users WHERE email = '${email}'`;
+
+// SECURE
+const query = 'SELECT * FROM users WHERE email = $1';
+await db.query(query, [email]);
+```
+
+---
+
+## Extended References
+
+For detailed examples and detection commands, see:
+
+- **[references/violations.md](references/violations.md)** - Extended violation examples with explanations
+- **[references/patterns.md](references/patterns.md)** - Correct patterns and migration strategies
+- **[references/detection.md](references/detection.md)** - Automated detection commands
+
+---
+
+## Severity Guidelines
+
+| Severity | Criteria | Examples |
+|----------|----------|----------|
+| **CRITICAL** | Data integrity or severe performance | SQL injection, N+1 unbounded, data loss migrations, missing FK on critical relations |
+| **HIGH** | Significant database issues | Inefficient JOINs, missing constraints, migrations without rollback |
+| **MEDIUM** | Moderate concerns | Minor denormalization, missing non-critical indexes |
+| **LOW** | Minor improvements | Naming conventions, index organization |
+
+---
+
+## Database Checklist
+
+Before approving database changes:
+
+- [ ] All queries have appropriate indexes
+- [ ] N+1 patterns identified and resolved
+- [ ] Migrations have rollback scripts
+- [ ] Data types are appropriate
+- [ ] Constraints enforce business rules
+- [ ] Foreign keys maintain referential integrity
+- [ ] No SQL injection vulnerabilities
+- [ ] Performance tested with production-like data volume

package/shared/skills/database-patterns/references/detection.md

@@ -0,0 +1,208 @@
+# Database Issue Detection
+
+Commands and patterns for detecting database issues in code reviews.
+
+## Automated Detection Commands
+
+### SQL Injection Detection
+
+```bash
+# String interpolation in queries (JavaScript/TypeScript)
+grep -rn "query.*\`.*\${" --include="*.ts" --include="*.js"
+grep -rn "query.*\(\`.*\${" --include="*.ts" --include="*.js"
+grep -rn 'query.*".*\+' --include="*.ts" --include="*.js"
+grep -rn "query.*'.*\+" --include="*.ts" --include="*.js"
+
+# String formatting in queries (Python)
+grep -rn 'execute.*f"' --include="*.py"
+grep -rn 'execute.*%' --include="*.py"
+grep -rn "execute.*\.format" --include="*.py"
+
+# Raw SQL with variables (any language)
+grep -rn "WHERE.*=.*'" --include="*.ts" --include="*.py" --include="*.go" | grep -v '\$'
+```
+
+### N+1 Query Detection
+
+```bash
+# Queries inside loops (TypeScript/JavaScript)
+grep -rn -A 5 "for.*of\|forEach\|\.map(" --include="*.ts" | grep -B 2 "await.*query\|await.*find"
+
+# ORM patterns that suggest N+1
+grep -rn "\.find.*{.*where" --include="*.ts" | grep -B 5 "for\|forEach\|map"
+
+# Sequential awaits that might be batched
+grep -rn "await.*await.*await" --include="*.ts"
+```
+
+### SELECT * Detection
+
+```bash
+# Direct SELECT * usage
+grep -rn "SELECT \*" --include="*.ts" --include="*.js" --include="*.sql"
+grep -rn 'SELECT \*' --include="*.py"
+
+# ORM patterns that select all columns
+grep -rn "\.find\(\)\|\.findAll\(\)\|\.all\(\)" --include="*.ts"
+```
+
+### Missing Index Indicators
+
+```bash
+# Queries with multiple WHERE conditions (potential composite index)
+grep -rn "WHERE.*AND.*AND" --include="*.ts" --include="*.sql"
+
+# Queries with ORDER BY (potential index needed)
+grep -rn "ORDER BY" --include="*.ts" --include="*.sql"
+
+# Queries with LIKE patterns
+grep -rn "LIKE.*%" --include="*.ts" --include="*.sql"
+```
+
+### Migration Risk Detection
+
+```bash
+# Dangerous migration operations
+find . -path "*/migrations/*" -o -path "*/migrate/*" | xargs grep -l "DROP\|DELETE\|TRUNCATE\|ALTER.*DROP"
+
+# Migrations without down method
+find . -path "*/migrations/*" -name "*.ts" | xargs grep -L "down"
+
+# NOT NULL additions (potential lock)
+find . -path "*/migrations/*" | xargs grep -n "NOT NULL"
+
+# Type changes
+find . -path "*/migrations/*" | xargs grep -n "ALTER.*TYPE\|MODIFY.*COLUMN"
+```
+
+### Security Pattern Detection
+
+```bash
+# Hardcoded credentials
+grep -rn "password.*=\|PASSWORD.*=\|secret.*=\|SECRET.*=" --include="*.ts" --include="*.env*"
+
+# Connection strings with credentials
+grep -rn "postgresql://.*:.*@\|mysql://.*:.*@\|mongodb://.*:.*@" --include="*.ts" --include="*.js"
+
+# Excessive privilege grants
+grep -rn "GRANT ALL\|SUPERUSER\|WITH GRANT OPTION" --include="*.sql" --include="*.ts"
+```
+
+---
+
+## Manual Review Patterns
+
+### Schema Review Checklist
+
+```sql
+-- Check for missing foreign keys
+SELECT
+  tc.table_name,
+  kcu.column_name
+FROM information_schema.table_constraints tc
+JOIN information_schema.key_column_usage kcu
+  ON tc.constraint_name = kcu.constraint_name
+WHERE tc.constraint_type = 'PRIMARY KEY'
+  AND kcu.column_name LIKE '%_id'
+  AND NOT EXISTS (
+    SELECT 1 FROM information_schema.referential_constraints rc
+    WHERE rc.constraint_name = tc.constraint_name
+  );
+
+-- Check for missing NOT NULL on required fields
+SELECT table_name, column_name, data_type
+FROM information_schema.columns
+WHERE is_nullable = 'YES'
+  AND column_name IN ('email', 'name', 'status', 'created_at')
+ORDER BY table_name;
+
+-- Check for VARCHAR without length limit
+SELECT table_name, column_name
+FROM information_schema.columns
+WHERE data_type = 'character varying'
+  AND character_maximum_length IS NULL;
+```
+
+### Index Review Checklist
+
+```sql
+-- Tables without primary key
+SELECT table_name
+FROM information_schema.tables t
+WHERE table_type = 'BASE TABLE'
+  AND NOT EXISTS (
+    SELECT 1 FROM information_schema.table_constraints tc
+    WHERE tc.table_name = t.table_name
+      AND tc.constraint_type = 'PRIMARY KEY'
+  );
+
+-- Foreign key columns without index
+SELECT
+  tc.table_name,
+  kcu.column_name
+FROM information_schema.table_constraints tc
+JOIN information_schema.key_column_usage kcu
+  ON tc.constraint_name = kcu.constraint_name
+WHERE tc.constraint_type = 'FOREIGN KEY'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_indexes
+    WHERE tablename = tc.table_name
+      AND indexdef LIKE '%' || kcu.column_name || '%'
+  );
+
+-- Unused indexes (PostgreSQL)
+SELECT
+  schemaname,
+  tablename,
+  indexname,
+  idx_scan
+FROM pg_stat_user_indexes
+WHERE idx_scan = 0
+  AND indexname NOT LIKE '%pkey%'
+ORDER BY pg_relation_size(indexrelid) DESC;
+```
+
+### Query Performance Review
+
+```sql
+-- Check execution plan for specific query
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+SELECT * FROM orders WHERE customer_id = 123;
+
+-- Expected good plan indicators:
+-- - Index Scan or Index Only Scan
+-- - Low cost estimates
+-- - Small row estimates matching actual
+
+-- Red flags in execution plans:
+-- - Seq Scan on large tables
+-- - Nested Loop with high row counts
+-- - Sort operations without index
+-- - Hash Join with large tables
+```
+
+---
+
+## Code Review Triggers
+
+When reviewing code, flag for database review if you see:
+
+### High Priority (Always Review)
+
+1. **New migration files** - Check for data loss risk, rollback strategy
+2. **Raw SQL queries** - Check for injection, parameterization
+3. **Loops with database calls** - Check for N+1 patterns
+4. **Schema changes** - Check for breaking changes, constraints
+
+### Medium Priority (Sample Review)
+
+1. **ORM model changes** - Verify schema alignment
+2. **New query methods** - Check for efficiency
+3. **Bulk operations** - Check for batching
+4. **Transaction usage** - Check for proper isolation
+
+### Low Priority (Spot Check)
+
+1. **Read-only queries** - Verify index usage
+2. **Logging of database data** - Check for sensitive data exposure
+3. **Error handling** - Check for proper connection cleanup