devflow-kit 0.8.1 → 1.0.0

package/plugins/devflow-code-review/skills/consistency-patterns/references/patterns.md

@@ -0,0 +1,202 @@
+# Correct Consistency Patterns Reference
+
+Extended examples of correct patterns to follow.
+
+---
+
+## Naming Conventions
+
+### Function Naming
+
+```typescript
+// EXISTING PATTERN: camelCase for functions
+function getUserById(id: string) { }
+function createOrder(data: OrderData) { }
+function validateInput(input: string) { }
+function processPayment(amount: number) { }
+
+// All new functions MUST match this style
+```
+
+### Class Naming
+
+```typescript
+// EXISTING PATTERN: PascalCase for classes
+class UserService { }
+class OrderRepository { }
+class PaymentGateway { }
+class ValidationError extends Error { }
+```
+
+### Constant Naming
+
+```typescript
+// EXISTING PATTERN: SCREAMING_SNAKE_CASE for true constants
+const MAX_RETRY_ATTEMPTS = 3;
+const API_BASE_URL = 'https://api.example.com';
+const DEFAULT_TIMEOUT_MS = 5000;
+
+// camelCase for configuration objects
+const serverConfig = { port: 3000 };
+```
+
+---
+
+## Error Handling
+
+### Result Type Pattern
+
+```typescript
+// EXISTING PATTERN: Result types
+function existingFunction(): Result<User, Error> {
+  if (!valid) return Err(new ValidationError('Detailed message'));
+  return Ok(user);
+}
+
+// CORRECT: Match existing
+function newFunction(): Result<Order, Error> {
+  if (!valid) return Err(new ValidationError('Detailed message'));
+  return Ok(order);
+}
+```
+
+### Error Messages
+
+```typescript
+// CORRECT: Informative error messages
+throw new Error(`Failed to process order ${orderId}: ${reason}. Customer: ${customerId}. Items: ${itemCount}`);
+
+// Include:
+// - What failed
+// - Why it failed (if known)
+// - Context for debugging
+// - Action the user can take (for user-facing)
+```
+
+---
+
+## Import Organization
+
+```typescript
+// CORRECT ORDER:
+// 1. Node built-ins
+import fs from 'fs';
+import path from 'path';
+
+// 2. External packages
+import express from 'express';
+import { z } from 'zod';
+
+// 3. Internal packages (@company/*)
+import { Logger } from '@internal/logger';
+import { Config } from '@internal/config';
+
+// 4. Relative imports (parent directories first)
+import { BaseService } from '../../base';
+import { User } from '../models';
+import { validate } from './utils';
+```
+
+---
+
+## Export Patterns
+
+### Named Exports (Preferred)
+
+```typescript
+// Functions
+export function createUser(data: UserInput): Result<User, Error> { }
+export function deleteUser(id: string): Result<void, Error> { }
+
+// Classes
+export class UserService { }
+export class UserRepository { }
+
+// Types
+export type UserId = string;
+export interface UserConfig { }
+
+// Constants
+export const DEFAULT_PAGE_SIZE = 20;
+```
+
+### Barrel Exports
+
+```typescript
+// src/services/index.ts
+export { UserService } from './user-service';
+export { OrderService } from './order-service';
+export type { ServiceConfig } from './types';
+```
+
+---
+
+## Configuration Preservation
+
+```typescript
+// CORRECT: Maintain configuration flexibility
+interface ServerConfig {
+  // Required
+  port: number;
+  host: string;
+
+  // Optional with defaults
+  timeout?: number;
+  maxConnections?: number;
+
+  // Nested configs
+  ssl?: SSLConfig;
+  logging?: LogConfig;
+  cors?: CorsConfig;
+}
+
+// Deprecation notice when removing options
+/**
+ * @deprecated Use `logging.level` instead. Will be removed in v3.0
+ */
+debugMode?: boolean;
+```
+
+---
+
+## Event Emission Preservation
+
+```typescript
+// CORRECT: Maintain all event emissions
+class OrderService {
+  async createOrder(data: OrderData) {
+    const order = await this.repository.create(data);
+
+    // All existing events preserved
+    this.events.emit('order.created', order);
+    this.events.emit('inventory.reserve', order.items);
+    this.events.emit('notification.send', {
+      type: 'order_confirmation',
+      userId: order.userId,
+    });
+
+    return order;
+  }
+}
+
+// If removing events, deprecate first:
+// DEPRECATED: 'order.legacy' event will be removed in v3.0
+```
+
+---
+
+## CLI Option Preservation
+
+```typescript
+// CORRECT: Maintain all CLI options
+program
+  .option('-v, --verbose', 'Enable verbose output')
+  .option('-d, --debug', 'Enable debug mode')
+  .option('-c, --config <path>', 'Config file path')
+  .option('--dry-run', 'Preview without executing')
+  // New options add to existing, don't replace
+  .option('--json', 'Output in JSON format');
+
+// If removing, add deprecation warning:
+.option('--old-flag', '[DEPRECATED] Use --new-flag instead')
+```

package/plugins/devflow-code-review/skills/consistency-patterns/references/violations.md

@@ -0,0 +1,213 @@
+# Consistency Violations Reference
+
+Extended examples of consistency violations to detect.
+
+---
+
+## Unnecessary Simplification
+
+### Content Truncation
+
+```typescript
+// BEFORE (comprehensive)
+const errorMessages = {
+  INVALID_EMAIL: 'Please enter a valid email address in the format user@domain.com',
+  PASSWORD_WEAK: 'Password must contain at least 8 characters, one uppercase, one lowercase, one number, and one special character',
+  USER_NOT_FOUND: 'We could not find an account with that email. Please check the email or create a new account.',
+};
+
+// AFTER (over-simplified - PROBLEM)
+const errorMessages = {
+  INVALID_EMAIL: 'Invalid email',
+  PASSWORD_WEAK: 'Password too weak',
+  USER_NOT_FOUND: 'Not found',
+};
+
+// RED FLAG: User-facing messages should be helpful, not minimal
+```
+
+### Removed Error Context
+
+```typescript
+// BEFORE (informative)
+throw new Error(`Failed to process order ${orderId}: ${reason}. Customer: ${customerId}. Items: ${itemCount}`);
+
+// AFTER (stripped - PROBLEM)
+throw new Error('Order failed');
+
+// RED FLAG: Debug info removed, harder to troubleshoot
+```
+
+### Stripped Configuration Options
+
+```typescript
+// BEFORE (flexible)
+interface ServerConfig {
+  port: number;
+  host: string;
+  timeout: number;
+  maxConnections: number;
+  ssl: SSLConfig;
+  logging: LogConfig;
+  cors: CorsConfig;
+}
+
+// AFTER (rigid - PROBLEM)
+interface ServerConfig {
+  port: number;
+}
+
+// RED FLAG: Configuration flexibility removed
+```
+
+---
+
+## Pattern Violations
+
+### Import Organization Inconsistency
+
+```typescript
+// EXISTING PATTERN: External, internal, relative
+import express from 'express';           // External
+import { Logger } from '@internal/logger'; // Internal
+import { User } from './models';          // Relative
+
+// VIOLATION: Mixed order
+import { User } from './models';
+import express from 'express';
+import { Logger } from '@internal/logger';
+
+// CORRECT: Match existing organization
+```
+
+### Export Pattern Mismatch
+
+```typescript
+// EXISTING PATTERN: Named exports
+export function createUser() { }
+export function deleteUser() { }
+export const UserSchema = z.object({ });
+
+// VIOLATION: Default export
+export default class UserService {  // Different pattern!
+  create() { }
+  delete() { }
+}
+
+// CORRECT: Match existing
+export class UserService { }
+export const userService = new UserService();
+```
+
+---
+
+## Feature Regression
+
+### Removed CLI Options
+
+```typescript
+// BEFORE
+program
+  .option('-v, --verbose', 'Enable verbose output')
+  .option('-d, --debug', 'Enable debug mode')
+  .option('-c, --config <path>', 'Config file path')
+  .option('--dry-run', 'Preview without executing');
+
+// AFTER (PROBLEM)
+program
+  .option('-c, --config <path>', 'Config file path');
+
+// RED FLAG: Users relying on removed options will break
+```
+
+### Changed Return Types
+
+```typescript
+// BEFORE
+async function fetchUsers(): Promise<User[]> {
+  return users;
+}
+
+// AFTER (PROBLEM)
+async function fetchUsers(): Promise<{ data: User[] }> {
+  return { data: users };  // Breaking change!
+}
+
+// All callers expecting User[] will break
+```
+
+### Removed Event Emissions
+
+```typescript
+// BEFORE
+class OrderService {
+  async createOrder(data: OrderData) {
+    const order = await this.repository.create(data);
+    this.events.emit('order.created', order);  // Other services listen
+    this.events.emit('inventory.reserve', order.items);
+    return order;
+  }
+}
+
+// AFTER (PROBLEM)
+class OrderService {
+  async createOrder(data: OrderData) {
+    const order = await this.repository.create(data);
+    return order;  // Events removed - listeners won't fire!
+  }
+}
+```
+
+---
+
+## Style Inconsistency
+
+### Brace Style
+
+```typescript
+// EXISTING PATTERN: Same-line braces
+function existing() {
+  if (condition) {
+    // ...
+  }
+}
+
+// VIOLATION: Next-line braces
+function newFunction()
+{
+  if (condition)
+  {
+    // ...
+  }
+}
+```
+
+### Quote Style
+
+```typescript
+// EXISTING PATTERN: Single quotes
+const name = 'John';
+const message = 'Hello';
+
+// VIOLATION: Double quotes
+const name = "Jane";  // Inconsistent
+
+// CORRECT: Match existing
+const name = 'Jane';
+```
+
+### Trailing Commas
+
+```typescript
+// EXISTING PATTERN: Trailing commas
+const config = {
+  name: 'app',
+  version: '1.0',
+};
+
+// VIOLATION: No trailing comma
+const newConfig = {
+  name: 'app',
+  version: '1.0'  // Missing trailing comma
+};
+```

package/plugins/devflow-code-review/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