@ontrails/testing 1.0.0-beta.2 → 1.0.0-beta.21

package/src/examples.ts

@@ -3,15 +3,17 @@
  *
  * 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 hikes with `follows`
- * declarations, checks that every declared follow was called at least once.
+ * determines which check to run per example. For trails with `composes`
+ * declarations, checks that every declared composing was called at least once.
  */
 
 import { describe, expect, test } from 'bun:test';
 
 import type {
-  AnyHike,
-  FollowFn,
+  ComposeFn,
+  ComposeOptions,
+  ExecuteTrailOptions,
+  ResourceOverrideMap,
   Topo,
   TrailExample,
   Trail,
@@ -19,20 +21,10 @@ import type {
 } from '@ontrails/core';
 
 import {
-  AlreadyExistsError,
-  AmbiguousError,
-  AssertionError,
-  AuthError,
-  CancelledError,
-  ConflictError,
-  InternalError,
-  NetworkError,
-  NotFoundError,
-  PermissionError,
-  RateLimitError,
+  buildComposeValidationSchema,
+  executeTrail,
+  parseTrailIdVersionReference,
   Result,
-  TimeoutError,
-  TrailsError,
   ValidationError,
   validateInput,
 } from '@ontrails/core';
@@ -41,39 +33,29 @@ import type { z } from 'zod';
 import {
   assertErrorMatch,
   assertFullMatch,
+  assertPartialMatch,
   assertSchemaMatch,
-  expectOk,
 } from './assertions.js';
-import { mergeTestContext } from './context.js';
-
-// ---------------------------------------------------------------------------
-// Error class name -> constructor map
-// ---------------------------------------------------------------------------
-
-const ERROR_MAP: Record<string, new (...args: never[]) => Error> = {
-  AlreadyExistsError: AlreadyExistsError as new (...args: never[]) => Error,
-  AmbiguousError: AmbiguousError as new (...args: never[]) => Error,
-  AssertionError: AssertionError as new (...args: never[]) => Error,
-  AuthError: AuthError as new (...args: never[]) => Error,
-  CancelledError: CancelledError as new (...args: never[]) => Error,
-  ConflictError: ConflictError as new (...args: never[]) => Error,
-  InternalError: InternalError as new (...args: never[]) => Error,
-  NetworkError: NetworkError as new (...args: never[]) => Error,
-  NotFoundError: NotFoundError as new (...args: never[]) => Error,
-  PermissionError: PermissionError as new (...args: never[]) => Error,
-  RateLimitError: RateLimitError as new (...args: never[]) => Error,
-  TimeoutError: TimeoutError as new (...args: never[]) => Error,
-  TrailsError: TrailsError as unknown as new (...args: never[]) => Error,
-  ValidationError: ValidationError as new (...args: never[]) => Error,
+import {
+  defaultCreatePermit,
+  mergeResourceOverrides,
+  mergeTestContext,
+  normalizeTestExecutionOptions,
+  createMockResources,
+} from './context.js';
+import type { PermittedTrail, TestExecutionOptions } from './context.js';
+import {
+  deriveTrailExampleTargets,
+  isDerivedExample,
+} from './effective-examples.js';
+import type { TrailExampleTarget } from './effective-examples.js';
+import { resolveErrorClass } from './errors.js';
+import { withSignalAssertions } from './signals.js';
+
+type TestingExecuteTrailOptions = ExecuteTrailOptions & {
+  readonly validationSchema?: ReturnType<typeof buildComposeValidationSchema>;
 };
 
-/**
- * Resolve an error class name string to the actual constructor.
- * Falls back to generic Error if the name is not in the core taxonomy.
- */
-const resolveErrorClass = (name: string): (new (...args: never[]) => Error) =>
-  ERROR_MAP[name] ?? (Error as new (...args: never[]) => Error);
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -84,16 +66,14 @@ const assertProgressiveMatch = (
   output: z.ZodType | undefined
 ): void => {
   if (example.expected !== undefined) {
-    assertFullMatch(result, example.expected);
-    return;
+    return assertFullMatch(result, example.expected);
+  }
+  if (example.expectedMatch !== undefined) {
+    return assertPartialMatch(result, example.expectedMatch);
   }
-
   if (example.error !== undefined) {
-    const errorClass = resolveErrorClass(example.error);
-    assertErrorMatch(result, errorClass);
-    return;
+    return assertErrorMatch(result, resolveErrorClass(example.error));
   }
-
   assertSchemaMatch(result, output);
 };
 
@@ -122,152 +102,221 @@ const handleValidationError = (
 };
 
 /**
- * Run a single example against a trail.
- * Handles validation, execution, and assertions.
+ * Apply auto-permit: if the trail declares scoped permits and the context
+ * doesn't already have a permit, create one and merge it into the context.
  */
-const runExample = async (
-  t: Trail<unknown, unknown>,
+const applyAutoPermit = (
+  ctx: TrailContext,
+  trailDef: PermittedTrail,
+  opts: TestExecutionOptions
+): TrailContext => {
+  if (opts.strictPermits) {
+    return ctx;
+  }
+  if (ctx.permit !== undefined) {
+    return ctx;
+  }
+  const create = opts.createPermit ?? defaultCreatePermit;
+  const permit = create(trailDef);
+  if (!permit) {
+    return ctx;
+  }
+  return { ...ctx, permit };
+};
+
+const runTargetExample = async (
+  target: TrailExampleTarget,
   example: TrailExample<unknown, unknown>,
-  output: z.ZodType | undefined,
-  testCtx: TrailContext
+  testCtx: TrailContext,
+  resources?: ResourceOverrideMap,
+  opts?: TestExecutionOptions
 ): Promise<void> => {
-  const validated = validateInput(t.input, example.input);
+  const { output, trail: t } = target;
+  const ctx = opts ? applyAutoPermit(testCtx, t, opts) : testCtx;
+  const signals = withSignalAssertions(ctx, example);
+  const validated = validateInput(target.input, example.input);
 
   if (handleValidationError(validated, example)) {
+    signals.assert();
     return;
   }
-  const validatedInput = expectOk(validated);
 
-  const result = await t.implementation(validatedInput, testCtx);
+  const result = await executeTrail(t, example.input, {
+    ctx: signals.ctx,
+    resources: resources ?? opts?.resources,
+    ...(target.version === undefined ? {} : { version: target.version }),
+  });
   assertProgressiveMatch(result, example, output);
+  signals.assert();
+};
+
+/**
+ * Run a single example against a trail.
+ * Handles validation, execution, and assertions.
+ */
+export const runExample = async (
+  t: Trail<unknown, unknown, unknown>,
+  example: TrailExample<unknown, unknown>,
+  output: z.ZodType | undefined,
+  testCtx: TrailContext,
+  resources?: ResourceOverrideMap,
+  opts?: TestExecutionOptions
+): Promise<void> => {
+  await runTargetExample(
+    {
+      composes: t.composes,
+      current: true,
+      examples: [example],
+      id: t.id,
+      input: t.input,
+      output,
+      trail: t,
+    },
+    example,
+    testCtx,
+    resources,
+    opts
+  );
 };
 
 // ---------------------------------------------------------------------------
-// Follows coverage for hikes
+// Composing coverage for trails with compositions
 // ---------------------------------------------------------------------------
 
 /**
- * Build a recording follow function that tracks which trail IDs are called.
+ * Build a recording compose function that tracks which trail IDs are called.
  *
- * Delegates to `baseFollow` when available, otherwise looks up the trail
+ * Delegates to `baseCompose` 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 createCoverageCompose = (
   called: Set<string>,
-  baseFollow: FollowFn | undefined,
+  baseCompose: ComposeFn | undefined,
   topo: Topo,
-  ctx: TrailContext
-): FollowFn => {
-  const follow = (id: string, input: unknown) => {
-    called.add(id);
+  ctx: TrailContext,
+  resources?: ResourceOverrideMap
+): ComposeFn => {
+  const invokeCompose = async (
+    idOrTrail: string | { readonly id: string },
+    input: unknown,
+    self: ComposeFn,
+    composeOptions?: ComposeOptions | undefined
+  ) => {
+    const parsed =
+      typeof idOrTrail === 'string'
+        ? parseTrailIdVersionReference(idOrTrail)
+        : Result.ok({ id: idOrTrail.id });
+    if (parsed.isErr()) {
+      return parsed;
+    }
+    const parsedVersion =
+      'version' in parsed.value ? parsed.value.version : undefined;
+    if (parsedVersion !== undefined && composeOptions?.version !== undefined) {
+      return Result.err(
+        new ValidationError(
+          `Trail "${parsed.value.id}" version was provided both in the id reference and ctx.compose() options`
+        )
+      );
+    }
 
-    if (baseFollow !== undefined) {
-      return baseFollow(id, input);
+    const { id } = parsed.value;
+    called.add(id);
+    const version = composeOptions?.version ?? parsedVersion;
+
+    if (baseCompose !== undefined) {
+      const forwardedOptions =
+        parsedVersion === undefined
+          ? composeOptions
+          : { ...composeOptions, version: parsedVersion };
+      return await baseCompose(id, input, forwardedOptions);
     }
 
     const trailDef = topo.get(id);
     if (trailDef !== undefined) {
-      const validated = validateInput(trailDef.input, input);
-      if (validated.isErr()) {
-        return Promise.resolve(validated);
-      }
-      return Promise.resolve(trailDef.implementation(validated.value, ctx));
+      const options: TestingExecuteTrailOptions = {
+        ctx: { ...ctx, compose: self },
+        resources,
+        ...(version === undefined ? {} : { version }),
+        validationSchema: buildComposeValidationSchema(trailDef),
+      };
+      return await executeTrail(trailDef, input, options);
     }
 
-    return Promise.resolve(Result.ok());
+    return Result.ok();
   };
-  return follow as FollowFn;
+
+  // Accepts either a trail object (typed compose), a string id (untyped),
+  // or a batch of `[target, input]` tuples.
+  const compose = async function compose(
+    idOrTrail:
+      | string
+      | { readonly id: string }
+      | readonly (readonly [string | { readonly id: string }, unknown])[],
+    inputOrOptions?: unknown,
+    singleOptions?: ComposeOptions
+  ) {
+    if (Array.isArray(idOrTrail)) {
+      return await Promise.all(
+        idOrTrail.map(([target, batchInput]) =>
+          invokeCompose(target, batchInput, compose as ComposeFn)
+        )
+      );
+    }
+
+    return await invokeCompose(
+      idOrTrail as string | { readonly id: string },
+      inputOrOptions,
+      compose as ComposeFn,
+      singleOptions
+    );
+  } as ComposeFn;
+
+  return compose;
 };
 
 /**
- * Run a single example against a hike, recording follow calls.
+ * Run a single example against a trail with compositions, recording compose calls.
  */
-const runHikeExample = async (
-  hikeDef: AnyHike,
+const runCompositionExample = async (
+  target: TrailExampleTarget,
   example: TrailExample<unknown, unknown>,
-  output: z.ZodType | undefined,
   baseCtx: TrailContext,
   called: Set<string>,
-  topo: Topo
+  topo: Topo,
+  resources?: ResourceOverrideMap,
+  opts?: TestExecutionOptions
 ): Promise<void> => {
-  const validated = validateInput(hikeDef.input, example.input);
+  const { output, trail: trailDef } = target;
+  const permittedCtx = opts
+    ? applyAutoPermit(baseCtx, trailDef, opts)
+    : baseCtx;
+  const signals = withSignalAssertions(permittedCtx, example);
+  const validated = validateInput(target.input, example.input);
 
   if (handleValidationError(validated, example)) {
+    signals.assert();
     return;
   }
-  const validatedInput = expectOk(validated);
-
-  const follow = createCoverageFollow(called, baseCtx.follow, topo, baseCtx);
-  const testCtx: TrailContext = { ...baseCtx, follow };
-
-  const result = await hikeDef.implementation(validatedInput, testCtx);
-  assertProgressiveMatch(result, example, output);
-};
-
-// ---------------------------------------------------------------------------
-// Hike entry with examples pre-validated
-// ---------------------------------------------------------------------------
-
-interface HikeWithExamples {
-  readonly hikeDef: AnyHike;
-  readonly hikeId: string;
-  readonly examples: readonly TrailExample<unknown, unknown>[];
-}
-
-const collectHikesWithExamples = (app: Topo): readonly HikeWithExamples[] =>
-  [...app.hikes]
-    .filter(([, h]) => h.examples !== undefined && h.examples.length > 0)
-    .map(([hikeId, hikeDef]) => ({
-      examples: hikeDef.examples as readonly TrailExample<unknown, unknown>[],
-      hikeDef,
-      hikeId,
-    }));
 
-// ---------------------------------------------------------------------------
-// Hike example describe blocks
-// ---------------------------------------------------------------------------
-
-/**
- * Generate describe/test blocks for hikes with follows coverage.
- *
- * Always uses a recording follow so that follows coverage can be checked.
- * Hikes without `follows` still run their examples but skip the coverage test.
- */
-const describeHikeExamples = (
-  hikesWithExamples: readonly HikeWithExamples[],
-  resolveCtx: () => Partial<TrailContext> | undefined,
-  topo: Topo
-): void => {
-  if (hikesWithExamples.length === 0) {
-    return;
-  }
-
-  describe.each([...hikesWithExamples])('$hikeId', ({ hikeDef, examples }) => {
-    const called = new Set<string>();
-
-    test.each([...examples])(
-      'example: $name',
-      async (example: TrailExample<unknown, unknown>) => {
-        const baseCtx = mergeTestContext(resolveCtx());
-        await runHikeExample(
-          hikeDef,
-          example,
-          hikeDef.output,
-          baseCtx,
-          called,
-          topo
-        );
-      }
-    );
-
-    if (hikeDef.follows.length > 0) {
-      test('follows coverage', () => {
-        const uncovered = hikeDef.follows.filter((id) => !called.has(id));
-        expect(uncovered).toEqual([]);
-      });
-    }
+  const compose = createCoverageCompose(
+    called,
+    signals.ctx.compose,
+    topo,
+    signals.ctx,
+    resources
+  );
+  const testCtx: TrailContext = { ...signals.ctx, compose };
+
+  // Top-level trail validates against trail.input (not merged composeInput).
+  // Merged validation only applies to compose targets in executeFromMap/createCoverageCompose.
+  const result = await executeTrail(trailDef, example.input, {
+    ctx: testCtx,
+    resources: resources ?? opts?.resources,
+    ...(target.version === undefined ? {} : { version: target.version }),
   });
+  assertProgressiveMatch(result, example, output);
+  signals.assert();
 };
 
 // ---------------------------------------------------------------------------
@@ -277,38 +326,114 @@ const describeHikeExamples = (
 /**
  * Generate describe/test blocks for every trail example in the app.
  *
- * For hikes with `follows` declarations and examples, also verifies that
- * every declared follow ID was called at least once across all examples.
+ * For trails with `composes` declarations and examples, also verifies that
+ * every declared composed ID was called at least once across all examples.
  *
  * One line in your test file:
  * ```ts
- * testExamples(app);
+ * testExamples(graph);
  * ```
  */
 export const testExamples = (
   app: Topo,
-  ctxOrFactory?: Partial<TrailContext> | (() => Partial<TrailContext>)
+  ctxOrFactory?:
+    | Partial<TrailContext>
+    | TestExecutionOptions
+    | (() => Partial<TrailContext> | TestExecutionOptions)
 ): void => {
-  const resolveCtx =
+  const resolveInput =
     typeof ctxOrFactory === 'function' ? ctxOrFactory : () => ctxOrFactory;
-  const trailEntries = [...app.trails];
-
-  describe.each(trailEntries)('%s', (_id, trailDef) => {
-    const t = trailDef as Trail<unknown, unknown>;
-    if (t.examples === undefined || t.examples.length === 0) {
-      return;
-    }
+  const withExamples = (app.list() as Trail<unknown, unknown, unknown>[])
+    .flatMap(deriveTrailExampleTargets)
+    .filter((target) => target.examples.length > 0);
+  const simpleTrails = withExamples.filter((t) => t.composes.length === 0);
+  const compositionTrails = withExamples.filter((t) => t.composes.length > 0);
+
+  // Simple trails: run examples directly
+  if (simpleTrails.length > 0) {
+    describe.each(simpleTrails)('$id', (t) => {
+      const { examples } = t;
+      if (!examples) {
+        return;
+      }
 
-    const { examples, output } = t;
+      test.each([...examples])(
+        'example: $name',
+        async (example: TrailExample<unknown, unknown>) => {
+          const resolved = normalizeTestExecutionOptions(resolveInput());
+          const resources = mergeResourceOverrides(
+            await createMockResources(app),
+            resolved.ctx,
+            resolved.resources
+          );
+          const testCtx = mergeTestContext(resolved.ctx);
+          await runTargetExample(t, example, testCtx, resources, resolved);
+        }
+      );
+    });
+  }
 
-    test.each([...examples])(
-      'example: $name',
-      async (example: TrailExample<unknown, unknown>) => {
-        const testCtx = mergeTestContext(resolveCtx());
-        await runExample(t, example, output, testCtx);
+  // Composition trails: use recording compose and check coverage.
+  //
+  // Composing coverage only runs against AUTHORED examples. Contour-derived
+  // fixtures are opportunistic coverage that may not exercise every
+  // `ctx.compose()` branch in the trail, so asserting coverage against them
+  // would produce false failures for trails whose authored intent was a
+  // single path. When a trail has zero authored examples the coverage
+  // assertion is skipped entirely — the derived-example runs still
+  // execute, but they are not required to cover declared compositions.
+  if (compositionTrails.length > 0) {
+    describe.each(compositionTrails)('$id', (t) => {
+      const { examples } = t;
+      if (!examples) {
+        return;
       }
-    );
-  });
 
-  describeHikeExamples(collectHikesWithExamples(app), resolveCtx, app);
+      const composedFromAuthored = new Set<string>();
+      const hasAuthoredExamples = examples.some(
+        (example) => !isDerivedExample(example)
+      );
+
+      // Only record compose calls from authored examples. Derived fixtures
+      // execute normally but do not contribute to coverage — the sink map
+      // puts each example in the right bucket without an inline
+      // conditional inside the test body.
+      const discardSink = new Set<string>();
+      const pickCoverageSink = (
+        example: TrailExample<unknown, unknown>
+      ): Set<string> =>
+        isDerivedExample(example) ? discardSink : composedFromAuthored;
+
+      test.each([...examples])(
+        'example: $name',
+        async (example: TrailExample<unknown, unknown>) => {
+          const resolved = normalizeTestExecutionOptions(resolveInput());
+          const resources = mergeResourceOverrides(
+            await createMockResources(app),
+            resolved.ctx,
+            resolved.resources
+          );
+          const baseCtx = mergeTestContext(resolved.ctx);
+          await runCompositionExample(
+            t,
+            example,
+            baseCtx,
+            pickCoverageSink(example),
+            app,
+            resources,
+            resolved
+          );
+        }
+      );
+
+      if (hasAuthoredExamples) {
+        test('composing coverage', () => {
+          const uncovered = t.composes.filter(
+            (id) => !composedFromAuthored.has(id)
+          );
+          expect(uncovered).toEqual([]);
+        });
+      }
+    });
+  }
 };