@playfast/reform-proof 1.0.1 → 1.2.0

package/src/errors.ts

@@ -1,16 +1,5 @@
 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>
@@ -20,7 +9,6 @@ const AssertionFailedBase: TaggedErrorClass<
   { 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}`
@@ -36,7 +24,6 @@ const UnknownActionBase: TaggedErrorClass<
   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))`
@@ -48,7 +35,6 @@ const UnknownSlotBase: TaggedErrorClass<
   { 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}'`

package/src/fingerprint.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { formatFingerprint } from './fingerprint'
+
+describe('proof render fingerprints', () => {
+  it('distinguishes bigint props from strings without throwing', () => {
+    expect(formatFingerprint({ sequence: 1n })).not.toBe(formatFingerprint({ sequence: '1' }))
+  })
+
+  it('stabilizes equivalent cyclic render props', () => {
+    const left: Array<unknown> = []
+    left.push(left)
+    const right: Array<unknown> = []
+    right.push(right)
+
+    expect(formatFingerprint(left)).toBe(formatFingerprint(right))
+  })
+
+  it('tracks Map and Set contents', () => {
+    expect(formatFingerprint(new Map([['feature', 'home']]))).not.toBe(
+      formatFingerprint(new Map([['feature', 'tasks']])),
+    )
+    expect(formatFingerprint(new Set(['home']))).not.toBe(formatFingerprint(new Set(['tasks'])))
+  })
+})

package/src/fingerprint.ts

@@ -0,0 +1,73 @@
+import * as Option from 'effect/Option'
+
+const readPropertyOption = Option.liftThrowable((target: object, key: PropertyKey): unknown =>
+  Reflect.get(target, key),
+)
+
+const readProperty = (target: object, key: PropertyKey): unknown =>
+  Option.getOrElse(readPropertyOption(target, key), () => '[Property read threw]')
+
+const propertyKeyFingerprint = (key: PropertyKey): string =>
+  typeof key === 'symbol'
+    ? `symbol:${String(key.description)}`
+    : typeof key === 'number'
+      ? `number-key:${String(key)}`
+      : `key:${key.length}:${key}`
+
+const valueFingerprint = (candidate: unknown, seen: WeakSet<object>): string => {
+  if (typeof candidate === 'bigint') {
+    return `bigint:${String(candidate)}`
+  }
+  if (typeof candidate === 'boolean') {
+    return candidate ? 'boolean:true' : 'boolean:false'
+  }
+  if (typeof candidate === 'function') {
+    return `function:${String(candidate)}`
+  }
+  if (typeof candidate === 'number') {
+    return `number:${String(candidate)}`
+  }
+  if (typeof candidate === 'string') {
+    return `string:${candidate.length}:${candidate}`
+  }
+  if (typeof candidate === 'symbol') {
+    return `symbol:${String(candidate.description)}`
+  }
+  if (typeof candidate === 'undefined') {
+    return 'undefined'
+  }
+  if (candidate === null) {
+    return 'null'
+  }
+  if (seen.has(candidate)) {
+    return '[Circular]'
+  }
+  seen.add(candidate)
+  if (Array.isArray(candidate)) {
+    return `[${candidate.map((arrayEntry) => valueFingerprint(arrayEntry, seen)).join(',')}]`
+  }
+  if (candidate instanceof Date) {
+    return `date:${String(candidate.getTime())}`
+  }
+  if (candidate instanceof Map) {
+    return `map:[${Array.from(
+      candidate,
+      ([mapKey, mapEntry]) =>
+        `${valueFingerprint(mapKey, seen)}=>${valueFingerprint(mapEntry, seen)}`,
+    ).join(',')}]`
+  }
+  if (candidate instanceof Set) {
+    return `set:[${Array.from(candidate, (setEntry) => valueFingerprint(setEntry, seen)).join(
+      ',',
+    )}]`
+  }
+  return `{${Reflect.ownKeys(candidate)
+    .map(
+      (key) =>
+        `${propertyKeyFingerprint(key)}:${valueFingerprint(readProperty(candidate, key), seen)}`,
+    )
+    .join(',')}}`
+}
+
+export const formatFingerprint = (fingerprintInput: unknown): string =>
+  valueFingerprint(fingerprintInput, new WeakSet())