devflow-kit 0.9.0 → 1.0.0

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

@@ -0,0 +1,361 @@
+# Complexity Violation Examples
+
+Extended examples of complexity issues to detect during code review.
+
+---
+
+## Deep Nesting Violations
+
+### Multi-level Conditional Nesting
+
+```typescript
+// VIOLATION: 5+ levels of nesting
+function processOrder(order: Order) {
+  if (order) {
+    if (order.items) {
+      for (const item of order.items) {
+        if (item.quantity > 0) {
+          if (item.product) {
+            if (item.product.inStock) {
+              // Finally the actual logic...
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Nested Try-Catch Blocks
+
+```typescript
+// VIOLATION: Exception handling adds nesting
+async function fetchAndProcess(url: string) {
+  try {
+    const response = await fetch(url);
+    if (response.ok) {
+      try {
+        const data = await response.json();
+        if (data.items) {
+          for (const item of data.items) {
+            try {
+              await processItem(item);
+            } catch (itemError) {
+              // Nested error handling
+            }
+          }
+        }
+      } catch (parseError) {
+        // More nesting
+      }
+    }
+  } catch (fetchError) {
+    // Top-level catch
+  }
+}
+```
+
+---
+
+## Long Function Violations
+
+### Monolithic Handler
+
+```typescript
+// VIOLATION: Function does too many things (150+ lines typical)
+function handleCheckout(cart: Cart, user: User) {
+  // Lines 1-30: Validate cart
+  // Lines 31-50: Check inventory
+  // Lines 51-80: Calculate pricing
+  // Lines 81-100: Apply discounts
+  // Lines 101-120: Process payment
+  // Lines 121-140: Update inventory
+  // Lines 141-150: Send notifications
+}
+```
+
+### God Function Pattern
+
+```typescript
+// VIOLATION: Single function handles entire feature
+async function userRegistrationFlow(formData: FormData) {
+  // Validation
+  // Sanitization
+  // Duplicate check
+  // Password hashing
+  // Database insert
+  // Email verification
+  // Welcome email
+  // Analytics tracking
+  // Session creation
+  // Redirect logic
+  // ... 200+ lines
+}
+```
+
+---
+
+## High Cyclomatic Complexity Violations
+
+### Decision Tree Anti-Pattern
+
+```typescript
+// VIOLATION: Too many decision paths (cyclomatic complexity > 10)
+function categorize(item: Item): string {
+  if (item.type === 'A') {
+    if (item.size > 10) {
+      if (item.color === 'red') return 'A-large-red';
+      else if (item.color === 'blue') return 'A-large-blue';
+      else return 'A-large-other';
+    } else {
+      if (item.color === 'red') return 'A-small-red';
+      else if (item.color === 'blue') return 'A-small-blue';
+      else return 'A-small-other';
+    }
+  } else if (item.type === 'B') {
+    if (item.size > 10) {
+      if (item.color === 'red') return 'B-large-red';
+      // ... another tree of conditions
+    }
+  }
+  // Pattern continues for types C, D, E...
+}
+```
+
+### Switch Statement Explosion
+
+```typescript
+// VIOLATION: Giant switch with embedded logic
+function handleEvent(event: Event) {
+  switch (event.type) {
+    case 'USER_CREATED':
+      // 20 lines of logic
+      break;
+    case 'USER_UPDATED':
+      // 25 lines of logic
+      break;
+    case 'USER_DELETED':
+      // 15 lines of logic
+      break;
+    // 20 more cases, each with substantial logic
+  }
+}
+```
+
+---
+
+## Magic Number/String Violations
+
+### Unexplained Literals
+
+```typescript
+// VIOLATION: Numbers without context
+if (status === 3) {
+  setTimeout(callback, 86400000);
+  retry(5);
+}
+
+// VIOLATION: String literals scattered in code
+if (user.role === 'admin' || user.role === 'superuser') {
+  if (document.status === 'pending_review') {
+    // ...
+  }
+}
+```
+
+### Hardcoded Configuration
+
+```typescript
+// VIOLATION: Magic values in business logic
+function calculateShipping(weight: number, distance: number) {
+  if (weight > 50) return 29.99;
+  if (distance > 500) return 19.99;
+  if (weight * distance > 10000) return 24.99;
+  return 9.99;
+}
+```
+
+---
+
+## Complex Expression Violations
+
+### Chained Operations
+
+```typescript
+// VIOLATION: Hard to parse mentally
+const result = data.filter(x => x.active && x.type === 'premium')
+  .map(x => ({ ...x, score: x.points * (x.bonus ? 1.5 : 1) / x.level }))
+  .sort((a, b) => b.score - a.score)[0]?.score || 0;
+```
+
+### Dense Ternary Chains
+
+```typescript
+// VIOLATION: Nested ternaries
+const status = isAdmin ? 'admin' : isModerator ? 'moderator' : isVerified ? 'verified' : isPending ? 'pending' : 'guest';
+
+const price = quantity > 100 ? basePrice * 0.8 : quantity > 50 ? basePrice * 0.9 : quantity > 10 ? basePrice * 0.95 : basePrice;
+```
+
+---
+
+## Unclear Naming Violations
+
+### Cryptic Variable Names
+
+```typescript
+// VIOLATION: Single-letter or abbreviated names
+const d = new Date();
+const t = d.getTime();
+const r = items.filter(i => i.t > t - 86400000);
+const x = r.reduce((a, b) => a + b.p, 0);
+```
+
+### Misleading Names
+
+```typescript
+// VIOLATION: Names don't match behavior
+function getData() {
+  // Actually deletes data before returning
+}
+
+const userList = fetchUser(); // Returns single user, not list
+```
+
+---
+
+## Code Duplication Violations
+
+### Repeated Validation Logic
+
+```typescript
+// VIOLATION: Same logic repeated
+function validateEmail(email: string) {
+  if (!email) return { valid: false, error: 'Required' };
+  if (!email.includes('@')) return { valid: false, error: 'Invalid format' };
+  return { valid: true, error: null };
+}
+
+function validateUsername(username: string) {
+  if (!username) return { valid: false, error: 'Required' };
+  if (username.length < 3) return { valid: false, error: 'Too short' };
+  return { valid: true, error: null };
+}
+
+// Similar pattern in 10+ more places
+```
+
+### Copy-Paste API Handlers
+
+```typescript
+// VIOLATION: Nearly identical handlers
+app.get('/users/:id', async (req, res) => {
+  try {
+    const user = await db.users.findById(req.params.id);
+    if (!user) return res.status(404).json({ error: 'Not found' });
+    res.json(user);
+  } catch (error) {
+    res.status(500).json({ error: 'Internal error' });
+  }
+});
+
+app.get('/orders/:id', async (req, res) => {
+  try {
+    const order = await db.orders.findById(req.params.id);
+    if (!order) return res.status(404).json({ error: 'Not found' });
+    res.json(order);
+  } catch (error) {
+    res.status(500).json({ error: 'Internal error' });
+  }
+});
+// Repeated for every resource...
+```
+
+---
+
+## Long Parameter List Violations
+
+### Function Signature Overload
+
+```typescript
+// VIOLATION: Too many parameters
+function createUser(
+  name: string,
+  email: string,
+  password: string,
+  role: string,
+  department: string,
+  manager: string,
+  startDate: Date,
+  salary: number,
+  benefits: string[]
+) {
+  // ...
+}
+```
+
+### Boolean Parameter Explosion
+
+```typescript
+// VIOLATION: Multiple booleans (unclear at call site)
+function formatDocument(
+  doc: Document,
+  includeHeader: boolean,
+  includeFooter: boolean,
+  useColor: boolean,
+  landscape: boolean,
+  doubleSided: boolean
+) {
+  // ...
+}
+
+// Call site is cryptic:
+formatDocument(doc, true, false, true, false, true);
+```
+
+---
+
+## Boolean Complexity Violations
+
+### Complex Boolean Expressions
+
+```typescript
+// VIOLATION: Hard to understand
+if (user.active && !user.deleted && (user.role === 'admin' || user.role === 'moderator') && user.verified && (!user.suspended || user.suspendedUntil < Date.now())) {
+  // ...
+}
+```
+
+### Negation Overuse
+
+```typescript
+// VIOLATION: Double/triple negatives
+if (!user.isNotActive && !items.isEmpty()) {
+  // ...
+}
+
+if (!(a && !b) || !(!c || d)) {
+  // ...
+}
+```
+
+---
+
+## Shotgun Surgery Indicators
+
+### Change Requires Many Files
+
+```typescript
+// VIOLATION: To add a new user type, you must modify:
+// - UserType enum
+// - UserFactory
+// - UserValidator
+// - UserSerializer
+// - UserRepository
+// - UserController
+// - user.routes.ts
+// - 5 more files...
+
+// Each file has a switch or if-else chain checking user type
+```

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

@@ -0,0 +1,140 @@
+---
+name: consistency-patterns
+description: Consistency analysis patterns for code review. Detects naming convention violations, pattern deviations, unnecessary simplification, and feature truncation in diffs. Loaded by Reviewer agent when focus=consistency.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Consistency Patterns
+
+Domain expertise for code consistency and unnecessary simplification detection. Use alongside `review-methodology` for complete consistency reviews.
+
+## Iron Law
+
+> **MATCH EXISTING PATTERNS OR JUSTIFY DEVIATION**
+>
+> New code should look like existing code. If the codebase uses camelCase, use camelCase.
+> If errors return Result types, return Result types. Consistency trumps personal preference.
+> Deviation requires explicit justification and team agreement. One codebase, one style.
+
+---
+
+## Consistency Categories
+
+### 1. Unnecessary Simplification
+
+Content truncation, stripped configuration, removed error context.
+
+```typescript
+// VIOLATION: Oversimplified error messages
+const errorMessages = {
+  INVALID_EMAIL: 'Invalid email',  // Was: detailed format guidance
+  USER_NOT_FOUND: 'Not found',     // Was: helpful next steps
+};
+
+// CORRECT: Preserve helpful context
+const errorMessages = {
+  INVALID_EMAIL: 'Please enter a valid email address in the format user@domain.com',
+  USER_NOT_FOUND: 'We could not find an account with that email. Please check or create a new account.',
+};
+```
+
+### 2. Pattern Violations
+
+Naming conventions, error handling styles, import/export organization.
+
+```typescript
+// EXISTING PATTERN: Result types
+function existingFunction(): Result<User, Error> {
+  if (!valid) return Err(new ValidationError('...'));
+  return Ok(user);
+}
+
+// VIOLATION: Throws instead of Result
+function newFunction(): User {
+  if (!valid) throw new Error('...');  // Different pattern!
+  return user;
+}
+
+// CORRECT: Match existing
+function newFunction(): Result<User, Error> {
+  if (!valid) return Err(new ValidationError('...'));
+  return Ok(user);
+}
+```
+
+### 3. Feature Regression
+
+Removed CLI options, changed return types, removed event emissions.
+
+```typescript
+// VIOLATION: Removed event emissions break listeners
+class OrderService {
+  async createOrder(data: OrderData) {
+    const order = await this.repository.create(data);
+    return order;  // Events removed - listeners won't fire!
+  }
+}
+
+// CORRECT: Preserve all event emissions
+class OrderService {
+  async createOrder(data: OrderData) {
+    const order = await this.repository.create(data);
+    this.events.emit('order.created', order);
+    this.events.emit('inventory.reserve', order.items);
+    return order;
+  }
+}
+```
+
+### 4. Style Inconsistency
+
+Brace style, quote style, trailing commas, naming conventions.
+
+```typescript
+// EXISTING: camelCase for functions
+function getUserById(id: string) { }
+function createOrder(data: OrderData) { }
+
+// VIOLATION: Different naming style
+function Process_Payment(amount: number) { }  // snake_case
+
+// CORRECT: Match existing
+function processPayment(amount: number) { }
+```
+
+---
+
+## Extended References
+
+For extended examples and detection commands, see:
+
+- `references/violations.md` - Extended violation examples by category
+- `references/patterns.md` - Extended correct pattern examples
+- `references/detection.md` - Bash commands for detecting issues
+
+---
+
+## Severity Guidelines
+
+| Severity | Description | Examples |
+|----------|-------------|----------|
+| **CRITICAL** | Breaking changes or significant content loss | API return types changed, CLI options removed, events removed |
+| **HIGH** | Inconsistency requiring attention | Error handling pattern mismatch, naming violations, export pattern change |
+| **MEDIUM** | Style inconsistency | Import organization, brace/quote style, formatting differences |
+| **LOW** | Minor observations | Personal preference territory, linter should catch |
+
+---
+
+## Consistency Checklist
+
+Before approving changes, verify:
+
+- [ ] Naming matches existing patterns (camelCase, PascalCase, etc.)
+- [ ] Error handling matches existing approach (throw vs Result)
+- [ ] Import organization matches existing files
+- [ ] Export style matches existing modules
+- [ ] No user-facing content was unnecessarily shortened
+- [ ] No configuration options were silently removed
+- [ ] No CLI flags/options were removed without deprecation
+- [ ] All removed functionality has explicit justification

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

@@ -0,0 +1,207 @@
+# Consistency Detection Patterns Reference
+
+Bash commands and patterns for detecting consistency issues.
+
+---
+
+## Diff Statistics Analysis
+
+### Files with Excessive Deletions
+
+```bash
+# Files with many more deletions than additions
+git diff main...HEAD --stat | awk '{
+  if (match($0, /\+([0-9]+).*-([0-9]+)/, arr)) {
+    added = arr[1]; deleted = arr[2];
+    if (deleted > added * 2 && deleted > 10) {
+      print "WARNING:", $0
+    }
+  }
+}'
+```
+
+### Content Length Changes
+
+```bash
+# Compare line counts for key files
+for file in $(git diff --name-only main...HEAD); do
+  if [ -f "$file" ]; then
+    before=$(git show main:"$file" 2>/dev/null | wc -l)
+    after=$(wc -l < "$file")
+    if [ "$before" -gt "$after" ]; then
+      reduction=$((before - after))
+      percent=$((reduction * 100 / before))
+      if [ "$percent" -gt 20 ]; then
+        echo "WARNING: $file reduced by $percent% ($before -> $after lines)"
+      fi
+    fi
+  fi
+done
+```
+
+---
+
+## Error Message Detection
+
+### Shortened Error Messages
+
+```bash
+# Find shortened error messages in diff
+git diff main...HEAD -- "*.ts" | grep "^-.*Error\|^-.*throw" | head -20
+
+# Compare error message lengths before/after
+git diff main...HEAD -- "*.ts" | grep -A1 "^-.*throw new Error" | head -30
+```
+
+### Generic Error Replacements
+
+```bash
+# Find generic error messages that replaced specific ones
+git diff main...HEAD -- "*.ts" | grep "^+.*'Error'\|^+.*'Failed'\|^+.*'Invalid'" | head -20
+```
+
+---
+
+## Export/Import Detection
+
+### Removed Exports
+
+```bash
+# Find removed exports
+git diff main...HEAD -- "*.ts" | grep "^-export" | head -20
+```
+
+### Changed Export Patterns
+
+```bash
+# Find export default vs named export changes
+git diff main...HEAD -- "*.ts" | grep "^-export\|^+export" | head -30
+```
+
+### Import Order Analysis
+
+```bash
+# Check for import order inconsistencies
+for file in $(git diff --name-only main...HEAD -- "*.ts"); do
+  echo "=== $file ==="
+  head -30 "$file" | grep "^import" | head -15
+done
+```
+
+---
+
+## CLI/Options Detection
+
+### Removed Options
+
+```bash
+# Find removed CLI options
+git diff main...HEAD -- "*.ts" | grep "^-.*\.option\|^-.*flag" | head -20
+
+# Find removed function parameters
+git diff main...HEAD -- "*.ts" | grep "^-.*function.*(" | head -20
+```
+
+### Changed Signatures
+
+```bash
+# Find changed function signatures
+git diff main...HEAD -- "*.ts" | grep -A2 "^-.*function\|^+.*function" | head -40
+```
+
+---
+
+## Naming Convention Detection
+
+### Unusual Naming Patterns
+
+```bash
+# Find snake_case in functions (unusual for TypeScript)
+grep -rn "function [A-Z_]" --include="*.ts" | head -10
+
+# Find SCREAMING_CASE functions (should be constants only)
+grep -rn "function [A-Z][A-Z]" --include="*.ts" | head -10
+
+# Find mixed function styles
+grep -rn "const [a-z].*= function" --include="*.ts" | head -10
+```
+
+### Quote Style Detection
+
+```bash
+# Find inconsistent quotes
+echo "Double quotes:"
+grep -rn '"[^"]*"' --include="*.ts" | head -5
+
+echo "Single quotes:"
+grep -rn "'[^']*'" --include="*.ts" | head -5
+```
+
+---
+
+## Event Emission Detection
+
+### Removed Event Emissions
+
+```bash
+# Find removed event emissions
+git diff main...HEAD -- "*.ts" | grep "^-.*\.emit\|^-.*emit(" | head -20
+
+# Find removed event listeners
+git diff main...HEAD -- "*.ts" | grep "^-.*\.on(\|^-.*addEventListener" | head -20
+```
+
+---
+
+## Configuration Detection
+
+### Removed Config Options
+
+```bash
+# Find removed interface properties
+git diff main...HEAD -- "*.ts" | grep "^-.*:" | grep -v "//" | head -20
+
+# Find removed config keys
+git diff main...HEAD -- "*.json" | grep "^-" | head -20
+```
+
+### Changed Default Values
+
+```bash
+# Find changed default values
+git diff main...HEAD -- "*.ts" | grep "^-.*=.*\|^+.*=.*" | grep default | head -20
+```
+
+---
+
+## Comprehensive Scan
+
+### Full Consistency Check
+
+```bash
+#!/bin/bash
+# Run all consistency checks
+
+echo "=== Excessive Deletions ==="
+git diff main...HEAD --stat | awk '{
+  if (match($0, /\+([0-9]+).*-([0-9]+)/, arr)) {
+    if (arr[2] > arr[1] * 2 && arr[2] > 10) print "WARNING:", $0
+  }
+}'
+
+echo ""
+echo "=== Removed Exports ==="
+git diff main...HEAD -- "*.ts" | grep "^-export" | head -10
+
+echo ""
+echo "=== Shortened Errors ==="
+git diff main...HEAD -- "*.ts" | grep "^-.*Error\|^-.*throw" | head -10
+
+echo ""
+echo "=== Removed Events ==="
+git diff main...HEAD -- "*.ts" | grep "^-.*\.emit" | head -10
+
+echo ""
+echo "=== Naming Issues ==="
+grep -rn "function [A-Z_]" --include="*.ts" | head -5
+```