@playfast/reform-proof 0.0.7 → 0.0.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-proof",
   "playbook": "./playbook",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "type": "module",
   "description": "Headless testing toolkit for reform — drive a scene's compositions and assert on the props they compute, with no DOM, timers, or text matching.",
   "keywords": [
@@ -27,7 +27,7 @@
     "./*": "./src/*.ts"
   },
   "files": [
-    "dist",
+    "src",
     "README.md"
   ],
   "scripts": {

package/src/engine.ts

@@ -0,0 +1,345 @@
+import { Effect, Layer, ManagedRuntime } from 'effect'
+import { yieldWrapGet } from 'effect/Utils'
+import { isValidElement } from 'react'
+import { UnknownAction, UnknownSlot } from './errors'
+import {
+  Bus,
+  CaptureSink,
+  type CaptureSinkApi,
+  Composition,
+  type CompositionClass,
+  type CompositionService,
+  isFeatureBinding,
+  type Node,
+  publish,
+  type RenderEnv,
+  type Scene,
+  type SlotChild,
+  type SlotClass,
+  type SlotHost,
+  type Trigger,
+  type UiCapture,
+  type UiContract,
+} from '@playfast/reform'
+import type { Action, DriveResult, Facade, Proof, ProofResult, SlotFacade, StepFrame } from './index'
+
+// reform-proof engine — the headless renderer the proof system runs on. It drives
+// the real reduce loop through a capturing FACADE: no DOM, no React reconciler, no
+// text matching. A proof never renders through React — props are recorded by
+// reform's Effect composition logic, and the only view code this engine runs is the
+// pure `(props, slots, events) => Node` body. `executeProof`/`driveProof` are the
+// two seams the `ProofRunner` layer exposes (see ./runner): one runs a proof to
+// completion, the other steps it a frame at a time for the editor's timeline.
+
+/** An erased facade — the runtime shape before the contract type is re-attached. */
+type AnyFacade = Facade<UiContract>
+type AnySlotFacade = SlotFacade<UiContract>
+
+// The drain loop, channels, RPC, and reducers run on forked fibers, so a
+// dispatched event takes an unknown number of ticks to flow through. Each poll
+// first drains COOPERATIVELY — a burst of `yieldNow` lets those forked fibers
+// cascade (event → channel → procedure → in-memory RPC → fact → reducer) with no
+// real time — so a synchronous flow reaches its final state within one poll. A
+// real-time `sleep` is still paid each poll to remain the correctness authority
+// for a genuinely time-delayed client (the cooperative drain alone could read a
+// flow waiting on a real timer as falsely "stable" and settle early). The render
+// then re-runs until the captured tree stops changing, bounded so a stuck flow
+// fails fast instead of hanging.
+const SETTLE_DRAIN = 30
+const SETTLE_STEP = '1 milli'
+const SETTLE_MAX_RENDERS = 100
+
+/** Cooperatively run forked engine fibers to a fixpoint without advancing real time. */
+const settleDrain = Effect.yieldNow().pipe(Effect.repeatN(SETTLE_DRAIN))
+
+// A keyed view backed by a getter — the only place dynamic keys are needed.
+const keyed = <V>(get: (key: string) => V): Record<string, V> => {
+  const target: Record<string, V> = Object.create(null)
+  return new Proxy(target, { get: (_t, key) => get(String(key)) })
+}
+
+const uiNameOf = (comp: CompositionClass<unknown>): string => comp.manifest.ui.manifest.name
+
+interface Sink {
+  readonly api: CaptureSinkApi
+  readonly captures: ReadonlyArray<UiCapture>
+  reset(): void
+}
+
+const makeSink = (): Sink => {
+  // A const holder whose array we swap on reset (no reassigned binding).
+  const state: { captures: UiCapture[] } = { captures: [] }
+  return {
+    api: { record: (capture) => state.captures.push(capture) },
+    get captures() {
+      return state.captures
+    },
+    reset: () => {
+      state.captures = []
+    },
+  }
+}
+
+type RuntimeServices = CompositionService | SlotChild | Bus
+
+/**
+ * Build a proof's runtime layer: the scene's closed wiring with the capture sink
+ * merged in, so `Ui`'s `serviceOption(CaptureSink)` finds it and records each
+ * render (absent in production, the same layer renders to React). The scene's
+ * `provide` is typed to the host-read subset (`MountedServices`); a proof also
+ * resolves slot-binding tags (`CompositionClass`), which the same closed layer
+ * supplies at runtime — restate that broader `RuntimeServices` surface here. This
+ * is the one erasure boundary, the same seam the react host crosses when it reads
+ * a slot tag with the requirement erased.
+ */
+const proofLayer = (scene: Scene, sink: Sink): Layer.Layer<RuntimeServices, never, never> => {
+  const sceneLayer = scene.provide.reduce((a, b) =>
+    Layer.merge(a, b),
+  ) as unknown as Layer.Layer<RuntimeServices, never, never>
+  return Layer.provideMerge(sceneLayer, Layer.succeed(CaptureSink, sink.api))
+}
+
+/** A composition queued to render, with the props its parent handed it. */
+interface Mounted {
+  readonly comp: CompositionClass<unknown>
+  readonly props: unknown
+}
+
+/**
+ * Walk a rendered node tree and invoke any slot components it contains (JSX
+ * defers them to the host; headless we drive them ourselves), enqueuing the
+ * child each stands for. Slot components are matched by identity, so this never
+ * calls — and never needs hooks from — ordinary components.
+ */
+const drive = (node: Node, enqueueBy: Map<Function, (props: unknown) => void>): void => {
+  if (Array.isArray(node)) {
+    for (const child of node) drive(child, enqueueBy)
+    return
+  }
+  if (!isValidElement<{ readonly children?: Node }>(node)) return
+  if (node.type instanceof Function) {
+    const enqueue = enqueueBy.get(node.type)
+    if (enqueue !== undefined) {
+      enqueue(node.props)
+      return
+    }
+  }
+  drive(node.props.children, enqueueBy)
+}
+
+const makeFacade = (
+  runtime: ManagedRuntime.ManagedRuntime<RuntimeServices, never>,
+  root: CompositionClass<unknown>,
+  sink: Sink,
+): { readonly facade: AnyFacade; readonly settle: Effect.Effect<void, never, CompositionService> } => {
+  // Slot bindings (`provide(slot, composition)`) are static, so resolve the
+  // whole child tree once, up front — keeping `renderTree` and slot navigation
+  // synchronous (no nested runtime drive).
+  const bindings = new Map<SlotClass, CompositionClass<unknown>>()
+  // A slot's child is a plain composition or a `FeatureBinding`. A proof drives the
+  // composition the feature mounts; for a `default` feature that composition's logic
+  // is already live (its eager `.live` was merged into the scene by `provide`), so
+  // unwrapping is all that's needed. (Driving a `lazy` feature — load gap +
+  // placeholders — is the proof host's Part B increment; until then a scene wires
+  // features as `default`, the eagerly-resolvable form.)
+  const childComposition = (child: SlotChild): CompositionClass<unknown> =>
+    isFeatureBinding(child) ? child.composition : child
+  const collect = (comp: CompositionClass<unknown>): Effect.Effect<void, never, SlotChild> =>
+    Effect.gen(function* () {
+      for (const slotClass of Object.values(comp.manifest.slots ?? {})) {
+        if (bindings.has(slotClass)) continue
+        const child = childComposition(yield* slotClass.tag)
+        bindings.set(slotClass, child)
+        yield* collect(child)
+      }
+    })
+  runtime.runSync(collect(root))
+
+  // One breadth-first render of the whole tree. Each view reports its
+  // `(props, events)` to the sink; each slot it renders enqueues a child (built
+  // on the next level), so a single sweep renders everything.
+  const renderLevel = (
+    frontier: ReadonlyArray<Mounted>,
+  ): Effect.Effect<void, never, CompositionService> =>
+    Effect.gen(function* () {
+      if (frontier.length === 0) return
+      const next: Array<Mounted> = []
+      for (const { comp, props } of frontier) {
+        const service = yield* comp.tag
+        // A slot renders to a deferred component (JSX `<slots.Item/>`); map each
+        // back to the child it stands for so the tree walk can enqueue it.
+        const enqueueBy = new Map<Function, (childProps: unknown) => void>()
+        const slots: SlotHost = {
+          slot: (name) => {
+            const slotClass = comp.manifest.slots?.[name]
+            const child = slotClass && bindings.get(slotClass)
+            const component: (childProps: unknown) => Node = () => null
+            if (child) enqueueBy.set(component, (childProps) => next.push({ comp: child, props: childProps }))
+            return component
+          },
+        }
+        const env: RenderEnv = { props, tracker: { add: () => {} }, slots }
+        const node = yield* Composition.render(service, env)
+        drive(node, enqueueBy)
+      }
+      yield* renderLevel(next)
+    })
+
+  const renderTree: Effect.Effect<void, never, CompositionService> = Effect.gen(function* () {
+    sink.reset()
+    yield* renderLevel([{ comp: root, props: {} }])
+  })
+
+  const capturesFor = (name: string): ReadonlyArray<UiCapture> =>
+    sink.captures.filter((capture) => capture.name === name)
+
+  // A cheap fingerprint of the rendered tree; when two successive renders match,
+  // the engine has stopped producing new state and the read is safe.
+  const fingerprint = (): string =>
+    JSON.stringify(sink.captures.map((capture) => [capture.name, capture.props]))
+
+  // Re-render until the tree is stable for two consecutive renders, or give up.
+  const settleFrom = (
+    previous: string,
+    remaining: number,
+  ): Effect.Effect<void, never, CompositionService> =>
+    Effect.gen(function* () {
+      if (remaining === 0) return
+      yield* settleDrain
+      yield* Effect.sleep(SETTLE_STEP)
+      yield* renderTree
+      const current = fingerprint()
+      if (current === previous) return
+      yield* settleFrom(current, remaining - 1)
+    })
+  const settle: Effect.Effect<void, never, CompositionService> = Effect.gen(function* () {
+    yield* settleDrain
+    yield* renderTree
+    yield* settleFrom(fingerprint(), SETTLE_MAX_RENDERS)
+  })
+
+  const triggerOf = (name: string, index: number, event: string): Trigger<unknown> => {
+    const trigger = capturesFor(name)[index]?.events[event]
+    if (trigger === undefined) {
+      throw new UnknownAction({ composition: name, action: event, rendered: capturesFor(name).length })
+    }
+    return trigger
+  }
+
+  const nodeFacade = (name: string, index: number, comp: CompositionClass<unknown>): AnyFacade => ({
+    props: Effect.map(renderTree, () => capturesFor(name)[index]?.props),
+    // `keyed` resolves event/slot names at runtime; cast the string-keyed proxy
+    // to the contract-typed surface. This is the one reflection boundary, the
+    // same seam as `definitionClass` — every name the proxy serves is a real
+    // contract member, so the cast is sound.
+    actions: keyed(
+      (event): Action =>
+        (payload) =>
+          renderTree.pipe(
+            Effect.flatMap(() => Effect.sync(() => triggerOf(name, index, event)(payload))),
+            Effect.flatMap(() => settle),
+          ),
+    ) as AnyFacade['actions'],
+    slots: keyed((slotName) => slotFacade(comp, slotName)) as AnyFacade['slots'],
+    frame: settle,
+  })
+
+  const slotFacade = (parent: CompositionClass<unknown>, slotName: string): AnySlotFacade => {
+    const slotClass = parent.manifest.slots?.[slotName]
+    const child = slotClass && bindings.get(slotClass)
+    if (child === undefined) {
+      throw new UnknownSlot({ parent: uiNameOf(parent), slot: slotName })
+    }
+    const childName = uiNameOf(child)
+    const at = (index: number): Effect.Effect<AnyFacade, never, CompositionService> =>
+      Effect.as(renderTree, nodeFacade(childName, index, child))
+    const first = nodeFacade(childName, 0, child)
+    return {
+      first: at(0),
+      at,
+      all: Effect.map(renderTree, () =>
+        capturesFor(childName).map((_capture, index) => nodeFacade(childName, index, child)),
+      ),
+      // Used directly, a slot behaves as its first instance.
+      props: first.props,
+      actions: first.actions,
+      slots: first.slots,
+      frame: first.frame,
+    }
+  }
+
+  return { facade: nodeFacade(uiNameOf(root), 0, root), settle }
+}
+
+/**
+ * Run one proof against a fresh runtime, returning its pass/fail result. Each
+ * proof gets its own isolated environment, so nothing leaks between proofs. Boots
+ * the scene as the host would, settles, then runs the proof body to completion.
+ */
+export const executeProof = async (proof: Proof): Promise<ProofResult> => {
+  const sink = makeSink()
+  const runtime = ManagedRuntime.make(proofLayer(proof.scene, sink))
+  try {
+    const { facade, settle } = makeFacade(runtime, proof.scene.composition, sink)
+    await runtime.runPromise(
+      Effect.forEach(proof.scene.boot ?? [], (event) => publish('High', event)).pipe(
+        Effect.flatMap(() => settle),
+      ),
+    )
+    await runtime.runPromise(Effect.gen(() => proof.body(facade)))
+    return { requirement: proof.requirement.manifest.statement, ok: true }
+  } catch (error) {
+    return {
+      requirement: proof.requirement.manifest.statement,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    }
+  } finally {
+    await runtime.dispose()
+  }
+}
+
+/**
+ * Drive one proof a step at a time, recording a `StepFrame` after each yielded
+ * effect settles. Reuses the same makeFacade runtime/facade/settle as
+ * `executeProof`, but instead of handing the body to `Effect.gen` (which runs it
+ * to completion), it pumps the generator by hand — `gen.next(value)` yields the
+ * next effect, we run it on the live runtime, snapshot the sink, and feed the
+ * result back. So the editor gets the per-step timeline with no change to the
+ * proof authoring API.
+ */
+export const driveProof = async (proof: Proof): Promise<DriveResult> => {
+  const sink = makeSink()
+  const runtime = ManagedRuntime.make(proofLayer(proof.scene, sink))
+  const frames: Array<StepFrame> = []
+  const statement = proof.requirement.manifest.statement
+  try {
+    const { facade, settle } = makeFacade(runtime, proof.scene.composition, sink)
+    await runtime.runPromise(
+      Effect.forEach(proof.scene.boot ?? [], (event) => publish('High', event)).pipe(
+        Effect.flatMap(() => settle),
+      ),
+    )
+    frames.push({ index: 0, captures: [...sink.captures] })
+    const generator = proof.body(facade)
+    // Pump the generator: run each yielded effect on the runtime, snapshot, recur.
+    const pump = async (input: unknown, index: number): Promise<void> => {
+      const step = generator.next(input)
+      if (step.done === true) return
+      const value = await runtime.runPromise(yieldWrapGet(step.value))
+      frames.push({ index, captures: [...sink.captures] })
+      await pump(value, index + 1)
+    }
+    await pump(undefined, 1)
+    return { requirement: statement, frames, ok: true }
+  } catch (error) {
+    return {
+      requirement: statement,
+      frames,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    }
+  } finally {
+    await runtime.dispose()
+  }
+}

package/src/errors.ts

@@ -0,0 +1,56 @@
+import { type Cause, Data } from 'effect'
+
+/**
+ * Tagged errors for the proof harness. A failed assertion or a malformed proof
+ * navigation throws one of these — tagged and structured, never a bare `Error` —
+ * so a runner can distinguish an assertion failure from a harness misuse.
+ */
+
+/**
+ * The constructor shape `Data.TaggedError(tag)<A>` produces, named so the
+ * generated `.d.ts` can describe the `extends` base under `isolatedDeclarations`
+ * (which forbids an inferred expression in an extends clause).
+ */
+type TaggedErrorClass<Tag extends string, A extends Record<string, unknown>> = new (
+  args: A,
+) => Cause.YieldableError & { readonly _tag: Tag } & Readonly<A>
+
+const AssertionFailedBase: TaggedErrorClass<
+  'reform-proof/AssertionFailed',
+  { readonly detail: string }
+> = Data.TaggedError('reform-proof/AssertionFailed')<{ readonly detail: string }>
+
+/** An `expect(...)` matcher did not hold. */
+export class AssertionFailed extends AssertionFailedBase {
+  override get message(): string {
+    return `reform-proof: assertion failed — ${this.detail}`
+  }
+}
+
+const UnknownActionBase: TaggedErrorClass<
+  'reform-proof/UnknownAction',
+  { readonly composition: string; readonly action: string; readonly rendered: number }
+> = Data.TaggedError('reform-proof/UnknownAction')<{
+  readonly composition: string
+  readonly action: string
+  readonly rendered: number
+}>
+
+/** A proof referenced an action the rendered composition never exposed. */
+export class UnknownAction extends UnknownActionBase {
+  override get message(): string {
+    return `reform-proof: '${this.composition}' has no action '${this.action}' (rendered ${this.rendered} instance(s))`
+  }
+}
+
+const UnknownSlotBase: TaggedErrorClass<
+  'reform-proof/UnknownSlot',
+  { readonly parent: string; readonly slot: string }
+> = Data.TaggedError('reform-proof/UnknownSlot')<{ readonly parent: string; readonly slot: string }>
+
+/** A proof navigated into a slot the parent composition does not declare. */
+export class UnknownSlot extends UnknownSlotBase {
+  override get message(): string {
+    return `reform-proof: '${this.parent}' has no slot '${this.slot}'`
+  }
+}