devflow-kit 1.8.3 → 2.0.1

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

@@ -1,369 +0,0 @@
-# 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

@@ -1,134 +0,0 @@
----
-name: database-patterns
-description: This skill should be used when reviewing database queries, migrations, indexes, or schema changes.
-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

@@ -1,208 +0,0 @@
-# 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