@ontrails/testing 1.0.0-beta.18 → 1.0.0-beta.19

package/src/harness-mcp.ts

@@ -6,13 +6,35 @@
  */
 
 import { deriveMcpTools } from '@ontrails/mcp';
-import type { McpToolDefinition } from '@ontrails/mcp';
-
 import type {
-  McpHarness,
-  McpHarnessOptions,
-  McpHarnessResult,
-} from './types.js';
+  DeriveMcpToolsOptions,
+  McpExtra,
+  McpToolDefinition,
+} from '@ontrails/mcp';
+import type { Topo } from '@ontrails/core';
+
+/** Options for creating an MCP harness. */
+export interface McpHarnessOptions extends DeriveMcpToolsOptions {
+  readonly extra?: Partial<McpExtra> | undefined;
+  readonly graph: Topo;
+}
+
+/** A test harness for MCP tools. */
+export interface McpHarness {
+  /** Call an MCP tool by name with arguments. */
+  callTool(
+    name: string,
+    args: Record<string, unknown>
+  ): Promise<McpHarnessResult>;
+}
+
+/** The result of an MCP harness tool invocation. */
+export interface McpHarnessResult {
+  readonly content: unknown;
+  readonly isError: boolean;
+  readonly meta?: Record<string, unknown> | undefined;
+  readonly structuredContent?: Record<string, unknown> | undefined;
+}
 
 // ---------------------------------------------------------------------------
 // createMcpHarness
@@ -25,6 +47,8 @@ import type {
  * that invokes tools directly without any transport boundary.
  *
  * ```ts
+ * import { createMcpHarness } from '@ontrails/testing/mcp';
+ *
  * const harness = createMcpHarness({ graph });
  * const result = await harness.callTool("myapp_entity_show", { name: "Alpha" });
  * expect(result.isError).toBe(false);

package/src/http.ts

@@ -0,0 +1,10 @@
+export { createHttpHarness } from './harness-http.js';
+export type {
+  HttpHarness,
+  HttpHarnessErrorBody,
+  HttpHarnessOptions,
+  HttpHarnessRequest,
+  HttpHarnessRequestOptions,
+  HttpHarnessResult,
+  HttpHarnessSuccessBody,
+} from './harness-http.js';

package/src/index.ts

@@ -1,15 +1,10 @@
 // Contract-driven testing
 export { testAll } from './all.js';
-export { testAllEstablished } from './all.js';
 export { testExamples } from './examples.js';
-export { testCrosses } from './crosses.js';
+export { testComposes } from './composes.js';
 export { testTrail } from './trail.js';
 export { testContracts } from './contracts.js';
 export { testDetours } from './detours.js';
-export {
-  runSurfaceParityExample,
-  testSurfaceParity,
-} from './surface-parity.js';
 
 // Assertions
 export {
@@ -28,50 +23,26 @@ export { executeScenarioSteps, ref, scenario } from './scenario.js';
 
 // Mock factories
 export {
-  createCrossContext,
+  createComposeContext,
   createTestContext,
   defaultCreatePermit,
 } from './context.js';
 export { createTestLogger } from './logger.js';
 
-// Surface harnesses
-export { createCliHarness } from './harness-cli.js';
-export { createHttpHarness } from './harness-http.js';
-export { createMcpHarness } from './harness-mcp.js';
-
 // Types
-export type { CreateCrossContextOptions } from './context.js';
+export type { CreateComposeContextOptions } from './context.js';
 export type {
   PermittedTrail,
   MinimalPermit,
   TestExecutionOptions,
 } from './context.js';
-export type { TestCrossOptions } from './crosses.js';
+export type { TestComposeOptions } from './composes.js';
 
 export type {
-  CrossScenario,
+  ComposeScenario,
   RefToken,
   ScenarioStep,
-  TestAllEstablishedOptions,
   TestScenario,
   TestLogger,
   TestTrailContextOptions,
-  CliHarness,
-  CliHarnessOptions,
-  CliHarnessResult,
-  HttpHarness,
-  HttpHarnessErrorBody,
-  HttpHarnessOptions,
-  HttpHarnessRequest,
-  HttpHarnessRequestOptions,
-  HttpHarnessResult,
-  HttpHarnessSuccessBody,
-  McpHarness,
-  McpHarnessOptions,
-  McpHarnessResult,
-  NormalizedSurfaceParityResult,
-  SurfaceParityExclusion,
-  SurfaceParityOptions,
-  SurfaceParitySurface,
 } from './types.js';
-export type { SurfaceParityComparison } from './surface-parity.js';

package/src/mcp.ts

@@ -0,0 +1,6 @@
+export { createMcpHarness } from './harness-mcp.js';
+export type {
+  McpHarness,
+  McpHarnessOptions,
+  McpHarnessResult,
+} from './harness-mcp.js';

package/src/scenario.ts

@@ -2,7 +2,7 @@
  * Multi-step scenario runner for composition testing.
  *
  * Scenarios express multi-trail flows as structured data — arrays of steps
- * with cross-step references via `ref()`. Each step invokes a trail through
+ * with compose-step references via `ref()`. Each step invokes a trail through
  * the normal execution pipeline (validation, layers, blaze, Result).
  */
 
@@ -10,19 +10,20 @@ import { describe, test } from 'bun:test';
 
 import type {
   AnyTrail,
-  CrossBatchOptions,
-  CrossFn,
+  ComposeBatchOptions,
+  ComposeFn,
+  ExecuteTrailOptions,
   ResourceOverrideMap,
   Result,
   Topo,
 } from '@ontrails/core';
 import {
-  buildCrossValidationSchema,
-  claimNextCrossBatchIndex,
-  createCrossBatchValidationResults,
+  buildComposeValidationSchema,
+  claimNextComposeBatchIndex,
+  createComposeBatchValidationResults,
   executeTrail,
   InternalError,
-  normalizeCrossBatchConcurrency,
+  normalizeComposeBatchConcurrency,
   Result as R,
 } from '@ontrails/core';
 
@@ -30,15 +31,18 @@ import { assertPartialMatch, expectOk } from './assertions.js';
 import { createTestContext, createMockResources } from './context.js';
 import type { RefToken, ScenarioStep } from './types.js';
 
-type ScenarioCrossTarget = string | { readonly id: string };
-type ScenarioCrossCall = readonly [ScenarioCrossTarget, unknown];
+type ScenarioComposeTarget = string | { readonly id: string };
+type ScenarioComposeCall = readonly [ScenarioComposeTarget, unknown];
+type TestingExecuteTrailOptions = ExecuteTrailOptions & {
+  readonly validationSchema?: ReturnType<typeof buildComposeValidationSchema>;
+};
 
 // ---------------------------------------------------------------------------
-// ref() — cross-step reference marker
+// ref() — compose-step reference marker
 // ---------------------------------------------------------------------------
 
 /**
- * Create a reference marker for cross-step data in scenario inputs.
+ * Create a reference marker for compose-step data in scenario inputs.
  *
  * `ref('create.id')` resolves to the `id` field of the step aliased as
  * `create`. Dot-paths are supported for nested access.
@@ -46,8 +50,8 @@ type ScenarioCrossCall = readonly [ScenarioCrossTarget, unknown];
  * @example
  * ```typescript
  * scenario('Fork flow', app, [
- *   { cross: createGist, input: { name: 'Hello' }, as: 'original' },
- *   { cross: forkGist, input: { id: ref('original.id') } },
+ *   { compose: createGist, input: { name: 'Hello' }, as: 'original' },
+ *   { compose: forkGist, input: { id: ref('original.id') } },
  * ]);
  * ```
  */
@@ -152,8 +156,8 @@ export const deriveRefs = (
  * @example
  * ```typescript
  * scenario('Create and show', app, [
- *   { cross: createItem, input: { name: 'Test' }, as: 'created' },
- *   { cross: showItem, input: { id: ref('created.id') },
+ *   { compose: createItem, input: { name: 'Test' }, as: 'created' },
+ *   { compose: showItem, input: { id: ref('created.id') },
  *     expectedMatch: { found: true } },
  * ]);
  * ```
@@ -176,10 +180,10 @@ const assertStepExpectations = async (
   }
 };
 
-const executeUnlimitedCrossBatch = async (
-  calls: readonly ScenarioCrossCall[],
+const executeUnlimitedComposeBatch = async (
+  calls: readonly ScenarioComposeCall[],
   runCall: (
-    call: ScenarioCrossCall,
+    call: ScenarioComposeCall,
     branchIndex: number
   ) => Promise<Result<unknown, Error>>
 ): Promise<Result<unknown, Error>[]> =>
@@ -187,10 +191,10 @@ const executeUnlimitedCrossBatch = async (
     calls.map((call, branchIndex) => runCall(call, branchIndex))
   );
 
-const executeLimitedCrossBatch = async (
-  calls: readonly ScenarioCrossCall[],
+const executeLimitedComposeBatch = async (
+  calls: readonly ScenarioComposeCall[],
   runCall: (
-    call: ScenarioCrossCall,
+    call: ScenarioComposeCall,
     branchIndex: number
   ) => Promise<Result<unknown, Error>>,
   limit: number
@@ -200,20 +204,20 @@ const executeLimitedCrossBatch = async (
 
   const runWorker = async () => {
     while (true) {
-      const branchIndex = claimNextCrossBatchIndex(nextIndex, calls);
+      const branchIndex = claimNextComposeBatchIndex(nextIndex, calls);
       if (branchIndex === undefined) {
         return;
       }
 
       const call = calls[branchIndex];
       if (call === undefined) {
-        // Defensive: `claimNextCrossBatchIndex` only returns indices within
+        // Defensive: `claimNextComposeBatchIndex` only returns indices within
         // bounds, so this slot should always be populated. If it ever isn't,
         // surface a clear InternalError in place of the missing slot and keep
         // the worker loop running so sibling branches still get processed.
         results[branchIndex] = R.err(
           new InternalError(
-            `unreachable: concurrent cross batch call missing at index ${branchIndex}`
+            `unreachable: concurrent compose batch call missing at index ${branchIndex}`
           )
         );
         continue;
@@ -228,78 +232,81 @@ const executeLimitedCrossBatch = async (
 };
 
 /**
- * Build a cross function that resolves trails from the topo and executes
- * them through the standard pipeline. Mirrors the pattern in crosses.ts
+ * Build a compose function that resolves trails from the topo and executes
+ * them through the standard pipeline. Mirrors the pattern in composes.ts
  * `executeFromMap` but without recording or injection.
  */
-const createScenarioCross = (
+const createScenarioCompose = (
   app: Topo,
   resources?: ResourceOverrideMap
-): CrossFn => {
-  const invokeCross = async (
-    idOrTrail: ScenarioCrossTarget,
+): ComposeFn => {
+  const invokeCompose = async (
+    idOrTrail: ScenarioComposeTarget,
     input: unknown,
-    self: CrossFn
+    self: ComposeFn
   ) => {
     const id = typeof idOrTrail === 'string' ? idOrTrail : idOrTrail.id;
     const trailDef: AnyTrail | undefined = app.get(id);
     if (trailDef === undefined) {
-      return R.err(new InternalError(`cross: trail "${id}" not found in topo`));
+      return R.err(
+        new InternalError(`compose: trail "${id}" not found in topo`)
+      );
     }
     const baseCtx = createTestContext();
-    return await executeTrail(trailDef, input, {
-      ctx: { ...baseCtx, cross: self },
+    const options: TestingExecuteTrailOptions = {
+      ctx: { ...baseCtx, compose: self },
       resources,
       topo: app,
-      validationSchema: buildCrossValidationSchema(trailDef),
-    });
+      validationSchema: buildComposeValidationSchema(trailDef),
+    };
+    return await executeTrail(trailDef, input, options);
   };
 
-  const executeCrossBatch = async (
-    calls: readonly ScenarioCrossCall[],
-    self: CrossFn,
-    options?: CrossBatchOptions
+  const executeComposeBatch = async (
+    calls: readonly ScenarioComposeCall[],
+    self: ComposeFn,
+    options?: ComposeBatchOptions
   ): Promise<Result<unknown, Error>[]> => {
     if (calls.length === 0) {
       return [];
     }
 
-    const concurrency = normalizeCrossBatchConcurrency(options);
+    const concurrency = normalizeComposeBatchConcurrency(options);
     if (concurrency.isErr()) {
-      return createCrossBatchValidationResults(calls, concurrency.error);
+      return createComposeBatchValidationResults(calls, concurrency.error);
     }
 
     const runCall = async (
-      [target, batchInput]: ScenarioCrossCall,
+      [target, batchInput]: ScenarioComposeCall,
       _branchIndex: number
-    ) => await invokeCross(target, batchInput, self);
+    ) => await invokeCompose(target, batchInput, self);
 
     const limit = concurrency.value ?? calls.length;
     return limit >= calls.length
-      ? await executeUnlimitedCrossBatch(calls, runCall)
-      : await executeLimitedCrossBatch(calls, runCall, limit);
+      ? await executeUnlimitedComposeBatch(calls, runCall)
+      : await executeLimitedComposeBatch(calls, runCall, limit);
   };
 
-  const cross = async function cross(
-    idOrTrail: ScenarioCrossTarget | readonly ScenarioCrossCall[],
+  const compose = async function compose(
+    idOrTrail: ScenarioComposeTarget | readonly ScenarioComposeCall[],
     inputOrOptions?: unknown
   ) {
     if (Array.isArray(idOrTrail)) {
-      return await executeCrossBatch(
+      return await executeComposeBatch(
         idOrTrail,
-        cross as CrossFn,
-        inputOrOptions as CrossBatchOptions | undefined
+        compose as ComposeFn,
+        inputOrOptions as ComposeBatchOptions | undefined
       );
     }
 
-    return await invokeCross(
-      idOrTrail as ScenarioCrossTarget,
+    return await invokeCompose(
+      idOrTrail as ScenarioComposeTarget,
       inputOrOptions,
-      cross as CrossFn
+      compose as ComposeFn
     );
-  } as CrossFn;
+  } as ComposeFn;
 
-  return cross;
+  return compose;
 };
 
 /**
@@ -319,18 +326,18 @@ const executeStep = async (
     );
   }
 
-  const scenarioCross = createScenarioCross(app, resources);
+  const scenarioCompose = createScenarioCompose(app, resources);
   const baseCtx = createTestContext();
   const resolvedInput = deriveRefs(step.input, outputs);
-  const result = await executeTrail(step.cross, resolvedInput, {
-    ctx: { ...baseCtx, cross: scenarioCross },
+  const result = await executeTrail(step.compose, resolvedInput, {
+    ctx: { ...baseCtx, compose: scenarioCompose },
     resources,
     topo: app,
   });
 
   if (result.isErr()) {
     throw new Error(
-      `Step ${String(index + 1)} ("${step.as ?? step.cross.id}") failed: ${result.error.message}`
+      `Step ${String(index + 1)} ("${step.as ?? step.compose.id}") failed: ${result.error.message}`
     );
   }
 

package/src/surface-parity.ts

@@ -5,11 +5,18 @@
 import { describe, expect, test } from 'bun:test';
 
 import { deriveCliPath, filterSurfaceTrails } from '@ontrails/core';
-import type { Topo, Trail, TrailContext, TrailExample } from '@ontrails/core';
+import type {
+  ResourceOverrideMap,
+  Topo,
+  Trail,
+  TrailContext,
+  TrailExample,
+} from '@ontrails/core';
 import { deriveHttpInputSource, deriveHttpMethod } from '@ontrails/http';
 import type { HttpMethod } from '@ontrails/http';
 import { MCP_TOOL_ERROR_META_KEY, deriveToolName } from '@ontrails/mcp';
 
+import type { TestAllEstablishedOptions } from './all-established.js';
 import {
   createMockResources,
   defaultCreatePermit,
@@ -18,19 +25,45 @@ import {
 } from './context.js';
 import { deriveTrailExamples } from './effective-examples.js';
 import { createCliHarness } from './harness-cli.js';
+import type { CliHarnessResult } from './harness-cli.js';
 import { createHttpHarness } from './harness-http.js';
+import type { HttpHarnessResult } from './harness-http.js';
 import { createMcpHarness } from './harness-mcp.js';
-import type {
-  CliHarnessResult,
-  HttpHarnessResult,
-  McpHarnessResult,
-  NormalizedSurfaceParityResult,
-  SurfaceParityExclusion,
-  SurfaceParityOptions,
-} from './types.js';
+import type { McpHarnessResult } from './harness-mcp.js';
 
 type ParityTrail = Trail<unknown, unknown, unknown>;
 
+export type SurfaceParitySurface = 'cli' | 'mcp' | 'http';
+
+export interface SurfaceParityExclusion {
+  /** Optional example name. Omit to exclude every example for the trail. */
+  readonly example?: string | undefined;
+  /** Human-readable reason shown in the skipped test name. */
+  readonly reason: string;
+  /** Trail ID to exclude. */
+  readonly trailId: string;
+}
+
+export interface SurfaceParityOptions extends TestAllEstablishedOptions {
+  readonly createResources?:
+    | (() => ResourceOverrideMap | Promise<ResourceOverrideMap>)
+    | undefined;
+  readonly exclusions?: readonly SurfaceParityExclusion[] | undefined;
+}
+
+export type NormalizedSurfaceParityResult =
+  | {
+      readonly ok: true;
+      readonly value: unknown;
+    }
+  | {
+      readonly error: {
+        readonly category: string;
+        readonly code: string;
+      };
+      readonly ok: false;
+    };
+
 export interface SurfaceParityComparison {
   readonly cli: NormalizedSurfaceParityResult;
   readonly http: NormalizedSurfaceParityResult;
@@ -308,7 +341,7 @@ const parityTrails = (app: Topo): readonly ParityTrail[] =>
  *
  * @example
  * ```ts
- * import { testSurfaceParity } from '@ontrails/testing';
+ * import { testSurfaceParity } from '@ontrails/testing/surface-parity';
  * import { graph } from '../src/app.js';
  *
  * testSurfaceParity(graph);