@ontrails/testing 1.0.0-beta.0

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc -b

package/.turbo/turbo-lint.log

@@ -0,0 +1,3 @@
+$ oxlint ./src
+Found 0 warnings and 0 errors.
+Finished in 109ms on 20 files with 93 rules using 24 threads.

package/.turbo/turbo-typecheck.log

@@ -0,0 +1 @@
+$ tsc --noEmit

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# @ontrails/testing
+
+## 1.0.0-beta.0
+
+### Minor Changes
+
+- Initial v1 beta release of the Trails framework.
+
+  - **@ontrails/core** — Result type, error taxonomy, trail/hike/event/topo, validateTopo, validateInput/Output, deriveFields, patterns, redaction, branded types, resilience
+  - **@ontrails/cli** — CLI surface adapter, Commander integration, flag derivation, layers
+  - **@ontrails/mcp** — MCP surface adapter, tool generation, annotations, progress bridge
+  - **@ontrails/logging** — Structured logging, sinks, formatters, LogTape adapter
+  - **@ontrails/testing** — testAll, testExamples, testTrail, testHike, testContracts, testDetours, surface harnesses
+  - **@ontrails/warden** — AST-based code convention rules via oxc-parser, drift detection, CI formatters
+  - **@ontrails/schema** — Surface map generation, hashing, semantic diffing
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.0
+  - @ontrails/cli@1.0.0-beta.0
+  - @ontrails/mcp@1.0.0-beta.0
+  - @ontrails/logging@1.0.0-beta.0

package/README.md

@@ -0,0 +1,221 @@
+# @ontrails/testing
+
+Contract-driven testing utilities for Trails. Write examples for agent fluency -- get test cases for free.
+
+## Installation
+
+```bash
+bun add -d @ontrails/testing
+```
+
+Peer dependencies: `@ontrails/core`, `@ontrails/cli`, `@ontrails/mcp`, `@ontrails/logging`, `zod`.
+
+## Quick Start
+
+```typescript
+import { testExamples } from '@ontrails/testing';
+import { app } from '../app';
+
+testExamples(app);
+```
+
+One line. The entire topo is tested. Every trail, every example: input validation, implementation execution, output verification.
+
+```text
+ PASS  src/__tests__/app.test.ts
+  greet
+    example: Basic greeting
+    example: Loud greeting
+  entity.show
+    example: Show entity by name
+```
+
+## API Overview
+
+### `testAll(topo, ctx?)`
+
+Single-line governance suite. Wraps topo validation, example execution, contract checks, and detour verification into one `governance` describe block:
+
+```typescript
+import { testAll } from '@ontrails/testing';
+import { app } from '../app';
+
+testAll(app);
+```
+
+For most apps, `testAll` is the only test call you need.
+
+### `testExamples(app, ctx?)`
+
+For each trail with `examples`, generates `describe`/`test` blocks using the Bun test runner.
+
+Per example:
+
+1. Validates `example.input` against the trail's Zod schema
+2. Calls the implementation with validated input
+3. Applies progressive assertion (see below)
+4. Validates output against the trail's output schema (if present)
+
+Trails with no examples produce no tests.
+
+The runtime implementation is always awaited, so `testExamples()` behaves the same for sync-authored and async-authored trails.
+
+### `testTrail(trail, scenarios, ctx?)`
+
+Custom scenarios for edge cases, boundary values, and regressions that do not belong in agent-facing examples:
+
+```typescript
+import { testTrail } from '@ontrails/testing';
+import { ValidationError, NotFoundError } from '@ontrails/core';
+
+testTrail(showTrail, [
+  { description: 'empty name', input: { name: '' }, expectOk: true },
+  { description: 'missing name', input: {}, expectErr: ValidationError },
+  {
+    description: 'exact match',
+    input: { name: 'Alpha' },
+    expectValue: { name: 'Alpha', type: 'concept' },
+  },
+  {
+    description: 'not found',
+    input: { name: 'missing' },
+    expectErr: NotFoundError,
+    expectErrMessage: 'not found',
+  },
+]);
+```
+
+### `testHike(hike, scenarios, ctx?)`
+
+Tests a hike's composition graph -- follow chains, failure injection, and multi-trail interactions:
+
+```typescript
+import { testHike } from '@ontrails/testing';
+
+testHike(onboardHike, [
+  { description: 'successful onboard', input: { name: 'Delta', type: 'tool' }, expectOk: true },
+  { description: 'fails when add fails', input: { name: 'Alpha' }, expectErr: AlreadyExistsError },
+]);
+```
+
+Where `testTrail` exercises a single trail in isolation, `testHike` exercises the follow graph and verifies that upstream failures propagate correctly.
+
+### `testContracts(app, ctx?)`
+
+Catches implementation-schema drift. Runs every example through the implementation, then validates the result against the trail's `output` schema. Reports detailed Zod errors on mismatch.
+
+```typescript
+import { testContracts } from '@ontrails/testing';
+
+testContracts(app);
+// Fails if any implementation returns data that doesn't match its declared output schema
+```
+
+### `testDetours(app)`
+
+Structural validation of detour declarations. Verifies every detour target trail exists in the topo. No implementation execution needed.
+
+```typescript
+import { testDetours } from '@ontrails/testing';
+
+testDetours(app);
+// Fails: Trail "entity.show" has detour target "entity.search" which does not exist in the topo
+```
+
+### Progressive Assertion
+
+What `testExamples` checks depends on what the example declares:
+
+**Full match** -- example has `expected`:
+
+```typescript
+{
+  name: 'Found',
+  input: { name: 'Alpha' },
+  expected: { name: 'Alpha', type: 'concept' },
+}
+```
+
+Asserts `result.isOk()` and `result.value` deep-equals `expected`.
+
+**Schema-only match** -- example has no `expected` and no `error`:
+
+```typescript
+{ name: 'Returns something valid', input: { name: 'Alpha' } }
+```
+
+Asserts `result.isOk()` and validates against the trail's output schema.
+
+**Error match** -- example has `error`:
+
+```typescript
+{ name: 'Not found', input: { name: 'missing' }, error: 'NotFoundError' }
+```
+
+Asserts `result.isErr()` and `instanceof` check.
+
+### Test Context and Mocks
+
+```typescript
+import { createTestContext, createTestLogger } from '@ontrails/testing';
+
+// TrailContext with sensible test defaults
+const ctx = createTestContext({
+  requestId: 'test-001',
+  env: { TRAILS_ENV: 'test' },
+});
+
+// Logger that captures entries in memory
+const logger = createTestLogger();
+logger.info('hello');
+logger.entries; // All captured records
+logger.assertLogged('info', 'hello'); // Passes if any entry matches
+logger.clear(); // Reset
+```
+
+### Surface Harnesses
+
+**CLI harness** -- execute commands in-process and capture stdout/stderr:
+
+```typescript
+import { createCliHarness } from '@ontrails/testing';
+
+const harness = createCliHarness({ app });
+const result = await harness.run('entity show --name Alpha --output json');
+
+expect(result.exitCode).toBe(0);
+expect(result.json).toMatchObject({ name: 'Alpha' });
+```
+
+**MCP harness** -- invoke tools directly without transport:
+
+```typescript
+import { createMcpHarness } from '@ontrails/testing';
+
+const harness = createMcpHarness({ app });
+const result = await harness.callTool('myapp_entity_show', { name: 'Alpha' });
+
+expect(result.isError).toBe(false);
+```
+
+## Exports
+
+```typescript
+import {
+  testAll,
+  testExamples,
+  testTrail,
+  testHike,
+  testContracts,
+  testDetours,
+  createTestContext,
+  createTestLogger,
+  createCliHarness,
+  createMcpHarness,
+} from '@ontrails/testing';
+```
+
+## Further Reading
+
+- [Testing Guide](../../docs/testing.md)
+- [Getting Started](../../docs/getting-started.md)

package/dist/all.d.ts

@@ -0,0 +1,30 @@
+/**
+ * testAll — single-line governance suite for any Topo.
+ *
+ * Wraps topo validation, example execution, contract checks, and detour
+ * verification into one describe block.
+ */
+import type { Topo, TrailContext } from '@ontrails/core';
+/**
+ * Run the full governance test suite for a Topo.
+ *
+ * Generates a `governance` describe block containing:
+ * - Structural validation via `validateTopo`
+ * - Example execution via `testExamples`
+ * - Output contract checks via `testContracts`
+ * - Detour target verification via `testDetours`
+ *
+ * Accepts either a static context or a factory function that produces a
+ * fresh context per test (useful when the context contains mutable state
+ * like an in-memory store).
+ *
+ * @example
+ * ```ts
+ * import { testAll } from '@ontrails/testing';
+ * import { app } from '../src/app.js';
+ *
+ * testAll(app);
+ * ```
+ */
+export declare const testAll: (topo: Topo, ctxOrFactory?: Partial<TrailContext> | (() => Partial<TrailContext>)) => void;
+//# sourceMappingURL=all.d.ts.map

package/dist/all.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"all.d.ts","sourceRoot":"","sources":["../src/all.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAOzD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,OAAO,GAClB,MAAM,IAAI,EACV,eAAe,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,KACnE,IAcF,CAAC"}

package/dist/all.js

@@ -0,0 +1,47 @@
+/**
+ * testAll — single-line governance suite for any Topo.
+ *
+ * Wraps topo validation, example execution, contract checks, and detour
+ * verification into one describe block.
+ */
+import { describe, expect, test } from 'bun:test';
+import { validateTopo } from '@ontrails/core';
+import { testContracts } from './contracts.js';
+import { testDetours } from './detours.js';
+import { testExamples } from './examples.js';
+/**
+ * Run the full governance test suite for a Topo.
+ *
+ * Generates a `governance` describe block containing:
+ * - Structural validation via `validateTopo`
+ * - Example execution via `testExamples`
+ * - Output contract checks via `testContracts`
+ * - Detour target verification via `testDetours`
+ *
+ * Accepts either a static context or a factory function that produces a
+ * fresh context per test (useful when the context contains mutable state
+ * like an in-memory store).
+ *
+ * @example
+ * ```ts
+ * import { testAll } from '@ontrails/testing';
+ * import { app } from '../src/app.js';
+ *
+ * testAll(app);
+ * ```
+ */
+export const testAll = (topo, ctxOrFactory) => {
+    describe('governance', () => {
+        test('topo validates', () => {
+            const result = validateTopo(topo);
+            expect(result.isOk()).toBe(true);
+        });
+        // oxlint-disable-next-line jest/require-hook -- these generate describe/test blocks, not setup code
+        testExamples(topo, ctxOrFactory);
+        // oxlint-disable-next-line jest/require-hook -- these generate describe/test blocks, not setup code
+        testContracts(topo, ctxOrFactory);
+        // oxlint-disable-next-line jest/require-hook -- these generate describe/test blocks, not setup code
+        testDetours(topo);
+    });
+};
+//# sourceMappingURL=all.js.map

package/dist/all.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"all.js","sourceRoot":"","sources":["../src/all.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAGlD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,IAAU,EACV,YAAoE,EAC9D,EAAE;IACR,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;QAC1B,IAAI,CAAC,gBAAgB,EAAE,GAAG,EAAE;YAC1B,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QAEH,oGAAoG;QACpG,YAAY,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QACjC,oGAAoG;QACpG,aAAa,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAClC,oGAAoG;QACpG,WAAW,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/assertions.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Progressive assertion logic for example-driven testing.
+ *
+ * Three tiers:
+ * 1. Full match — example has `expected` output
+ * 2. Schema-only — no expected output, no error
+ * 3. Error match — example declares an error class name
+ */
+import type { Result } from '@ontrails/core';
+import type { z } from 'zod';
+/**
+ * Assert that a Result is Ok and return its value.
+ *
+ * Eliminates the `if (result.isOk())` / `as unknown as` dance in tests.
+ *
+ * @example
+ * ```typescript
+ * const value = expectOk(result);
+ * expect(value.name).toBe('Alice');
+ * ```
+ */
+export declare const expectOk: <T, E>(result: Result<T, E>) => T;
+/**
+ * Assert that a Result is Err and return its error.
+ *
+ * Eliminates the `if (result.isErr())` / `as unknown as` dance in tests.
+ *
+ * @example
+ * ```typescript
+ * const error = expectErr(result);
+ * expect(error).toBeInstanceOf(ValidationError);
+ * ```
+ */
+export declare const expectErr: <T, E>(result: Result<T, E>) => E;
+/**
+ * Assert that the result is ok and its value deep-equals the expected output.
+ */
+export declare const assertFullMatch: (result: Result<unknown, Error>, expected: unknown) => void;
+/**
+ * Assert that the result is ok and, if an output schema is provided,
+ * the value parses against it.
+ */
+export declare const assertSchemaMatch: (result: Result<unknown, Error>, outputSchema: z.ZodType | undefined) => void;
+/**
+ * Assert that the result is an error of the specified type, with optional
+ * message substring matching.
+ */
+export declare const assertErrorMatch: (result: Result<unknown, Error>, expectedError: new (...args: never[]) => Error, expectedMessage?: string) => void;
+//# sourceMappingURL=assertions.d.ts.map

package/dist/assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../src/assertions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAM7B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAGrD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAGtD,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,EAC9B,UAAU,OAAO,KAChB,IAGF,CAAC;AAMF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,EAC9B,cAAc,CAAC,CAAC,OAAO,GAAG,SAAS,KAClC,IAUF,CAAC;AAMF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,EAC9B,eAAe,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,KAAK,EAC9C,kBAAkB,MAAM,KACvB,IAMF,CAAC"}

package/dist/assertions.js

@@ -0,0 +1,84 @@
+/**
+ * Progressive assertion logic for example-driven testing.
+ *
+ * Three tiers:
+ * 1. Full match — example has `expected` output
+ * 2. Schema-only — no expected output, no error
+ * 3. Error match — example declares an error class name
+ */
+import { expect } from 'bun:test';
+import { formatZodIssues } from '@ontrails/core';
+// ---------------------------------------------------------------------------
+// Result narrowing helpers
+// ---------------------------------------------------------------------------
+/**
+ * Assert that a Result is Ok and return its value.
+ *
+ * Eliminates the `if (result.isOk())` / `as unknown as` dance in tests.
+ *
+ * @example
+ * ```typescript
+ * const value = expectOk(result);
+ * expect(value.name).toBe('Alice');
+ * ```
+ */
+export const expectOk = (result) => {
+    expect(result.isOk()).toBe(true);
+    return result.value;
+};
+/**
+ * Assert that a Result is Err and return its error.
+ *
+ * Eliminates the `if (result.isErr())` / `as unknown as` dance in tests.
+ *
+ * @example
+ * ```typescript
+ * const error = expectErr(result);
+ * expect(error).toBeInstanceOf(ValidationError);
+ * ```
+ */
+export const expectErr = (result) => {
+    expect(result.isErr()).toBe(true);
+    return result.error;
+};
+// ---------------------------------------------------------------------------
+// Full Match
+// ---------------------------------------------------------------------------
+/**
+ * Assert that the result is ok and its value deep-equals the expected output.
+ */
+export const assertFullMatch = (result, expected) => {
+    const value = expectOk(result);
+    expect(value).toEqual(expected);
+};
+// ---------------------------------------------------------------------------
+// Schema-Only Match
+// ---------------------------------------------------------------------------
+/**
+ * Assert that the result is ok and, if an output schema is provided,
+ * the value parses against it.
+ */
+export const assertSchemaMatch = (result, outputSchema) => {
+    const value = expectOk(result);
+    if (outputSchema !== undefined) {
+        const parsed = outputSchema.safeParse(value);
+        if (!parsed.success) {
+            throw new Error(`Output does not match schema: ${formatZodIssues(parsed.error.issues).join('; ')}`);
+        }
+    }
+};
+// ---------------------------------------------------------------------------
+// Error Match
+// ---------------------------------------------------------------------------
+/**
+ * Assert that the result is an error of the specified type, with optional
+ * message substring matching.
+ */
+export const assertErrorMatch = (result, expectedError, expectedMessage) => {
+    const error = expectErr(result);
+    expect(error).toBeInstanceOf(expectedError);
+    if (expectedMessage !== undefined) {
+        expect(error.message).toContain(expectedMessage);
+    }
+};
+//# sourceMappingURL=assertions.js.map

package/dist/assertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.js","sourceRoot":"","sources":["../src/assertions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjD,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAO,MAAoB,EAAK,EAAE;IACxD,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjC,OAAQ,MAAkC,CAAC,KAAK,CAAC;AACnD,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAO,MAAoB,EAAK,EAAE;IACzD,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,OAAQ,MAAkC,CAAC,KAAK,CAAC;AACnD,CAAC,CAAC;AAEF,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,MAA8B,EAC9B,QAAiB,EACX,EAAE;IACR,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAClC,CAAC,CAAC;AAEF,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,MAA8B,EAC9B,YAAmC,EAC7B,EAAE;IACR,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,iCAAiC,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACnF,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,MAA8B,EAC9B,aAA8C,EAC9C,eAAwB,EAClB,EAAE;IACR,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAC5C,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;IACnD,CAAC;AACH,CAAC,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Test context factory for creating TrailContext instances suitable for testing.
+ */
+import type { TrailContext } from '@ontrails/core';
+import type { TestTrailContextOptions } from './types.js';
+/**
+ * Create a TrailContext with deterministic, test-friendly defaults.
+ *
+ * - `requestId`: `"test-request-001"` (deterministic)
+ * - `logger`: a `TestLogger` that captures entries
+ * - `signal`: a non-aborted AbortController signal
+ */
+export declare const createTestContext: (overrides?: TestTrailContextOptions) => TrailContext;
+/**
+ * Merge a Partial<TrailContext> into a test context.
+ * Used internally when the public API accepts Partial<TrailContext>.
+ */
+export declare const mergeTestContext: (ctx?: Partial<TrailContext>) => TrailContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAM1D;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,YAAY,uBAAuB,KAClC,YAMD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,OAAO,CAAC,YAAY,CAAC,KAAG,YAO9D,CAAC"}

package/dist/context.js

@@ -0,0 +1,33 @@
+/**
+ * Test context factory for creating TrailContext instances suitable for testing.
+ */
+import { createTestLogger } from './logger.js';
+// ---------------------------------------------------------------------------
+// createTestContext
+// ---------------------------------------------------------------------------
+/**
+ * Create a TrailContext with deterministic, test-friendly defaults.
+ *
+ * - `requestId`: `"test-request-001"` (deterministic)
+ * - `logger`: a `TestLogger` that captures entries
+ * - `signal`: a non-aborted AbortController signal
+ */
+export const createTestContext = (overrides) => ({
+    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(),
+});
+/**
+ * Merge a Partial<TrailContext> into a test context.
+ * Used internally when the public API accepts Partial<TrailContext>.
+ */
+export const mergeTestContext = (ctx) => {
+    if (ctx === undefined) {
+        return createTestContext();
+    }
+    const base = createTestContext();
+    return { ...base, ...ctx };
+};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,SAAmC,EACrB,EAAE,CAAC,CAAC;IAClB,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE;IAC7C,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,gBAAgB,EAAE;IAC/C,SAAS,EAAE,SAAS,EAAE,SAAS,IAAI,kBAAkB;IACrD,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC,MAAM;IACzD,aAAa,EAAE,SAAS,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;CAC/C,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAA2B,EAAgB,EAAE;IAC5E,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,iBAAiB,EAAE,CAAC;IAC7B,CAAC;IAED,MAAM,IAAI,GAAG,iBAAiB,EAAE,CAAC;IACjC,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,GAAG,EAAE,CAAC;AAC7B,CAAC,CAAC"}

package/dist/contracts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * testContracts — output schema verification.
+ *
+ * For every trail that has both examples and an output schema,
+ * run each example and validate the implementation output against
+ * the declared schema.
+ */
+import type { Topo, TrailContext } from '@ontrails/core';
+/**
+ * Verify that every trail's implementation output matches its declared
+ * output schema. Catches implementation-schema drift.
+ *
+ * Trails without output schemas or examples are skipped.
+ */
+export declare const testContracts: (app: Topo, ctxOrFactory?: Partial<TrailContext> | (() => Partial<TrailContext>)) => void;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAuB,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA8B9E;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,KAAK,IAAI,EACT,eAAe,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC,KACnE,IAmCF,CAAC"}

package/dist/contracts.js

@@ -0,0 +1,56 @@
+/**
+ * testContracts — output schema verification.
+ *
+ * For every trail that has both examples and an output schema,
+ * run each example and validate the implementation output against
+ * the declared schema.
+ */
+import { describe, test } from 'bun:test';
+import { formatZodIssues, validateInput } from '@ontrails/core';
+import { expectOk } from './assertions.js';
+import { mergeTestContext } from './context.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const validateOutputSchema = (outputSchema, value, trailId, exampleName) => {
+    const parsed = outputSchema.safeParse(value);
+    if (!parsed.success) {
+        const issues = formatZodIssues(parsed.error.issues);
+        throw new Error(`Output schema violation for trail "${trailId}", example "${exampleName}":\n${issues.map((i) => `  - ${i}`).join('\n')}\n\nActual output: ${JSON.stringify(value, null, 2)}`);
+    }
+};
+// ---------------------------------------------------------------------------
+// testContracts
+// ---------------------------------------------------------------------------
+/**
+ * Verify that every trail's implementation output matches its declared
+ * output schema. Catches implementation-schema drift.
+ *
+ * Trails without output schemas or examples are skipped.
+ */
+export const testContracts = (app, ctxOrFactory) => {
+    const resolveCtx = typeof ctxOrFactory === 'function' ? ctxOrFactory : () => ctxOrFactory;
+    const trailEntries = [...app.trails];
+    describe('contracts', () => {
+        describe.each(trailEntries)('%s', (_id, trailDef) => {
+            const t = trailDef;
+            if (t.output === undefined) {
+                return;
+            }
+            if (t.examples === undefined || t.examples.length === 0) {
+                return;
+            }
+            const { examples, output: outputSchema } = t;
+            const successExamples = examples.filter((e) => e.error === undefined);
+            test.each(successExamples)('contract: $name', async (example) => {
+                const testCtx = mergeTestContext(resolveCtx());
+                const validated = validateInput(t.input, example.input);
+                const validatedInput = expectOk(validated);
+                const result = await t.implementation(validatedInput, testCtx);
+                const resultValue = expectOk(result);
+                validateOutputSchema(outputSchema, resultValue, t.id, example.name);
+            });
+        });
+    });
+};
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"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"}

package/dist/detours.d.ts

@@ -0,0 +1,12 @@
+/**
+ * testDetours — verify that all detour targets exist in the topo.
+ *
+ * Pure structural validation. No implementation execution needed.
+ */
+import type { Topo } from '@ontrails/core';
+/**
+ * Verify that every trail's detour targets reference trails that
+ * actually exist in the app's topo.
+ */
+export declare const testDetours: (app: Topo) => void;
+//# sourceMappingURL=detours.d.ts.map

package/dist/detours.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detours.d.ts","sourceRoot":"","sources":["../src/detours.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAS,MAAM,gBAAgB,CAAC;AAMlD;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,IAAI,KAAG,IAyBvC,CAAC"}