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

package/src/__tests__/effective-examples.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, test } from 'bun:test';
+
+import { contour, Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { deriveTrailExamples } from '../effective-examples.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;
+};
+
+const userContour = contour(
+  'user',
+  {
+    email: z.string().email(),
+    id: z.string().uuid(),
+    name: z.string(),
+  },
+  {
+    examples: [
+      {
+        email: 'ada@example.com',
+        id: '550e8400-e29b-41d4-a716-446655440000',
+        name: 'Ada',
+      },
+      {
+        email: 'grace@example.com',
+        id: '0f31f6ba-6ff0-41ce-9f6b-8d132b6c4b81',
+        name: 'Grace',
+      },
+    ],
+    identity: 'id',
+  }
+);
+
+const gistContour = contour(
+  'gist',
+  {
+    id: z.string().uuid(),
+    ownerId: userContour.id(),
+    title: z.string(),
+  },
+  {
+    examples: [
+      {
+        id: '8f7ef40d-8234-4f73-8de8-4bb8366cf5c0',
+        ownerId: '550e8400-e29b-41d4-a716-446655440000',
+        title: 'Ada Gist',
+      },
+      {
+        id: 'f104f457-b3fd-4643-87b9-d872c54b8a79',
+        ownerId: '0f31f6ba-6ff0-41ce-9f6b-8d132b6c4b81',
+        title: 'Grace Gist',
+      },
+    ],
+    identity: 'id',
+  }
+);
+
+describe('deriveTrailExamples', () => {
+  test('prefers authored trail examples over contour-derived fixtures', () => {
+    const authoredExample = {
+      expected: { email: 'manual@example.com', name: 'Manual' },
+      input: { email: 'manual@example.com', name: 'Manual' },
+      name: 'Manual example',
+    } as const;
+
+    const trailDef = trail('user.manual', {
+      blaze: (input: { email: string; name: string }) => Result.ok(input),
+      contours: [userContour],
+      examples: [authoredExample],
+      input: z.object({ email: z.string().email(), name: z.string() }),
+      output: z.object({ email: z.string().email(), name: z.string() }),
+    });
+
+    expect(deriveTrailExamples(trailDef)).toEqual([authoredExample]);
+  });
+
+  test('derives single-contour fixtures and preserves full contour output', () => {
+    const firstUserExample = requireContourExample(userContour, 0);
+
+    const trailDef = trail('user.create', {
+      blaze: () => Result.ok(firstUserExample),
+      contours: [userContour],
+      input: userContour.pick({ email: true, name: true }),
+      output: userContour,
+    });
+
+    const examples = deriveTrailExamples(trailDef);
+    expect(examples).toHaveLength(2);
+    const firstRecord = firstUserExample as Record<string, unknown>;
+    expect(examples[0]).toEqual(
+      expect.objectContaining({
+        expected: firstUserExample,
+        // Input is projected down to the keys `trail.input` declares, so
+        // only `email` and `name` (from `.pick`) survive.
+        input: {
+          email: firstRecord.email,
+          name: firstRecord.name,
+        },
+      })
+    );
+  });
+
+  test('filters contour fixtures that do not satisfy the trail input schema', () => {
+    const trailDef = trail('user.slug-only', {
+      blaze: () => Result.ok({ slug: 'unused' }),
+      contours: [userContour],
+      input: z.object({ slug: z.string() }),
+      output: z.object({ slug: z.string() }),
+    });
+
+    expect(deriveTrailExamples(trailDef)).toEqual([]);
+  });
+
+  test('matches cross-contour references and exposes contour-prefixed aliases', () => {
+    const trailDef = trail('gist.star', {
+      blaze: (input: { gistId: string; userId: string }) => Result.ok(input),
+      contours: [userContour, gistContour],
+      input: z.object({
+        gistId: gistContour.id(),
+        userId: userContour.id(),
+      }),
+      output: z.object({
+        gistId: gistContour.shape.id,
+        userId: userContour.shape.id,
+      }),
+    });
+
+    const examples = deriveTrailExamples(trailDef);
+    expect(examples).toHaveLength(2);
+    // No contour fixture parses as the output schema on its own (the
+    // output expects `gistId` and `userId`, but the fixtures expose
+    // `id`, `ownerId`, etc.), so derived examples are left without an
+    // `expected` and fall back to schema-only validation at runtime.
+    expect(examples).toEqual([
+      {
+        input: {
+          gistId: '8f7ef40d-8234-4f73-8de8-4bb8366cf5c0',
+          userId: '550e8400-e29b-41d4-a716-446655440000',
+        },
+        name: expect.stringContaining('Derived fixture 1'),
+      },
+      {
+        input: {
+          gistId: 'f104f457-b3fd-4643-87b9-d872c54b8a79',
+          userId: '0f31f6ba-6ff0-41ce-9f6b-8d132b6c4b81',
+        },
+        name: expect.stringContaining('Derived fixture 2'),
+      },
+    ]);
+  });
+
+  test('derives fixtures for strict input schemas by projecting to known keys', () => {
+    const firstUserExample = requireContourExample(userContour, 0);
+
+    const trailDef = trail('user.strict-create', {
+      blaze: (input: { email: string; name: string }) => Result.ok(input),
+      contours: [userContour],
+      input: z.object({ email: z.string().email(), name: z.string() }).strict(),
+      output: z.object({ email: z.string().email(), name: z.string() }),
+    });
+
+    const examples = deriveTrailExamples(trailDef);
+    expect(examples).toHaveLength(2);
+    expect(examples[0]?.input).toEqual({
+      email: (firstUserExample as { email: string }).email,
+      name: (firstUserExample as { name: string }).name,
+    });
+  });
+
+  test('does not infer expected from merged input when no contour fixture matches the output', () => {
+    // The output schema is a subset of the input shape, so the merged
+    // derived input would parse as the output if we tried to infer from
+    // it — but that inference is semantically wrong because input and
+    // output have distinct meanings. Since no contour fixture matches
+    // the output schema (userContour fixtures carry id+email+name, and
+    // the strict output only accepts email+name), `expected` must be
+    // omitted entirely.
+    const trailDef = trail('user.create-strict-output', {
+      blaze: (input: { email: string; name: string }) => Result.ok(input),
+      contours: [userContour],
+      input: z.object({ email: z.string().email(), name: z.string() }),
+      output: z
+        .object({ email: z.string().email(), name: z.string() })
+        .strict(),
+    });
+
+    const examples = deriveTrailExamples(trailDef);
+    expect(examples.length).toBeGreaterThan(0);
+    for (const example of examples) {
+      expect(example.expected).toBeUndefined();
+    }
+  });
+});

package/src/__tests__/examples.test.ts

@@ -1,6 +1,16 @@
 import { describe, test } from 'bun:test';
 
-import { NotFoundError, Result, provision, trail, topo } from '@ontrails/core';
+import {
+  ConflictError,
+  contour,
+  DerivationError,
+  NotFoundError,
+  Result,
+  RetryExhaustedError,
+  resource,
+  trail,
+  topo,
+} from '@ontrails/core';
 import { z } from 'zod';
 
 import { testExamples } from '../examples.js';
@@ -67,41 +77,68 @@ const noExamplesTrail = trail('noexamples', {
   input: z.object({ x: z.number() }),
 });
 
-const mockDbProvision = provision('db.mock.examples', {
+const taxonomyErrorTrail = trail('taxonomy.errors', {
+  blaze: (input: { type: 'derivation' | 'retry' }) => {
+    if (input.type === 'derivation') {
+      return Result.err(new DerivationError('could not derive projection'));
+    }
+    return Result.err(
+      new RetryExhaustedError(new ConflictError('version mismatch'), {
+        attempts: 3,
+        detour: 'ConflictError',
+      })
+    );
+  },
+  examples: [
+    {
+      error: 'DerivationError',
+      input: { type: 'derivation' },
+      name: 'Derivation failure returns DerivationError',
+    },
+    {
+      error: 'RetryExhaustedError',
+      input: { type: 'retry' },
+      name: 'Exhausted detour returns RetryExhaustedError',
+    },
+  ],
+  input: z.object({ type: z.enum(['derivation', 'retry']) }),
+});
+
+const mockDbResource = resource('db.mock.examples', {
   create: () => Result.ok({ source: 'factory' }),
   mock: () => ({ source: 'mock' }),
 });
 
-const mockProvisionTrail = trail('provision.mocked', {
+const mockResourceTrail = trail('resource.mocked', {
   blaze: (_input, ctx) =>
-    Result.ok({ source: mockDbProvision.from(ctx).source }),
-  description: 'Trail that reads from a mocked provision',
+    Result.ok({ source: mockDbResource.from(ctx).source }),
+  description: 'Trail that reads from a mocked resource',
   examples: [
     {
       expected: { source: 'mock' },
       input: {},
-      name: 'Uses auto-resolved provision mock',
+      name: 'Uses auto-resolved resource mock',
     },
   ],
   input: z.object({}),
   output: z.object({ source: z.string() }),
-  provisions: [mockDbProvision],
+  resources: [mockDbResource],
 });
 
-const explicitOverrideTrail = trail('provision.override', {
+const explicitOverrideTrail = trail('resource.override', {
   blaze: (_input, ctx) =>
-    Result.ok({ source: mockDbProvision.from(ctx).source }),
-  description: 'Trail whose provision mock can be overridden explicitly',
+    Result.ok({ source: mockDbResource.from(ctx).source }),
+  description: 'Trail whose resource mock can be overridden explicitly',
   examples: [
     {
       expected: { source: 'override' },
       input: {},
-      name: 'Explicit provision override wins over mock factory',
+      name: 'Explicit resource override wins over mock factory',
     },
   ],
   input: z.object({}),
   output: z.object({ source: z.string() }),
-  provisions: [mockDbProvision],
+  resources: [mockDbResource],
 });
 
 const transformedInputTrail = trail('example.transformed', {
@@ -120,62 +157,62 @@ const transformedInputTrail = trail('example.transformed', {
   output: z.object({ value: z.number() }),
 });
 
-const ctxOverrideTrail = trail('provision.ctx-override', {
+const ctxOverrideTrail = trail('resource.ctx-override', {
   blaze: (_input, ctx) =>
-    Result.ok({ source: mockDbProvision.from(ctx).source }),
-  description: 'Trail whose provision mock can be overridden by ctx.extensions',
+    Result.ok({ source: mockDbResource.from(ctx).source }),
+  description: 'Trail whose resource mock can be overridden by ctx.extensions',
   examples: [
     {
       expected: { source: 'ctx' },
       input: {},
-      name: 'Context extensions beat auto-resolved mock provisions',
+      name: 'Context extensions beat auto-resolved mock resources',
     },
   ],
   input: z.object({}),
   output: z.object({ source: z.string() }),
-  provisions: [mockDbProvision],
+  resources: [mockDbResource],
 });
 
-const undeclaredDbProvision = provision('db.undeclared.examples', {
+const undeclaredDbResource = resource('db.undeclared.examples', {
   create: () => Result.ok({ source: 'factory' }),
   mock: () => ({ source: 'mock' }),
 });
 
-const undeclaredProvisionTrail = trail('provision.undeclared.examples', {
+const undeclaredResourceTrail = trail('resource.undeclared.examples', {
   blaze: (_input, ctx) =>
-    Result.ok({ source: undeclaredDbProvision.from(ctx).source }),
-  description: 'Trail that uses a provision without declaring it',
+    Result.ok({ source: undeclaredDbResource.from(ctx).source }),
+  description: 'Trail that uses a resource without declaring it',
   examples: [
     {
       error: 'InternalError',
       input: {},
-      name: 'Undeclared provisions stay unavailable during example execution',
+      name: 'Undeclared resources stay unavailable during example execution',
     },
   ],
   input: z.object({}),
   output: z.object({ source: z.string() }),
 });
-const crossDbProvision = provision('db.mock.examples.crosses', {
+const crossDbResource = resource('db.mock.examples.crosses', {
   create: () => Result.ok({ source: 'factory' }),
   mock: () => ({ source: 'mock' }),
 });
 
-const crossLeafTrail = trail('provision.crosses.leaf', {
+const crossLeafTrail = trail('resource.crosses.leaf', {
   blaze: (_input, ctx) =>
-    Result.ok({ childSource: crossDbProvision.from(ctx).source }),
-  description: 'Leaf trail that resolves a provision inside a cross chain',
+    Result.ok({ childSource: crossDbResource.from(ctx).source }),
+  description: 'Leaf trail that resolves a resource inside a cross chain',
   input: z.object({}),
   output: z.object({ childSource: z.string() }),
-  provisions: [crossDbProvision],
+  resources: [crossDbResource],
 });
 
-const crossRootTrail = trail('provision.crosses.root', {
+const crossRootTrail = trail('resource.crosses.root', {
   blaze: async (_input, ctx) => {
     if (!ctx.cross) {
       return Result.err(new Error('cross not available'));
     }
     const childResult = await ctx.cross<{ childSource: string }>(
-      'provision.crosses.leaf',
+      'resource.crosses.leaf',
       {}
     );
     if (childResult.isErr()) {
@@ -183,21 +220,21 @@ const crossRootTrail = trail('provision.crosses.root', {
     }
     return Result.ok({
       childSource: childResult.value.childSource,
-      rootSource: crossDbProvision.from(ctx).source,
+      rootSource: crossDbResource.from(ctx).source,
     });
   },
-  crosses: ['provision.crosses.leaf'],
-  description: 'Root trail that crosses a child trail using provisions',
+  crosses: ['resource.crosses.leaf'],
+  description: 'Root trail that crosses a child trail using resources',
   examples: [
     {
       expected: { childSource: 'mock', rootSource: 'mock' },
       input: {},
-      name: 'Propagates provision mocks through cross execution',
+      name: 'Propagates resource mocks through cross execution',
     },
   ],
   input: z.object({}),
   output: z.object({ childSource: z.string(), rootSource: z.string() }),
-  provisions: [crossDbProvision],
+  resources: [crossDbResource],
 });
 
 // ---------------------------------------------------------------------------
@@ -262,6 +299,7 @@ describe('testExamples', () => {
       greetTrail,
       noExamplesTrail,
       searchTrail,
+      taxonomyErrorTrail,
     } as Record<string, unknown>)
   );
 
@@ -296,25 +334,25 @@ describe('testExamples skips trails with no examples', () => {
   });
 });
 
-describe('testExamples provision mocks', () => {
+describe('testExamples resource mocks', () => {
   // eslint-disable-next-line jest/require-hook
   testExamples(
-    topo('provision-mock-app', {
-      mockDbProvision,
-      mockProvisionTrail,
+    topo('resource-mock-app', {
+      mockDbResource,
+      mockResourceTrail,
     } as Record<string, unknown>)
   );
 });
 
-describe('testExamples explicit provision overrides', () => {
+describe('testExamples explicit resource overrides', () => {
   // eslint-disable-next-line jest/require-hook
   testExamples(
-    topo('provision-override-app', {
+    topo('resource-override-app', {
       explicitOverrideTrail,
-      mockDbProvision,
+      mockDbResource,
     } as Record<string, unknown>),
     {
-      provisions: { 'db.mock.examples': { source: 'override' } },
+      resources: { 'db.mock.examples': { source: 'override' } },
     }
   );
 });
@@ -333,7 +371,7 @@ describe('testExamples context extension overrides', () => {
   testExamples(
     topo('ctx-override-app', {
       ctxOverrideTrail,
-      mockDbProvision,
+      mockDbResource,
     } as Record<string, unknown>),
     {
       ctx: {
@@ -343,12 +381,12 @@ describe('testExamples context extension overrides', () => {
   );
 });
 
-describe('testExamples provision declarations', () => {
+describe('testExamples resource declarations', () => {
   // eslint-disable-next-line jest/require-hook
   testExamples(
-    topo('undeclared-provision-app', {
-      undeclaredDbProvision,
-      undeclaredProvisionTrail,
+    topo('undeclared-resource-app', {
+      undeclaredDbResource,
+      undeclaredResourceTrail,
     } as Record<string, unknown>)
   );
 });
@@ -364,11 +402,11 @@ describe('testExamples crossing coverage for trails with crossings', () => {
   );
 });
 
-describe('testExamples provision mocks through cross', () => {
+describe('testExamples resource mocks through cross', () => {
   // eslint-disable-next-line jest/require-hook
   testExamples(
-    topo('provision-cross-app', {
-      crossDbProvision,
+    topo('resource-cross-app', {
+      crossDbResource,
       crossLeafTrail,
       crossRootTrail,
     } as Record<string, unknown>)
@@ -532,3 +570,67 @@ describe('testExamples auto-minting permits', () => {
     );
   });
 });
+
+// ---------------------------------------------------------------------------
+// Derived-fixture crossing coverage regression
+// ---------------------------------------------------------------------------
+//
+// A composition trail whose only examples come from contour-derived
+// fixtures must not fail crossing-coverage — derived inputs are not
+// guaranteed to exercise every declared cross.
+
+const itemContour = contour(
+  'item',
+  {
+    id: z.string(),
+    name: z.string(),
+  },
+  {
+    examples: [{ id: 'abc', name: 'Widget' }],
+    identity: 'id',
+  }
+);
+
+const helperTrail = trail('derived.helper', {
+  blaze: (input: { id: string }) => Result.ok({ id: input.id, ok: true }),
+  description: 'Helper referenced by a conditional cross',
+  input: z.object({ id: z.string() }),
+  output: z.object({ id: z.string(), ok: z.boolean() }),
+});
+
+const conditionalCrossTrail = trail('derived.conditional', {
+  blaze: async (input: { id: string; name: string }, ctx) => {
+    // The conditional cross is never taken for derived fixtures because
+    // `shouldCross` is always false in the synthesized input. This is
+    // exactly the case the provenance gate exists to protect: if we
+    // asserted crossing coverage against derived examples, this trail
+    // would fail even though its declaration is accurate for authored
+    // use.
+    const { shouldCross } = input as { shouldCross?: boolean };
+    if (shouldCross && ctx.cross) {
+      const result = await ctx.cross<{ id: string; ok: boolean }>(
+        'derived.helper',
+        { id: input.id }
+      );
+      if (result.isErr()) {
+        return result;
+      }
+    }
+    return Result.ok({ id: input.id, name: input.name });
+  },
+  contours: [itemContour],
+  crosses: ['derived.helper'],
+  description: 'Composition trail with a cross that derived fixtures skip',
+  input: z.object({ id: z.string(), name: z.string() }),
+  output: z.object({ id: z.string(), name: z.string() }),
+});
+
+describe('testExamples derived-fixture crossing coverage is gated', () => {
+  // eslint-disable-next-line jest/require-hook
+  testExamples(
+    topo('derived-coverage-app', {
+      conditionalCrossTrail,
+      helperTrail,
+    } as Record<string, unknown>)
+  );
+});

package/src/__tests__/harness-cli.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resource, Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { createCliHarness } from '../harness-cli.js';
+
+describe('createCliHarness', () => {
+  test('runs top-level commands', async () => {
+    const greet = trail('greet', {
+      blaze: (input: { name: string }) => Result.ok(`Hello, ${input.name}!`),
+      input: z.object({ name: z.string() }),
+    });
+    const harness = createCliHarness({
+      graph: topo('test-app', { greet }),
+    });
+
+    const result = await harness.run('greet --name Trails');
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain('Hello, Trails!');
+  });
+
+  test('runs nested commands using the full ordered path', async () => {
+    const pin = trail('topo.pin', {
+      blaze: (input: { name: string }) => Result.ok(`Pinned ${input.name}`),
+      input: z.object({ name: z.string() }),
+    });
+    const harness = createCliHarness({
+      graph: topo('test-app', { pin }),
+    });
+
+    const result = await harness.run('topo pin --name before-auth');
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain('Pinned before-auth');
+  });
+
+  test('prefers the deepest matching executable path', async () => {
+    const calls: string[] = [];
+    const topoShow = trail('topo', {
+      blaze: () => {
+        calls.push('topo');
+        return Result.ok('topo');
+      },
+      input: z.object({}),
+    });
+    const topoPin = trail('topo.pin', {
+      blaze: () => {
+        calls.push('topo.pin');
+        return Result.ok('topo.pin');
+      },
+      input: z.object({}),
+    });
+    const harness = createCliHarness({
+      graph: topo('test-app', { topoPin, topoShow }),
+    });
+
+    const child = await harness.run('topo pin');
+    const parent = await harness.run('topo');
+
+    expect(child.exitCode).toBe(0);
+    expect(parent.exitCode).toBe(0);
+    expect(calls).toEqual(['topo.pin', 'topo']);
+  });
+
+  test('threads resource overrides through CLI projection options', async () => {
+    const dbResource = resource('db.main', {
+      create: () => Result.ok({ source: 'factory' }),
+    });
+    const readResource = trail('resource.read', {
+      blaze: (_input, ctx) =>
+        Result.ok({ source: dbResource.from(ctx).source as string }),
+      input: z.object({}),
+      output: z.object({ source: z.string() }),
+      resources: [dbResource],
+    });
+    const harness = createCliHarness({
+      graph: topo('test-app', { dbResource, readResource }),
+      resources: {
+        'db.main': { source: 'override' },
+      },
+    });
+
+    const result = await harness.run('resource read --output json');
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain('"override"');
+  });
+});

package/src/__tests__/harness-mcp.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resource, Result, topo, trail } from '@ontrails/core';
+import { deriveToolName } from '@ontrails/mcp';
+import { z } from 'zod';
+
+import { createMcpHarness } from '../harness-mcp.js';
+
+describe('createMcpHarness', () => {
+  test('threads resource overrides through MCP projection options', async () => {
+    const dbResource = resource('db.main', {
+      create: () => Result.ok({ source: 'factory' }),
+    });
+    const readResource = trail('resource.read', {
+      blaze: (_input, ctx) =>
+        Result.ok({ source: dbResource.from(ctx).source as string }),
+      input: z.object({}),
+      output: z.object({ source: z.string() }),
+      resources: [dbResource],
+    });
+    const graph = topo('test-app', { dbResource, readResource });
+    const harness = createMcpHarness({
+      graph,
+      resources: {
+        'db.main': { source: 'override' },
+      },
+    });
+
+    const result = await harness.callTool(
+      deriveToolName(graph.name, readResource.id),
+      {}
+    );
+
+    expect(result.isError).toBe(false);
+    expect(JSON.stringify(result.content)).toContain('override');
+  });
+});