devflow-kit 0.9.0 → 1.0.0

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

@@ -0,0 +1,276 @@
+# Validation Checklist
+
+Comprehensive checklist for code review and validation against core engineering patterns.
+
+---
+
+## Pre-Implementation Checklist
+
+Before writing code, verify:
+
+- [ ] Understood the existing patterns in the codebase
+- [ ] Identified similar implementations to follow
+- [ ] Determined if Result types are used (and will follow same pattern)
+- [ ] Identified dependencies that need injection
+- [ ] Planned separation of pure logic from side effects
+
+---
+
+## Result Types Checklist
+
+### Functions That Can Fail
+
+- [ ] All business functions return `Result<T, E>` types
+- [ ] No `throw` statements in business logic
+- [ ] Error types are discriminated unions (not generic Error)
+- [ ] Each error type has all context needed to handle it
+- [ ] Async functions return `Promise<Result<T, E>>`
+
+### Exception Boundaries
+
+- [ ] Try/catch ONLY at system boundaries (API handlers, DB adapters)
+- [ ] Boundaries convert exceptions to Result types
+- [ ] HTTP responses derived from Result errors
+- [ ] No silent error swallowing (empty catch blocks)
+
+### Error Handling
+
+- [ ] All Result errors are handled explicitly
+- [ ] No `if (!result.ok) return;` without proper handling
+- [ ] Error propagation preserves context
+- [ ] Logging happens before converting errors
+
+---
+
+## Dependency Injection Checklist
+
+### Constructor Injection
+
+- [ ] All dependencies passed through constructor
+- [ ] No `new` keyword for dependencies inside classes
+- [ ] No imported singletons used directly
+- [ ] No static method calls on external services
+
+### Interfaces
+
+- [ ] Dependencies typed as interfaces, not implementations
+- [ ] Interfaces are small and focused (ISP)
+- [ ] Mock implementations easy to create
+- [ ] No concrete class imports in business logic
+
+### Testing
+
+- [ ] Can instantiate class with mock dependencies
+- [ ] No test requires real database/network
+- [ ] No environment manipulation in tests
+- [ ] Test setup is < 10 lines
+
+---
+
+## Immutability Checklist
+
+### Objects
+
+- [ ] All updates return new objects (spread operator)
+- [ ] No direct property assignment on inputs
+- [ ] No `delete` operator on inputs
+- [ ] Nested updates also create new objects
+
+### Arrays
+
+- [ ] No `.push()`, `.pop()`, `.shift()`, `.unshift()`
+- [ ] No `.splice()`, `.reverse()`, `.sort()` on originals
+- [ ] Use `.map()`, `.filter()`, `.reduce()` for transformations
+- [ ] Copy before sorting: `[...arr].sort()`
+
+### State
+
+- [ ] No module-level `let` or `var`
+- [ ] No global mutable state
+- [ ] Configuration is frozen after initialization
+- [ ] Caches use immutable entries
+
+---
+
+## Pure Functions Checklist
+
+### Business Logic
+
+- [ ] Pure functions have no side effects
+- [ ] Same input always produces same output
+- [ ] No date/time access (inject clock)
+- [ ] No random values (inject generator)
+- [ ] No environment variable access
+
+### Side Effect Isolation
+
+- [ ] I/O operations in wrapper functions
+- [ ] Pure calculations extracted and tested separately
+- [ ] Side effects clearly documented
+- [ ] Logging/metrics in wrappers, not core logic
+
+### Dependencies
+
+- [ ] Time/random injected as dependencies
+- [ ] Environment config loaded once at startup
+- [ ] File system access at boundaries only
+- [ ] Network calls at boundaries only
+
+---
+
+## Type Safety Checklist
+
+### Strict Types
+
+- [ ] No `any` types (use `unknown` for dynamic data)
+- [ ] All function parameters typed
+- [ ] All return types explicit
+- [ ] Strict null checks enabled
+
+### Pattern Matching
+
+- [ ] Switch statements are exhaustive
+- [ ] Discriminated unions for state/variants
+- [ ] No default case that hides missing patterns
+- [ ] Type guards for runtime narrowing
+
+### Type Design
+
+- [ ] Domain types prevent primitive obsession
+- [ ] Branded types for IDs that shouldn't mix
+- [ ] Optional fields explicit (`field?: Type`)
+- [ ] Readonly where appropriate
+
+---
+
+## Error Type Design Checklist
+
+### Discriminated Unions
+
+- [ ] Each error type has a `type` discriminator
+- [ ] Error types include all context needed
+- [ ] Related errors grouped in union types
+- [ ] Error unions are exhaustive
+
+### Error Information
+
+- [ ] Error messages are actionable
+- [ ] Technical details preserved for logging
+- [ ] User-facing messages are sanitized
+- [ ] Error codes are unique and documented
+
+---
+
+## Resource Cleanup Checklist
+
+### File/Connection Handling
+
+- [ ] All file handles closed in `finally`
+- [ ] All connections released in `finally`
+- [ ] Using context managers (Python) or `using` (TS)
+- [ ] Pool resources released after use
+
+### Subscriptions/Timers
+
+- [ ] Event listeners removed on cleanup
+- [ ] Intervals cleared when done
+- [ ] Timeouts cleared if operation completes early
+- [ ] Subscription manager for complex lifecycles
+
+### Memory
+
+- [ ] Large data structures released when done
+- [ ] Caches have size limits or TTL
+- [ ] Circular references avoided
+- [ ] WeakMap/WeakSet for object keys
+
+---
+
+## API Consistency Checklist
+
+### Error Handling Pattern
+
+- [ ] Same error handling pattern across module
+- [ ] All methods return Result OR all throw (not mixed)
+- [ ] Error types consistent across related methods
+- [ ] HTTP error mapping centralized
+
+### Async Pattern
+
+- [ ] Single async pattern (async/await preferred)
+- [ ] No mixing callbacks and promises
+- [ ] All async calls awaited (no fire-and-forget)
+- [ ] Promise.all for parallel operations
+
+### Naming
+
+- [ ] Consistent naming across codebase
+- [ ] PascalCase for types/classes
+- [ ] camelCase for functions/variables
+- [ ] SCREAMING_SNAKE_CASE for constants
+
+---
+
+## Architecture Documentation Checklist
+
+### Code Comments
+
+- [ ] Public APIs have JSDoc/docstrings
+- [ ] Complex algorithms explained
+- [ ] Non-obvious decisions documented
+- [ ] Architecture boundaries marked
+
+### Exceptions/Workarounds
+
+- [ ] All workarounds labeled (HACK:, TODO:, TEMPORARY:)
+- [ ] Architecture exceptions have justification
+- [ ] Technical debt has tracking ticket
+- [ ] Deadlines on temporary solutions
+
+---
+
+## Performance Checklist
+
+### Measurement
+
+- [ ] Performance claims have benchmarks
+- [ ] Hot paths identified and measured
+- [ ] No premature optimization
+- [ ] Trade-offs documented
+
+### Common Issues
+
+- [ ] No N+1 queries
+- [ ] Appropriate data structures (Map vs Array)
+- [ ] Lazy evaluation for expensive operations
+- [ ] Batch operations where possible
+
+---
+
+## Anti-Pattern Checklist
+
+Verify NONE of these exist:
+
+- [ ] No hardcoded responses simulating functionality
+- [ ] No silent error swallowing
+- [ ] No unlabeled magic values
+- [ ] No global mutable state
+- [ ] No tight coupling to concrete implementations
+- [ ] No mixing error handling patterns
+- [ ] No fire-and-forget async calls
+- [ ] No resource leaks
+
+---
+
+## Final Review Checklist
+
+Before considering code complete:
+
+- [ ] All tests pass
+- [ ] No TypeScript errors
+- [ ] No ESLint warnings
+- [ ] Code matches existing patterns
+- [ ] Documentation updated
+- [ ] No TODO without ticket
+- [ ] No console.log in production code
+- [ ] No commented-out code

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

@@ -0,0 +1,144 @@
+# Code Smell Violations Reference
+
+Extended examples of fake solutions, unlabeled workarounds, deceptive code, and magic values. Absorbed from the former `code-smell` skill into `core-patterns`.
+
+---
+
+## 1. Hardcoded Data (FAKE SOLUTIONS)
+
+### Violation: Mock data masquerading as real functionality
+
+```typescript
+async function fetchRecommendations(userId: string): Promise<Product[]> {
+  // TODO: Connect to recommendation engine
+  return [
+    { id: "1", name: "Product 1", price: 99.99 },
+    { id: "2", name: "Product 2", price: 149.99 }
+  ];
+}
+```
+
+**Problem**: Returns static data instead of fetching from actual service.
+
+### Correct: Honest implementation with Result type
+
+```typescript
+async function getUserProfile(userId: string): Promise<Result<UserProfile, Error>> {
+  try {
+    const response = await api.get(`/users/${userId}`);
+    return { ok: true, value: response.data };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+```
+
+### Correct: Clearly labeled mock for testing
+
+```typescript
+// MOCK: For development only, not production-ready
+async function getUserProfileMock(userId: string): Promise<UserProfile> {
+  return { id: userId, name: "Test User", email: "test@example.com" };
+}
+```
+
+---
+
+## 2. Missing Labels (UNDOCUMENTED WORKAROUNDS)
+
+### Violation: Temporary fix without documentation
+
+```typescript
+async function syncData() {
+  await sleep(1000); // Wait for previous operation
+  await performSync();
+}
+```
+
+### Correct: Clearly labeled workaround
+
+```typescript
+function processPayment(amount: number): boolean {
+  // TEMPORARY: Validation disabled until payment gateway integration complete
+  // TODO: Add amount validation, currency checks, fraud detection
+  // Target: Sprint 23 (2025-11-15)
+  // Ticket: PAY-456
+  return true;
+}
+```
+
+### Correct: Documented hack with rationale
+
+```typescript
+async function syncData() {
+  // HACK: Sleep required due to race condition in legacy sync system
+  // Root cause: Event system doesn't guarantee order
+  // Proper fix: Implement event sequencing (3-week effort)
+  await sleep(1000);
+  await performSync();
+}
+```
+
+---
+
+## 3. Fake Functionality (DECEPTIVE CODE)
+
+### Violation: Fake error handling
+
+```typescript
+async function sendEmail(to: string, subject: string, body: string): Promise<void> {
+  try {
+    // TODO: Implement SMTP
+    console.log(`Email sent to ${to}`);
+  } catch (error) {
+    // Ignore errors
+  }
+}
+```
+
+### Correct: Honest unimplemented function
+
+```typescript
+function validateEmail(email: string): Result<boolean, Error> {
+  return {
+    ok: false,
+    error: new Error('NOT-IMPLEMENTED: Email validation pending regex pattern approval')
+  };
+}
+```
+
+---
+
+## 4. Magic Values (UNEXPLAINED CONSTANTS)
+
+### Violation: Magic numbers
+
+```typescript
+function calculateDiscount(price: number, userLevel: number): number {
+  if (userLevel >= 5) return price * 0.15;
+  return 0;
+}
+```
+
+### Correct: Named constants with documentation
+
+```typescript
+const USER_LEVEL_THRESHOLD = { PREMIUM: 5 } as const;
+const DISCOUNT_RATE = { PREMIUM: 0.15 } as const;
+
+function calculateDiscount(price: number, userLevel: number): number {
+  if (userLevel >= USER_LEVEL_THRESHOLD.PREMIUM) return price * DISCOUNT_RATE.PREMIUM;
+  return 0;
+}
+```
+
+---
+
+## Detection Quick Reference
+
+Code passes smell check when:
+- No hardcoded return data in business logic
+- All workarounds have required labels (HACK:, MOCK:, TODO:, TEMPORARY:, NOT-PRODUCTION:, ARCHITECTURE EXCEPTION:)
+- All fake/mock code clearly marked
+- Magic values extracted to named constants
+- Functions do what their names promise

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

@@ -0,0 +1,303 @@
+# Detection Patterns
+
+Grep patterns and code analysis techniques for detecting pattern violations.
+
+---
+
+## Result Type Violations
+
+### Detecting Throws in Business Logic
+
+```bash
+# Find throw statements (potential violations)
+grep -rn "throw new\|throw Error\|throw \w" --include="*.ts" src/services/ src/domain/
+
+# Find try/catch blocks (review for appropriateness)
+grep -rn "try {" --include="*.ts" -A 5 src/services/ src/domain/
+
+# Find functions that don't return Result but could fail
+grep -rn "async function\|function" --include="*.ts" src/services/ | grep -v "Result<"
+```
+
+### Detecting Silent Failures
+
+```bash
+# Empty catch blocks
+grep -rn "catch.*{" --include="*.ts" -A 1 | grep -E "catch.*\{\s*\}"
+
+# Catch blocks that return null/undefined
+grep -rn "catch" --include="*.ts" -A 3 | grep -E "return (null|undefined|void 0);"
+
+# Catch blocks with only console.log
+grep -rn "catch" --include="*.ts" -A 3 | grep -E "^\s*console\.(log|error)"
+```
+
+---
+
+## Dependency Injection Violations
+
+### Detecting Internal Instantiation
+
+```bash
+# Find 'new' keyword in class bodies (potential DI violation)
+grep -rn "private.*= new\|this\.\w* = new" --include="*.ts" src/
+
+# Find imported singletons
+grep -rn "import.*from.*\./.*instance\|import.*from.*\./.*singleton" --include="*.ts"
+
+# Find static method calls on external classes
+grep -rn "\w+Service\.\w+(\|Calculator\.\w+(" --include="*.ts" src/services/
+```
+
+### Detecting Global State Access
+
+```bash
+# Find process.env access outside config
+grep -rn "process\.env\." --include="*.ts" src/ | grep -v "config\|Config"
+
+# Find global variable access
+grep -rn "globalThis\.\|window\.\|global\." --include="*.ts" src/
+
+# Find module-level let/var (mutable global state)
+grep -rn "^let \|^var " --include="*.ts" src/
+```
+
+---
+
+## Immutability Violations
+
+### Detecting Array Mutations
+
+```bash
+# Array mutating methods
+grep -rn "\.push(\|\.pop(\|\.shift(\|\.unshift(\|\.splice(\|\.reverse(\|\.sort(\|\.fill(" --include="*.ts" src/
+
+# Assignment to array elements
+grep -rn "\[\d+\]\s*=" --include="*.ts" src/
+
+# forEach with mutations
+grep -rn "\.forEach.*=>" --include="*.ts" -A 2 | grep -E "\.\w+\s*="
+```
+
+### Detecting Object Mutations
+
+```bash
+# Direct property assignment on parameters
+grep -rn "function.*(\w+:" --include="*.ts" -A 10 | grep -E "^\s+\w+\.\w+\s*="
+
+# delete operator
+grep -rn "delete \w+\." --include="*.ts" src/
+
+# Object.assign mutating first argument
+grep -rn "Object\.assign(\w+," --include="*.ts" src/
+```
+
+---
+
+## Pure Function Violations
+
+### Detecting Side Effects
+
+```bash
+# Console/logging in business logic
+grep -rn "console\.\|logger\.\|log(" --include="*.ts" src/domain/ src/services/
+
+# Date/time access (non-deterministic)
+grep -rn "new Date(\|Date\.now(\|performance\.now(" --include="*.ts" src/domain/
+
+# Random number generation
+grep -rn "Math\.random(\|crypto\.random" --include="*.ts" src/domain/
+
+# File system access
+grep -rn "fs\.\|readFile\|writeFile" --include="*.ts" src/domain/
+```
+
+### Detecting External Dependencies
+
+```bash
+# Network calls
+grep -rn "fetch(\|axios\.\|http\.\|https\." --include="*.ts" src/domain/
+
+# Database calls
+grep -rn "db\.\|prisma\.\|mongoose\.\|sequelize\." --include="*.ts" src/domain/
+
+# Environment access
+grep -rn "process\.env\|import\.meta\.env" --include="*.ts" src/domain/
+```
+
+---
+
+## Type Safety Violations
+
+### Detecting Any Types
+
+```bash
+# Explicit any
+grep -rn ": any\|<any>\|as any" --include="*.ts" src/
+
+# Implicit any (missing return types)
+grep -rn "function \w+(" --include="*.ts" src/ | grep -v "): \w"
+
+# Type assertions without guards
+grep -rn "as \w+\[" --include="*.ts" src/ | grep -v "if.*typeof\|if.*instanceof"
+```
+
+### Detecting Non-Exhaustive Patterns
+
+```bash
+# Switch without default that might need exhaustive check
+grep -rn "switch.*{" --include="*.ts" -A 20 | grep -v "default:"
+
+# If chains without else
+grep -rn "if.*===.*'\\|if.*===.*\"" --include="*.ts" -A 5 | grep -v "else"
+```
+
+---
+
+## Resource Cleanup Violations
+
+### Detecting Missing Cleanup
+
+```bash
+# File opens without close
+grep -rn "fs\.open\|createReadStream\|createWriteStream" --include="*.ts" -A 10 | grep -v "close\|finally"
+
+# Connection acquires without release
+grep -rn "\.connect(\|getConnection(\|acquire(" --include="*.ts" -A 10 | grep -v "release\|close\|finally"
+
+# Event listeners without removal
+grep -rn "\.on(\|addEventListener(" --include="*.ts" | grep -v "removeEventListener\|off("
+```
+
+### Detecting Timer Leaks
+
+```bash
+# setInterval without clearInterval
+grep -rn "setInterval(" --include="*.ts" -B 5 -A 5 | grep -v "clearInterval"
+
+# setTimeout in loops without clear
+grep -rn "setTimeout(" --include="*.ts" | grep -v "clearTimeout"
+```
+
+---
+
+## API Consistency Violations
+
+### Detecting Mixed Patterns
+
+```bash
+# Functions returning different error patterns in same file
+grep -rn "return null\|throw new\|return Err\|return { ok:" --include="*.ts" src/services/
+
+# Mixed async patterns
+grep -rn "callback\|\.then(\|async " --include="*.ts" src/services/
+```
+
+### Detecting Missing Awaits
+
+```bash
+# Async calls without await (potential fire-and-forget)
+grep -rn "async function" --include="*.ts" -A 20 | grep -E "^\s+\w+\.\w+\(" | grep -v "await\|return"
+```
+
+---
+
+## Architecture Violations
+
+### Detecting Layer Boundary Violations
+
+```bash
+# Domain importing from infrastructure
+grep -rn "from.*\/infrastructure\|from.*\/adapters\|from.*\/repositories" --include="*.ts" src/domain/
+
+# Controllers containing business logic (too many lines)
+wc -l src/controllers/*.ts | sort -n | tail -10
+
+# Services importing from controllers
+grep -rn "from.*\/controllers\|from.*\/routes\|from.*\/handlers" --include="*.ts" src/services/
+```
+
+### Detecting Missing Documentation
+
+```bash
+# Public functions without JSDoc
+grep -rn "^export function\|^export async function" --include="*.ts" -B 1 | grep -v "/\*\*\|//\|@"
+
+# Classes without documentation
+grep -rn "^export class" --include="*.ts" -B 1 | grep -v "/\*\*\|//"
+```
+
+---
+
+## Automated Detection Script
+
+```bash
+#!/bin/bash
+# pattern-check.sh - Detect common pattern violations
+
+echo "=== Pattern Violation Detection ==="
+echo ""
+
+echo "1. Checking for throws in business logic..."
+THROWS=$(grep -rn "throw new\|throw Error" --include="*.ts" src/services/ src/domain/ 2>/dev/null | wc -l)
+echo "   Found: $THROWS potential violations"
+
+echo ""
+echo "2. Checking for any types..."
+ANYS=$(grep -rn ": any\|<any>\|as any" --include="*.ts" src/ 2>/dev/null | wc -l)
+echo "   Found: $ANYS uses of 'any'"
+
+echo ""
+echo "3. Checking for array mutations..."
+MUTATIONS=$(grep -rn "\.push(\|\.pop(\|\.splice(\|\.sort(" --include="*.ts" src/ 2>/dev/null | wc -l)
+echo "   Found: $MUTATIONS potential array mutations"
+
+echo ""
+echo "4. Checking for internal instantiation..."
+INTERNAL=$(grep -rn "private.*= new\|this\.\w* = new" --include="*.ts" src/ 2>/dev/null | wc -l)
+echo "   Found: $INTERNAL internal instantiations (DI violations)"
+
+echo ""
+echo "5. Checking for console.log in business logic..."
+CONSOLE=$(grep -rn "console\." --include="*.ts" src/services/ src/domain/ 2>/dev/null | wc -l)
+echo "   Found: $CONSOLE console statements"
+
+echo ""
+echo "=== Summary ==="
+TOTAL=$((THROWS + ANYS + MUTATIONS + INTERNAL + CONSOLE))
+echo "Total potential violations: $TOTAL"
+```
+
+---
+
+## IDE/Editor Integration
+
+### ESLint Rules
+
+```json
+{
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/explicit-function-return-type": "error",
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/no-throw-literal": "error",
+    "no-console": ["error", { "allow": ["warn", "error"] }],
+    "no-param-reassign": "error"
+  }
+}
+```
+
+### TypeScript Compiler Options
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+```