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

package/src/examples.ts

@@ -3,15 +3,15 @@
  *
  * Iterates every trail in the app's topo. For each trail with examples,
  * generates describe/test blocks using bun:test. Progressive assertion
- * determines which check to run per example. For trails with `follow`
- * declarations, checks that every declared follow was called at least once.
+ * determines which check to run per example. For trails with `crosses`
+ * declarations, checks that every declared crossing was called at least once.
  */
 
 import { describe, expect, test } from 'bun:test';
 
 import type {
-  FollowFn,
-  ServiceOverrideMap,
+  CrossFn,
+  ProvisionOverrideMap,
   Topo,
   TrailExample,
   Trail,
@@ -45,12 +45,13 @@ import {
   assertSchemaMatch,
 } from './assertions.js';
 import {
-  mergeServiceOverrides,
+  defaultMintPermit,
+  mergeProvisionOverrides,
   mergeTestContext,
   normalizeTestExecutionOptions,
-  resolveMockServices,
+  resolveMockProvisions,
 } from './context.js';
-import type { TestExecutionOptions } from './context.js';
+import type { MintableTrail, TestExecutionOptions } from './context.js';
 
 // ---------------------------------------------------------------------------
 // Error class name -> constructor map
@@ -127,6 +128,29 @@ const handleValidationError = (
   );
 };
 
+/**
+ * Apply auto-minting: if the trail declares scoped permits and the context
+ * doesn't already have a permit, mint one and merge it into the context.
+ */
+const applyAutoMint = (
+  ctx: TrailContext,
+  trailDef: MintableTrail,
+  opts: TestExecutionOptions
+): TrailContext => {
+  if (opts.strictPermits) {
+    return ctx;
+  }
+  if (ctx.permit !== undefined) {
+    return ctx;
+  }
+  const mint = opts.mintPermit ?? defaultMintPermit;
+  const permit = mint(trailDef);
+  if (!permit) {
+    return ctx;
+  }
+  return { ...ctx, permit };
+};
+
 /**
  * Run a single example against a trail.
  * Handles validation, execution, and assertions.
@@ -136,7 +160,8 @@ const runExample = async (
   example: TrailExample<unknown, unknown>,
   output: z.ZodType | undefined,
   testCtx: TrailContext,
-  services?: ServiceOverrideMap
+  provisions?: ProvisionOverrideMap,
+  opts?: TestExecutionOptions
 ): Promise<void> => {
   const validated = validateInput(t.input, example.input);
 
@@ -144,53 +169,55 @@ const runExample = async (
     return;
   }
 
+  const ctx = opts ? applyAutoMint(testCtx, t, opts) : testCtx;
+
   const result = await executeTrail(t, example.input, {
-    ctx: testCtx,
-    services,
+    ctx,
+    provisions: provisions ?? opts?.provisions,
   });
   assertProgressiveMatch(result, example, output);
 };
 
 // ---------------------------------------------------------------------------
-// Follow coverage for composition trails
+// Crossing coverage for trails with crossings
 // ---------------------------------------------------------------------------
 
 /**
- * Build a recording follow function that tracks which trail IDs are called.
+ * Build a recording cross function that tracks which trail IDs are called.
  *
- * Delegates to `baseFollow` when available, otherwise looks up the trail
+ * Delegates to `baseCross` when available, otherwise looks up the trail
  * in the topo and executes it with validated input. Falls back to
  * `Result.ok()` when neither is available.
  */
-const createCoverageFollow = (
+const createCoverageCross = (
   called: Set<string>,
-  baseFollow: FollowFn | undefined,
+  baseCross: CrossFn | undefined,
   topo: Topo,
   ctx: TrailContext,
-  services?: ServiceOverrideMap
-): FollowFn => {
-  const follow = (id: string, input: unknown) => {
+  provisions?: ProvisionOverrideMap
+): CrossFn => {
+  const cross = (id: string, input: unknown) => {
     called.add(id);
 
-    if (baseFollow !== undefined) {
-      return baseFollow(id, input);
+    if (baseCross !== undefined) {
+      return baseCross(id, input);
     }
 
     const trailDef = topo.get(id);
     if (trailDef !== undefined) {
       return executeTrail(trailDef, input, {
-        ctx: { ...ctx, follow },
-        services,
+        ctx: { ...ctx, cross },
+        provisions,
       });
     }
 
     return Promise.resolve(Result.ok());
   };
-  return follow as FollowFn;
+  return cross as CrossFn;
 };
 
 /**
- * Run a single example against a composition trail, recording follow calls.
+ * Run a single example against a trail with crossings, recording cross calls.
  */
 const runCompositionExample = async (
   trailDef: Trail<unknown, unknown>,
@@ -199,7 +226,8 @@ const runCompositionExample = async (
   baseCtx: TrailContext,
   called: Set<string>,
   topo: Topo,
-  services?: ServiceOverrideMap
+  provisions?: ProvisionOverrideMap,
+  opts?: TestExecutionOptions
 ): Promise<void> => {
   const validated = validateInput(trailDef.input, example.input);
 
@@ -207,18 +235,19 @@ const runCompositionExample = async (
     return;
   }
 
-  const follow = createCoverageFollow(
+  const mintedCtx = opts ? applyAutoMint(baseCtx, trailDef, opts) : baseCtx;
+  const cross = createCoverageCross(
     called,
-    baseCtx.follow,
+    mintedCtx.cross,
     topo,
-    baseCtx,
-    services
+    mintedCtx,
+    provisions
   );
-  const testCtx: TrailContext = { ...baseCtx, follow };
+  const testCtx: TrailContext = { ...mintedCtx, cross };
 
   const result = await executeTrail(trailDef, example.input, {
     ctx: testCtx,
-    services,
+    provisions: provisions ?? opts?.provisions,
   });
   assertProgressiveMatch(result, example, output);
 };
@@ -230,8 +259,8 @@ const runCompositionExample = async (
 /**
  * Generate describe/test blocks for every trail example in the app.
  *
- * For trails with `follow` declarations and examples, also verifies that
- * every declared follow ID was called at least once across all examples.
+ * For trails with `crosses` declarations and examples, also verifies that
+ * every declared crossed ID was called at least once across all examples.
  *
  * One line in your test file:
  * ```ts
@@ -252,8 +281,8 @@ export const testExamples = (
   const withExamples = allTrails.filter(
     (t) => t.examples !== undefined && t.examples.length > 0
   );
-  const simpleTrails = withExamples.filter((t) => t.follow.length === 0);
-  const compositionTrails = withExamples.filter((t) => t.follow.length > 0);
+  const simpleTrails = withExamples.filter((t) => t.crosses.length === 0);
+  const compositionTrails = withExamples.filter((t) => t.crosses.length > 0);
 
   // Simple trails: run examples directly
   if (simpleTrails.length > 0) {
@@ -267,19 +296,19 @@ export const testExamples = (
         'example: $name',
         async (example: TrailExample<unknown, unknown>) => {
           const resolved = normalizeTestExecutionOptions(resolveInput());
-          const services = mergeServiceOverrides(
-            await resolveMockServices(app),
+          const provisions = mergeProvisionOverrides(
+            await resolveMockProvisions(app),
             resolved.ctx,
-            resolved.services
+            resolved.provisions
           );
           const testCtx = mergeTestContext(resolved.ctx);
-          await runExample(t, example, output, testCtx, services);
+          await runExample(t, example, output, testCtx, provisions, resolved);
         }
       );
     });
   }
 
-  // Composition trails: use recording follow and check coverage
+  // Composition trails: use recording cross and check coverage
   if (compositionTrails.length > 0) {
     describe.each(compositionTrails)('$id', (t) => {
       const { examples, output } = t;
@@ -293,10 +322,10 @@ export const testExamples = (
         'example: $name',
         async (example: TrailExample<unknown, unknown>) => {
           const resolved = normalizeTestExecutionOptions(resolveInput());
-          const services = mergeServiceOverrides(
-            await resolveMockServices(app),
+          const provisions = mergeProvisionOverrides(
+            await resolveMockProvisions(app),
             resolved.ctx,
-            resolved.services
+            resolved.provisions
           );
           const baseCtx = mergeTestContext(resolved.ctx);
           await runCompositionExample(
@@ -306,13 +335,14 @@ export const testExamples = (
             baseCtx,
             called,
             app,
-            services
+            provisions,
+            resolved
           );
         }
       );
 
-      test('follow coverage', () => {
-        const uncovered = t.follow.filter((id) => !called.has(id));
+      test('crossing coverage', () => {
+        const uncovered = t.crosses.filter((id) => !called.has(id));
         expect(uncovered).toEqual([]);
       });
     });

package/src/harness-mcp.ts

@@ -22,7 +22,7 @@ import type {
  * Create an MCP harness for integration testing.
  *
  * Builds MCP tools from the app's topo and provides a `callTool()` method
- * that invokes tools directly without any transport layer.
+ * that invokes tools directly without any transport boundary.
  *
  * ```ts
  * const harness = createMcpHarness({ app });
@@ -54,9 +54,9 @@ export const createMcpHarness = (options: McpHarnessOptions): McpHarness => {
       }
 
       const result = await tool.handler(args, {
+        abortSignal: undefined,
         progressToken: undefined,
         sendProgress: undefined,
-        signal: undefined,
       });
 
       return {

package/src/index.ts

@@ -1,7 +1,7 @@
 // Contract-driven testing
 export { testAll } from './all.js';
 export { testExamples } from './examples.js';
-export { testFollows } from './follows.js';
+export { testCrosses } from './crosses.js';
 export { testTrail } from './trail.js';
 export { testContracts } from './contracts.js';
 export { testDetours } from './detours.js';
@@ -16,20 +16,28 @@ export {
 } from './assertions.js';
 
 // Mock factories
-export { createFollowContext, createTestContext } from './context.js';
+export {
+  createCrossContext,
+  createTestContext,
+  defaultMintPermit,
+} from './context.js';
 export { createTestLogger } from './logger.js';
 
-// Surface harnesses
+// Trailhead harnesses
 export { createCliHarness } from './harness-cli.js';
 export { createMcpHarness } from './harness-mcp.js';
 
 // Types
-export type { CreateFollowContextOptions } from './context.js';
-export type { TestExecutionOptions } from './context.js';
-export type { TestFollowOptions } from './follows.js';
+export type { CreateCrossContextOptions } from './context.js';
+export type {
+  MintableTrail,
+  MintedPermit,
+  TestExecutionOptions,
+} from './context.js';
+export type { TestCrossOptions } from './crosses.js';
 
 export type {
-  FollowScenario,
+  CrossScenario,
   TestScenario,
   TestLogger,
   TestTrailContextOptions,

package/src/trail.ts

@@ -82,7 +82,7 @@ const runScenario = async (
   }
   const validatedInput = expectOk(validated);
 
-  const result = await trailDef.run(validatedInput, testCtx);
+  const result = await trailDef.blaze(validatedInput, testCtx);
   assertScenarioResult(result, scenario, trailDef);
 };
 

package/src/types.ts

@@ -26,16 +26,16 @@ export interface TestScenario {
 }
 
 // ---------------------------------------------------------------------------
-// Follow Scenario (for testFollows)
+// Cross Scenario (for testCrosses)
 // ---------------------------------------------------------------------------
 
-/** A test scenario for a trail's composition graph. */
-export interface FollowScenario extends TestScenario {
-  /** Assert these trail IDs were followed, in order. */
-  readonly expectFollowed?: readonly string[] | undefined;
-  /** Assert follow counts per trail ID. */
-  readonly expectFollowedCount?: Readonly<Record<string, number>> | undefined;
-  /** Inject failure from a followed trail's example by description. */
+/** A test scenario for a trail's crossing graph. */
+export interface CrossScenario extends TestScenario {
+  /** Assert these trail IDs were crossed, in order. */
+  readonly expectCrossed?: readonly string[] | undefined;
+  /** Assert crossing counts per trail ID. */
+  readonly expectCrossedCount?: Readonly<Record<string, number>> | undefined;
+  /** Inject failure from a crossed trail's example by description. */
   readonly injectFromExample?: Readonly<Record<string, string>> | undefined;
 }
 
@@ -65,7 +65,7 @@ export interface TestTrailContextOptions {
   readonly env?: Record<string, string> | undefined;
   readonly logger?: Logger | undefined;
   readonly requestId?: string | undefined;
-  readonly signal?: AbortSignal | undefined;
+  readonly abortSignal?: AbortSignal | undefined;
 }
 
 // ---------------------------------------------------------------------------

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/all.ts","./src/assertions.ts","./src/context.ts","./src/contracts.ts","./src/detours.ts","./src/examples.ts","./src/follows.ts","./src/harness-cli.ts","./src/harness-mcp.ts","./src/index.ts","./src/logger.ts","./src/trail.ts","./src/types.ts"],"version":"5.9.3"}
+{"root":["./src/all.ts","./src/assertions.ts","./src/context.ts","./src/contracts.ts","./src/crosses.ts","./src/detours.ts","./src/examples.ts","./src/harness-cli.ts","./src/harness-mcp.ts","./src/index.ts","./src/logger.ts","./src/trail.ts","./src/types.ts"],"version":"5.9.3"}