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

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @ontrails/testing
 
+## 1.0.0-beta.16
+
+### Minor Changes
+
+- bcdc484: Add an explicit `unmockable: { reason }` resource marker and have testing auto-mock resolution skip intentionally unmockable resources.
+- bb1cadf: Rename the generated `testAll` suite from `governance` to `contract`.
+
+### Patch Changes
+
+- d40430d: Remove the retired `@ontrails/logging` workspace from the prerelease package set. Use `@ontrails/observe` for log and trace sink contracts and `@ontrails/logtape` for LogTape forwarding.
+- 193ae78: Migrate testing logger types from the legacy `@ontrails/logging` package to `@ontrails/observe`.
+- Updated dependencies [73622ae]
+- Updated dependencies [e991a5b]
+- Updated dependencies [25f3c5c]
+- Updated dependencies [6300f70]
+- Updated dependencies [d172013]
+- Updated dependencies [c3fc5c3]
+- Updated dependencies [20d7a5c]
+- Updated dependencies [be5fb46]
+- Updated dependencies [e898cc4]
+- Updated dependencies [a8997ed]
+- Updated dependencies [fe03945]
+- Updated dependencies [3395234]
+- Updated dependencies [d40430d]
+- Updated dependencies [bcdc484]
+- Updated dependencies [ed171d5]
+- Updated dependencies [49c2e7d]
+- Updated dependencies [331e3a9]
+- Updated dependencies [4399fdb]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [fbd42fc]
+- Updated dependencies [63d1aef]
+- Updated dependencies [112b9f2]
+- Updated dependencies [893025e]
+- Updated dependencies [ed888e2]
+- Updated dependencies [2e05e27]
+- Updated dependencies [9cdb0f2]
+- Updated dependencies [c8caa5e]
+- Updated dependencies [f4b90c9]
+- Updated dependencies [eec5e9d]
+- Updated dependencies [4e75129]
+- Updated dependencies [47505fe]
+- Updated dependencies [ebd4434]
+- Updated dependencies [863d473]
+- Updated dependencies [344f2f7]
+- Updated dependencies [26f9ffd]
+- Updated dependencies [66056ac]
+- Updated dependencies [0bad534]
+- Updated dependencies [10eae9a]
+- Updated dependencies [22c6c06]
+  - @ontrails/core@1.0.0-beta.16
+  - @ontrails/cli@1.0.0-beta.16
+  - @ontrails/mcp@1.0.0-beta.16
+  - @ontrails/observe@1.0.0-beta.16
+
+## 1.0.0-beta.15
+
+### Minor Changes
+
+- f511a3a: Rename `app` field to `graph` in `CliHarnessOptions` and `McpHarnessOptions`
+
+### Patch Changes
+
+- Updated dependencies [4ad6b25]
+  - @ontrails/core@1.0.0-beta.15
+  - @ontrails/cli@1.0.0-beta.15
+  - @ontrails/observe@1.0.0-beta.15
+  - @ontrails/mcp@1.0.0-beta.15
+
 ## 1.0.0-beta.14
 
 ### Minor Changes

package/README.md

@@ -1,14 +1,14 @@
 # @ontrails/testing
 
-Contract-driven testing for Trails. Add examples to your trails, then `testAll(app)` runs them as assertions, validates output schemas, checks composition graphs, and verifies structural integrity. One line of test code, full governance.
+Contract-driven testing for Trails. Add examples to your trails, then `testAll(graph)` runs them as assertions, validates output schemas, checks composition graphs, and verifies structural integrity. One line of test code, full contract coverage.
 
 ## Usage
 
 ```typescript
 import { testAll } from '@ontrails/testing';
-import { app } from '../app';
+import { graph } from '../app';
 
-testAll(app);
+testAll(graph);
 ```
 
 That single call covers example execution, contract validation, detour checks, and topo validation. For most apps, this is all you need.
@@ -18,20 +18,20 @@ If you want finer control:
 ```typescript
 import { testExamples, testContracts, testDetours } from '@ontrails/testing';
 
-testExamples(app);   // Run every trail's examples as tests
-testContracts(app);  // Validate outputs against declared schemas
-testDetours(app);    // Verify detour targets exist
+testExamples(graph);   // Run every trail's examples as tests
+testContracts(graph);  // Validate outputs against declared schemas
+testDetours(graph);    // Validate detour constructor, recover, and ordering semantics
 ```
 
 ## API
 
 | Export | What it does |
 | --- | --- |
-| `testAll(topo, ctx?)` | Single-line governance suite: validation + examples + contracts + detours |
+| `testAll(topo, ctx?)` | Single-line contract suite: validation + examples + contracts + detours |
 | `testExamples(topo, ctx?)` | Run trail examples as `describe`/`test` blocks |
 | `testTrail(trail, scenarios)` | Custom scenarios for edge cases, error paths, and cross chains |
 | `testContracts(topo, ctx?)` | Validate output against declared schemas |
-| `testDetours(topo)` | Verify every detour target exists in the topo |
+| `testDetours(topo)` | Validate detour constructor, recover, and shadowing semantics |
 | `createCrossContext(options?)` | Mock `CrossFn` for testing composite trails; returns preconfigured `Result` values keyed by trail ID |
 | `createTestContext(options?)` | `TrailContext` with sensible test defaults |
 | `createTestLogger()` | Logger that captures entries in memory for assertions |
@@ -81,23 +81,23 @@ const cross = createCrossContext({
   },
 });
 const ctx = { ...createTestContext(), cross };
-const result = await onboardTrail.run({ name: 'Delta', type: 'tool' }, ctx);
+const result = await onboardTrail.blaze({ name: 'Delta', type: 'tool' }, ctx);
 ```
 
 Calls to unregistered trail IDs return `Result.err` with a descriptive message, so missing stubs fail loudly.
 
-## Trailhead harnesses
+## Surface Harnesses
 
 ```typescript
 import { createCliHarness, createMcpHarness } from '@ontrails/testing';
 
 // CLI
-const cli = createCliHarness({ app });
+const cli = createCliHarness({ graph });
 const result = await cli.run('entity show --name Alpha --output json');
 expect(result.exitCode).toBe(0);
 
 // MCP
-const mcp = createMcpHarness({ app });
+const mcp = createMcpHarness({ graph });
 const tool = await mcp.callTool('myapp_entity_show', { name: 'Alpha' });
 expect(tool.isError).toBe(false);
 ```

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@ontrails/testing",
-  "version": "1.0.0-beta.14",
+  "version": "1.0.0-beta.16",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,13 +22,14 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "devDependencies": {
-    "@ontrails/store": "^1.0.0-beta.13"
+    "@ontrails/drizzle": "^1.0.0-beta.15",
+    "@ontrails/store": "^1.0.0-beta.15"
   },
   "peerDependencies": {
-    "@ontrails/cli": "^1.0.0-beta.13",
-    "@ontrails/core": "^1.0.0-beta.13",
-    "@ontrails/logging": "^1.0.0-beta.13",
-    "@ontrails/mcp": "^1.0.0-beta.13",
+    "@ontrails/cli": "^1.0.0-beta.15",
+    "@ontrails/core": "^1.0.0-beta.15",
+    "@ontrails/mcp": "^1.0.0-beta.15",
+    "@ontrails/observe": "^1.0.0-beta.15",
     "zod": "^4.3.5"
   }
 }

package/src/all.ts

@@ -1,28 +1,31 @@
 /**
- * testAll — single-line governance suite for any Topo.
+ * testAll — single-line contract suite for any Topo.
  *
  * Wraps topo validation, example execution, contract checks, and detour
- * verification into one describe block.
+ * contract validation into one describe block.
  */
 
 import { describe, expect, test } from 'bun:test';
 
 import type { Topo, TrailContext } from '@ontrails/core';
-import { validateTopo } from '@ontrails/core';
+import { validateEstablishedTopo, validateTopo } from '@ontrails/core';
 
+import { createCliHarness } from './harness-cli.js';
+import { createMcpHarness } from './harness-mcp.js';
 import { testContracts } from './contracts.js';
 import type { TestExecutionOptions } from './context.js';
 import { testDetours } from './detours.js';
 import { testExamples } from './examples.js';
+import type { TestAllEstablishedOptions } from './types.js';
 
 /**
- * Run the full governance test suite for a Topo.
+ * Run the full contract test suite for a Topo.
  *
- * Generates a `governance` describe block containing:
+ * Generates a `contract` describe block containing:
  * - Structural validation via `validateTopo`
  * - Example execution via `testExamples`
  * - Output contract checks via `testContracts`
- * - Detour target verification via `testDetours`
+ * - Detour contract validation 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
@@ -31,22 +34,53 @@ import { testExamples } from './examples.js';
  * @example
  * ```ts
  * import { testAll } from '@ontrails/testing';
- * import { app } from '../src/app.js';
+ * import { graph } from '../src/app.js';
  *
- * testAll(app);
+ * testAll(graph);
  * ```
  */
-export const testAll = (
+type TestAllInput =
+  | Partial<TrailContext>
+  | TestExecutionOptions
+  | (() => Partial<TrailContext> | TestExecutionOptions);
+
+const formatValidationFailure = (error: Error): string => {
+  const issues = (
+    error as {
+      context?: { issues?: readonly Record<string, unknown>[] };
+    }
+  ).context?.issues;
+
+  if (issues === undefined || issues.length === 0) {
+    return error.message;
+  }
+
+  const details = issues.map((issue) => {
+    const id = typeof issue['id'] === 'string' ? issue['id'] : undefined;
+    const message =
+      typeof issue['message'] === 'string' ? issue['message'] : undefined;
+    const rule = typeof issue['rule'] === 'string' ? issue['rule'] : undefined;
+
+    return [rule, id, message].filter(Boolean).join(': ');
+  });
+
+  return [error.message, ...details].join('\n');
+};
+
+const assertValidTopo = (result: ReturnType<typeof validateTopo>): void => {
+  if (result.isErr()) {
+    throw new Error(formatValidationFailure(result.error));
+  }
+};
+
+const registerContractSuite = (
   topo: Topo,
-  ctxOrFactory?:
-    | Partial<TrailContext>
-    | TestExecutionOptions
-    | (() => Partial<TrailContext> | TestExecutionOptions)
+  ctxOrFactory: TestAllInput | undefined,
+  validate: (topo: Topo) => ReturnType<typeof validateTopo>
 ): void => {
-  describe('governance', () => {
+  describe('contract', () => {
     test('topo validates', () => {
-      const result = validateTopo(topo);
-      expect(result.isOk()).toBe(true);
+      expect(() => assertValidTopo(validate(topo))).not.toThrow();
     });
 
     // oxlint-disable-next-line jest/require-hook -- these generate describe/test blocks, not setup code
@@ -57,3 +91,106 @@ export const testAll = (
     testDetours(topo);
   });
 };
+
+export const testAll = (topo: Topo, ctxOrFactory?: TestAllInput): void => {
+  registerContractSuite(topo, ctxOrFactory, validateTopo);
+};
+
+type EstablishedInput =
+  | Partial<TrailContext>
+  | TestAllEstablishedOptions
+  | (() => Partial<TrailContext> | TestAllEstablishedOptions);
+
+const isEstablishedOptions = (
+  input: Partial<TrailContext> | TestAllEstablishedOptions | undefined
+): input is TestAllEstablishedOptions =>
+  input !== undefined &&
+  (Object.hasOwn(input, 'cli') ||
+    Object.hasOwn(input, 'createPermit') ||
+    Object.hasOwn(input, 'ctx') ||
+    Object.hasOwn(input, 'mcp') ||
+    Object.hasOwn(input, 'resources') ||
+    Object.hasOwn(input, 'strictPermits'));
+
+const normalizeEstablishedOptions = (
+  input?: Partial<TrailContext> | TestAllEstablishedOptions
+): TestAllEstablishedOptions =>
+  isEstablishedOptions(input) ? input : { ctx: input };
+
+const toExecutionOptions = (
+  options: TestAllEstablishedOptions
+): TestExecutionOptions => ({
+  ...(options.createPermit === undefined
+    ? {}
+    : { createPermit: options.createPermit }),
+  ...(options.ctx === undefined ? {} : { ctx: options.ctx }),
+  ...(options.resources === undefined ? {} : { resources: options.resources }),
+  ...(options.strictPermits === undefined
+    ? {}
+    : { strictPermits: options.strictPermits }),
+});
+
+const toCliHarnessOptions = (
+  topo: Topo,
+  options: TestAllEstablishedOptions
+) => {
+  const cliOptions = {
+    graph: topo,
+    ...options.cli,
+  };
+
+  if (options.ctx !== undefined) {
+    cliOptions.ctx = options.ctx;
+  }
+
+  return cliOptions;
+};
+
+const toMcpHarnessOptions = (
+  topo: Topo,
+  options: TestAllEstablishedOptions
+) => ({
+  graph: topo,
+  ...options.mcp,
+});
+
+const registerEstablishedSurfaceSuite = (
+  topo: Topo,
+  resolveInput: () =>
+    | Partial<TrailContext>
+    | TestAllEstablishedOptions
+    | undefined
+): void => {
+  describe('surfaces', () => {
+    test('CLI projection validates established topo', () => {
+      const options = normalizeEstablishedOptions(resolveInput());
+      expect(() =>
+        createCliHarness(toCliHarnessOptions(topo, options))
+      ).not.toThrow();
+    });
+
+    test('MCP projection validates established topo', () => {
+      const options = normalizeEstablishedOptions(resolveInput());
+      expect(() =>
+        createMcpHarness(toMcpHarnessOptions(topo, options))
+      ).not.toThrow();
+    });
+  });
+};
+
+export const testAllEstablished = (
+  topo: Topo,
+  optionsOrFactory?: EstablishedInput
+): void => {
+  const resolveInput =
+    typeof optionsOrFactory === 'function'
+      ? optionsOrFactory
+      : () => optionsOrFactory;
+
+  registerContractSuite(
+    topo,
+    () => toExecutionOptions(normalizeEstablishedOptions(resolveInput())),
+    validateEstablishedTopo
+  );
+  registerEstablishedSurfaceSuite(topo, resolveInput);
+};

package/src/assertions.ts

@@ -49,6 +49,40 @@ export const expectErr = <T, E>(result: Result<T, E>): E => {
   return (result as unknown as { error: E }).error;
 };
 
+// ---------------------------------------------------------------------------
+// Result Match Tokens
+// ---------------------------------------------------------------------------
+
+export interface OkResultMatch {
+  readonly __resultMatch: 'ok';
+  readonly value?: unknown | undefined;
+}
+
+export interface ErrResultMatch {
+  readonly __resultMatch: 'err';
+  readonly error?: unknown | undefined;
+}
+
+type ResultMatchToken = OkResultMatch | ErrResultMatch;
+
+/**
+ * Create a partial-match token for `Result.ok(...)` values nested inside
+ * arrays or objects, such as the `Result[]` returned by batch `ctx.cross()`.
+ */
+export const okResultMatch = (value?: unknown): OkResultMatch => ({
+  __resultMatch: 'ok',
+  value,
+});
+
+/**
+ * Create a partial-match token for `Result.err(...)` values nested inside
+ * arrays or objects, such as mixed-success batch `ctx.cross()`.
+ */
+export const errResultMatch = (error?: unknown): ErrResultMatch => ({
+  __resultMatch: 'err',
+  error,
+});
+
 // ---------------------------------------------------------------------------
 // Full Match
 // ---------------------------------------------------------------------------
@@ -87,6 +121,225 @@ export const assertSchemaMatch = (
   }
 };
 
+// ---------------------------------------------------------------------------
+// Partial Match
+// ---------------------------------------------------------------------------
+
+/** Format a path for error messages. */
+const formatLoc = (path: readonly string[]): string =>
+  path.length > 0 ? path.join('.') : 'root';
+
+interface ResultLike {
+  readonly error?: unknown;
+  isErr(): boolean;
+  isOk(): boolean;
+  readonly value?: unknown;
+}
+
+const isResultMatchToken = (value: unknown): value is ResultMatchToken =>
+  typeof value === 'object' &&
+  value !== null &&
+  '__resultMatch' in value &&
+  ((value as Record<string, unknown>)['__resultMatch'] === 'ok' ||
+    (value as Record<string, unknown>)['__resultMatch'] === 'err');
+
+const isResultLike = (value: unknown): value is ResultLike =>
+  typeof value === 'object' &&
+  value !== null &&
+  'isOk' in value &&
+  typeof (value as Record<string, unknown>)['isOk'] === 'function' &&
+  'isErr' in value &&
+  typeof (value as Record<string, unknown>)['isErr'] === 'function';
+
+/** Find an unconsumed actual element that deep-matches the expected object. */
+const findObjectMatch = (
+  actual: unknown[],
+  elem: object,
+  consumed: ReadonlySet<number>,
+  path: readonly string[],
+  index: number
+): number =>
+  actual.findIndex((a, idx) => {
+    if (consumed.has(idx)) {
+      return false;
+    }
+    try {
+      // oxlint-disable-next-line no-use-before-define -- mutual recursion with assertSubset
+      assertSubset(a, elem, [...path, `[${String(index)}]`]);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+
+/**
+ * Assert that every element in `expected` exists in `actual` (order-independent).
+ *
+ * Tracks consumed indices so that duplicate expected elements each require a
+ * distinct actual element — `['a', 'a']` does not match `['a']`.
+ */
+const assertArraySubset = (
+  actual: unknown[],
+  expected: unknown[],
+  path: readonly string[],
+  loc: string
+): void => {
+  const consumed = new Set<number>();
+  for (let i = 0; i < expected.length; i += 1) {
+    const elem = expected[i];
+    const matchIndex =
+      typeof elem === 'object' && elem !== null
+        ? findObjectMatch(actual, elem, consumed, path, i)
+        : actual.findIndex((a, idx) => !consumed.has(idx) && a === elem);
+
+    if (matchIndex === -1) {
+      throw new Error(
+        `at ${loc}[${String(i)}]: expected array to contain ${JSON.stringify(elem)}`
+      );
+    }
+    consumed.add(matchIndex);
+  }
+};
+
+/** Assert that every key in `expected` exists in `actual` with a matching value. */
+const assertObjectSubset = (
+  actual: Record<string, unknown>,
+  expected: Record<string, unknown>,
+  path: readonly string[]
+): void => {
+  for (const key of Object.keys(expected)) {
+    if (!(key in actual)) {
+      throw new Error(
+        `at ${[...path, key].join('.')}: key not found in actual`
+      );
+    }
+    // oxlint-disable-next-line no-use-before-define -- mutual recursion with assertSubset
+    assertSubset(actual[key], expected[key], [...path, key]);
+  }
+};
+
+/**
+ * Recursively assert that `actual` is a superset of `expected`.
+ *
+ * - **Scalars:** strict equality.
+ * - **Objects:** every key in `expected` must exist in `actual` with a matching
+ *   value. Extra keys in `actual` are ignored.
+ * - **Arrays:** every element in `expected` must exist in `actual`
+ *   (order-independent subset check).
+ * - **Nested objects:** recursive subset matching.
+ */
+// oxlint-disable-next-line max-statements -- recursive dispatch across four type branches
+const assertSubset = (
+  actual: unknown,
+  expected: unknown,
+  path: readonly string[]
+): void => {
+  const loc = formatLoc(path);
+
+  if (expected === null || expected === undefined) {
+    if (actual !== expected) {
+      throw new Error(
+        `at ${loc}: expected ${String(expected)}, got ${String(actual)}`
+      );
+    }
+    return;
+  }
+
+  if (isResultMatchToken(expected)) {
+    // oxlint-disable-next-line no-use-before-define -- result token matching delegates back into assertSubset
+    assertResultTokenMatch(actual, expected, path);
+    return;
+  }
+
+  if (Array.isArray(expected)) {
+    if (!Array.isArray(actual)) {
+      throw new TypeError(`at ${loc}: expected an array, got ${typeof actual}`);
+    }
+    assertArraySubset(actual, expected, path, loc);
+    return;
+  }
+
+  if (typeof expected === 'object') {
+    if (
+      typeof actual !== 'object' ||
+      actual === null ||
+      Array.isArray(actual)
+    ) {
+      throw new Error(`at ${loc}: expected an object, got ${typeof actual}`);
+    }
+    assertObjectSubset(
+      actual as Record<string, unknown>,
+      expected as Record<string, unknown>,
+      path
+    );
+    return;
+  }
+
+  if (actual !== expected) {
+    throw new Error(
+      `at ${loc}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`
+    );
+  }
+};
+
+const assertOkResultTokenMatch = (
+  actual: ResultLike,
+  expected: OkResultMatch,
+  loc: string,
+  path: readonly string[]
+): void => {
+  if (!actual.isOk()) {
+    throw new Error(`at ${loc}: expected Result.ok(...), got Result.err(...)`);
+  }
+  if (expected.value !== undefined) {
+    assertSubset(actual.value, expected.value, [...path, 'value']);
+  }
+};
+
+const assertErrResultTokenMatch = (
+  actual: ResultLike,
+  expected: ErrResultMatch,
+  loc: string,
+  path: readonly string[]
+): void => {
+  if (!actual.isErr()) {
+    throw new Error(`at ${loc}: expected Result.err(...), got Result.ok(...)`);
+  }
+  if (expected.error !== undefined) {
+    assertSubset(actual.error, expected.error, [...path, 'error']);
+  }
+};
+
+const assertResultTokenMatch = (
+  actual: unknown,
+  expected: ResultMatchToken,
+  path: readonly string[]
+): void => {
+  const loc = formatLoc(path);
+  if (!isResultLike(actual)) {
+    throw new TypeError(`at ${loc}: expected a Result-like value`);
+  }
+
+  if (expected.__resultMatch === 'ok') {
+    assertOkResultTokenMatch(actual, expected, loc, path);
+    return;
+  }
+
+  assertErrResultTokenMatch(actual, expected, loc, path);
+};
+
+/**
+ * Assert that the result is ok and its value is a superset of the expected
+ * partial output. Declared fields must match; extra fields are ignored.
+ */
+export const assertPartialMatch = (
+  result: Result<unknown, Error>,
+  expectedMatch: unknown
+): void => {
+  const value = expectOk(result);
+  assertSubset(value, expectedMatch, []);
+};
+
 // ---------------------------------------------------------------------------
 // Error Match
 // ---------------------------------------------------------------------------