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

package/src/context.ts

@@ -4,11 +4,16 @@
 
 import type {
   CrossFn,
-  ProvisionOverrideMap,
+  ResourceOverrideMap,
   Topo,
   TrailContext,
 } from '@ontrails/core';
-import { Result, createProvisionLookup } from '@ontrails/core';
+import {
+  Result,
+  buildCrossValidationSchema,
+  createResourceLookup,
+  passthroughTrace,
+} from '@ontrails/core';
 
 import { createTestLogger } from './logger.js';
 import type { TestTrailContextOptions } from './types.js';
@@ -39,10 +44,11 @@ export const createTestContext = (
     extensions: undefined,
     logger: overrides?.logger ?? createTestLogger(),
     requestId: overrides?.requestId ?? 'test-request-001',
+    trace: overrides?.trace ?? passthroughTrace,
     workspaceRoot: cwd,
   } as MutableTrailContext;
-  const lookup = createProvisionLookup(() => ctx);
-  ctx.provision = lookup;
+  const lookup = createResourceLookup(() => ctx);
+  ctx.resource = lookup;
   return ctx;
 };
 
@@ -54,14 +60,14 @@ export interface CreateCrossContextOptions {
   readonly responses?: Record<string, Result<unknown, Error>> | undefined;
 }
 
-/** Minimal permit shape returned by the mint function. */
-export interface MintedPermit {
+/** Minimal permit shape returned by the create function. */
+export interface MinimalPermit {
   readonly id: string;
   readonly scopes: readonly string[];
 }
 
-/** Trail shape consumed by the mint function — avoids importing permits. */
-export interface MintableTrail {
+/** Trail shape consumed by the create function — avoids importing permits. */
+export interface PermittedTrail {
   readonly permit?:
     | { readonly scopes: readonly string[] }
     | 'public'
@@ -70,21 +76,21 @@ export interface MintableTrail {
 
 export interface TestExecutionOptions {
   readonly ctx?: Partial<TrailContext> | undefined;
-  readonly provisions?: ProvisionOverrideMap | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
   /**
-   * When true, disables automatic permit minting. Tests must provide
+   * When true, disables automatic permit creation. Tests must provide
    * explicit permits.
    */
   readonly strictPermits?: boolean | undefined;
   /**
-   * Optional function to mint a test permit for a trail. When provided,
+   * Optional function to create 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.
+   * Returning `undefined` skips creation 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;
+  readonly createPermit?: (trail: PermittedTrail) => MinimalPermit | undefined;
 }
 
 /**
@@ -105,7 +111,10 @@ export const createCrossContext = (
   options?: CreateCrossContextOptions
 ): CrossFn => {
   const responses = options?.responses ?? {};
-  return <O>(id: string, _input: unknown): Promise<Result<O, Error>> => {
+  const respondToCross = <O>(
+    idOrTrail: string | { readonly id: string }
+  ): Promise<Result<O, Error>> => {
+    const id = typeof idOrTrail === 'string' ? idOrTrail : idOrTrail.id;
     const response = responses[id];
     if (response === undefined) {
       return Promise.resolve(
@@ -117,15 +126,31 @@ export const createCrossContext = (
     }
     return Promise.resolve(response as Result<O, Error>);
   };
+  const cross = (async (
+    idOrTrail:
+      | string
+      | { readonly id: string }
+      | readonly (readonly [string | { readonly id: string }, unknown])[],
+    _input?: unknown
+  ) => {
+    if (Array.isArray(idOrTrail)) {
+      return await Promise.all(
+        idOrTrail.map(([target]) => respondToCross(target))
+      );
+    }
+
+    return await respondToCross(idOrTrail as string | { readonly id: string });
+  }) as CrossFn;
+  return cross;
 };
 
 /**
- * Default permit minter — reads `trail.permit.scopes` and produces a
+ * Default permit creator — reads `trail.permit.scopes` and produces a
  * minimal permit object. No dependency on `@ontrails/permits`.
  */
-export const defaultMintPermit = (
-  trail: MintableTrail
-): MintedPermit | undefined => {
+export const defaultCreatePermit = (
+  trail: PermittedTrail
+): MinimalPermit | undefined => {
   if (!trail.permit || trail.permit === 'public') {
     return undefined;
   }
@@ -137,41 +162,45 @@ const isTestExecutionOptions = (
 ): input is TestExecutionOptions =>
   input !== undefined &&
   (Object.hasOwn(input, 'ctx') ||
-    Object.hasOwn(input, 'provisions') ||
+    Object.hasOwn(input, 'resources') ||
     Object.hasOwn(input, 'strictPermits') ||
-    Object.hasOwn(input, 'mintPermit'));
+    Object.hasOwn(input, 'createPermit'));
 
 export const normalizeTestExecutionOptions = (
   input?: Partial<TrailContext> | TestExecutionOptions
 ): TestExecutionOptions =>
   isTestExecutionOptions(input) ? input : { ctx: input };
 
-export const mergeProvisionOverrides = (
-  autoResolved: ProvisionOverrideMap,
+export const mergeResourceOverrides = (
+  autoResolved: ResourceOverrideMap,
   ctx: Partial<TrailContext> | undefined,
-  explicit: ProvisionOverrideMap | undefined
-): ProvisionOverrideMap => ({
+  explicit: ResourceOverrideMap | undefined
+): ResourceOverrideMap => ({
   ...autoResolved,
   ...ctx?.extensions,
   ...explicit,
 });
 
-const buildMockProvisions = async (
-  app: Topo
-): Promise<ProvisionOverrideMap> => {
-  const provisions: Record<string, unknown> = {};
-  for (const declaredProvision of app.listProvisions()) {
-    if (!declaredProvision.mock) {
+const buildMockResources = async (app: Topo): Promise<ResourceOverrideMap> => {
+  const resources: Record<string, unknown> = {};
+  for (const declaredResource of app.listResources()) {
+    if (declaredResource.unmockable !== undefined) {
+      continue;
+    }
+    if (!declaredResource.mock) {
       continue;
     }
-    provisions[declaredProvision.id] = await declaredProvision.mock();
+    resources[declaredResource.id] = await declaredResource.mock();
   }
-  return provisions;
+  return resources;
 };
 
-export const resolveMockProvisions = async (
+export const createMockResources = async (
   app: Topo
-): Promise<ProvisionOverrideMap> => await buildMockProvisions(app);
+): Promise<ResourceOverrideMap> => await buildMockResources(app);
+
+// Re-export from core so existing consumers of this module continue to work.
+export { buildCrossValidationSchema };
 
 /**
  * Merge a Partial<TrailContext> into a test context.
@@ -179,20 +208,20 @@ export const resolveMockProvisions = async (
  */
 export const mergeTestContext = (
   ctx?: Partial<TrailContext>,
-  provisions?: ProvisionOverrideMap
+  resources?: ResourceOverrideMap
 ): TrailContext => {
   const base = createTestContext();
   const extensions = {
     ...base.extensions,
     ...ctx?.extensions,
-    ...provisions,
+    ...resources,
   };
   const merged = {
     ...base,
     ...ctx,
     extensions: Object.keys(extensions).length === 0 ? undefined : extensions,
   } as MutableTrailContext;
-  const lookup = createProvisionLookup(() => merged);
-  merged.provision = lookup;
+  const lookup = createResourceLookup(() => merged);
+  merged.resource = lookup;
   return merged;
 };

package/src/contracts.ts

@@ -14,29 +14,18 @@ import type { z } from 'zod';
 
 import { expectOk } from './assertions.js';
 import {
-  mergeProvisionOverrides,
+  mergeResourceOverrides,
   mergeTestContext,
   normalizeTestExecutionOptions,
-  resolveMockProvisions,
+  createMockResources,
 } from './context.js';
 import type { TestExecutionOptions } from './context.js';
+import { deriveTrailExamples } from './effective-examples.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** 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 { crosses?: readonly string[] };
-  if (!spec.crosses || spec.crosses.length === 0) {
-    return false;
-  }
-  return !normalizeTestExecutionOptions(resolveCtx()).ctx?.cross;
-};
-
 const validateOutputSchema = (
   outputSchema: z.ZodType,
   value: unknown,
@@ -71,20 +60,21 @@ export const testContracts = (
 ): void => {
   const resolveInput =
     typeof ctxOrFactory === 'function' ? ctxOrFactory : () => ctxOrFactory;
-  const allEntries = app.list() as Trail<unknown, unknown>[];
+  const allEntries = (app.list() as Trail<unknown, unknown, unknown>[]).map(
+    (trailDef) => ({
+      ...trailDef,
+      examples: deriveTrailExamples(trailDef),
+    })
+  );
 
   describe('contracts', () => {
     describe.each(allEntries)('$id', (t) => {
       if (t.output === undefined) {
         return;
       }
-      if (t.examples === undefined || t.examples.length === 0) {
+      if (t.examples.length === 0) {
         return;
       }
-      if (needsCrossContext(t, resolveInput)) {
-        return;
-      }
-
       const { examples, output: outputSchema } = t;
       const successExamples = examples.filter((e) => e.error === undefined);
 
@@ -92,10 +82,10 @@ export const testContracts = (
         'contract: $name',
         async (example: TrailExample<unknown, unknown>) => {
           const resolved = normalizeTestExecutionOptions(resolveInput());
-          const provisions = mergeProvisionOverrides(
-            await resolveMockProvisions(app),
+          const resources = mergeResourceOverrides(
+            await createMockResources(app),
             resolved.ctx,
-            resolved.provisions
+            resolved.resources
           );
           const testCtx = mergeTestContext(resolved.ctx);
 
@@ -104,7 +94,8 @@ export const testContracts = (
 
           const result = await executeTrail(t, example.input, {
             ctx: testCtx,
-            provisions,
+            resources,
+            topo: app,
           });
           const resultValue = expectOk(result);
 

package/src/crosses.ts

@@ -10,10 +10,11 @@ import { describe, expect, test } from 'bun:test';
 import type {
   AnyTrail,
   CrossFn,
-  ProvisionOverrideMap,
+  ResourceOverrideMap,
   TrailContext,
 } from '@ontrails/core';
 import {
+  buildCrossValidationSchema,
   executeTrail,
   InternalError,
   Result,
@@ -26,7 +27,7 @@ import {
   assertFullMatch,
   assertSchemaMatch,
 } from './assertions.js';
-import { mergeProvisionOverrides, mergeTestContext } from './context.js';
+import { mergeResourceOverrides, mergeTestContext } from './context.js';
 import type { CrossScenario } from './types.js';
 
 // ---------------------------------------------------------------------------
@@ -38,21 +39,21 @@ interface CrossRecord {
   readonly input: unknown;
 }
 
-const collectDeclaredProvisions = (
+const collectDeclaredResources = (
   trailDef: AnyTrail,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined
-): AnyTrail['provisions'] => {
-  const seenProvisionIds = new Set<string>();
+): AnyTrail['resources'] => {
+  const seenResourceIds = new Set<string>();
   const seenTrailIds = new Set<string>();
-  const provisions: AnyTrail['provisions'][number][] = [];
+  const resources: AnyTrail['resources'][number][] = [];
 
   const collect = (candidate: AnyTrail): void => {
-    for (const declaredProvision of candidate.provisions) {
-      if (seenProvisionIds.has(declaredProvision.id)) {
+    for (const declaredResource of candidate.resources) {
+      if (seenResourceIds.has(declaredResource.id)) {
         continue;
       }
-      seenProvisionIds.add(declaredProvision.id);
-      provisions.push(declaredProvision);
+      seenResourceIds.add(declaredResource.id);
+      resources.push(declaredResource);
     }
   };
 
@@ -71,26 +72,26 @@ const collectDeclaredProvisions = (
   };
 
   visit(trailDef);
-  return provisions;
+  return resources;
 };
 
-const resolveCrossMockProvisions = async (
+const resolveCrossMockResources = async (
   trailDef: AnyTrail,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined
-): Promise<ProvisionOverrideMap> => {
-  const provisions: Record<string, unknown> = {};
+): Promise<ResourceOverrideMap> => {
+  const resources: Record<string, unknown> = {};
 
-  for (const declaredProvision of collectDeclaredProvisions(
+  for (const declaredResource of collectDeclaredResources(
     trailDef,
     trailsMap
   )) {
-    if (!declaredProvision.mock) {
+    if (!declaredResource.mock) {
       continue;
     }
-    provisions[declaredProvision.id] = await declaredProvision.mock();
+    resources[declaredResource.id] = await declaredResource.mock();
   }
 
-  return provisions;
+  return resources;
 };
 
 // ---------------------------------------------------------------------------
@@ -143,15 +144,12 @@ const tryInjectError = (
   return Result.err(new Error(errorName));
 };
 
-/**
- * Execute a trail from the map, validating input first.
- */
 const executeFromMap = (
   id: string,
   input: unknown,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
   ctx: TrailContext,
-  provisions: ProvisionOverrideMap | undefined,
+  resources: ResourceOverrideMap | undefined,
   cross?: CrossFn
 ): Result<unknown, Error> | Promise<Result<unknown, Error>> | undefined => {
   const trailDef = trailsMap?.get(id);
@@ -162,14 +160,36 @@ const executeFromMap = (
   const nestedCtx = cross ? { ...ctx, cross } : ctx;
   return executeTrail(trailDef, input, {
     ctx: nestedCtx,
-    provisions,
+    resources,
+    validationSchema: buildCrossValidationSchema(trailDef),
   });
 };
 
+/** Extract trail ID from either a trail object or a string. */
+const resolveCrossId = (idOrTrail: string | { readonly id: string }): string =>
+  typeof idOrTrail === 'string' ? idOrTrail : idOrTrail.id;
+
 // ---------------------------------------------------------------------------
 // Cross factory
 // ---------------------------------------------------------------------------
 
+/** Delegate to baseCross, executeFromMap, or fall back to Result.ok(). */
+const delegateCross = (
+  id: string,
+  input: unknown,
+  baseCross: CrossFn | undefined,
+  trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
+  ctx: TrailContext,
+  resources: ResourceOverrideMap | undefined,
+  self: CrossFn
+): Promise<Result<unknown, Error>> => {
+  if (baseCross !== undefined) {
+    return baseCross(id, input);
+  }
+  const executed = executeFromMap(id, input, trailsMap, ctx, resources, self);
+  return Promise.resolve(executed ?? Result.ok());
+};
+
 /**
  * Build a recording cross function that optionally injects errors.
  */
@@ -179,37 +199,59 @@ const createRecordingCross = (
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
   baseCross: CrossFn | undefined,
   ctx: TrailContext,
-  provisions: ProvisionOverrideMap | undefined
+  resources: ResourceOverrideMap | 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 cross = (id: string, input: unknown) => {
+  const invokeCross = async (
+    idOrTrail: string | { readonly id: string },
+    input: unknown,
+    self: CrossFn
+  ) => {
+    const id = resolveCrossId(idOrTrail);
     trace.push({ id, input });
 
     const injected = tryInjectError(id, scenario, trailsMap);
     if (injected !== undefined) {
-      return Promise.resolve(injected);
+      return injected;
     }
 
-    if (baseCross !== undefined) {
-      return baseCross(id, input);
-    }
-
-    const executed = executeFromMap(
+    return await delegateCross(
       id,
       input,
+      baseCross,
       trailsMap,
       ctx,
-      provisions,
-      cross as CrossFn
+      resources,
+      self
     );
-    if (executed !== undefined) {
-      return Promise.resolve(executed);
+  };
+
+  // Accepts either a trail object (typed cross), a string id (untyped),
+  // or a batch of `[target, input]` tuples.
+  const cross = async function cross(
+    idOrTrail:
+      | string
+      | { readonly id: string }
+      | readonly (readonly [string | { readonly id: string }, unknown])[],
+    input?: unknown
+  ) {
+    if (Array.isArray(idOrTrail)) {
+      return await Promise.all(
+        idOrTrail.map(([target, batchInput]) =>
+          invokeCross(target, batchInput, cross as CrossFn)
+        )
+      );
     }
 
-    return Promise.resolve(Result.ok());
-  };
-  return cross as CrossFn;
+    return await invokeCross(
+      idOrTrail as string | { readonly id: string },
+      input,
+      cross as CrossFn
+    );
+  } as CrossFn;
+
+  return cross;
 };
 
 // ---------------------------------------------------------------------------
@@ -280,7 +322,7 @@ const buildTestContext = (
   scenario: CrossScenario,
   ctx: Partial<TrailContext> | undefined,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
-  provisions: ProvisionOverrideMap | undefined
+  resources: ResourceOverrideMap | undefined
 ): { trace: CrossRecord[]; testCtx: TrailContext } => {
   const trace: CrossRecord[] = [];
   const baseCtx = mergeTestContext(ctx);
@@ -290,7 +332,7 @@ const buildTestContext = (
     trailsMap,
     baseCtx.cross,
     baseCtx,
-    provisions
+    resources
   );
   return { testCtx: { ...baseCtx, cross }, trace };
 };
@@ -300,7 +342,7 @@ const runScenario = async (
   scenario: CrossScenario,
   ctx: Partial<TrailContext> | undefined,
   trailsMap: ReadonlyMap<string, AnyTrail> | undefined,
-  provisions: ProvisionOverrideMap | undefined
+  resources: ResourceOverrideMap | undefined
 ): Promise<void> => {
   const validated = validateInput(trailDef.input, scenario.input);
   if (handleValidationError(validated, scenario)) {
@@ -311,11 +353,11 @@ const runScenario = async (
     scenario,
     ctx,
     trailsMap,
-    provisions
+    resources
   );
   const result = await executeTrail(trailDef, scenario.input, {
     ctx: testCtx,
-    provisions,
+    resources,
   });
   assertCrossTrace(trace, scenario);
   assertScenarioResult(result, scenario, trailDef);
@@ -330,11 +372,11 @@ export interface TestCrossOptions {
   /** Partial context overrides. */
   readonly ctx?: Partial<TrailContext> | undefined;
   /**
-   * Explicit provision overrides merged on top of auto-resolved mocks for every
+   * Explicit resource overrides merged on top of auto-resolved mocks for every
    * scenario. Values are passed by reference — provide immutable objects, or
-   * use `mock()` on the provision definition to get a fresh instance per run.
+   * use `mock()` on the resource definition to get a fresh instance per run.
    */
-  readonly provisions?: ProvisionOverrideMap | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
   /** Map of trail ID to trail definition, used for injectFromExample. */
   readonly trails?: ReadonlyMap<string, AnyTrail> | undefined;
 }
@@ -359,23 +401,23 @@ export const testCrosses = (
   scenarios: readonly CrossScenario[],
   options?: TestCrossOptions
 ): void => {
-  const explicitProvisions = options?.provisions;
+  const explicitResources = options?.resources;
 
   describe(trailDef.id, () => {
     test.each([...scenarios])(
       '$description',
       async (scenario: CrossScenario) => {
-        const provisions = mergeProvisionOverrides(
-          await resolveCrossMockProvisions(trailDef, options?.trails),
+        const resources = mergeResourceOverrides(
+          await resolveCrossMockResources(trailDef, options?.trails),
           options?.ctx,
-          explicitProvisions
+          explicitResources
         );
         await runScenario(
           trailDef,
           scenario,
           options?.ctx,
           options?.trails,
-          provisions
+          resources
         );
       }
     );