@ontrails/testing 1.0.0-beta.14 → 1.0.0-beta.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/testing",
-  "version": "1.0.0-beta.14",
+  "version": "1.0.0-beta.15",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,13 +14,14 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "devDependencies": {
-    "@ontrails/store": "^1.0.0-beta.13"
+    "@ontrails/drizzle": "^1.0.0-beta.14",
+    "@ontrails/store": "^1.0.0-beta.14"
   },
   "peerDependencies": {
-    "@ontrails/cli": "^1.0.0-beta.13",
-    "@ontrails/core": "^1.0.0-beta.13",
-    "@ontrails/logging": "^1.0.0-beta.13",
-    "@ontrails/mcp": "^1.0.0-beta.13",
+    "@ontrails/cli": "^1.0.0-beta.14",
+    "@ontrails/core": "^1.0.0-beta.14",
+    "@ontrails/logging": "^1.0.0-beta.14",
+    "@ontrails/mcp": "^1.0.0-beta.14",
     "zod": "^4.3.5"
   }
 }

package/src/__tests__/all.test.ts

@@ -1,11 +1,25 @@
-import { describe } from 'bun:test';
+import { afterAll, describe, expect, mock, test } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 
-import { Result, trail, topo } from '@ontrails/core';
+import { contour, Result, trail, topo } from '@ontrails/core';
+import { connectDrizzle } from '@ontrails/drizzle';
 import { z } from 'zod';
 
 import { testAll } from '../all.js';
 import { store as defineStore } from '@ontrails/store';
-import { connectDrizzle } from '@ontrails/store/drizzle';
+
+const requireContourExample = (
+  contourDef: { examples?: readonly Record<string, unknown>[] },
+  index: number
+) => {
+  const example = contourDef.examples?.[index];
+  expect(example).toBeDefined();
+  if (!example) {
+    throw new Error(`Expected contour example at index ${index}`);
+  }
+  return example;
+};
 
 const dbDefinition = defineStore({
   entities: {
@@ -26,7 +40,7 @@ const dbDefinition = defineStore({
   },
 });
 
-const createDbProvision = (
+const createDbResource = (
   seed?: readonly {
     readonly id: string;
     readonly name: string;
@@ -40,7 +54,7 @@ const createDbProvision = (
   });
 
 const createOverrideStore = () => {
-  const { mock } = createDbProvision([
+  const { mock: mockFactory } = createDbResource([
     {
       id: 'seed-1',
       name: 'Override',
@@ -48,11 +62,11 @@ const createOverrideStore = () => {
     },
   ]);
 
-  if (mock === undefined) {
+  if (mockFactory === undefined) {
     throw new Error('Expected drizzle test store to expose a mock factory');
   }
 
-  const created = mock();
+  const created = mockFactory();
   if (created instanceof Promise) {
     throw new TypeError(
       'Expected drizzle test store mock to resolve synchronously'
@@ -62,11 +76,11 @@ const createOverrideStore = () => {
   return created;
 };
 
-const mockDbProvision = createDbProvision();
+const mockDbResource = createDbResource();
 
-const mockedTrail = trail('provision.mocked.all', {
+const mockedTrail = trail('resource.mocked.all', {
   blaze: async (_input, ctx) => {
-    const entity = await mockDbProvision.from(ctx).entities.get('seed-1');
+    const entity = await mockDbResource.from(ctx).entities.get('seed-1');
     if (entity === null) {
       return Result.err(new Error('expected seeded entity to exist'));
     }
@@ -74,22 +88,22 @@ const mockedTrail = trail('provision.mocked.all', {
     return Result.ok({ name: entity.name, source: entity.source });
   },
   description:
-    'Trail that uses a mocked connector-bound provision through testAll',
+    'Trail that uses a mocked connector-bound resource through testAll',
   examples: [
     {
       expected: { name: 'Alpha', source: 'mock' },
       input: {},
-      name: 'Uses auto-resolved provision mock',
+      name: 'Uses auto-resolved resource mock',
     },
   ],
   input: z.object({}),
   output: z.object({ name: z.string(), source: z.string() }),
-  provisions: [mockDbProvision],
+  resources: [mockDbResource],
 });
 
-const overrideTrail = trail('provision.override.all', {
+const overrideTrail = trail('resource.override.all', {
   blaze: async (_input, ctx) => {
-    const entity = await mockDbProvision.from(ctx).entities.get('seed-1');
+    const entity = await mockDbResource.from(ctx).entities.get('seed-1');
     if (entity === null) {
       return Result.err(new Error('expected overridden entity to exist'));
     }
@@ -101,35 +115,140 @@ const overrideTrail = trail('provision.override.all', {
     {
       expected: { name: 'Override', source: 'override' },
       input: {},
-      name: 'Explicit provision override wins',
+      name: 'Explicit resource override wins',
     },
   ],
   input: z.object({}),
   output: z.object({ name: z.string(), source: z.string() }),
-  provisions: [mockDbProvision],
+  resources: [mockDbResource],
 });
 
-describe('testAll provision mocks', () => {
+const contourFixture = contour(
+  'allFixture',
+  {
+    id: z.string().uuid(),
+    name: z.string(),
+  },
+  {
+    examples: [
+      {
+        id: 'f46b837e-6c8d-42ec-8539-536f4e6daf0e',
+        name: 'Contour-derived governance fixture',
+      },
+    ],
+    identity: 'id',
+  }
+);
+
+const contourDerivedBlaze = mock(() =>
+  Result.ok(requireContourExample(contourFixture, 0))
+);
+
+const contourDerivedTrail = trail('contour.derived.all', {
+  blaze: () => contourDerivedBlaze(),
+  contours: [contourFixture],
+  description: 'Trail that relies on contour-derived fixtures inside testAll',
+  input: z.object({ id: contourFixture.shape.id }),
+  output: contourFixture,
+});
+
+const repoTempDir = (): string =>
+  join(
+    resolve(import.meta.dir, '../..'),
+    '.tmp-tests',
+    `test-all-established-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+
+const runGeneratedGovernanceSuite = (
+  helperName: 'testAll' | 'testAllEstablished'
+): { readonly exitCode: number; readonly output: string } => {
+  const dir = repoTempDir();
+  const testFile = join(dir, `${helperName}.test.ts`);
+
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    testFile,
+    `import { Result, trail, topo } from '@ontrails/core';
+import { ${helperName} } from '../../src/index.ts';
+import { z } from 'zod';
+
+const draftTrail = trail('_draft.entity.prepare', {
+  blaze: async () => Result.ok({ ok: true }),
+  input: z.object({}),
+  output: z.object({ ok: z.boolean() }),
+});
+
+${helperName}(topo('draft-topo', { draftTrail }));
+`
+  );
+
+  try {
+    const proc = Bun.spawnSync({
+      cmd: ['bun', 'test', testFile, '--bail'],
+      cwd: resolve(import.meta.dir, '..', '..', '..'),
+      stderr: 'pipe',
+      stdout: 'pipe',
+    });
+
+    return {
+      exitCode: proc.exitCode,
+      output: `${proc.stdout.toString()}\n${proc.stderr.toString()}`,
+    };
+  } finally {
+    rmSync(dir, { force: true, recursive: true });
+  }
+};
+
+describe('testAll resource mocks', () => {
   // eslint-disable-next-line jest/require-hook
   testAll(
-    topo('test-all-provision-mock-app', {
-      mockDbProvision,
+    topo('test-all-resource-mock-app', {
+      mockDbResource,
       mockedTrail,
     } as Record<string, unknown>)
   );
 });
 
-describe('testAll explicit provision overrides', () => {
+describe('testAll explicit resource overrides', () => {
   // eslint-disable-next-line jest/require-hook
   testAll(
-    topo('test-all-provision-override-app', {
-      mockDbProvision,
+    topo('test-all-resource-override-app', {
+      mockDbResource,
       overrideTrail,
     } as Record<string, unknown>),
     () => ({
-      provisions: {
+      resources: {
         'db.mock.all': createOverrideStore(),
       },
     })
   );
 });
+
+describe('testAll contour-derived fixtures', () => {
+  // eslint-disable-next-line jest/require-hook
+  testAll(
+    topo('test-all-contour-derived-app', {
+      contourDerivedTrail,
+      contourFixture,
+    } as Record<string, unknown>)
+  );
+
+  afterAll(() => {
+    expect(contourDerivedBlaze).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('testAllEstablished draft hygiene', () => {
+  test('keeps testAll draft-friendly for in-progress graphs', () => {
+    const result = runGeneratedGovernanceSuite('testAll');
+
+    expect(result.exitCode).toBe(0);
+  });
+
+  test('fails draft-contaminated graphs under testAllEstablished', () => {
+    const result = runGeneratedGovernanceSuite('testAllEstablished');
+
+    expect(result.exitCode).toBe(1);
+    expect(result.output).toContain('_draft.entity.prepare');
+  });
+});

package/src/__tests__/context.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, test } from 'bun:test';
 
-import { Result, provision, topo } from '@ontrails/core';
+import { Result, resource, topo } from '@ontrails/core';
 
 import {
   createCrossContext,
   createTestContext,
   mergeTestContext,
-  resolveMockProvisions,
+  createMockResources,
 } from '../context.js';
 import type { TestLogger } from '../types.js';
 
@@ -22,6 +22,7 @@ describe('createTestContext', () => {
     expect(ctx.abortSignal).toBeDefined();
     expect(ctx.abortSignal.aborted).toBe(false);
     expect(ctx.logger).toBeDefined();
+    expect(ctx.trace).toBeDefined();
     expect(ctx.workspaceRoot).toBe(process.cwd());
   });
 
@@ -66,6 +67,25 @@ describe('createTestContext', () => {
     const env = ctx['env'] as Record<string, string>;
     expect(env).toEqual({ CUSTOM: '1', NODE_ENV: 'test' });
   });
+
+  test('default trace passthrough resolves the callback result', async () => {
+    const ctx = createTestContext();
+    const result = await ctx.trace('test-span', () => Promise.resolve('ok'));
+    expect(result).toBe('ok');
+  });
+
+  test('overrides trace', async () => {
+    const calls: string[] = [];
+    const ctx = createTestContext({
+      trace: async (label, fn) => {
+        calls.push(label);
+        return await fn();
+      },
+    });
+
+    await ctx.trace('custom-span', () => Promise.resolve('done'));
+    expect(calls).toEqual(['custom-span']);
+  });
 });
 
 describe('createCrossContext', () => {
@@ -102,7 +122,7 @@ describe('createCrossContext', () => {
 });
 
 describe('mergeTestContext', () => {
-  test('merges provision overrides into extensions and the provision accessor', () => {
+  test('merges resource overrides into extensions and the resource accessor', () => {
     const ctx = mergeTestContext(
       {
         extensions: { existing: true },
@@ -114,14 +134,14 @@ describe('mergeTestContext', () => {
       'db.main': { source: 'mock' },
       existing: true,
     });
-    expect(ctx.provision<{ source: string }>('db.main').source).toBe('mock');
+    expect(ctx.resource<{ source: string }>('db.main').source).toBe('mock');
   });
 });
 
-describe('resolveMockProvisions', () => {
-  test('creates fresh mock provisions for each invocation', async () => {
+describe('createMockResources', () => {
+  test('creates fresh mock resources for each invocation', async () => {
     let mockCalls = 0;
-    const mockable = provision(`provision.mock.${Bun.randomUUIDv7()}`, {
+    const mockable = resource(`resource.mock.${Bun.randomUUIDv7()}`, {
       create: () => Result.ok({ source: 'factory' }),
       mock: () => {
         mockCalls += 1;
@@ -130,8 +150,8 @@ describe('resolveMockProvisions', () => {
     });
     const app = topo('mock-app', { mockable } as Record<string, unknown>);
 
-    const first = await resolveMockProvisions(app);
-    const second = await resolveMockProvisions(app);
+    const first = await createMockResources(app);
+    const second = await createMockResources(app);
 
     expect(first).toEqual({ [mockable.id]: { source: 'mock' } });
     expect(second).toEqual(first);
@@ -139,12 +159,12 @@ describe('resolveMockProvisions', () => {
     expect(mockCalls).toBe(2);
   });
 
-  test('skips provisions without mock factories', async () => {
-    const plain = provision(`provision.plain.${Bun.randomUUIDv7()}`, {
+  test('skips resources without mock factories', async () => {
+    const plain = resource(`resource.plain.${Bun.randomUUIDv7()}`, {
       create: () => Result.ok({ source: 'factory' }),
     });
     const app = topo('plain-app', { plain } as Record<string, unknown>);
 
-    expect(await resolveMockProvisions(app)).toEqual({});
+    expect(await createMockResources(app)).toEqual({});
   });
 });

package/src/__tests__/contracts.test.ts

@@ -1,10 +1,22 @@
-import { describe, test } from 'bun:test';
+import { afterAll, describe, expect, mock, test } from 'bun:test';
 
-import { Result, provision, trail, topo } from '@ontrails/core';
+import { contour, Result, resource, trail, topo } from '@ontrails/core';
 import { z } from 'zod';
 
 import { testContracts } from '../contracts.js';
 
+const requireContourExample = (
+  contourDef: { examples?: readonly Record<string, unknown>[] },
+  index: number
+) => {
+  const example = contourDef.examples?.[index];
+  expect(example).toBeDefined();
+  if (!example) {
+    throw new Error(`Expected contour example at index ${index}`);
+  }
+  return example;
+};
+
 // ---------------------------------------------------------------------------
 // Test trails
 // ---------------------------------------------------------------------------
@@ -72,46 +84,74 @@ const transformedInputTrail = trail('contract.transformed', {
   output: z.object({ value: z.number() }),
 });
 
-const undeclaredContractDbProvision = provision('db.undeclared.contracts', {
+const undeclaredContractDbResource = resource('db.undeclared.contracts', {
   create: () => Result.ok({ source: 'factory' }),
   mock: () => ({ source: 'mock' }),
 });
 
-const undeclaredContractTrail = trail('provision.undeclared.contracts', {
+const undeclaredContractTrail = trail('resource.undeclared.contracts', {
   blaze: (_input, ctx) =>
     Result.ok({
-      hasInjectedProvision:
-        ctx.extensions?.[undeclaredContractDbProvision.id] !== undefined,
+      hasInjectedResource:
+        ctx.extensions?.[undeclaredContractDbResource.id] !== undefined,
     }),
   examples: [
     {
-      expected: { hasInjectedProvision: false },
+      expected: { hasInjectedResource: false },
       input: {},
-      name: 'Undeclared provisions are not preloaded into contract contexts',
+      name: 'Undeclared resources are not preloaded into contract contexts',
     },
   ],
   input: z.object({}),
-  output: z.object({ hasInjectedProvision: z.literal(false) }),
+  output: z.object({ hasInjectedResource: z.literal(false) }),
 });
 
-const ctxOverrideContractProvision = provision('db.mock.contracts', {
+const ctxOverrideContractResource = resource('db.mock.contracts', {
   create: () => Result.ok({ source: 'factory' }),
   mock: () => ({ source: 'mock' }),
 });
 
-const ctxOverrideContractTrail = trail('provision.ctx.contracts', {
+const ctxOverrideContractTrail = trail('resource.ctx.contracts', {
   blaze: (_input, ctx) =>
-    Result.ok({ source: ctxOverrideContractProvision.from(ctx).source }),
+    Result.ok({ source: ctxOverrideContractResource.from(ctx).source }),
   examples: [
     {
       expected: { source: 'ctx' },
       input: {},
-      name: 'Context extensions beat auto-resolved contract provision mocks',
+      name: 'Context extensions beat auto-resolved contract resource mocks',
     },
   ],
   input: z.object({}),
   output: z.object({ source: z.literal('ctx') }),
-  provisions: [ctxOverrideContractProvision],
+  resources: [ctxOverrideContractResource],
+});
+
+const derivedContractContour = contour(
+  'contractFixture',
+  {
+    id: z.string().uuid(),
+    name: z.string(),
+  },
+  {
+    examples: [
+      {
+        id: '03a5873c-0ca6-43c4-9201-3cb3c07ca6bf',
+        name: 'Contour contract fixture',
+      },
+    ],
+    identity: 'id',
+  }
+);
+
+const derivedContractBlaze = mock(() =>
+  Result.ok(requireContourExample(derivedContractContour, 0))
+);
+
+const derivedContractTrail = trail('contract.derived', {
+  blaze: () => derivedContractBlaze(),
+  contours: [derivedContractContour],
+  input: z.object({ id: derivedContractContour.shape.id }),
+  output: derivedContractContour,
 });
 
 // ---------------------------------------------------------------------------
@@ -163,7 +203,7 @@ describe('testContracts: context extension overrides', () => {
   // eslint-disable-next-line jest/require-hook
   testContracts(
     topo('ctx-contract-app', {
-      ctxOverrideContractProvision,
+      ctxOverrideContractResource,
       ctxOverrideContractTrail,
     } as Record<string, unknown>),
     {
@@ -174,12 +214,26 @@ describe('testContracts: context extension overrides', () => {
   );
 });
 
-describe('testContracts provision declarations', () => {
+describe('testContracts resource declarations', () => {
   // eslint-disable-next-line jest/require-hook
   testContracts(
-    topo('undeclared-contract-provision-app', {
-      undeclaredContractDbProvision,
+    topo('undeclared-contract-resource-app', {
+      undeclaredContractDbResource,
       undeclaredContractTrail,
     } as Record<string, unknown>)
   );
 });
+
+describe('testContracts derives contour examples when trail examples are absent', () => {
+  // eslint-disable-next-line jest/require-hook
+  testContracts(
+    topo('derived-contract-app', {
+      derivedContractContour,
+      derivedContractTrail,
+    } as Record<string, unknown>)
+  );
+
+  afterAll(() => {
+    expect(derivedContractBlaze).toHaveBeenCalledTimes(1);
+  });
+});