ushman-characterize 0.4.0

package/dist/time.d.ts

@@ -0,0 +1,3 @@
+export declare const nowIso: () => string;
+export declare const sleep: (ms: number) => Promise<unknown>;
+//# sourceMappingURL=time.d.ts.map

package/dist/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,MAAM,cAAyD,CAAC;AAE7E,eAAO,MAAM,KAAK,GAAI,IAAI,MAAM,qBAQ/B,CAAC"}

package/dist/time.js

@@ -0,0 +1,10 @@
+export const nowIso = () => new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+export const sleep = (ms) => {
+    if (!Number.isFinite(ms)) {
+        throw new TypeError(`sleep(ms) requires a finite number; received ${String(ms)}`);
+    }
+    if (ms < 0) {
+        throw new RangeError(`sleep(ms) requires a non-negative number; received ${ms}`);
+    }
+    return new Promise((resolve) => setTimeout(resolve, ms));
+};

package/dist/trace-format.d.ts

@@ -0,0 +1,24 @@
+import { type CanonicalizeTraceOptions, canonicalizeSceneTree, canonicalizeThrownValue, canonicalizeTraceValue, compareTraceValues, EXEMPT_FIELD_MARKER, hydrateTraceValue, type SceneCanonicalizeOptions } from './trace-serializer.ts';
+export declare const workspaceHarnessPaths: (workspaceRoot: string) => {
+    characterizeDir: string;
+    harnessFile: string;
+    modulesDir: string;
+    pureFixturesDir: string;
+    replayFixturesDir: string;
+    reportsDir: string;
+    sceneFixturesDir: string;
+    tracesDir: string;
+};
+export declare const ensureWorkspaceTraceHarness: (workspaceRoot: string) => Promise<{
+    characterizeDir: string;
+    harnessFile: string;
+    modulesDir: string;
+    pureFixturesDir: string;
+    replayFixturesDir: string;
+    reportsDir: string;
+    sceneFixturesDir: string;
+    tracesDir: string;
+}>;
+export type { CanonicalizeTraceOptions, SceneCanonicalizeOptions };
+export { canonicalizeSceneTree, canonicalizeThrownValue, canonicalizeTraceValue, compareTraceValues, EXEMPT_FIELD_MARKER, hydrateTraceValue, };
+//# sourceMappingURL=trace-format.d.ts.map

package/dist/trace-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-format.d.ts","sourceRoot":"","sources":["../src/trace-format.ts"],"names":[],"mappings":"AAQA,OAAO,EAEH,KAAK,wBAAwB,EAC7B,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,wBAAwB,EAChC,MAAM,uBAAuB,CAAC;AAkM/B,eAAO,MAAM,qBAAqB,GAAI,eAAe,MAAM;;;;;;;;;CASzD,CAAC;AAEH,eAAO,MAAM,2BAA2B,GAAU,eAAe,MAAM;;;;;;;;;EAKtE,CAAC;AAEF,YAAY,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,CAAC;AACnE,OAAO,EACH,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,GACpB,CAAC"}

package/dist/trace-format.js

@@ -0,0 +1,213 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { CHARACTERIZE_SUPPORT_VERSION, REPLAY_FIXTURE_SCHEMA_NAME, REPLAY_FIXTURE_SCHEMA_VERSION, } from "./constants.js";
+import { sanitizeSymbolName } from "./shared.js";
+import { buildTraceRuntimeSupportSource, canonicalizeSceneTree, canonicalizeThrownValue, canonicalizeTraceValue, compareTraceValues, EXEMPT_FIELD_MARKER, hydrateTraceValue, } from "./trace-serializer.js";
+const renderWorkspaceHarnessSource = () => `import { expect } from 'bun:test';
+
+${buildTraceRuntimeSupportSource()}
+
+const sanitizeFixtureName = ${sanitizeSymbolName.toString()};
+const replayFixtureSchemaName = ${JSON.stringify(REPLAY_FIXTURE_SCHEMA_NAME)};
+const replayFixtureSchemaVersion = ${JSON.stringify(REPLAY_FIXTURE_SCHEMA_VERSION)};
+const characterizeSupportVersion = ${JSON.stringify(CHARACTERIZE_SUPPORT_VERSION)};
+const defaultFloatMatchDigits = 4;
+
+const fixtureFile = (kind, name) => new URL(\`./\${kind}/\${sanitizeFixtureName(name)}.json\`, import.meta.url);
+
+const describeObservedFixtureVersion = (value) => {
+  if (!value || typeof value !== 'object') {
+    return 'an invalid non-object payload';
+  }
+  const schemaName = typeof value.schemaName === 'string' ? value.schemaName : 'unknown-schema';
+  const schemaVersion = typeof value.schemaVersion === 'string' ? value.schemaVersion : 'unknown-version';
+  const supportVersion = typeof value.supportVersion === 'string' ? value.supportVersion : 'unknown-support';
+  return \`\${schemaName}@\${schemaVersion} support=\${supportVersion}\`;
+};
+
+const parseReplayFixture = (name, value) => {
+  if (!value || typeof value !== 'object') {
+    throw new Error(\`Replay fixture "\${name}" must be an object. Re-run ushman-characterize generate-replay for this workspace.\`);
+  }
+  if (
+    value.schemaName !== replayFixtureSchemaName ||
+    value.schemaVersion !== replayFixtureSchemaVersion ||
+    value.supportVersion !== characterizeSupportVersion
+  ) {
+    throw new Error(
+      \`Replay fixture "\${name}" is incompatible. Expected \${replayFixtureSchemaName}@\${replayFixtureSchemaVersion} support=\${characterizeSupportVersion}, found \${describeObservedFixtureVersion(value)}. Re-run ushman-characterize generate-replay for this workspace.\`,
+    );
+  }
+  if (!Array.isArray(value.cases)) {
+    throw new Error(\`Replay fixture "\${name}" is missing its cases array. Re-run ushman-characterize generate-replay for this workspace.\`);
+  }
+  for (const [index, entry] of value.cases.entries()) {
+    if (!entry || typeof entry !== 'object' || typeof entry.i !== 'number' || typeof entry.state !== 'string') {
+      throw new Error(\`Replay fixture "\${name}" has an invalid case at index \${index}. Re-run ushman-characterize generate-replay for this workspace.\`);
+    }
+  }
+  return value.cases;
+};
+
+export const fixture = async (kind, name) => {
+  const value = JSON.parse(await Bun.file(fixtureFile(kind, name)).text());
+  return kind === 'replay' ? parseReplayFixture(name, value) : value;
+};
+
+const hydrateArgs = (value) => {
+  const raw = hydrateTraceValue(value);
+  if (!Array.isArray(raw)) {
+    throw new Error('Expected replay args to hydrate to an array.');
+  }
+  return raw;
+};
+
+export const invokeManagedTraceCase = async (callable, entry) => {
+  const hydratedArgs = hydrateArgs(entry?.args);
+  const hydratedThisArg = hydrateTraceValue(entry?.thisArg);
+  try {
+    return {
+      threw: null,
+      value: await callable.apply(hydratedThisArg, hydratedArgs),
+    };
+  } catch (error) {
+    return {
+      threw: error,
+      value: undefined,
+    };
+  }
+};
+
+export const assertObservedTraceValue = (actual, expected, options = {}) => {
+  const digits = typeof options.floatDigits === 'number' ? options.floatDigits : defaultFloatMatchDigits;
+  if (typeof actual === 'number' && typeof expected === 'number' && Number.isFinite(actual) && Number.isFinite(expected)) {
+    expect(actual).toBeCloseTo(expected, digits);
+    return;
+  }
+  expect(canonicalizeTraceValue(actual)).toEqual(expected);
+};
+
+const installSideEffectRecorder = () => {
+  const sideEffects = [];
+  const restore = [];
+  const recordSideEffect = (effect) => {
+    sideEffects.push(canonicalizeTraceValue(effect));
+  };
+
+  if (globalThis.fetch) {
+    const originalFetch = globalThis.fetch.bind(globalThis);
+    const wrappedFetch = (...args) => {
+      recordSideEffect({ type: 'fetch', url: String(args[0]), method: args[1]?.method ?? 'GET' });
+      return originalFetch(...args);
+    };
+    globalThis.fetch = wrappedFetch;
+    restore.push(() => {
+      globalThis.fetch = originalFetch;
+    });
+  }
+
+  if (globalThis.localStorage) {
+    const storage = globalThis.localStorage;
+    const setItem = storage.setItem.bind(storage);
+    const removeItem = storage.removeItem.bind(storage);
+    storage.setItem = (key, value) => {
+      recordSideEffect({ type: 'localStorage.setItem', key, value });
+      return setItem(key, value);
+    };
+    storage.removeItem = (key) => {
+      recordSideEffect({ type: 'localStorage.removeItem', key });
+      return removeItem(key);
+    };
+    restore.push(() => {
+      storage.setItem = setItem;
+      storage.removeItem = removeItem;
+    });
+  }
+
+  return () => {
+    for (const undo of restore.reverse()) {
+      undo();
+    }
+    return sideEffects;
+  };
+};
+
+export const replay = {
+  async callMethod(instance, methodName, input) {
+    const args = hydrateArgs(input?.args);
+    const receiver = instance ?? {};
+    return await receiver[methodName](...args);
+  },
+  async capture(run) {
+    const uninstall = installSideEffectRecorder();
+    try {
+      const value = await run();
+      return {
+        sideEffects: uninstall(),
+        threw: null,
+        value,
+      };
+    } catch (error) {
+      return {
+        sideEffects: uninstall(),
+        threw: error,
+        value: undefined,
+      };
+    }
+  },
+  hydrate(ClassCtor, snapshot) {
+    const raw = hydrateTraceValue(snapshot);
+    if (!ClassCtor || !ClassCtor.prototype || !raw || typeof raw !== 'object') {
+      return raw;
+    }
+    return Object.assign(Object.create(ClassCtor.prototype), raw);
+  },
+  async invoke(fn, input) {
+    const args = hydrateArgs(input?.args);
+    const thisArg = hydrateTraceValue(input?.thisArg);
+    return await fn.apply(thisArg, args);
+  },
+};
+
+let matchersRegistered = false;
+export const registerTraceMatchers = () => {
+  if (matchersRegistered) return;
+  matchersRegistered = true;
+  expect.extend({
+    toMatchTrace(received, expected) {
+      const actual = canonicalizeTraceValue(received);
+      const mode = process.env.USHMAN_CHARACTERIZE_MATCH_MODE ?? 'strict';
+      const pass = compareTraceValues(expected, actual, mode);
+      return {
+        pass,
+        message: () => \`Expected trace \${pass ? 'not ' : ''}to match in \${mode} mode.\\nexpected=\${JSON.stringify(expected, null, 2)}\\nactual=\${JSON.stringify(actual, null, 2)}\`,
+      };
+    },
+  });
+};
+
+export {
+  EXEMPT_FIELD_MARKER,
+  canonicalizeSceneTree,
+  canonicalizeThrownValue,
+  canonicalizeTraceValue,
+  hydrateTraceValue,
+};
+`;
+export const workspaceHarnessPaths = (workspaceRoot) => ({
+    characterizeDir: path.join(workspaceRoot, '.lab', 'characterize'),
+    harnessFile: path.join(workspaceRoot, '.lab', 'characterize', 'index.ts'),
+    modulesDir: path.join(workspaceRoot, '.lab', 'characterize', 'modules'),
+    pureFixturesDir: path.join(workspaceRoot, '.lab', 'characterize', 'pure'),
+    replayFixturesDir: path.join(workspaceRoot, '.lab', 'characterize', 'replay'),
+    reportsDir: path.join(workspaceRoot, '.lab', 'characterize', 'reports'),
+    sceneFixturesDir: path.join(workspaceRoot, '.lab', 'characterize', 'scene'),
+    tracesDir: path.join(workspaceRoot, '.lab', 'characterize', 'traces'),
+});
+export const ensureWorkspaceTraceHarness = async (workspaceRoot) => {
+    const paths = workspaceHarnessPaths(workspaceRoot);
+    await mkdir(paths.characterizeDir, { recursive: true });
+    await Bun.write(paths.harnessFile, `${renderWorkspaceHarnessSource().trimEnd()}\n`);
+    return paths;
+};
+export { canonicalizeSceneTree, canonicalizeThrownValue, canonicalizeTraceValue, compareTraceValues, EXEMPT_FIELD_MARKER, hydrateTraceValue, };

package/dist/trace-serializer.d.ts

@@ -0,0 +1,94 @@
+import { EXEMPT_FIELD_MARKER } from './constants.ts';
+export type CanonicalizeTraceOptions = {
+    readonly depthLimit?: number;
+};
+export type SceneCanonicalizeOptions = {
+    readonly exemptFields?: readonly string[];
+};
+export type TraceMatchMode = 'lenient' | 'strict';
+export declare const roundTraceNumber: (value: number) => number;
+export declare const canonicalizeNumericValue: (value: number) => number | {
+    __t: string;
+    value: string;
+};
+export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+export declare const buildStableHash: (value: string) => string;
+export declare const canonicalizeThreeLikeValue: (value: Record<string, unknown>) => {
+    x: number | {
+        __t: string;
+        value: string;
+    };
+    y: number | {
+        __t: string;
+        value: string;
+    };
+    w?: number | {
+        __t: string;
+        value: string;
+    } | undefined;
+    z?: number | {
+        __t: string;
+        value: string;
+    } | undefined;
+    __t: string;
+} | {
+    __t: string;
+    order: string | null;
+    x: number | {
+        __t: string;
+        value: string;
+    };
+    y: number | {
+        __t: string;
+        value: string;
+    };
+    z: number | {
+        __t: string;
+        value: string;
+    };
+} | {
+    __t: string;
+    elements: any[];
+} | {
+    __t: string;
+    hex: string;
+} | {
+    __t: string;
+    children: number;
+    name: string;
+    path: string;
+    type: string;
+} | {
+    __t: string;
+    attributeKeys: string[];
+    hash: string;
+    hasIndex: boolean;
+    type: string;
+} | {
+    __t: string;
+    color: string | null;
+    opacity: number | {
+        __t: string;
+        value: string;
+    } | null;
+    transparent: boolean | null;
+    type: string;
+} | {
+    __t: string;
+    image: {
+        height: number | null;
+        src: string | null;
+        width: number | null;
+    } | null;
+    name: string;
+} | null;
+export declare const canonicalizeTraceValue: (value: unknown, options?: CanonicalizeTraceOptions) => unknown;
+export declare const canonicalizeThrownValue: (value: unknown) => unknown;
+export declare const hydrateTraceValue: (value: unknown, state?: {
+    refs: Map<number, object>;
+}) => unknown;
+export declare const compareTraceValues: (expected: unknown, actual: unknown, mode?: TraceMatchMode) => boolean;
+export declare const canonicalizeSceneTree: (value: unknown, options?: SceneCanonicalizeOptions) => unknown;
+export declare const buildTraceRuntimeSupportSource: () => string;
+export { EXEMPT_FIELD_MARKER };
+//# sourceMappingURL=trace-serializer.d.ts.map

package/dist/trace-serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-serializer.d.ts","sourceRoot":"","sources":["../src/trace-serializer.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,mBAAmB,EAAyB,MAAM,gBAAgB,CAAC;AAEvG,MAAM,MAAM,wBAAwB,GAAG;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAqBlD,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,WAAsE,CAAC;AAErH,eAAO,MAAM,wBAAwB,GAAI,OAAO,MAAM;;;CAcrD,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAM7E,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,WAO5C,CAAC;AA8OF,eAAO,MAAM,0BAA0B,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAQxE,CAAC;AA6KF,eAAO,MAAM,sBAAsB,GAAI,OAAO,OAAO,EAAE,UAAS,wBAA6B,KAAG,OAK1F,CAAC;AAEP,eAAO,MAAM,uBAAuB,GAAI,OAAO,OAAO,YAAkC,CAAC;AA8GzF,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,EAAE;;CAA8B,KAAG,OAiClF,CAAC;AAwBF,eAAO,MAAM,kBAAkB,GAAI,UAAU,OAAO,EAAE,QAAQ,OAAO,EAAE,OAAM,cAAyB,KAAG,OAexG,CAAC;AA6BF,eAAO,MAAM,qBAAqB,GAAI,OAAO,OAAO,EAAE,UAAS,wBAA6B,KAAG,OAC5B,CAAC;AA+CpE,eAAO,MAAM,8BAA8B,cA0BzB,CAAC;AAEnB,OAAO,EAAE,mBAAmB,EAAE,CAAC"}