@ontrails/testing 1.0.0-beta.3 → 1.0.0-beta.32

package/src/context.ts

@@ -2,11 +2,26 @@
  * Test context factory for creating TrailContext instances suitable for testing.
  */
 
-import type { TrailContext } from '@ontrails/core';
+import type {
+  ComposeFn,
+  ResourceOverrideMap,
+  Topo,
+  TrailContext,
+} from '@ontrails/core';
+import {
+  Result,
+  buildComposeValidationSchema,
+  createResourceLookup,
+  passthroughTrace,
+} from '@ontrails/core';
 
 import { createTestLogger } from './logger.js';
 import type { TestTrailContextOptions } from './types.js';
 
+type MutableTrailContext = {
+  -readonly [K in keyof TrailContext]: TrailContext[K];
+};
+
 // ---------------------------------------------------------------------------
 // createTestContext
 // ---------------------------------------------------------------------------
@@ -16,27 +31,198 @@ import type { TestTrailContextOptions } from './types.js';
  *
  * - `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 => ({
-  env: overrides?.env ?? { TRAILS_ENV: 'test' },
-  logger: overrides?.logger ?? createTestLogger(),
-  requestId: overrides?.requestId ?? 'test-request-001',
-  signal: overrides?.signal ?? new AbortController().signal,
-  workspaceRoot: overrides?.cwd ?? process.cwd(),
+): 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',
+    trace: overrides?.trace ?? passthroughTrace,
+    workspaceRoot: cwd,
+  } as MutableTrailContext;
+  const lookup = createResourceLookup(() => ctx);
+  ctx.resource = lookup;
+  return ctx;
+};
+
+// ---------------------------------------------------------------------------
+// createComposeContext
+// ---------------------------------------------------------------------------
+
+export interface CreateComposeContextOptions {
+  readonly responses?: Record<string, Result<unknown, Error>> | undefined;
+}
+
+/** Minimal permit shape returned by the create function. */
+export interface MinimalPermit {
+  readonly id: string;
+  readonly scopes: readonly string[];
+}
+
+/** Trail shape consumed by the create function — avoids importing permits. */
+export interface PermittedTrail {
+  readonly permit?:
+    | { readonly scopes: readonly string[] }
+    | 'public'
+    | undefined;
+}
+
+export interface TestExecutionOptions {
+  readonly ctx?: Partial<TrailContext> | undefined;
+  readonly resources?: ResourceOverrideMap | undefined;
+  /**
+   * When true, disables automatic permit creation. Tests must provide
+   * explicit permits.
+   */
+  readonly strictPermits?: boolean | undefined;
+  /**
+   * 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 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 createPermit?: (trail: PermittedTrail) => MinimalPermit | undefined;
+}
+
+/**
+ * Create a mock `ComposeFn` 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 compose = createComposeContext({
+ *   responses: { 'entity.add': Result.ok({ id: '1', name: 'Alpha' }) },
+ * });
+ * const ctx = { ...createTestContext(), compose };
+ * ```
+ */
+export const createComposeContext = (
+  options?: CreateComposeContextOptions
+): ComposeFn => {
+  const responses = options?.responses ?? {};
+  const respondToCompose = <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(
+        Result.err(
+          new Error(`No mock response for compose("${id}")`)
+        ) as Result<O, Error>
+      );
+    }
+    return Promise.resolve(response as Result<O, Error>);
+  };
+  const compose = (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]) => respondToCompose(target))
+      );
+    }
+
+    return await respondToCompose(
+      idOrTrail as string | { readonly id: string }
+    );
+  }) as ComposeFn;
+  return compose;
+};
+
+/**
+ * Default permit creator — reads `trail.permit.scopes` and produces a
+ * minimal permit object. No dependency on `@ontrails/permits`.
+ */
+export const defaultCreatePermit = (
+  trail: PermittedTrail
+): MinimalPermit | 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, 'resources') ||
+    Object.hasOwn(input, 'strictPermits') ||
+    Object.hasOwn(input, 'createPermit'));
+
+export const normalizeTestExecutionOptions = (
+  input?: Partial<TrailContext> | TestExecutionOptions
+): TestExecutionOptions =>
+  isTestExecutionOptions(input) ? input : { ctx: input };
+
+export const mergeResourceOverrides = (
+  autoResolved: ResourceOverrideMap,
+  ctx: Partial<TrailContext> | undefined,
+  explicit: ResourceOverrideMap | undefined
+): ResourceOverrideMap => ({
+  ...autoResolved,
+  ...ctx?.extensions,
+  ...explicit,
 });
 
+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;
+    }
+    resources[declaredResource.id] = await declaredResource.mock();
+  }
+  return resources;
+};
+
+export const createMockResources = async (
+  app: Topo
+): Promise<ResourceOverrideMap> => await buildMockResources(app);
+
+// Re-export from core so existing consumers of this module continue to work.
+export { buildComposeValidationSchema };
+
 /**
  * Merge a Partial<TrailContext> into a test context.
  * Used internally when the public API accepts Partial<TrailContext>.
  */
-export const mergeTestContext = (ctx?: Partial<TrailContext>): TrailContext => {
-  if (ctx === undefined) {
-    return createTestContext();
-  }
-
+export const mergeTestContext = (
+  ctx?: Partial<TrailContext>,
+  resources?: ResourceOverrideMap
+): TrailContext => {
   const base = createTestContext();
-  return { ...base, ...ctx };
+  const extensions = {
+    ...base.extensions,
+    ...ctx?.extensions,
+    ...resources,
+  };
+  const merged = {
+    ...base,
+    ...ctx,
+    extensions: Object.keys(extensions).length === 0 ? undefined : extensions,
+  } as MutableTrailContext;
+  const lookup = createResourceLookup(() => merged);
+  merged.resource = lookup;
+  return merged;
 };

package/src/contracts.ts

@@ -1,36 +1,32 @@
 /**
  * testContracts — output schema verification.
  *
- * For every trail and hike that has both examples and an output schema,
- * run each example and validate the implementation output against
+ * For every trail that has both examples and an output schema,
+ * run each example and validate the Result.ok value against
  * the declared schema.
  */
 
 import { describe, test } from 'bun:test';
 
 import type { Topo, TrailExample, Trail, TrailContext } from '@ontrails/core';
-import { formatZodIssues, validateInput } from '@ontrails/core';
+import { executeTrail, formatZodIssues, validateInput } from '@ontrails/core';
 import type { z } from 'zod';
 
 import { expectOk } from './assertions.js';
-import { mergeTestContext } from './context.js';
+import {
+  mergeResourceOverrides,
+  mergeTestContext,
+  normalizeTestExecutionOptions,
+  createMockResources,
+} from './context.js';
+import type { TestExecutionOptions } from './context.js';
+import type { TrailExampleTarget } from './effective-examples.js';
+import { deriveTrailExampleTargets } from './effective-examples.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** Check if a trail/hike requires follow() but the context doesn't provide it. */
-const needsFollowContext = (
-  t: unknown,
-  resolveCtx: () => Partial<TrailContext> | undefined
-): boolean => {
-  const spec = t as { follows?: readonly string[] };
-  if (!spec.follows || spec.follows.length === 0) {
-    return false;
-  }
-  return !resolveCtx()?.follow;
-};
-
 const validateOutputSchema = (
   outputSchema: z.ZodType,
   value: unknown,
@@ -46,48 +42,63 @@ const validateOutputSchema = (
   }
 };
 
+type ContractExampleTarget = TrailExampleTarget & {
+  readonly output: z.ZodType;
+};
+
+const hasContractExamples = (
+  target: TrailExampleTarget
+): target is ContractExampleTarget =>
+  target.output !== undefined && target.examples.length > 0;
+
 // ---------------------------------------------------------------------------
 // testContracts
 // ---------------------------------------------------------------------------
 
 /**
- * Verify that every trail and hike implementation output matches its declared
- * output schema. Catches implementation-schema drift.
+ * Verify that every successful trail result matches its declared
+ * output schema. Catches output-schema drift.
  *
- * Trails and hikes without output schemas or examples are skipped.
+ * Trails without output schemas or examples are skipped.
  */
 export const testContracts = (
   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 allEntries = app.list() as Trail<unknown, unknown>[];
+  const allEntries = (app.list() as Trail<unknown, unknown, unknown>[])
+    .flatMap(deriveTrailExampleTargets)
+    .filter(hasContractExamples);
 
   describe('contracts', () => {
     describe.each(allEntries)('$id', (t) => {
-      if (t.output === undefined) {
-        return;
-      }
-      if (t.examples === undefined || t.examples.length === 0) {
-        return;
-      }
-      if (needsFollowContext(t, resolveCtx)) {
-        return;
-      }
-
       const { examples, output: outputSchema } = t;
       const successExamples = examples.filter((e) => e.error === undefined);
 
       test.each(successExamples)(
         'contract: $name',
         async (example: TrailExample<unknown, unknown>) => {
-          const testCtx = mergeTestContext(resolveCtx());
+          const resolved = normalizeTestExecutionOptions(resolveInput());
+          const resources = mergeResourceOverrides(
+            await createMockResources(app),
+            resolved.ctx,
+            resolved.resources
+          );
+          const testCtx = mergeTestContext(resolved.ctx);
 
           const validated = validateInput(t.input, example.input);
-          const validatedInput = expectOk(validated);
+          expectOk(validated);
 
-          const result = await t.implementation(validatedInput, testCtx);
+          const result = await executeTrail(t.trail, example.input, {
+            ctx: testCtx,
+            resources,
+            topo: app,
+            ...(t.version === undefined ? {} : { version: t.version }),
+          });
           const resultValue = expectOk(result);
 
           validateOutputSchema(outputSchema, resultValue, t.id, example.name);

package/src/detours.ts

@@ -1,42 +1,179 @@
 /**
- * testDetours — verify that all detour targets exist in the topo.
+ * testDetours — validate the live detour contract for every trail.
  *
- * Pure structural validation. No implementation execution needed.
+ * Pure structural validation. No blaze or detour recovery execution needed.
  */
 
-import { describe, expect, test } from 'bun:test';
+import { describe, test } from 'bun:test';
 
+import { TrailsError } from '@ontrails/core';
 import type { Topo, Trail } from '@ontrails/core';
 
-// ---------------------------------------------------------------------------
-// testDetours
-// ---------------------------------------------------------------------------
+interface RuntimeDetour {
+  readonly on?: unknown;
+  readonly recover?: unknown;
+}
+
+const isErrorConstructor = (
+  value: unknown
+): value is abstract new (...args: never[]) => Error => {
+  if (typeof value !== 'function') {
+    return false;
+  }
+
+  const { prototype } = value as { prototype?: unknown };
+  return prototype instanceof Error;
+};
+
+const detourLabel = (trailId: string, index: number, detour: RuntimeDetour) => {
+  if (typeof detour.on === 'function') {
+    const { name } = detour.on as { name?: unknown };
+    if (typeof name === 'string' && name.length > 0) {
+      return `${trailId} detour[${index}] on ${name}`;
+    }
+  }
+
+  return `${trailId} detour[${index}]`;
+};
+
+const assertValidOn = (
+  trailId: string,
+  index: number,
+  detour: RuntimeDetour
+): void => {
+  if (isErrorConstructor(detour.on)) {
+    return;
+  }
+
+  throw new Error(
+    `${detourLabel(trailId, index, detour)} must declare a real error constructor in on:`
+  );
+};
+
+const assertCallableRecover = (
+  trailId: string,
+  index: number,
+  detour: RuntimeDetour
+): void => {
+  if (typeof detour.recover === 'function') {
+    return;
+  }
+
+  throw new Error(
+    `${detourLabel(trailId, index, detour)} must declare a callable recover function`
+  );
+};
+
+const sameOrSubtype = (
+  candidate: abstract new (...args: never[]) => Error,
+  ancestor: abstract new (...args: never[]) => Error
+): boolean => {
+  if (candidate === ancestor) {
+    return true;
+  }
+
+  let current = Object.getPrototypeOf(candidate.prototype);
+  while (current && typeof current === 'object') {
+    const ctor = (current as { constructor?: unknown }).constructor;
+    if (ctor === ancestor) {
+      return true;
+    }
+    current = Object.getPrototypeOf(current);
+  }
+
+  return false;
+};
+
+const getShadowingDetour = (
+  detours: readonly RuntimeDetour[],
+  index: number
+):
+  | {
+      readonly index: number;
+      readonly on: abstract new (...args: never[]) => Error;
+    }
+  | undefined => {
+  const detour = detours[index];
+  if (!detour || !isErrorConstructor(detour.on)) {
+    return undefined;
+  }
+
+  for (let previousIndex = 0; previousIndex < index; previousIndex += 1) {
+    const previous = detours[previousIndex];
+    if (!previous || !isErrorConstructor(previous.on)) {
+      continue;
+    }
+
+    if (sameOrSubtype(detour.on, previous.on)) {
+      return { index: previousIndex, on: previous.on };
+    }
+  }
+
+  return undefined;
+};
+
+const assertNotShadowed = (
+  trailId: string,
+  detours: readonly RuntimeDetour[],
+  index: number
+): void => {
+  const detour = detours[index];
+  if (!detour || !isErrorConstructor(detour.on)) {
+    return;
+  }
+
+  const shadowing = getShadowingDetour(detours, index);
+  if (!shadowing) {
+    return;
+  }
+
+  const previousName = shadowing.on.name || TrailsError.name;
+  const currentName = detour.on.name || TrailsError.name;
+  throw new Error(
+    `${trailId} detour[${index}] on ${currentName} is shadowed by earlier detour[${shadowing.index}] on ${previousName}`
+  );
+};
 
 /**
- * Verify that every trail's detour targets reference trails that
- * actually exist in the app's topo.
+ * Verify that every trail's detours match the live runtime contract:
+ * `on` must be an error constructor, `recover` must be callable, and
+ * later detours must not be shadowed by earlier broader `on` types.
  */
 export const testDetours = (app: Topo): void => {
   const trailEntries = [...app.trails];
 
   describe('detours', () => {
     describe.each(trailEntries)('%s', (_id, trailDef) => {
-      const t = trailDef as Trail<unknown, unknown>;
+      const trail = trailDef as Trail<unknown, unknown, unknown>;
 
-      if (t.detours === undefined) {
+      if (trail.detours.length === 0) {
         return;
       }
 
-      const { detours } = t;
-      const testCases = Object.entries(detours).flatMap(
-        ([detourName, targets]) =>
-          targets.map((targetId) => ({ detourName, targetId }))
+      const detourCases = trail.detours.map((detour, index) => ({
+        detour,
+        index,
+        trailId: trail.id,
+      }));
+
+      test.each(detourCases)(
+        '$trailId detour[$index] uses an error constructor',
+        ({ detour, index, trailId }) => {
+          assertValidOn(trailId, index, detour);
+        }
+      );
+
+      test.each(detourCases)(
+        '$trailId detour[$index] provides a callable recover',
+        ({ detour, index, trailId }) => {
+          assertCallableRecover(trailId, index, detour);
+        }
       );
 
-      test.each(testCases)(
-        'detour "$detourName" -> "$targetId" exists',
-        ({ targetId }) => {
-          expect(app.has(targetId)).toBe(true);
+      test.each(detourCases)(
+        '$trailId detour[$index] is not shadowed by an earlier detour',
+        ({ index, trailId }) => {
+          assertNotShadowed(trailId, trail.detours, index);
         }
       );
     });