@directive-run/claude-plugin 1.16.0

package/skills/testing-directive-code/SKILL.md

@@ -0,0 +1,479 @@
+---
+name: testing-directive-code
+description: "Test Directive modules and systems using createTestSystem, mockResolver, assertFact, assertDerivation, assertRequirement, settleWithFakeTimers, and flushMicrotasks. Use when writing tests for Directive modules, constraints, resolvers, derivations, effects, or time-travel behavior."
+---
+
+# Testing Directive Code
+
+## Prerequisites
+
+This skill applies when the project uses `@directive-run/core`. If not found in `package.json`, suggest installing it: `npm install @directive-run/core`.
+
+## When Claude Should Use This Skill
+
+**Auto-invoke when the user:**
+- Says "write a test", "add tests for this module", or "how do I test this resolver"
+- Shows a Directive module and asks how to verify its behavior
+- Asks about mocking resolvers, fake timers, or asserting facts in tests
+- Asks about testing time-travel or snapshot behavior
+
+**Do NOT invoke when:**
+- Writing the module under test (see `writing-directive-modules.md`)
+- Asking about system composition (see `building-directive-systems.md`)
+- Asking about constraint patterns without a testing context (see `writing-directive-constraints.md`)
+
+---
+
+## Decision Tree: What Are You Testing?
+
+```
+What are you testing?
+├── A single module in isolation       → createTestSystem(module)
+├── Multiple modules together          → createTestSystemFromModules({ a, b })
+├── A constraint fires correctly       → Set facts, call assertRequirement
+├── A resolver mutates facts           → Mock resolver, trigger, settle, assertFact
+├── A derivation computes correctly    → Set facts, call assertDerivation
+├── Async/retry behavior               → settleWithFakeTimers(system, vi)
+├── Intermediate state (mid-resolve)   → flushMicrotasks()
+└── Time-travel / snapshots            → Enable history in createTestSystem options
+```
+
+---
+
+## Imports
+
+```typescript
+import {
+  createTestSystem,
+  createTestSystemFromModules,
+  mockResolver,
+  flushMicrotasks,
+  settleWithFakeTimers,
+  assertFact,
+  assertDerivation,
+  assertRequirement,
+} from "@directive-run/core/testing";
+```
+
+---
+
+## Creating Test Systems
+
+### Single module
+
+```typescript
+// Minimal – testing defaults: time-travel off, no plugins, sync settling
+const system = createTestSystem(myModule);
+
+// With initial state
+const system = createTestSystem(myModule, {
+  initialFacts: { count: 5, phase: "loading" },
+});
+
+// With mocked resolvers
+const system = createTestSystem(myModule, {
+  mockResolvers: [
+    mockResolver("FETCH_USER", async (req, context) => {
+      context.facts.user = { id: req.userId, name: "Test User" };
+    }),
+  ],
+});
+
+// Combined
+const system = createTestSystem(myModule, {
+  initialFacts: { isAuthenticated: true, profile: null },
+  mockResolvers: [
+    mockResolver("FETCH_PROFILE", async (req, context) => {
+      context.facts.profile = { bio: "Test bio" };
+    }),
+  ],
+});
+```
+
+### Multi-module
+
+```typescript
+const system = createTestSystemFromModules(
+  { auth: authModule, cart: cartModule },
+  {
+    mockResolvers: [
+      mockResolver("AUTHENTICATE", async (req, context) => {
+        context.facts.auth.token = "test-token";
+        context.facts.auth.isAuthenticated = true;
+      }),
+    ],
+  },
+);
+```
+
+---
+
+## Testing Constraints
+
+Set facts to satisfy the constraint's `when()`, then assert the requirement was emitted.
+
+```typescript
+describe("fetchWhenAuth constraint", () => {
+  it("emits FETCH_USER when authenticated without profile", () => {
+    const system = createTestSystem(userModule);
+
+    system.facts.isAuthenticated = true;
+    system.facts.profile = null;
+
+    assertRequirement(system, "FETCH_USER");
+  });
+
+  it("does NOT emit when profile already loaded", () => {
+    const system = createTestSystem(userModule, {
+      initialFacts: {
+        isAuthenticated: true,
+        profile: { id: "1", name: "Alice" },
+      },
+    });
+
+    const { requirements } = system.inspect();
+    const fetchReqs = requirements.filter((r) => r.type === "FETCH_USER");
+    expect(fetchReqs).toHaveLength(0);
+  });
+
+  it("emits dynamic requirement with correct payload", () => {
+    const system = createTestSystem(userModule, {
+      initialFacts: { isAuthenticated: true, userId: "u-42", profile: null },
+    });
+
+    // assertRequirement can check payload
+    assertRequirement(system, "FETCH_USER", { userId: "u-42" });
+  });
+});
+```
+
+---
+
+## Testing Resolvers
+
+Mock the resolver, trigger the constraint, settle, then assert fact mutations.
+
+```typescript
+describe("fetchUser resolver", () => {
+  it("stores fetched user and updates phase", async () => {
+    const system = createTestSystem(userModule, {
+      mockResolvers: [
+        mockResolver("FETCH_USER", async (req, context) => {
+          context.facts.user = { id: req.userId, name: "Mocked User" };
+          context.facts.phase = "loaded";
+        }),
+      ],
+    });
+
+    system.facts.isAuthenticated = true;
+    system.facts.user = null;
+
+    await system.settle();
+
+    assertFact(system, "user", { id: expect.any(String), name: "Mocked User" });
+    assertFact(system, "phase", "loaded");
+  });
+
+  it("handles resolver error gracefully", async () => {
+    const system = createTestSystem(userModule, {
+      mockResolvers: [
+        mockResolver("FETCH_USER", async () => {
+          throw new Error("Network failure");
+        }),
+      ],
+    });
+
+    system.facts.isAuthenticated = true;
+    system.facts.user = null;
+
+    // If error boundary uses "skip", settle resolves normally
+    await system.settle();
+    assertFact(system, "phase", "error");
+  });
+});
+```
+
+---
+
+## Testing Derivations
+
+Set facts, then read the derived value. No need to settle – derivations are synchronous.
+
+```typescript
+describe("isOverBudget derivation", () => {
+  it("returns true when total exceeds budget", () => {
+    const system = createTestSystem(budgetModule, {
+      initialFacts: { total: 150, budget: 100 },
+    });
+
+    assertDerivation(system, "isOverBudget", true);
+  });
+
+  it("recomputes reactively when facts change", () => {
+    const system = createTestSystem(budgetModule, {
+      initialFacts: { total: 50, budget: 100 },
+    });
+
+    assertDerivation(system, "isOverBudget", false);
+
+    system.facts.total = 200;
+
+    assertDerivation(system, "isOverBudget", true);
+  });
+});
+```
+
+---
+
+## Testing with Fake Timers
+
+Use `settleWithFakeTimers` when resolvers use retry delays, timeouts, or exponential backoff.
+
+```typescript
+import { describe, it, expect, vi } from "vitest";
+import { createTestSystem, settleWithFakeTimers, mockResolver, assertFact } from "@directive-run/core/testing";
+
+describe("retry behavior", () => {
+  it("retries on failure with exponential backoff", async () => {
+    vi.useFakeTimers();
+    let attempts = 0;
+
+    const system = createTestSystem(myModule, {
+      mockResolvers: [
+        mockResolver("FETCH_DATA", async (req, context) => {
+          attempts += 1;
+          if (attempts < 3) {
+            throw new Error("Temporary failure");
+          }
+          context.facts.data = "success";
+        }),
+      ],
+    });
+
+    system.facts.needsData = true;
+
+    // Advances fake timers through retry delays and waits for settlement
+    await settleWithFakeTimers(system, vi);
+
+    expect(attempts).toBe(3);
+    assertFact(system, "data", "success");
+
+    vi.useRealTimers();
+  });
+});
+```
+
+---
+
+## Testing Intermediate Async State
+
+Use `flushMicrotasks()` to process pending promises without fully settling.
+
+```typescript
+it("shows loading phase during resolution", async () => {
+  const system = createTestSystem(myModule, {
+    mockResolvers: [
+      mockResolver("FETCH_DATA", async (req, context) => {
+        context.facts.phase = "loading";
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        context.facts.phase = "done";
+      }),
+    ],
+  });
+
+  system.facts.trigger = true;
+
+  await flushMicrotasks();
+  assertFact(system, "phase", "loading");
+
+  await system.settle();
+  assertFact(system, "phase", "done");
+});
+```
+
+---
+
+## Testing Effects
+
+Effects run after reconciliation. Settle first, then check side effects.
+
+```typescript
+describe("logPhase effect", () => {
+  it("logs when phase changes", async () => {
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    const system = createTestSystem(myModule, {
+      initialFacts: { phase: "idle" },
+    });
+
+    system.facts.phase = "loading";
+    await system.settle();
+
+    expect(consoleSpy).toHaveBeenCalledWith("Phase: loading");
+
+    consoleSpy.mockRestore();
+  });
+});
+```
+
+---
+
+## Testing Time-Travel
+
+Enable time-travel in the test system config. In most cases, prefer `assertFact` over snapshot testing.
+
+```typescript
+describe("history", () => {
+  it("can undo a fact change", () => {
+    const system = createTestSystem(editorModule, {
+      history: { maxSnapshots: 20 },
+    });
+
+    system.facts.text = "Hello";
+    system.facts.text = "Hello, world";
+
+    const history = system.history;
+    expect(system.facts.text).toBe("Hello, world");
+
+    history.goBack();
+    expect(system.facts.text).toBe("Hello");
+  });
+
+  it("can export and import history", () => {
+    const system = createTestSystem(myModule, {
+      history: true,
+    });
+
+    system.facts.count = 1;
+    system.facts.count = 2;
+
+    const history = system.history;
+    const exported = history.export();
+
+    history.import(exported);
+    history.goTo(0);
+    expect(system.facts.count).toBe(1);
+  });
+});
+```
+
+---
+
+## Critical Anti-Patterns
+
+### 1. Testing real resolvers (hitting real APIs)
+
+```typescript
+// WRONG – slow, flaky, external dependency
+const system = createTestSystem(myModule);
+system.facts.needsFetch = true;
+await system.settle();   // Makes real HTTP call
+
+// CORRECT – always mock resolvers in unit tests
+const system = createTestSystem(myModule, {
+  mockResolvers: [mockResolver("FETCH", async (req, context) => {
+    context.facts.data = { mocked: true };
+  })],
+});
+```
+
+### 2. Forgetting to settle before asserting async results
+
+```typescript
+// WRONG – resolver hasn't completed
+system.facts.trigger = true;
+assertFact(system, "result", "done");   // Fails
+
+// CORRECT
+system.facts.trigger = true;
+await system.settle();
+assertFact(system, "result", "done");
+```
+
+### 3. Resolver parameter naming
+Always use `(req, context)` – never `(req, ctx)` or `(request, context)`. Applies to `mockResolver` callbacks too.
+
+### 4. Testing implementation details instead of behavior
+
+```typescript
+// WRONG – testing internal resolver call count without behavior check
+expect(mockFn).toHaveBeenCalledTimes(1);
+
+// CORRECT – test the observable outcome (facts, derivations)
+assertFact(system, "user", { id: "1", name: "Alice" });
+assertDerivation(system, "isLoggedIn", true);
+```
+
+### 5. Using createSystem instead of createTestSystem
+
+```typescript
+// WRONG – production system, no test defaults, runs plugins
+const system = createSystem({ module: myModule });
+
+// CORRECT – isolated, no plugins, testing utilities available
+const system = createTestSystem(myModule);
+```
+
+### 6. Not resetting fake timers
+
+```typescript
+// WRONG – leaks fake timers to other tests
+vi.useFakeTimers();
+await settleWithFakeTimers(system, vi);
+// Missing vi.useRealTimers()
+
+// CORRECT – always restore in afterEach or at the end of the test
+vi.useFakeTimers();
+await settleWithFakeTimers(system, vi);
+vi.useRealTimers();
+```
+
+### 7. Enabling time-travel when you don't need it
+
+```typescript
+// Prefer assertFact/assertDerivation for most tests.
+// Only enable time-travel when specifically testing undo/redo or snapshot export.
+```
+
+### 8. Forgetting to destroy the system between tests
+
+```typescript
+// CORRECT – use afterEach to clean up
+let system: ReturnType<typeof createTestSystem>;
+
+beforeEach(() => {
+  system = createTestSystem(myModule);
+});
+
+afterEach(() => {
+  system.destroy();
+});
+```
+
+---
+
+## Assertion Quick Reference
+
+```typescript
+// Assert a fact value
+assertFact(system, "phase", "done");
+assertFact(system, "user", { id: expect.any(String) });
+
+// Assert a derivation value
+assertDerivation(system, "isLoading", false);
+assertDerivation(system, "itemCount", 3);
+
+// Assert a requirement was emitted
+assertRequirement(system, "FETCH_USER");
+assertRequirement(system, "FETCH_USER", { userId: "u-42" });  // With payload
+
+// Inspect raw state
+const { facts, requirements, resolvers, inflight } = system.inspect();
+```
+
+---
+
+## Reference Files
+
+- `testing.md` – full testing API, createTestSystem options, multi-module test setup
+- `history.md` – history API, changesets, export/import, performance considerations

package/skills/testing-directive-code/api-skeleton.md

@@ -0,0 +1,5 @@
+# API Skeleton
+
+> Auto-generated. Do not edit.
+
+> Source JSON not found. Build website docs first.

package/skills/testing-directive-code/examples.md

@@ -0,0 +1,156 @@
+# Examples
+
+> Auto-generated from extracted examples. Do not edit manually.
+
+## time-machine
+
+```typescript
+// Example: time-machine
+// Source: examples/time-machine/src/module.ts
+// Pure module file — no DOM wiring
+
+/**
+ * Time Machine — Directive Module
+ *
+ * Drawing canvas where each stroke is a fact mutation. Full time-travel:
+ * undo/redo, export/import JSON, replay animation, changesets, snapshot slider.
+ */
+
+import {
+  type ModuleSchema,
+  createModule,
+  createSystem,
+  t,
+} from "@directive-run/core";
+import { devtoolsPlugin } from "@directive-run/core/plugins";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface Stroke {
+  id: string;
+  x: number;
+  y: number;
+  color: string;
+  size: number;
+}
+
+export interface TimelineEntry {
+  time: number;
+  event: string;
+  detail: string;
+  type:
+    | "stroke"
+    | "undo"
+    | "redo"
+    | "changeset"
+    | "export"
+    | "import"
+    | "replay"
+    | "goto";
+}
+
+// ============================================================================
+// Timeline (external mutable array, same pattern as fraud-analysis)
+// ============================================================================
+
+export const timeline: TimelineEntry[] = [];
+
+export function addTimeline(
+  event: string,
+  detail: string,
+  type: TimelineEntry["type"],
+): void {
+  timeline.unshift({ time: Date.now(), event, detail, type });
+  if (timeline.length > 50) {
+    timeline.length = 50;
+  }
+}
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const schema = {
+  facts: {
+    strokes: t.array<Stroke>(),
+    currentColor: t.string(),
+    brushSize: t.number(),
+    changesetActive: t.boolean(),
+    changesetLabel: t.string(),
+  },
+  derivations: {
+    strokeCount: t.number(),
+    canUndo: t.boolean(),
+    canRedo: t.boolean(),
+    currentIndex: t.number(),
+    totalSnapshots: t.number(),
+  },
+  events: {
+    addStroke: { x: t.number(), y: t.number() },
+    setColor: { value: t.string() },
+    setBrushSize: { value: t.number() },
+    clearCanvas: {},
+  },
+  requirements: {},
+} satisfies ModuleSchema;
+
+// ============================================================================
+// Module
+// ============================================================================
+
+const canvasModule = createModule("canvas", {
+  schema,
+
+  init: (facts) => {
+    facts.strokes = [];
+    facts.currentColor = "#5ba3a3";
+    facts.brushSize = 12;
+    facts.changesetActive = false;
+    facts.changesetLabel = "";
+  },
+
+  derive: {
+    strokeCount: (facts) => facts.strokes.length,
+    // These will be updated from the time-travel manager
+    canUndo: () => false,
+    canRedo: () => false,
+    currentIndex: () => 0,
+    totalSnapshots: () => 0,
+  },
+
+  events: {
+    addStroke: (facts, { x, y }) => {
+      const stroke: Stroke = {
+        id: `s${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+        x,
+        y,
+        color: facts.currentColor,
+        size: facts.brushSize,
+      };
+      facts.strokes = [...facts.strokes, stroke];
+    },
+    setColor: (facts, { value }) => {
+      facts.currentColor = value;
+    },
+    setBrushSize: (facts, { value }) => {
+      facts.brushSize = value;
+    },
+    clearCanvas: (facts) => {
+      facts.strokes = [];
+    },
+  },
+});
+
+// ============================================================================
+// System with Time-Travel
+// ============================================================================
+
+export const system = createSystem({
+  module: canvasModule,
+  history: { maxSnapshots: 200 },
+  trace: true,
+  plugins: [devtoolsPlugin({ name: "time-machine" })],
+});
+```