@contractspec/lib.testing 3.7.5 → 3.7.7

package/README.md

@@ -1,51 +1,62 @@
 # @contractspec/lib.testing
 
-Website: https://contractspec.io/
+Website: https://contractspec.io
 
+**Contract-aware testing utilities and runners.**
 
-**Safe regeneration verification** — Capture production traffic and generate golden tests automatically.
+## What It Provides
 
-Golden-test utilities that record real requests/responses and generate runnable test suites. Prove that regenerated code behaves identically to the original.
+- **Layer**: lib.
+- **Consumers**: CLI, bundles.
+- `src/adapters/` contains runtime, provider, or environment-specific adapters.
+- Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`.
+- `src/adapters/` contains runtime, provider, or environment-specific adapters.
 
-- **TrafficRecorder** captures production requests/responses with sampling + sanitization.
-- **GoldenTestGenerator** converts snapshots into runnable suites.
-- **Adapters** output Vitest or Jest files and helper runners.
-
-### Usage
-
-```ts
-import {
-  TrafficRecorder,
-  InMemoryTrafficStore,
-} from '@contractspec/lib.testing/recorder';
-
-const recorder = new TrafficRecorder({
-  store: new InMemoryTrafficStore(),
-  sampleRate: 0.01,
-});
-
-await recorder.record({
-  operation: { name: 'orders.create', version: 3 },
-  input: payload,
-  output,
-  success: true,
-  timestamp: new Date(),
-});
-```
-
-See `GoldenTestGenerator` for generating suites and CLI in `@contractspec/app.contracts-cli`.
+## Installation
 
+`npm install @contractspec/lib.testing`
 
+or
 
+`bun add @contractspec/lib.testing`
 
+## Usage
 
+Import the root entrypoint from `@contractspec/lib.testing`, or choose a documented subpath when you only need one part of the package surface.
 
+## Architecture
 
+- `src/adapters/` contains runtime, provider, or environment-specific adapters.
+- `src/generator` is part of the package's public or composition surface.
+- `src/index.ts` is the root public barrel and package entrypoint.
+- `src/recorder` is part of the package's public or composition surface.
+- `src/types.ts` is shared public type definitions.
 
+## Public Entry Points
 
+- Export `.` resolves through `./src/index.ts`.
 
+## Local Commands
 
+- `bun run dev` — contractspec-bun-build dev
+- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
+- `bun run test` — bun test
+- `bun run lint` — bun lint:fix
+- `bun run lint:check` — biome check .
+- `bun run lint:fix` — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
+- `bun run typecheck` — tsc --noEmit
+- `bun run publish:pkg` — bun publish --tolerate-republish --ignore-scripts --verbose
+- `bun run publish:pkg:canary` — bun publish:pkg --tag canary
+- `bun run clean` — rimraf dist .turbo
+- `bun run build:bundle` — contractspec-bun-build transpile
+- `bun run build:types` — contractspec-bun-build types
+- `bun run prebuild` — contractspec-bun-build prebuild
 
+## Recent Updates
 
+- Replace eslint+prettier by biomejs to optimize speed.
 
+## Notes
 
+- TrafficRecorder and GoldenTestGenerator interfaces are public API — do not break signatures.
+- Test output format must stay compatible with Vitest and Jest runners.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export * from './types';
-export * from './recorder/traffic-recorder';
-export * from './generator/golden-test-generator';
-export * from './generator/assertion-builder';
-export * from './adapters/vitest-adapter';
 export * from './adapters/jest-adapter';
+export * from './adapters/vitest-adapter';
+export * from './generator/assertion-builder';
+export * from './generator/golden-test-generator';
+export * from './recorder/traffic-recorder';
+export * from './types';

package/dist/index.js

@@ -1,71 +1,4 @@
 // @bun
-// src/recorder/traffic-recorder.ts
-import { randomUUID } from "crypto";
-
-class InMemoryTrafficStore {
-  items = [];
-  async save(snapshot) {
-    this.items.push(snapshot);
-  }
-  async list(operation) {
-    if (!operation)
-      return [...this.items];
-    return this.items.filter((item) => item.operation.name === operation);
-  }
-}
-
-class TrafficRecorder {
-  store;
-  sampleRate;
-  sanitize;
-  constructor(options) {
-    this.store = options.store;
-    this.sampleRate = options.sampleRate ?? 1;
-    this.sanitize = options.sanitize;
-  }
-  async record(input) {
-    if (!this.shouldSample())
-      return;
-    const snapshot = {
-      id: randomUUID(),
-      operation: input.operation,
-      input: structuredCloneSafe(input.input),
-      output: structuredCloneSafe(input.output),
-      error: input.error ? structuredCloneSafe(input.error) : undefined,
-      success: input.success,
-      timestamp: new Date,
-      durationMs: input.durationMs,
-      tenantId: input.tenantId,
-      userId: input.userId,
-      channel: input.channel,
-      metadata: input.metadata
-    };
-    const sanitized = this.sanitize ? this.sanitize(snapshot) : snapshot;
-    await this.store.save(sanitized);
-  }
-  shouldSample() {
-    if (this.sampleRate >= 1)
-      return true;
-    return Math.random() <= this.sampleRate;
-  }
-}
-function structuredCloneSafe(value) {
-  if (value == null)
-    return value ?? undefined;
-  try {
-    const clone = globalThis.structuredClone;
-    if (typeof clone === "function") {
-      return clone(value);
-    }
-    return JSON.parse(JSON.stringify(value));
-  } catch {
-    return;
-  }
-}
-// src/generator/golden-test-generator.ts
-import { randomUUID as randomUUID2 } from "crypto";
-import { performance } from "perf_hooks";
-
 // src/generator/assertion-builder.ts
 function buildAssertions(testCase, ctx) {
   if (testCase.success) {
@@ -87,60 +20,60 @@ function serialize(value) {
   }, 2);
 }
 
-// src/adapters/vitest-adapter.ts
-function generateVitestSuite(options) {
+// src/adapters/jest-adapter.ts
+function generateJestSuite(options) {
   const caseBlocks = options.cases.map((testCase) => {
     const inputConst = serialize(testCase.input);
     const metadataConst = serialize(testCase.metadata ?? {});
-    const assertions = testCase.success ? [
-      `const result = await ${options.runnerFunction}(input${testCase.id}, metadata${testCase.id});`,
-      `expect(result).toEqual(${serialize(testCase.expectedOutput ?? null)});`
-    ] : [
-      `await expect(${options.runnerFunction}(input${testCase.id}, metadata${testCase.id})).rejects.toMatchObject(${serialize(testCase.expectedError ?? { message: "expected failure" })});`
-    ];
+    const successBlock = `const result = await ${options.runnerFunction}(input${testCase.id}, metadata${testCase.id});
+    expect(result).toEqual(${serialize(testCase.expectedOutput ?? null)});`;
+    const failureBlock = `await expect(${options.runnerFunction}(input${testCase.id}, metadata${testCase.id})).rejects.toMatchObject(${serialize(testCase.expectedError ?? { message: "expected failure" })});`;
     return `
-  it('${testCase.name}', async () => {
+  test('${testCase.name}', async () => {
     const input${testCase.id} = ${inputConst};
     const metadata${testCase.id} = ${metadataConst};
-    ${assertions.join(`
-    `)}
+    ${testCase.success ? successBlock : failureBlock}
   });`;
   }).join(`
 `);
   return `
-import { describe, it, expect } from 'bun:test';
 import { ${options.runnerFunction} } from '${options.runnerImport}';
 
 describe('${options.suiteName}', () => {${caseBlocks}
 });
 `.trim();
 }
-
-// src/adapters/jest-adapter.ts
-function generateJestSuite(options) {
+// src/adapters/vitest-adapter.ts
+function generateVitestSuite(options) {
   const caseBlocks = options.cases.map((testCase) => {
     const inputConst = serialize(testCase.input);
     const metadataConst = serialize(testCase.metadata ?? {});
-    const successBlock = `const result = await ${options.runnerFunction}(input${testCase.id}, metadata${testCase.id});
-    expect(result).toEqual(${serialize(testCase.expectedOutput ?? null)});`;
-    const failureBlock = `await expect(${options.runnerFunction}(input${testCase.id}, metadata${testCase.id})).rejects.toMatchObject(${serialize(testCase.expectedError ?? { message: "expected failure" })});`;
+    const assertions = testCase.success ? [
+      `const result = await ${options.runnerFunction}(input${testCase.id}, metadata${testCase.id});`,
+      `expect(result).toEqual(${serialize(testCase.expectedOutput ?? null)});`
+    ] : [
+      `await expect(${options.runnerFunction}(input${testCase.id}, metadata${testCase.id})).rejects.toMatchObject(${serialize(testCase.expectedError ?? { message: "expected failure" })});`
+    ];
     return `
-  test('${testCase.name}', async () => {
+  it('${testCase.name}', async () => {
     const input${testCase.id} = ${inputConst};
     const metadata${testCase.id} = ${metadataConst};
-    ${testCase.success ? successBlock : failureBlock}
+    ${assertions.join(`
+    `)}
   });`;
   }).join(`
 `);
   return `
+import { describe, it, expect } from 'bun:test';
 import { ${options.runnerFunction} } from '${options.runnerImport}';
 
 describe('${options.suiteName}', () => {${caseBlocks}
 });
 `.trim();
 }
-
 // src/generator/golden-test-generator.ts
+import { randomUUID } from "crypto";
+import { performance } from "perf_hooks";
 class GoldenTestGenerator {
   serializeMetadata;
   constructor(serializeMetadata = (snapshot) => ({
@@ -152,7 +85,7 @@ class GoldenTestGenerator {
   }
   createCases(snapshots) {
     return snapshots.map((snapshot, index) => ({
-      id: snapshot.id ?? randomUUID2(),
+      id: snapshot.id ?? randomUUID(),
       name: snapshot.success ? `case-${index + 1}-success` : `case-${index + 1}-failure`,
       input: snapshot.input,
       expectedOutput: snapshot.output,
@@ -212,6 +145,69 @@ async function runGoldenTests(cases, runner) {
   }
   return results;
 }
+// src/recorder/traffic-recorder.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+class InMemoryTrafficStore {
+  items = [];
+  async save(snapshot) {
+    this.items.push(snapshot);
+  }
+  async list(operation) {
+    if (!operation)
+      return [...this.items];
+    return this.items.filter((item) => item.operation.name === operation);
+  }
+}
+
+class TrafficRecorder {
+  store;
+  sampleRate;
+  sanitize;
+  constructor(options) {
+    this.store = options.store;
+    this.sampleRate = options.sampleRate ?? 1;
+    this.sanitize = options.sanitize;
+  }
+  async record(input) {
+    if (!this.shouldSample())
+      return;
+    const snapshot = {
+      id: randomUUID2(),
+      operation: input.operation,
+      input: structuredCloneSafe(input.input),
+      output: structuredCloneSafe(input.output),
+      error: input.error ? structuredCloneSafe(input.error) : undefined,
+      success: input.success,
+      timestamp: new Date,
+      durationMs: input.durationMs,
+      tenantId: input.tenantId,
+      userId: input.userId,
+      channel: input.channel,
+      metadata: input.metadata
+    };
+    const sanitized = this.sanitize ? this.sanitize(snapshot) : snapshot;
+    await this.store.save(sanitized);
+  }
+  shouldSample() {
+    if (this.sampleRate >= 1)
+      return true;
+    return Math.random() <= this.sampleRate;
+  }
+}
+function structuredCloneSafe(value) {
+  if (value == null)
+    return value ?? undefined;
+  try {
+    const clone = globalThis.structuredClone;
+    if (typeof clone === "function") {
+      return clone(value);
+    }
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return;
+  }
+}
 export {
   serialize,
   runGoldenTests,

package/dist/node/index.js

@@ -1,70 +1,3 @@
-// src/recorder/traffic-recorder.ts
-import { randomUUID } from "node:crypto";
-
-class InMemoryTrafficStore {
-  items = [];
-  async save(snapshot) {
-    this.items.push(snapshot);
-  }
-  async list(operation) {
-    if (!operation)
-      return [...this.items];
-    return this.items.filter((item) => item.operation.name === operation);
-  }
-}
-
-class TrafficRecorder {
-  store;
-  sampleRate;
-  sanitize;
-  constructor(options) {
-    this.store = options.store;
-    this.sampleRate = options.sampleRate ?? 1;
-    this.sanitize = options.sanitize;
-  }
-  async record(input) {
-    if (!this.shouldSample())
-      return;
-    const snapshot = {
-      id: randomUUID(),
-      operation: input.operation,
-      input: structuredCloneSafe(input.input),
-      output: structuredCloneSafe(input.output),
-      error: input.error ? structuredCloneSafe(input.error) : undefined,
-      success: input.success,
-      timestamp: new Date,
-      durationMs: input.durationMs,
-      tenantId: input.tenantId,
-      userId: input.userId,
-      channel: input.channel,
-      metadata: input.metadata
-    };
-    const sanitized = this.sanitize ? this.sanitize(snapshot) : snapshot;
-    await this.store.save(sanitized);
-  }
-  shouldSample() {
-    if (this.sampleRate >= 1)
-      return true;
-    return Math.random() <= this.sampleRate;
-  }
-}
-function structuredCloneSafe(value) {
-  if (value == null)
-    return value ?? undefined;
-  try {
-    const clone = globalThis.structuredClone;
-    if (typeof clone === "function") {
-      return clone(value);
-    }
-    return JSON.parse(JSON.stringify(value));
-  } catch {
-    return;
-  }
-}
-// src/generator/golden-test-generator.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
-import { performance } from "node:perf_hooks";
-
 // src/generator/assertion-builder.ts
 function buildAssertions(testCase, ctx) {
   if (testCase.success) {
@@ -86,60 +19,60 @@ function serialize(value) {
   }, 2);
 }
 
-// src/adapters/vitest-adapter.ts
-function generateVitestSuite(options) {
+// src/adapters/jest-adapter.ts
+function generateJestSuite(options) {
   const caseBlocks = options.cases.map((testCase) => {
     const inputConst = serialize(testCase.input);
     const metadataConst = serialize(testCase.metadata ?? {});
-    const assertions = testCase.success ? [
-      `const result = await ${options.runnerFunction}(input${testCase.id}, metadata${testCase.id});`,
-      `expect(result).toEqual(${serialize(testCase.expectedOutput ?? null)});`
-    ] : [
-      `await expect(${options.runnerFunction}(input${testCase.id}, metadata${testCase.id})).rejects.toMatchObject(${serialize(testCase.expectedError ?? { message: "expected failure" })});`
-    ];
+    const successBlock = `const result = await ${options.runnerFunction}(input${testCase.id}, metadata${testCase.id});
+    expect(result).toEqual(${serialize(testCase.expectedOutput ?? null)});`;
+    const failureBlock = `await expect(${options.runnerFunction}(input${testCase.id}, metadata${testCase.id})).rejects.toMatchObject(${serialize(testCase.expectedError ?? { message: "expected failure" })});`;
     return `
-  it('${testCase.name}', async () => {
+  test('${testCase.name}', async () => {
     const input${testCase.id} = ${inputConst};
     const metadata${testCase.id} = ${metadataConst};
-    ${assertions.join(`
-    `)}
+    ${testCase.success ? successBlock : failureBlock}
   });`;
   }).join(`
 `);
   return `
-import { describe, it, expect } from 'bun:test';
 import { ${options.runnerFunction} } from '${options.runnerImport}';
 
 describe('${options.suiteName}', () => {${caseBlocks}
 });
 `.trim();
 }
-
-// src/adapters/jest-adapter.ts
-function generateJestSuite(options) {
+// src/adapters/vitest-adapter.ts
+function generateVitestSuite(options) {
   const caseBlocks = options.cases.map((testCase) => {
     const inputConst = serialize(testCase.input);
     const metadataConst = serialize(testCase.metadata ?? {});
-    const successBlock = `const result = await ${options.runnerFunction}(input${testCase.id}, metadata${testCase.id});
-    expect(result).toEqual(${serialize(testCase.expectedOutput ?? null)});`;
-    const failureBlock = `await expect(${options.runnerFunction}(input${testCase.id}, metadata${testCase.id})).rejects.toMatchObject(${serialize(testCase.expectedError ?? { message: "expected failure" })});`;
+    const assertions = testCase.success ? [
+      `const result = await ${options.runnerFunction}(input${testCase.id}, metadata${testCase.id});`,
+      `expect(result).toEqual(${serialize(testCase.expectedOutput ?? null)});`
+    ] : [
+      `await expect(${options.runnerFunction}(input${testCase.id}, metadata${testCase.id})).rejects.toMatchObject(${serialize(testCase.expectedError ?? { message: "expected failure" })});`
+    ];
     return `
-  test('${testCase.name}', async () => {
+  it('${testCase.name}', async () => {
     const input${testCase.id} = ${inputConst};
     const metadata${testCase.id} = ${metadataConst};
-    ${testCase.success ? successBlock : failureBlock}
+    ${assertions.join(`
+    `)}
   });`;
   }).join(`
 `);
   return `
+import { describe, it, expect } from 'bun:test';
 import { ${options.runnerFunction} } from '${options.runnerImport}';
 
 describe('${options.suiteName}', () => {${caseBlocks}
 });
 `.trim();
 }
-
 // src/generator/golden-test-generator.ts
+import { randomUUID } from "node:crypto";
+import { performance } from "node:perf_hooks";
 class GoldenTestGenerator {
   serializeMetadata;
   constructor(serializeMetadata = (snapshot) => ({
@@ -151,7 +84,7 @@ class GoldenTestGenerator {
   }
   createCases(snapshots) {
     return snapshots.map((snapshot, index) => ({
-      id: snapshot.id ?? randomUUID2(),
+      id: snapshot.id ?? randomUUID(),
       name: snapshot.success ? `case-${index + 1}-success` : `case-${index + 1}-failure`,
       input: snapshot.input,
       expectedOutput: snapshot.output,
@@ -211,6 +144,69 @@ async function runGoldenTests(cases, runner) {
   }
   return results;
 }
+// src/recorder/traffic-recorder.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+
+class InMemoryTrafficStore {
+  items = [];
+  async save(snapshot) {
+    this.items.push(snapshot);
+  }
+  async list(operation) {
+    if (!operation)
+      return [...this.items];
+    return this.items.filter((item) => item.operation.name === operation);
+  }
+}
+
+class TrafficRecorder {
+  store;
+  sampleRate;
+  sanitize;
+  constructor(options) {
+    this.store = options.store;
+    this.sampleRate = options.sampleRate ?? 1;
+    this.sanitize = options.sanitize;
+  }
+  async record(input) {
+    if (!this.shouldSample())
+      return;
+    const snapshot = {
+      id: randomUUID2(),
+      operation: input.operation,
+      input: structuredCloneSafe(input.input),
+      output: structuredCloneSafe(input.output),
+      error: input.error ? structuredCloneSafe(input.error) : undefined,
+      success: input.success,
+      timestamp: new Date,
+      durationMs: input.durationMs,
+      tenantId: input.tenantId,
+      userId: input.userId,
+      channel: input.channel,
+      metadata: input.metadata
+    };
+    const sanitized = this.sanitize ? this.sanitize(snapshot) : snapshot;
+    await this.store.save(sanitized);
+  }
+  shouldSample() {
+    if (this.sampleRate >= 1)
+      return true;
+    return Math.random() <= this.sampleRate;
+  }
+}
+function structuredCloneSafe(value) {
+  if (value == null)
+    return value ?? undefined;
+  try {
+    const clone = globalThis.structuredClone;
+    if (typeof clone === "function") {
+      return clone(value);
+    }
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return;
+  }
+}
 export {
   serialize,
   runGoldenTests,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.testing",
-  "version": "3.7.5",
+  "version": "3.7.7",
   "description": "Contract-aware testing utilities and runners",
   "keywords": [
     "contractspec",
@@ -23,20 +23,20 @@
     "dev": "contractspec-bun-build dev",
     "clean": "rimraf dist .turbo",
     "lint": "bun lint:fix",
-    "lint:fix": "eslint src --fix",
-    "lint:check": "eslint src",
+    "lint:fix": "biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .",
+    "lint:check": "biome check .",
     "test": "bun test",
     "prebuild": "contractspec-bun-build prebuild",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.schema": "3.7.5",
-    "@contractspec/lib.contracts-spec": "3.7.5"
+    "@contractspec/lib.schema": "3.7.6",
+    "@contractspec/lib.contracts-spec": "4.0.0"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.5",
+    "@contractspec/tool.typescript": "3.7.6",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.7.5"
+    "@contractspec/tool.bun": "3.7.6"
   },
   "exports": {
     ".": {