ima-claude 2.9.0

package/plugins/ima-claude/skills/unit-testing/references/mock-patterns.md

@@ -0,0 +1,181 @@
+# Mock Patterns for FP Codebases
+
+## The FP Alternative to Mocking
+
+Before reaching for a mock, ask: **can I extract the pure logic instead?**
+
+### Before (Hard to Test — Needs Mocks)
+
+```javascript
+// Impure: mixed logic + side effects
+function processOrder(orderId) {
+  const order = db.getOrder(orderId)         // side effect
+  const total = order.items.reduce((s, i) => s + i.price * i.qty, 0)
+  const tax = total * 0.08
+  const discount = total > 100 ? total * 0.1 : 0
+  db.updateOrder(orderId, { total, tax, discount })  // side effect
+  return { total, tax, discount }
+}
+```
+
+### After (Easy to Test — No Mocks Needed)
+
+```javascript
+// Pure: extract the logic
+const calculateOrderTotals = (items, taxRate = 0.08, discountThreshold = 100) => {
+  const total = items.reduce((s, i) => s + i.price * i.qty, 0)
+  const tax = total * taxRate
+  const discount = total > discountThreshold ? total * 0.1 : 0
+  return { total, tax, discount }
+}
+
+// Impure shell: thin wrapper
+function processOrder(orderId) {
+  const order = db.getOrder(orderId)
+  const totals = calculateOrderTotals(order.items)
+  db.updateOrder(orderId, totals)
+  return totals
+}
+```
+
+Now `calculateOrderTotals` is tested with zero mocks. The impure shell is thin enough to verify by inspection or a single integration test.
+
+## When Mocking IS Appropriate
+
+Mock when the dependency is:
+
+| Dependency | Mock? | Why |
+|-----------|-------|-----|
+| External API (Stripe, Twilio) | Yes | Unreliable, slow, costs money |
+| Database | Yes (for unit tests) | Slow, requires setup/teardown |
+| Filesystem | Yes | Non-deterministic, platform-specific |
+| Time/Date | Yes | Non-deterministic |
+| Random/UUID | Yes | Non-deterministic |
+| Your own pure functions | **No** | Use the real thing |
+| Your own classes | **Rarely** | Extract the logic instead |
+
+## Mock Types: When to Use Each
+
+### Stub (Default Choice)
+
+Returns canned data. Use for most cases.
+
+```javascript
+// JS: Simple stub
+const getUser = vi.fn().mockReturnValue({ id: 1, name: 'Alice' })
+
+// PHP: PHPUnit stub
+$repo = $this->createStub(UserRepository::class);
+$repo->method('find')->willReturn(new User(1, 'Alice'));
+```
+
+### Spy (Verify Calls)
+
+Records calls for later assertion. Use when you need to verify a side effect happened.
+
+```javascript
+// JS: Spy on a method
+const sendEmail = vi.fn()
+processSignup(user, { sendEmail })
+expect(sendEmail).toHaveBeenCalledWith(user.email, expect.any(String))
+
+// PHP: PHPUnit expects
+$mailer = $this->createMock(Mailer::class);
+$mailer->expects($this->once())
+       ->method('send')
+       ->with($this->equalTo('alice@example.com'));
+```
+
+### Fake (Simplified Implementation)
+
+A working but simplified version. Use for complex interfaces.
+
+```javascript
+// JS: In-memory store as a fake
+const createFakeStore = () => {
+  const data = new Map()
+  return {
+    get: (key) => data.get(key),
+    set: (key, value) => data.set(key, value),
+    delete: (key) => data.delete(key),
+  }
+}
+```
+
+### Full Mock (Almost Never)
+
+Strict expectations on exact call sequences. Couples tests tightly to implementation.
+
+**Use only when:** the exact call sequence IS the behavior (e.g., protocol compliance, ordered operations).
+
+## Language-Specific Tooling
+
+### JavaScript/TypeScript
+
+| Tool | Best For |
+|------|----------|
+| `vi.fn()` / `jest.fn()` | Stubs and spies |
+| `vi.mock()` / `jest.mock()` | Module-level mocking |
+| `msw` (Mock Service Worker) | HTTP API mocking (integration/E2E) |
+| `@testing-library/*` | Component testing without implementation details |
+
+### PHP
+
+| Tool | Best For |
+|------|----------|
+| PHPUnit `createStub()` | Simple return values |
+| PHPUnit `createMock()` | Stubs with expectations |
+| `Brain\Monkey` | WordPress function mocking |
+| `WP_Mock` | WordPress hook/filter mocking |
+| `Mockery` | Complex mocking (use sparingly) |
+
+## Anti-Patterns
+
+### Mocking What You Own
+
+```javascript
+// BAD: Mocking your own utility
+const calculateTax = vi.fn().mockReturnValue(8.0)
+const result = processOrder(items, { calculateTax })
+expect(result.tax).toBe(8.0)  // This proves nothing!
+```
+
+You're testing that your test setup works, not that the code works. Use the real function.
+
+### Deep Mock Chains
+
+```javascript
+// BAD: Mock chain hell
+const mockDb = {
+  getConnection: vi.fn().mockReturnValue({
+    query: vi.fn().mockReturnValue({
+      rows: vi.fn().mockReturnValue([{ id: 1 }])
+    })
+  })
+}
+```
+
+If you need this, the code needs refactoring, not more mocks. Extract the pure logic.
+
+### Mocking to Achieve Coverage
+
+```javascript
+// BAD: Mocking just to hit a coverage number
+const fs = vi.mock('fs')
+fs.readFileSync.mockReturnValue('data')
+// ... test that proves readFileSync was called with the right path
+```
+
+This tests that you called `readFileSync`, not that your logic is correct. Extract the logic that processes the data and test that instead.
+
+### Over-Specified Mocks
+
+```javascript
+// BAD: Testing implementation, not behavior
+expect(mockDb.query).toHaveBeenCalledWith(
+  'SELECT * FROM users WHERE id = ? AND active = ?',
+  [1, true]
+)
+```
+
+This breaks if you rename a column or change the query. Test the behavior: "given user ID 1, returns the user's data."

package/plugins/ima-claude/skills/unit-testing/references/tdd-workflow.md

@@ -0,0 +1,177 @@
+# TDD Workflow
+
+## Red-Green-Refactor Mechanics
+
+### Red: Write a Failing Test
+
+Write the test FIRST. It must fail for the right reason.
+
+```javascript
+// 1. Start with the desired behavior
+test('filters out inactive users', () => {
+  const users = [
+    { name: 'Alice', active: true },
+    { name: 'Bob', active: false },
+    { name: 'Carol', active: true },
+  ]
+  expect(getActiveUsers(users)).toEqual([
+    { name: 'Alice', active: true },
+    { name: 'Carol', active: true },
+  ])
+})
+// Fails: getActiveUsers is not defined ✓ (correct failure)
+```
+
+**Key:** The test should fail because the feature doesn't exist yet — not because of a typo or setup error.
+
+### Green: Make It Pass (Minimum Code)
+
+Write the simplest code that makes the test pass. Fight the urge to generalize.
+
+```javascript
+// 2. Simplest passing implementation
+const getActiveUsers = (users) => users.filter(u => u.active)
+```
+
+**Key:** Don't optimize. Don't handle edge cases you haven't tested. Just make it green.
+
+### Refactor: Clean Up
+
+With a passing test as your safety net, improve the code.
+
+- Rename for clarity
+- Extract shared logic
+- Remove duplication
+- Improve performance (only if needed)
+
+**Key:** Tests stay green throughout refactoring. If they go red, you broke something.
+
+## TDD with Pure Functions
+
+Pure functions are TDD's sweet spot. No setup, no teardown, no mocking.
+
+```
+Input → Function → Output
+Test:   Input → Function → Assert Output
+```
+
+The cycle is fast:
+1. Write test with input/output pair (10 seconds)
+2. Write function (10 seconds)
+3. Run test (1 second)
+4. Refactor if needed (30 seconds)
+
+### Table-Driven TDD
+
+For pure functions, use parameterized tests to cover multiple cases efficiently:
+
+```javascript
+test.each([
+  [0, 'F'],
+  [59, 'F'],
+  [60, 'D'],
+  [70, 'C'],
+  [80, 'B'],
+  [90, 'A'],
+  [100, 'A'],
+])('score %i gets grade %s', (score, expected) => {
+  expect(getGrade(score)).toBe(expected)
+})
+```
+
+Write all cases first (red), then implement until all pass (green).
+
+## TDD for Impure Boundaries
+
+When TDD meets side effects, use the **functional core / imperative shell** pattern:
+
+### 1. Define the Interface
+
+```typescript
+// What does the boundary need to provide?
+type UserRepository = {
+  findById: (id: string) => Promise<User | null>
+  save: (user: User) => Promise<void>
+}
+```
+
+### 2. TDD the Pure Logic
+
+```javascript
+// Test the decision logic, not the I/O
+test('deactivates user when last login > 90 days ago', () => {
+  const user = { lastLogin: daysAgo(91), active: true }
+  expect(shouldDeactivate(user)).toBe(true)
+})
+
+test('keeps user active when last login < 90 days ago', () => {
+  const user = { lastLogin: daysAgo(30), active: true }
+  expect(shouldDeactivate(user)).toBe(false)
+})
+```
+
+### 3. Wire the Shell (Minimal Integration Test)
+
+```javascript
+// One integration test to verify wiring
+test('deactivation job processes inactive users', async () => {
+  const fakeRepo = createFakeUserRepo([
+    { id: '1', lastLogin: daysAgo(91), active: true },
+  ])
+  await runDeactivationJob(fakeRepo)
+  expect(fakeRepo.findById('1')).resolves.toMatchObject({ active: false })
+})
+```
+
+## When TDD Slows You Down
+
+TDD is a tool, not a dogma. Skip it when:
+
+### Exploratory / Prototype Code
+
+You're figuring out what the code should even do. TDD assumes you know the desired behavior.
+
+**Instead:** Spike first, extract and test after.
+
+### Trivial Glue Code
+
+Code that just wires things together with no logic.
+
+```javascript
+// No TDD needed for this
+app.get('/users', authenticate, userController.list)
+```
+
+### UI Layout / Styling
+
+Visual output is better verified by looking at it, not by asserting CSS properties.
+
+**Instead:** Use visual regression tests (screenshot comparison) after the layout stabilizes.
+
+### Rapidly Changing Requirements
+
+If the spec changes daily, tests written today are deleted tomorrow.
+
+**Instead:** Wait for requirements to stabilize, then add tests.
+
+## TDD Anti-Patterns
+
+### Testing Too Much at Once
+
+Write one test, make it pass. Repeat. Don't write 10 failing tests and try to make them all pass simultaneously.
+
+### Gold-Plating in Green Phase
+
+The green phase is about making it work, not making it elegant. Save elegance for refactor.
+
+### Skipping Refactor Phase
+
+Red-green without refactor accumulates technical debt. The refactor step is where design emerges.
+
+### Testing Private Methods
+
+If you feel the need to test a private method, it's a sign that the method should be extracted as a separate pure function.
+
+### Assertion-Free Tests
+
+A test that only checks "it doesn't throw" is not a test. Assert on the output.

package/plugins/ima-claude/skills/unit-testing/references/test-strategy.md

@@ -0,0 +1,126 @@
+# Test Strategy for FP Codebases
+
+## The Test Pyramid (FP Edition)
+
+FP codebases are bottom-heavy by nature. Pure functions are trivially testable — lean into this.
+
+```
+        /  E2E  \          Few: critical user journeys only
+       /----------\
+      / Integration \      Some: boundary wiring, API contracts
+     /----------------\
+    /    Unit Tests     \   Many: pure functions, transformations, validators
+   /____________________\
+```
+
+### Why FP Pyramids Are Bottom-Heavy
+
+- Pure functions need zero setup → unit tests are cheap
+- Side effects are isolated at boundaries → integration tests are focused
+- Business logic is testable without infrastructure → fast feedback
+
+## Coverage Strategy
+
+**Coverage is a floor, not a ceiling.**
+
+### Setting the Floor
+
+- New projects: 80% line coverage as a starting point
+- Legacy projects: measure current coverage, set floor 5% below, ratchet up
+- Never chase 100% — the last 20% costs more than the first 80%
+
+### What to Cover
+
+| Priority | What | Why |
+|----------|------|-----|
+| High | Pure business logic | Core value, easy to test |
+| High | Data transformations | Bugs here corrupt everything downstream |
+| High | Validation functions | Security and correctness boundary |
+| Medium | Integration wiring | Verify components connect correctly |
+| Medium | Error handling paths | Prevent silent failures |
+| Low | Glue code / configuration | Low logic density |
+| Skip | Framework boilerplate | Trust the framework |
+
+### What NOT to Cover
+
+- Trivial getters/setters with no logic
+- Framework-generated code (migrations, stubs)
+- Configuration files
+- Type definitions (TypeScript interfaces, PHP type hints)
+
+## When to Write Each Test Type
+
+### Unit Tests
+
+Write when:
+- Function takes input, returns output (pure)
+- Logic has branches (if/else, switch, pattern matching)
+- Data transformation or validation
+- Algorithm implementation
+
+Skip when:
+- Code is pure glue (just wires things together)
+- Logic is trivially obvious (`return this.name`)
+
+### Integration Tests
+
+Write when:
+- Verifying database queries return correct data
+- API endpoint contracts (request → response shape)
+- Multiple components must work together
+- Third-party service integration points
+
+Skip when:
+- You can test the logic as a pure function instead
+- The integration is trivial and well-typed
+
+### E2E Tests
+
+Write when:
+- Critical user journeys (login, checkout, signup)
+- Complex multi-step workflows
+- Regression tests for bugs that slipped through unit/integration
+
+Skip when:
+- The behavior is fully covered by unit + integration tests
+- The UI is rapidly changing (tests will be constantly rewritten)
+- The test would be flaky by nature (animations, timing)
+
+## Retrofitting Tests onto Legacy Code
+
+Legacy code without tests is the norm. Don't try to add 100% coverage at once.
+
+### The Characterization Test Approach
+
+1. **Identify the change point** — what code are you about to modify?
+2. **Write characterization tests** — tests that document current behavior (even if buggy)
+3. **Extract pure logic** — pull testable functions out of the tangled code
+4. **Test the extracted logic** — proper unit tests for the new pure functions
+5. **Make your change** — now you have a safety net
+6. **Update tests** — adjust characterization tests if behavior intentionally changed
+
+### Priority Order for Legacy Code
+
+1. Code you're about to change (safety net)
+2. Code with known bugs (prevent regression)
+3. Business-critical paths (high impact if broken)
+4. Frequently modified code (high churn = high risk)
+5. Everything else (only if you have time)
+
+### The Strangler Pattern for Tests
+
+Don't rewrite all tests at once. Instead:
+- Every time you touch legacy code, add tests for what you changed
+- Over time, coverage grows organically where it matters most
+- Old untested code stays untested until it needs to change
+
+## When NOT to Test
+
+Testing has diminishing returns. Don't test:
+
+- **Prototype/spike code** — it's throwaway by definition
+- **One-off scripts** — run it, verify manually, done
+- **Configuration** — JSON/YAML files don't need unit tests
+- **Type system guarantees** — if TypeScript/PHP types prevent it, don't test it
+- **Third-party library internals** — test your usage, not their code
+- **Obvious glue code** — `app.use(cors())` doesn't need a test