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

package/src/context.ts

@@ -3,12 +3,12 @@
  */
 
 import type {
-  FollowFn,
-  ServiceOverrideMap,
+  CrossFn,
+  ProvisionOverrideMap,
   Topo,
   TrailContext,
 } from '@ontrails/core';
-import { Result, createServiceLookup } from '@ontrails/core';
+import { Result, createProvisionLookup } from '@ontrails/core';
 
 import { createTestLogger } from './logger.js';
 import type { TestTrailContextOptions } from './types.js';
@@ -26,61 +26,90 @@ type MutableTrailContext = {
  *
  * - `requestId`: `"test-request-001"` (deterministic)
  * - `logger`: a `TestLogger` that captures entries
- * - `signal`: a non-aborted AbortController signal
+ * - `abortSignal`: a non-aborted AbortController signal
  */
 export const createTestContext = (
   overrides?: TestTrailContextOptions
 ): TrailContext => {
   const cwd = overrides?.cwd ?? process.cwd();
   const ctx = {
+    abortSignal: overrides?.abortSignal ?? new AbortController().signal,
     cwd,
     env: overrides?.env ?? { TRAILS_ENV: 'test' },
     extensions: undefined,
     logger: overrides?.logger ?? createTestLogger(),
     requestId: overrides?.requestId ?? 'test-request-001',
-    signal: overrides?.signal ?? new AbortController().signal,
     workspaceRoot: cwd,
   } as MutableTrailContext;
-  ctx.service = createServiceLookup(() => ctx);
+  const lookup = createProvisionLookup(() => ctx);
+  ctx.provision = lookup;
   return ctx;
 };
 
 // ---------------------------------------------------------------------------
-// createFollowContext
+// createCrossContext
 // ---------------------------------------------------------------------------
 
-export interface CreateFollowContextOptions {
+export interface CreateCrossContextOptions {
   readonly responses?: Record<string, Result<unknown, Error>> | undefined;
 }
 
+/** Minimal permit shape returned by the mint function. */
+export interface MintedPermit {
+  readonly id: string;
+  readonly scopes: readonly string[];
+}
+
+/** Trail shape consumed by the mint function — avoids importing permits. */
+export interface MintableTrail {
+  readonly permit?:
+    | { readonly scopes: readonly string[] }
+    | 'public'
+    | undefined;
+}
+
 export interface TestExecutionOptions {
   readonly ctx?: Partial<TrailContext> | undefined;
-  readonly services?: ServiceOverrideMap | undefined;
+  readonly provisions?: ProvisionOverrideMap | undefined;
+  /**
+   * When true, disables automatic permit minting. Tests must provide
+   * explicit permits.
+   */
+  readonly strictPermits?: boolean | undefined;
+  /**
+   * Optional function to mint a test permit for a trail. When provided,
+   * called for each trail with a non-public `permit` requirement.
+   * Returning `undefined` skips minting for that trail.
+   *
+   * A default inline implementation is used when this is not provided,
+   * keeping the testing package free of a hard dependency on `@ontrails/permits`.
+   */
+  readonly mintPermit?: (trail: MintableTrail) => MintedPermit | undefined;
 }
 
 /**
- * Create a mock `FollowFn` for testing composite trails.
+ * Create a mock `CrossFn` for testing composite trails.
  *
  * Returns preconfigured `Result` values keyed by trail ID. Calls to
  * unregistered IDs return `Result.err` with a descriptive message.
  *
  * @example
  * ```ts
- * const follow = createFollowContext({
+ * const cross = createCrossContext({
  *   responses: { 'entity.add': Result.ok({ id: '1', name: 'Alpha' }) },
  * });
- * const ctx = { ...createTestContext(), follow };
+ * const ctx = { ...createTestContext(), cross };
  * ```
  */
-export const createFollowContext = (
-  options?: CreateFollowContextOptions
-): FollowFn => {
+export const createCrossContext = (
+  options?: CreateCrossContextOptions
+): CrossFn => {
   const responses = options?.responses ?? {};
   return <O>(id: string, _input: unknown): Promise<Result<O, Error>> => {
     const response = responses[id];
     if (response === undefined) {
       return Promise.resolve(
-        Result.err(new Error(`No mock response for follow("${id}")`)) as Result<
+        Result.err(new Error(`No mock response for cross("${id}")`)) as Result<
           O,
           Error
         >
@@ -90,41 +119,59 @@ export const createFollowContext = (
   };
 };
 
+/**
+ * Default permit minter — reads `trail.permit.scopes` and produces a
+ * minimal permit object. No dependency on `@ontrails/permits`.
+ */
+export const defaultMintPermit = (
+  trail: MintableTrail
+): MintedPermit | undefined => {
+  if (!trail.permit || trail.permit === 'public') {
+    return undefined;
+  }
+  return { id: 'test-permit', scopes: trail.permit.scopes };
+};
+
 const isTestExecutionOptions = (
   input: Partial<TrailContext> | TestExecutionOptions | undefined
 ): input is TestExecutionOptions =>
   input !== undefined &&
-  (Object.hasOwn(input, 'ctx') || Object.hasOwn(input, 'services'));
+  (Object.hasOwn(input, 'ctx') ||
+    Object.hasOwn(input, 'provisions') ||
+    Object.hasOwn(input, 'strictPermits') ||
+    Object.hasOwn(input, 'mintPermit'));
 
 export const normalizeTestExecutionOptions = (
   input?: Partial<TrailContext> | TestExecutionOptions
 ): TestExecutionOptions =>
   isTestExecutionOptions(input) ? input : { ctx: input };
 
-export const mergeServiceOverrides = (
-  autoResolved: ServiceOverrideMap,
+export const mergeProvisionOverrides = (
+  autoResolved: ProvisionOverrideMap,
   ctx: Partial<TrailContext> | undefined,
-  explicit: ServiceOverrideMap | undefined
-): ServiceOverrideMap => ({
+  explicit: ProvisionOverrideMap | undefined
+): ProvisionOverrideMap => ({
   ...autoResolved,
   ...ctx?.extensions,
   ...explicit,
 });
 
-const buildMockServices = async (app: Topo): Promise<ServiceOverrideMap> => {
-  const services: Record<string, unknown> = {};
-  for (const declaredService of app.listServices()) {
-    if (!declaredService.mock) {
+const buildMockProvisions = async (
+  app: Topo
+): Promise<ProvisionOverrideMap> => {
+  const provisions: Record<string, unknown> = {};
+  for (const declaredProvision of app.listProvisions()) {
+    if (!declaredProvision.mock) {
       continue;
     }
-    services[declaredService.id] = await declaredService.mock();
+    provisions[declaredProvision.id] = await declaredProvision.mock();
   }
-  return services;
+  return provisions;
 };
 
-export const resolveMockServices = async (
+export const resolveMockProvisions = async (
   app: Topo
-): Promise<ServiceOverrideMap> => await buildMockServices(app);
+): Promise<ProvisionOverrideMap> => await buildMockProvisions(app);
 
 /**
  * Merge a Partial<TrailContext> into a test context.
@@ -132,19 +179,20 @@ export const resolveMockServices = async (
  */
 export const mergeTestContext = (
   ctx?: Partial<TrailContext>,
-  services?: ServiceOverrideMap
+  provisions?: ProvisionOverrideMap
 ): TrailContext => {
   const base = createTestContext();
   const extensions = {
     ...base.extensions,
     ...ctx?.extensions,
-    ...services,
+    ...provisions,
   };
   const merged = {
     ...base,
     ...ctx,
     extensions: Object.keys(extensions).length === 0 ? undefined : extensions,
   } as MutableTrailContext;
-  merged.service = createServiceLookup(() => merged);
+  const lookup = createProvisionLookup(() => merged);
+  merged.provision = lookup;
   return merged;
 };

package/src/contracts.ts

@@ -14,10 +14,10 @@ import type { z } from 'zod';
 
 import { expectOk } from './assertions.js';
 import {
-  mergeServiceOverrides,
+  mergeProvisionOverrides,
   mergeTestContext,
   normalizeTestExecutionOptions,
-  resolveMockServices,
+  resolveMockProvisions,
 } from './context.js';
 import type { TestExecutionOptions } from './context.js';
 
@@ -25,16 +25,16 @@ import type { TestExecutionOptions } from './context.js';
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** Check if a trail requires follow() but the context doesn't provide it. */
-const needsFollowContext = (
+/** Check if a trail requires cross() but the context doesn't provide it. */
+const needsCrossContext = (
   t: unknown,
   resolveCtx: () => Partial<TrailContext> | TestExecutionOptions | undefined
 ): boolean => {
-  const spec = t as { follow?: readonly string[] };
-  if (!spec.follow || spec.follow.length === 0) {
+  const spec = t as { crosses?: readonly string[] };
+  if (!spec.crosses || spec.crosses.length === 0) {
     return false;
   }
-  return !normalizeTestExecutionOptions(resolveCtx()).ctx?.follow;
+  return !normalizeTestExecutionOptions(resolveCtx()).ctx?.cross;
 };
 
 const validateOutputSchema = (
@@ -81,7 +81,7 @@ export const testContracts = (
       if (t.examples === undefined || t.examples.length === 0) {
         return;
       }
-      if (needsFollowContext(t, resolveInput)) {
+      if (needsCrossContext(t, resolveInput)) {
         return;
       }
 
@@ -92,10 +92,10 @@ export const testContracts = (
         'contract: $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);
 
@@ -104,7 +104,7 @@ export const testContracts = (
 
           const result = await executeTrail(t, example.input, {
             ctx: testCtx,
-            services,
+            provisions,
           });
           const resultValue = expectOk(result);
 

package/src/{follows.ts → crosses.ts}

@@ -1,16 +1,16 @@
 /**
- * testFollows — composition-aware scenario testing for trails with follow.
+ * testCrosses — crossing-aware scenario testing for trails with crossings.
  *
- * Tests the follow graph: which trails were followed, in what order,
- * and supports failure injection from followed trail examples.
+ * Tests the crossing graph: which trails were crossed, in what order,
+ * and supports failure injection from crossed trail examples.
  */
 
 import { describe, expect, test } from 'bun:test';
 
 import type {
   AnyTrail,
-  FollowFn,
-  ServiceOverrideMap,
+  CrossFn,
+  ProvisionOverrideMap,
   TrailContext,
 } from '@ontrails/core';
 import {
@@ -26,33 +26,33 @@ import {
   assertFullMatch,
   assertSchemaMatch,
 } from './assertions.js';
-import { mergeServiceOverrides, mergeTestContext } from './context.js';
-import type { FollowScenario } from './types.js';
+import { mergeProvisionOverrides, mergeTestContext } from './context.js';
+import type { CrossScenario } from './types.js';
 
 // ---------------------------------------------------------------------------
-// Follow trace
+// Cross trace
 // ---------------------------------------------------------------------------
 
-interface FollowRecord {
+interface CrossRecord {
   readonly id: string;
   readonly input: unknown;
 }
 
-const collectDeclaredServices = (
+const collectDeclaredProvisions = (
   trailDef: AnyTrail,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined
-): AnyTrail['services'] => {
-  const seenServiceIds = new Set<string>();
+): AnyTrail['provisions'] => {
+  const seenProvisionIds = new Set<string>();
   const seenTrailIds = new Set<string>();
-  const services: AnyTrail['services'][number][] = [];
+  const provisions: AnyTrail['provisions'][number][] = [];
 
   const collect = (candidate: AnyTrail): void => {
-    for (const declaredService of candidate.services) {
-      if (seenServiceIds.has(declaredService.id)) {
+    for (const declaredProvision of candidate.provisions) {
+      if (seenProvisionIds.has(declaredProvision.id)) {
         continue;
       }
-      seenServiceIds.add(declaredService.id);
-      services.push(declaredService);
+      seenProvisionIds.add(declaredProvision.id);
+      provisions.push(declaredProvision);
     }
   };
 
@@ -62,32 +62,35 @@ const collectDeclaredServices = (
     }
     seenTrailIds.add(candidate.id);
     collect(candidate);
-    for (const followedId of candidate.follow) {
-      const followedTrail = trailsMap?.get(followedId);
-      if (followedTrail) {
-        visit(followedTrail);
+    for (const crossedId of candidate.crosses) {
+      const crossedTrail = trailsMap?.get(crossedId);
+      if (crossedTrail) {
+        visit(crossedTrail);
       }
     }
   };
 
   visit(trailDef);
-  return services;
+  return provisions;
 };
 
-const resolveMockServices = async (
+const resolveCrossMockProvisions = async (
   trailDef: AnyTrail,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined
-): Promise<ServiceOverrideMap> => {
-  const services: Record<string, unknown> = {};
-
-  for (const declaredService of collectDeclaredServices(trailDef, trailsMap)) {
-    if (!declaredService.mock) {
+): Promise<ProvisionOverrideMap> => {
+  const provisions: Record<string, unknown> = {};
+
+  for (const declaredProvision of collectDeclaredProvisions(
+    trailDef,
+    trailsMap
+  )) {
+    if (!declaredProvision.mock) {
       continue;
     }
-    services[declaredService.id] = await declaredService.mock();
+    provisions[declaredProvision.id] = await declaredProvision.mock();
   }
 
-  return services;
+  return provisions;
 };
 
 // ---------------------------------------------------------------------------
@@ -110,12 +113,12 @@ const findErrorExample = (
 };
 
 /**
- * Try to inject an error from a followed trail's example.
+ * Try to inject an error from a crossed trail's example.
  * Returns undefined when no injection is configured for this trail ID.
  */
 const tryInjectError = (
   id: string,
-  scenario: FollowScenario,
+  scenario: CrossScenario,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined
 ): Result<unknown, Error> | undefined => {
   const injection = scenario.injectFromExample?.[id];
@@ -148,39 +151,39 @@ const executeFromMap = (
   input: unknown,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
   ctx: TrailContext,
-  services: ServiceOverrideMap | undefined,
-  follow?: FollowFn
+  provisions: ProvisionOverrideMap | undefined,
+  cross?: CrossFn
 ): Result<unknown, Error> | Promise<Result<unknown, Error>> | undefined => {
   const trailDef = trailsMap?.get(id);
   if (trailDef === undefined) {
     return undefined;
   }
 
-  const nestedCtx = follow ? { ...ctx, follow } : ctx;
+  const nestedCtx = cross ? { ...ctx, cross } : ctx;
   return executeTrail(trailDef, input, {
     ctx: nestedCtx,
-    services,
+    provisions,
   });
 };
 
 // ---------------------------------------------------------------------------
-// Follow factory
+// Cross factory
 // ---------------------------------------------------------------------------
 
 /**
- * Build a recording follow function that optionally injects errors.
+ * Build a recording cross function that optionally injects errors.
  */
-const createRecordingFollow = (
-  trace: FollowRecord[],
-  scenario: FollowScenario,
+const createRecordingCross = (
+  trace: CrossRecord[],
+  scenario: CrossScenario,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
-  baseFollow: FollowFn | undefined,
+  baseCross: CrossFn | undefined,
   ctx: TrailContext,
-  services: ServiceOverrideMap | undefined
-): FollowFn => {
-  // The generic O on FollowFn is erased at runtime; the cast is safe
+  provisions: ProvisionOverrideMap | undefined
+): CrossFn => {
+  // The generic O on CrossFn is erased at runtime; the cast is safe
   // because callers narrow via isOk/isErr before accessing the value.
-  const follow = (id: string, input: unknown) => {
+  const cross = (id: string, input: unknown) => {
     trace.push({ id, input });
 
     const injected = tryInjectError(id, scenario, trailsMap);
@@ -188,8 +191,8 @@ const createRecordingFollow = (
       return Promise.resolve(injected);
     }
 
-    if (baseFollow !== undefined) {
-      return baseFollow(id, input);
+    if (baseCross !== undefined) {
+      return baseCross(id, input);
     }
 
     const executed = executeFromMap(
@@ -197,8 +200,8 @@ const createRecordingFollow = (
       input,
       trailsMap,
       ctx,
-      services,
-      follow as FollowFn
+      provisions,
+      cross as CrossFn
     );
     if (executed !== undefined) {
       return Promise.resolve(executed);
@@ -206,7 +209,7 @@ const createRecordingFollow = (
 
     return Promise.resolve(Result.ok());
   };
-  return follow as FollowFn;
+  return cross as CrossFn;
 };
 
 // ---------------------------------------------------------------------------
@@ -215,7 +218,7 @@ const createRecordingFollow = (
 
 const assertScenarioResult = (
   result: Result<unknown, Error>,
-  scenario: FollowScenario,
+  scenario: CrossScenario,
   trailDef: AnyTrail
 ): void => {
   if (scenario.expectValue !== undefined) {
@@ -233,26 +236,26 @@ const assertScenarioResult = (
   }
 };
 
-const assertFollowTrace = (
-  trace: readonly FollowRecord[],
-  scenario: FollowScenario
+const assertCrossTrace = (
+  trace: readonly CrossRecord[],
+  scenario: CrossScenario
 ): void => {
-  if (scenario.expectFollowed !== undefined) {
-    const followedIds = trace.map((r) => r.id);
-    expect(followedIds).toEqual([...scenario.expectFollowed]);
+  if (scenario.expectCrossed !== undefined) {
+    const crossedIds = trace.map((r) => r.id);
+    expect(crossedIds).toEqual([...scenario.expectCrossed]);
   }
-  if (scenario.expectFollowedCount !== undefined) {
+  if (scenario.expectCrossedCount !== undefined) {
     const counts: Record<string, number> = {};
     for (const record of trace) {
       counts[record.id] = (counts[record.id] ?? 0) + 1;
     }
-    expect(counts).toEqual({ ...scenario.expectFollowedCount });
+    expect(counts).toEqual({ ...scenario.expectCrossedCount });
   }
 };
 
 const handleValidationError = (
   validated: Result<unknown, Error>,
-  scenario: FollowScenario
+  scenario: CrossScenario
 ): boolean => {
   if (!validated.isErr()) {
     return false;
@@ -274,30 +277,30 @@ const handleValidationError = (
 // ---------------------------------------------------------------------------
 
 const buildTestContext = (
-  scenario: FollowScenario,
+  scenario: CrossScenario,
   ctx: Partial<TrailContext> | undefined,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
-  services: ServiceOverrideMap | undefined
-): { trace: FollowRecord[]; testCtx: TrailContext } => {
-  const trace: FollowRecord[] = [];
+  provisions: ProvisionOverrideMap | undefined
+): { trace: CrossRecord[]; testCtx: TrailContext } => {
+  const trace: CrossRecord[] = [];
   const baseCtx = mergeTestContext(ctx);
-  const follow = createRecordingFollow(
+  const cross = createRecordingCross(
     trace,
     scenario,
     trailsMap,
-    baseCtx.follow,
+    baseCtx.cross,
     baseCtx,
-    services
+    provisions
   );
-  return { testCtx: { ...baseCtx, follow }, trace };
+  return { testCtx: { ...baseCtx, cross }, trace };
 };
 
 const runScenario = async (
   trailDef: AnyTrail,
-  scenario: FollowScenario,
+  scenario: CrossScenario,
   ctx: Partial<TrailContext> | undefined,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
-  services: ServiceOverrideMap | undefined
+  provisions: ProvisionOverrideMap | undefined
 ): Promise<void> => {
   const validated = validateInput(trailDef.input, scenario.input);
   if (handleValidationError(validated, scenario)) {
@@ -308,69 +311,71 @@ const runScenario = async (
     scenario,
     ctx,
     trailsMap,
-    services
+    provisions
   );
   const result = await executeTrail(trailDef, scenario.input, {
     ctx: testCtx,
-    services,
+    provisions,
   });
-  assertFollowTrace(trace, scenario);
+  assertCrossTrace(trace, scenario);
   assertScenarioResult(result, scenario, trailDef);
 };
 
 // ---------------------------------------------------------------------------
-// testFollows
+// testCrosses
 // ---------------------------------------------------------------------------
 
-/** Options for testFollows that provide trail definitions for injection. */
-export interface TestFollowOptions {
+/** Options for testCrosses that provide trail definitions for injection. */
+export interface TestCrossOptions {
   /** Partial context overrides. */
   readonly ctx?: Partial<TrailContext> | undefined;
   /**
-   * Explicit service overrides merged on top of auto-resolved mocks for every
+   * Explicit provision overrides merged on top of auto-resolved mocks for every
    * scenario. Values are passed by reference — provide immutable objects, or
-   * use `mock()` on the service definition to get a fresh instance per run.
+   * use `mock()` on the provision definition to get a fresh instance per run.
    */
-  readonly services?: ServiceOverrideMap | undefined;
+  readonly provisions?: ProvisionOverrideMap | undefined;
   /** Map of trail ID to trail definition, used for injectFromExample. */
   readonly trails?: ReadonlyMap<string, AnyTrail> | undefined;
 }
 
 /**
- * Generate a describe block for a composition trail with one test per scenario.
+ * Generate a describe block for a trail with crossings with one test per scenario.
  *
  * @example
  * ```ts
- * testFollows(onboardTrail, [
+ * testCrosses(onboardTrail, [
  *   {
- *     description: "follows add then relate",
+ *     description: "crosses add then relate",
  *     input: { name: "Alpha" },
  *     expectOk: true,
- *     expectFollowed: ["entity.add", "entity.relate"],
+ *     expectCrossed: ["entity.add", "entity.relate"],
  *   },
  * ]);
  * ```
  */
-export const testFollows = (
+export const testCrosses = (
   trailDef: AnyTrail,
-  scenarios: readonly FollowScenario[],
-  options?: TestFollowOptions
+  scenarios: readonly CrossScenario[],
+  options?: TestCrossOptions
 ): void => {
+  const explicitProvisions = options?.provisions;
+
   describe(trailDef.id, () => {
     test.each([...scenarios])(
       '$description',
-      async (scenario: FollowScenario) => {
-        const services = mergeServiceOverrides(
-          await resolveMockServices(trailDef, options?.trails),
+      async (scenario: CrossScenario) => {
+        const provisions = mergeProvisionOverrides(
+          await resolveCrossMockProvisions(trailDef, options?.trails),
           options?.ctx,
-          options?.services
+          explicitProvisions
         );
         await runScenario(
           trailDef,
           scenario,
           options?.ctx,
           options?.trails,
-          services
+          provisions
         );
       }
     );