devflow-kit 1.8.3 → 2.0.1

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

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

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

@@ -1,303 +0,0 @@
-# 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
-  }
-}
-```