devflow-kit 0.8.1 → 1.0.0

package/shared/skills/self-review/references/violations.md

@@ -0,0 +1,308 @@
+# Self-Review Violations
+
+Common anti-patterns and code violations organized by the 9 pillars.
+
+---
+
+## Self-Review Process Violations
+
+| Violation | Problem | Fix |
+|-----------|---------|-----|
+| Skipping pillars | Incomplete review | Check all 9 pillars |
+| Ignoring P0/P1 issues | Returning broken code | Fix before returning |
+| Surface-level review | Missing deep issues | Review each pillar thoroughly |
+| No evidence | Unverifiable claims | Reference specific code |
+| Deferring critical fixes | Technical debt | Fix CRITICAL/HIGH immediately |
+
+---
+
+## P0 Pillars (MUST Fix)
+
+### 1. Design Violations
+
+**Question**: Does the implementation fit the architecture?
+
+**Red Flags**:
+```typescript
+// BAD: Direct database access in controller
+class UserController {
+  async getUser(req, res) {
+    const user = await db.query('SELECT * FROM users WHERE id = ?', [req.params.id]);
+  }
+}
+
+// BAD: God class doing everything
+class ApplicationManager {
+  createUser() {}
+  processPayment() {}
+  sendEmail() {}
+  generateReport() {}
+  // 500 more methods...
+}
+
+// BAD: Circular dependencies
+// a.ts imports b.ts, b.ts imports a.ts
+```
+
+**Checklist**:
+- [ ] Follows existing patterns in codebase
+- [ ] Respects layer boundaries (controller/service/repository)
+- [ ] Dependencies injected, not instantiated
+- [ ] Not over-engineering (YAGNI)
+- [ ] Not under-engineering (technical debt)
+- [ ] Interactions with other components are sound
+
+---
+
+### 2. Functionality Violations
+
+**Question**: Does the code work as intended?
+
+**Red Flags**:
+```typescript
+// BAD: Missing null check
+function getDisplayName(user: User) {
+  return user.profile.displayName;  // user.profile could be undefined!
+}
+
+// BAD: Race condition
+let balance = await getBalance();
+if (balance >= amount) {
+  await withdraw(amount);  // Balance could change between check and withdraw!
+}
+
+// BAD: Off-by-one error
+for (let i = 0; i <= array.length; i++) {  // Should be < not <=
+  process(array[i]);
+}
+```
+
+**Checklist**:
+- [ ] Happy path works correctly
+- [ ] Edge cases handled (null, empty, boundary values)
+- [ ] Error cases handled gracefully
+- [ ] No race conditions in concurrent code
+- [ ] No infinite loops or recursion without base case
+- [ ] State mutations are intentional and correct
+
+---
+
+### 3. Security Violations
+
+**Question**: Are there security vulnerabilities?
+
+**Red Flags**:
+```typescript
+// BAD: SQL injection
+const query = `SELECT * FROM users WHERE email = '${email}'`;
+
+// BAD: Command injection
+exec(`ls ${userInput}`);
+
+// BAD: Hardcoded secret
+const API_KEY = 'sk-abc123xyz789';
+
+// BAD: Missing auth check
+app.delete('/api/users/:id', async (req, res) => {
+  await deleteUser(req.params.id);  // No auth!
+});
+```
+
+**Checklist**:
+- [ ] No SQL/NoSQL injection
+- [ ] No command injection
+- [ ] No XSS vulnerabilities
+- [ ] Input validated at boundaries
+- [ ] No hardcoded secrets
+- [ ] Authentication/authorization checked
+- [ ] Sensitive data not logged
+
+---
+
+## P1 Pillars (SHOULD Fix)
+
+### 4. Complexity Violations
+
+**Question**: Can a reader understand this in 5 minutes?
+
+**Red Flags**:
+```typescript
+// BAD: Deep nesting
+if (a) {
+  if (b) {
+    if (c) {
+      if (d) {
+        if (e) {
+          // actual logic buried here
+        }
+      }
+    }
+  }
+}
+
+// BAD: Magic numbers
+setTimeout(callback, 86400000);
+if (status === 3) { }
+```
+
+**Checklist**:
+- [ ] Functions are < 50 lines
+- [ ] Nesting depth < 4 levels
+- [ ] Cyclomatic complexity < 10
+- [ ] No magic numbers/strings
+- [ ] Single responsibility per function
+- [ ] Complex logic has explanatory comments
+
+---
+
+### 5. Error Handling Violations
+
+**Question**: Are errors handled explicitly and consistently?
+
+**Red Flags**:
+```typescript
+// BAD: Swallowed exception
+try {
+  await riskyOperation();
+} catch (e) {
+  // silently ignored!
+}
+
+// BAD: Generic error message
+throw new Error('Something went wrong');
+
+// BAD: Resource leak on error
+const file = await openFile(path);
+await processFile(file);  // If this throws, file never closed!
+await file.close();
+```
+
+**Checklist**:
+- [ ] Errors are caught and handled appropriately
+- [ ] Error messages are helpful (not generic)
+- [ ] No silent failures (swallowed exceptions)
+- [ ] Consistent error handling pattern (Result types or throws)
+- [ ] Resources cleaned up in error paths
+- [ ] Errors logged with context
+
+---
+
+### 6. Tests Violations
+
+**Question**: Is the new functionality tested?
+
+**Red Flags**:
+```typescript
+// BAD: No tests for new function
+export function calculateDiscount(price, type) {
+  // 20 lines of logic with no tests
+}
+
+// BAD: Test that doesn't verify behavior
+it('creates user', async () => {
+  await createUser(data);
+  expect(mockDb.insert).toHaveBeenCalled();  // Only checks mock was called
+});
+
+// BAD: Missing edge case tests
+describe('divide', () => {
+  it('divides numbers', () => {
+    expect(divide(10, 2)).toBe(5);
+  });
+  // No test for divide by zero!
+});
+```
+
+**Checklist**:
+- [ ] New code has corresponding tests
+- [ ] Tests cover happy path
+- [ ] Tests cover error cases
+- [ ] Tests cover edge cases
+- [ ] Tests are not brittle (test behavior, not implementation)
+- [ ] Tests would fail if code breaks
+
+---
+
+## P2 Pillars (FIX if Time Permits)
+
+### 7. Naming Violations
+
+**Question**: Are names clear and descriptive?
+
+**Red Flags**:
+```typescript
+// BAD: Cryptic names
+const d = new Date();
+const r = items.filter(i => i.t > d);
+const x = r.reduce((a, b) => a + b.p, 0);
+
+// BAD: Misleading name
+function getUser(id) {
+  return db.users.findAll();  // Returns ALL users, not one!
+}
+```
+
+**Checklist**:
+- [ ] Variable names describe content
+- [ ] Function names describe action
+- [ ] No single-letter names (except loop indices)
+- [ ] No abbreviations that aren't universal
+- [ ] Consistent naming style (camelCase/snake_case)
+
+---
+
+### 8. Consistency Violations
+
+**Question**: Does this match existing patterns?
+
+**Red Flags**:
+```typescript
+// BAD: Different style than rest of codebase
+// Existing code uses Result types
+function existingFunction(): Result<User, Error> { }
+
+// Your code throws instead
+function yourFunction(): User {
+  throw new Error('...');  // Inconsistent!
+}
+```
+
+**Checklist**:
+- [ ] Follows existing code style
+- [ ] Uses same patterns as surrounding code
+- [ ] Error handling matches project conventions
+- [ ] Import organization matches existing files
+- [ ] No unnecessary divergence from norms
+
+---
+
+### 9. Documentation Violations
+
+**Question**: Will others understand this code?
+
+**Red Flags**:
+```typescript
+// BAD: Missing docs on complex function
+export function calculateProratedBilling(plan, start, end, previous) {
+  // 50 lines of complex billing logic with no explanation
+}
+
+// BAD: Outdated comment
+// Returns user's full name
+function getDisplayName(user) {
+  return user.username;  // Actually returns username!
+}
+```
+
+**Checklist**:
+- [ ] Complex logic has explanatory comments
+- [ ] Public APIs have JSDoc/docstrings
+- [ ] README updated if behavior changes
+- [ ] No outdated comments
+- [ ] Comments explain "why", not "what"
+
+---
+
+## Quick Reference
+
+See [patterns.md](patterns.md) for correct patterns and [report-template.md](report-template.md) for self-review format.

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

@@ -0,0 +1,183 @@
+---
+name: test-patterns
+description: This skill should be used when the user asks to "write tests", "fix failing tests", "improve test coverage", "add integration tests", "debug a flaky test", or reviews test quality. Provides behavior-focused testing patterns, coverage analysis, and detection of brittle test anti-patterns like implementation coupling and non-deterministic assertions.
+user-invocable: false
+allowed-tools: Read, Grep, Glob, AskUserQuestion
+activation:
+  file-patterns:
+    - "**/*.test.*"
+    - "**/*.spec.*"
+    - "**/test/**"
+    - "**/tests/**"
+    - "**/__tests__/**"
+  exclude:
+    - "node_modules/**"
+---
+
+# Test Patterns
+
+## Iron Law
+
+> **TESTS VALIDATE BEHAVIOR, NOT IMPLEMENTATION**
+>
+> A test should fail when behavior breaks, not when implementation changes. If refactoring
+> breaks tests without changing behavior, the tests are wrong. Mock boundaries, not internals.
+> Test the contract, not the code. If tests are hard to write, the design is wrong — fix the
+> architecture, not the tests.
+
+---
+
+## Test Design Red Flags
+
+### 1. Complex Setup
+
+**RED FLAG**: Test setup >10 lines means the design is wrong.
+
+```typescript
+// VIOLATION: Too many dependencies
+beforeEach(async () => {
+  mockDb = new MockDatabase();
+  await mockDb.connect();
+  mockCache = new MockCache();
+  // ... 10+ more lines
+  service = new UserService(mockDb, mockCache, mockLogger, mockConfig);
+});
+
+// CORRECT: Simple setup
+it('should return Ok with valid data', () => {
+  const result = createUser({ name: 'test', email: 'test@example.com' });
+  expect(result.ok).toBe(true);
+});
+```
+
+**Detection**: `beforeEach` >10 lines, multiple mocks, async setup, database seeding
+
+### 2. Repetitive Boilerplate
+
+**RED FLAG**: Same pattern repeated >3 times means the API is wrong.
+
+```typescript
+// VIOLATION: Try/catch everywhere
+try { await api.createUser(data); fail(); } catch (e) { expect(e.status).toBe(400); }
+
+// CORRECT: Result types eliminate repetition
+const result = createUser(invalidData);
+expect(result.ok).toBe(false);
+expect(result.error.type).toBe('ValidationError');
+```
+
+### 3. Difficult Mocking
+
+**RED FLAG**: Mock setup >20 lines means dependencies are wrong.
+
+```typescript
+// VIOLATION: Nested mock structures
+mockDb = { transaction: jest.fn(), orders: { create: jest.fn(), update: jest.fn() } };
+
+// CORRECT: Pure functions need no mocking
+const result = processOrder(order);
+expect(result.ok).toBe(true);
+```
+
+### 4. Implementation Testing
+
+**RED FLAG**: Testing internals means tests are fragile.
+
+```typescript
+// VIOLATION: Spying on private methods
+const spy = jest.spyOn(cart as any, 'updateTotal');
+expect(spy).toHaveBeenCalled();
+
+// CORRECT: Test observable behavior
+expect(cart.getTotal()).toBe(10);
+```
+
+---
+
+## Coverage & Review
+
+### Coverage Issues
+
+- **Untested new code**: New functions/branches without corresponding tests
+- **Missing edge cases**: Only happy path tested, no error paths
+- **Missing error paths**: `throw`/`reject` in source without matching test assertions
+
+### Test Quality Issues
+
+- **Brittle tests**: Testing HOW (mock call verification) not WHAT (outcome)
+- **Unclear test names**: `it('test1')` instead of `it('validates email format on creation')`
+- **Missing AAA structure**: Mixed arrange/act/assert without clear separation
+
+### Mocking Issues
+
+- **Over-mocking**: Everything mocked, nothing actually tested
+- **Mocking third-party internals**: Mock at your own interface boundary instead
+
+---
+
+## Severity Guidelines
+
+| Severity | Criteria |
+|----------|----------|
+| **CRITICAL** | Tests pass but don't verify behavior; critical paths untested; tests mock everything |
+| **HIGH** | Missing error path coverage; flaky tests; extremely slow (>10s); >10 line setup |
+| **MEDIUM** | Some edge cases missing; weak assertions; unclear structure |
+| **LOW** | Organization could improve; naming could be clearer |
+
+---
+
+## Test Suite Safety
+
+```typescript
+// vitest.config.ts / jest.config.js
+{ fileParallelism: false, maxWorkers: 1, testTimeout: 10000 }
+```
+
+```bash
+NODE_OPTIONS="--max-old-space-size=512" npm test
+```
+
+---
+
+## Extended References
+
+For comprehensive examples and detection patterns:
+
+| Reference | Contents |
+|-----------|----------|
+| `references/violations.md` | Full violation examples for all categories |
+| `references/patterns.md` | Correct test patterns and organization |
+| `references/detection.md` | Bash commands for automated detection |
+| `references/report-template.md` | Full report format for documenting issues |
+
+---
+
+## Quality Gates
+
+Tests pass design review when:
+- [ ] Setup code <10 lines per test file
+- [ ] No repetitive try/catch or error handling patterns
+- [ ] Mocking requires <5 lines of setup
+- [ ] No spying on private methods or internal state
+- [ ] Tests verify behavior, not implementation details
+- [ ] Pure business logic testable without mocks
+- [ ] New code has corresponding tests
+- [ ] All branches covered (happy path + errors + edge cases)
+- [ ] Test names describe expected behavior
+- [ ] Tests follow Arrange-Act-Assert structure
+- [ ] No real delays (use mocked timers)
+- [ ] No flaky patterns (race conditions, timing dependencies)
+
+---
+
+## Review Checklist
+
+- [ ] New code has corresponding tests
+- [ ] All branches covered (happy path + errors + edge cases)
+- [ ] Tests verify behavior, not implementation
+- [ ] Test names describe expected behavior
+- [ ] Tests follow Arrange-Act-Assert structure
+- [ ] No real delays (use mocked timers)
+- [ ] Assertions are specific and meaningful
+- [ ] Mocking limited to boundaries (not internals)
+- [ ] No flaky patterns (race conditions, timing dependencies)

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

@@ -0,0 +1,149 @@
+# Test Issue Detection
+
+Commands and patterns for detecting test quality issues.
+
+---
+
+## Coverage Detection
+
+### Find Untested Functions
+
+```bash
+# List exported functions in source
+grep -rn "export function\|export async function" --include="*.ts" src/ | cut -d: -f1,3 | sort
+
+# List tested functions
+grep -rn "describe\|it\(" --include="*.test.ts" | grep -oE "'[^']+'" | sort -u
+
+# Compare to find gaps (manual comparison needed)
+```
+
+### Find Missing Error Tests
+
+```bash
+# Count error-throwing code in source
+grep -rn "throw\|reject\|Error" --include="*.ts" src/ | grep -v test | wc -l
+
+# Count error test assertions
+grep -rn "rejects.toThrow\|toThrow\|toThrowError" --include="*.test.ts" | wc -l
+
+# Large discrepancy indicates missing error tests
+```
+
+---
+
+## Quality Detection
+
+### Tests Without Assertions
+
+```bash
+# Find test blocks that may lack assertions
+grep -rn "it\(.*=>" --include="*.test.ts" -A20 | grep -v "expect" | head -50
+
+# Find empty test blocks
+grep -rn "it\(.*{\s*}\)" --include="*.test.ts"
+```
+
+### Weak Assertions
+
+```bash
+# Find overly permissive assertions
+grep -rn "toBeDefined\|toBeTruthy\|not.toBeNull\|not.toBeUndefined" --include="*.test.ts"
+
+# Count for comparison with strong assertions
+grep -rn "toEqual\|toMatchObject\|toHaveLength\|toBe(" --include="*.test.ts" | wc -l
+```
+
+### Implementation Testing
+
+```bash
+# Find tests that verify mock calls (may indicate implementation testing)
+grep -rn "toHaveBeenCalledWith\|toHaveBeenCalled\|toHaveBeenCalledTimes" --include="*.test.ts"
+```
+
+---
+
+## Design Detection
+
+### Slow Tests
+
+```bash
+# Find tests with long timeouts (>5000ms)
+grep -rn "}, [0-9][0-9][0-9][0-9][0-9])" --include="*.test.ts"
+
+# Find real delays in tests
+grep -rn "setTimeout\|sleep\|delay" --include="*.test.ts"
+```
+
+### Complex Setup
+
+```bash
+# Find tests with many mock objects
+grep -rn "jest.fn\|sinon.stub\|mock" --include="*.test.ts" | cut -d: -f1 | uniq -c | sort -rn | head -10
+
+# Find long beforeEach blocks
+grep -rn "beforeEach" --include="*.test.ts" -A30 | head -100
+```
+
+---
+
+## Mocking Detection
+
+### Over-Mocking
+
+```bash
+# Count mocks per test file
+for f in $(find . -name "*.test.ts" -type f); do
+  count=$(grep -c "jest.fn\|mock" "$f" 2>/dev/null || echo 0)
+  echo "$count $f"
+done | sort -rn | head -20
+
+# Files with >20 mocks may be over-mocked
+```
+
+### Third-Party Library Mocking
+
+```bash
+# Find jest.mock of node_modules
+grep -rn "jest.mock\(['\"]" --include="*.test.ts" | grep -v "\./" | grep -v "\.\./"
+
+# These should be wrapped in interfaces instead
+```
+
+---
+
+## Summary Report Script
+
+```bash
+#!/bin/bash
+# test-health-check.sh - Quick test quality assessment
+
+echo "=== Test Health Check ==="
+echo ""
+
+echo "Coverage Indicators:"
+echo "  Source functions: $(grep -rn 'export function' --include='*.ts' src/ 2>/dev/null | wc -l)"
+echo "  Test blocks: $(grep -rn 'it\(' --include='*.test.ts' 2>/dev/null | wc -l)"
+echo ""
+
+echo "Quality Indicators:"
+echo "  Strong assertions: $(grep -rn 'toEqual\|toMatchObject' --include='*.test.ts' 2>/dev/null | wc -l)"
+echo "  Weak assertions: $(grep -rn 'toBeDefined\|toBeTruthy' --include='*.test.ts' 2>/dev/null | wc -l)"
+echo ""
+
+echo "Design Indicators:"
+echo "  Long timeouts: $(grep -rn '}, [0-9]\{5,\})' --include='*.test.ts' 2>/dev/null | wc -l)"
+echo "  Mock count: $(grep -rn 'jest.fn\|mock' --include='*.test.ts' 2>/dev/null | wc -l)"
+```
+
+---
+
+## Test Coverage Guidelines
+
+| Code Type | Required Coverage | Test Type |
+|-----------|-------------------|-----------|
+| Business logic | 90%+ | Unit tests |
+| API endpoints | 80%+ | Integration tests |
+| UI components | 70%+ | Component tests |
+| Utilities | 100% | Unit tests |
+| Error paths | 100% | Unit tests |