@jterrazz/test 16.1.1 → 17.0.0

package/docs/decisions/007-compose-mode-leaves-the-package.md

@@ -1,53 +0,0 @@
-# ADR-007: Compose mode leaves the package
-
-**Status:** Accepted
-**Date:** 2026-09-20
-
-## Context
-
-`specification.api({ mode: 'compose' })` let a spec meet the application as a
-container stack described by a `docker/compose.test.yaml` rather than as a Hono
-app handed to `server`. It carried a binding resolver, a compose-file reader, a
-`composeService` name on every service handle, a `TEST_MODE` environment
-variable, a fetch adapter for the api facet, five lint rules (A5, A6, A6w, A10,
-I3) with their fixtures and specs, an `api-stack` project, and an orchestrator
-that had to start two shapes of world.
-
-A no-ignore grep of every clone on the workbench found **zero** consumer files
-using it. The one trace outside this package is a prose mention in one
-repository's testing chapter.
-
-The mode was also the source of a whole class of confusion the surveys kept
-finding: two ways to say what the subject is (`server` and a compose service),
-two names for one service (its record key and its `composeName`), and a set of
-rules whose only job was to keep the two from contradicting each other.
-
-## Decision
-
-Compose mode leaves, with no deprecation window: none opens for a consumer that
-does not exist.
-
-What goes: `mode`, `TEST_MODE`, the `docker/compose.test.yaml` binding,
-`composeService`, `src/integrations/compose/`, the api facet's fetch adapter,
-rules A5, A6, A6w, A10 and I3 with every fixture and spec of theirs, and the
-`api-stack` project.
-
-The record KEY becomes the only name a service has: `serviceName`, assigned
-from the key at start, and the init script a database runs is read from
-`<root>/docker/<serviceName>/init.sql`. `ROOT_MARKERS` collapses to
-`package.json`.
-
-## Consequences
-
-- One shape of world: a specification starts the services its record declares
-  and hands the subject to `server`. An agent that knows one facet knows them
-  all, and the orchestrator has one path through startup instead of two.
-- A consumer config naming a removed rule id fails oxlint's unknown-rule check
-  — the same failure mode ADR-002 had for J1/J3/J4/J5, and the survey found no
-  consumer config naming any of the five.
-- A future need to drive a deployed stack is not closed: `process()` is the one
-  shape an external process takes in either slot, and `url` already targets a
-  world this run did not start. What is closed is a SECOND vocabulary for it.
-- The package's own specs lost the one place where a spec reached past the
-  public entry to build an `Orchestrator` by hand; both were rewritten through
-  the entry, which is what rule F3 asks of every consumer.

package/docs/decisions/008-vitest-5-node-24-and-the-native-seams-as-optional-peers.md

@@ -1,75 +0,0 @@
-# ADR-008: Vitest 5, Node 24, the native seams as optional peers, and every artefact under `.artifacts/`
-
-**Status:** Accepted
-**Date:** 2026-09-20
-
-## Context
-
-Three questions came due together at the major.
-
-**Which runner?** 15.2 and 15.3 shipped against `vitest ^4.1.10 || ^5`, which
-meant the package proved itself on two runners and a consumer could be on
-either. Vitest 5 is not a drop-in: `Assertion` gained a type parameter (an
-augmentation whose parameter list differs is refused outright), and Browser Mode
-pins its provider to the runner's EXACT patch — `@vitest/browser-playwright@X`
-peers `vitest: X`.
-
-**Which dependencies?** `better-sqlite3`, `pg`, `redis` and `testcontainers`
-were plain dependencies: every consumer installed four native packages, and
-three of them built native code on install, to run a suite most of them never
-pointed at a database. Under pnpm a native seam only builds when it is named in
-`only-built-dependencies`, so the cost was not even paid consistently.
-
-**Where do artefacts go?** Vitest 5 writes to `.vitest/` at the repository root,
-Browser Mode leaks `.vitest-attachments/` there and `__screenshots__/` beside
-the tests. The estate's doctrine says an artefact is never on the row, and the
-toolchain's gate enforces it — which would have failed every consumer's first
-run on 5.
-
-## Decision
-
-**`vitest ^5`, and only 5.** The peer is `^5`; the package's own devDependency
-pins `vitest` and `@vitest/browser-playwright` to the same exact patch, and
-`component()` asserts that equality at startup, naming both versions. The adopt
-flow bumps the pair in one unit.
-
-**`engines.node: ">=24"`** — the toolchain's floor, not a third one.
-
-**The four native seams become OPTIONAL peers**, each loaded on first use
-through `loadPeer()`, whose refusal names the facet, the peer, the install
-command of the package manager the project's own lockfile names, and — under
-pnpm — the `onlyBuiltDependencies` line. What stays a dependency is what every
-consumer uses and none should declare: `msw`, `vitest-mock-extended`, `yaml`.
-That list is what rule F8 reads.
-
-The saving is npm's and Bun's. pnpm resolves a peer it can satisfy whatever
-the consumer declares — with `auto-install-peers` (its default since 8) all
-four arrive anyway, and the native one builds — so under pnpm the change buys
-the DECLARATION, not the install: a member that uses `sqlite()` says so, and a
-member that does not is no longer described by its dependency tree as a
-database consumer.
-
-**Every artefact under `.artifacts/vitest/`**: `attachmentsDir`, the
-json/junit/html/blob `outputFile` map, and both screenshot directories, set by
-the preset. A path the tool pins and cannot relocate is the toolchain map's to
-list, not this package's to hide.
-
-The preset also takes the hygiene defaults a suite should not have to restate:
-`retry: 0`, `restoreMocks`, `unstubGlobals`, `unstubEnvs`.
-
-## Consequences
-
-- A consumer on vitest 4 stays on `@jterrazz/test` 15.x until it adopts 5. The
-  package no longer pays for two runners, and the type augmentation can state
-  vitest 5's signature character for character.
-- A consumer using `sqlite()`, `postgres()`, `redis()` or a container declares
-  that peer — three repositories on the workbench use `sqlite()` today. Every
-  other consumer stops installing four native packages it never loads.
-- The failure mode for a missing peer is a startup message naming the install
-  command, not a module-resolution error from inside an adapter.
-- The artefact paths are the package's to set and the toolchain's to allow: one
-  entry in its allowlist, one row in the estate's toolchain map, and the gate
-  holds for every consumer from their first run.
-- The version pin is exact on purpose. It is the one dependency where "compatible"
-  is not enough: the provider and the runner exchange a protocol, and a patch
-  apart they refuse each other at startup rather than at type-check.

package/docs/decisions/_template.md

@@ -1,22 +0,0 @@
-# ADR-NNN: Title
-
-**Status:** Proposed
-**Date:** YYYY-MM-DD
-
-An agent leaves the status `Proposed`; only the owner writes `Accepted`.
-
-A retroactive record carries one honest line here: written YYYY-MM-DD from
-the evidence it was reconstructed from. A record written at decision time
-carries nothing.
-
-## Context
-
-The situation that forced a decision — the forces, not the answer.
-
-## Decision
-
-What was decided, and the shape of the choice.
-
-## Consequences
-
-- What follows: costs accepted, freedoms gained, doors closed and opened.

package/docs/reference/classes/Matcher.md

@@ -1,120 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Class: Matcher
-
-Defined in: [src/model/matching/match.ts:70](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L70)
-
-A dynamic-value matcher. Created via the [match](../variables/match.md) factories — never
-constructed directly by user code.
-
-## Constructors
-
-### Constructor
-
-```ts
-new Matcher(kind, options?): Matcher;
-```
-
-Defined in: [src/model/matching/match.ts:81](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L81)
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `kind` | [`MatcherKind`](../type-aliases/MatcherKind.md) |
-| `options` | \{ `includes?`: `string`; `notRef?`: `string`; `refName?`: `string`; `regex?`: `RegExp`; \} |
-| `options.includes?` | `string` |
-| `options.notRef?` | `string` |
-| `options.refName?` | `string` |
-| `options.regex?` | `RegExp` |
-
-#### Returns
-
-`Matcher`
-
-## Properties
-
-### includes?
-
-```ts
-readonly optional includes?: string;
-```
-
-Defined in: [src/model/matching/match.ts:72](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L72)
-
-For kind 'includes': the substring the actual value must contain.
-
-***
-
-### kind
-
-```ts
-readonly kind: MatcherKind;
-```
-
-Defined in: [src/model/matching/match.ts:73](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L73)
-
-***
-
-### notRef?
-
-```ts
-readonly optional notRef?: string;
-```
-
-Defined in: [src/model/matching/match.ts:75](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L75)
-
-For kind 'ref': the capture to assert inequality against.
-
-***
-
-### refName?
-
-```ts
-readonly optional refName?: string;
-```
-
-Defined in: [src/model/matching/match.ts:77](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L77)
-
-For kind 'ref': the capture name.
-
-***
-
-### regex?
-
-```ts
-readonly optional regex?: RegExp;
-```
-
-Defined in: [src/model/matching/match.ts:79](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L79)
-
-For kind 'regex': the pattern the actual value must match.
-
-## Methods
-
-### toJSON()
-
-```ts
-toJSON(): string;
-```
-
-Defined in: [src/model/matching/match.ts:117](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L117)
-
-#### Returns
-
-`string`
-
-***
-
-### toString()
-
-```ts
-toString(): string;
-```
-
-Defined in: [src/model/matching/match.ts:98](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L98)
-
-Placeholder-style rendering used in failure diffs and serialization.
-
-#### Returns
-
-`string`

package/docs/reference/classes/ProcessHandle.md

@@ -1,368 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Class: ProcessHandle
-
-Defined in: [src/model/chain/process.ts:21](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L21)
-
-An external process, declared like any other service.
-
-One shape for every one of them: a site's dev server, an API behind the
-site, the bundler a simulator loads from. Without it each is declared
-somewhere else — a facet option, a document's `serve:` entry, a `beforeAll`
-spawning a child and an `afterAll` that sometimes forgets to kill it — and
-the lifetime belongs to whoever remembered. Here it is the framework's.
-
-It sits in a `services` record beside `postgres()`, `redis()` and
-`sqlite()`, so it starts after them and can be handed their connection
-strings through `env`, and it is stopped with the specification.
-
-## Implements
-
-- [`ServiceHandle`](../type-aliases/ServiceHandle.md)
-
-## Constructors
-
-### Constructor
-
-```ts
-new ProcessHandle(options): ProcessHandle;
-```
-
-Defined in: [src/model/chain/process.ts:35](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L35)
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `options` | [`ProcessOptions`](../type-aliases/ProcessOptions.md) |
-
-#### Returns
-
-`ProcessHandle`
-
-## Properties
-
-### connectionString
-
-```ts
-connectionString: string = '';
-```
-
-Defined in: [src/model/chain/process.ts:29](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L29)
-
-Connection string — populated after start.
-
-#### Implementation of
-
-```ts
-ServiceHandle.connectionString
-```
-
-***
-
-### defaultImage
-
-```ts
-readonly defaultImage: "" = '';
-```
-
-Defined in: [src/model/chain/process.ts:23](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L23)
-
-Embedded: nothing to pull, nothing to run in a container.
-
-#### Implementation of
-
-```ts
-ServiceHandle.defaultImage
-```
-
-***
-
-### defaultPort
-
-```ts
-readonly defaultPort: 0 = 0;
-```
-
-Defined in: [src/model/chain/process.ts:24](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L24)
-
-Default container port for this service type.
-
-#### Implementation of
-
-```ts
-ServiceHandle.defaultPort
-```
-
-***
-
-### environment
-
-```ts
-readonly environment: Record<string, string> = {};
-```
-
-Defined in: [src/model/chain/process.ts:25](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L25)
-
-Environment variables to pass to the container.
-
-#### Implementation of
-
-```ts
-ServiceHandle.environment
-```
-
-***
-
-### serviceName
-
-```ts
-serviceName: string | null = null;
-```
-
-Defined in: [src/model/chain/process.ts:28](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L28)
-
-The name this handle is known by. Left `null` until the orchestrator
-assigns it at start time: it is the kebab-case form of the RECORD KEY,
-so `{ analyticsDb: postgres() }` reports as `analytics-db` and reads its
-init script from `docker/analytics-db/`. The key is the only name a
-specification writes; a handle carries no second one of its own.
-
-#### Implementation of
-
-```ts
-ServiceHandle.serviceName
-```
-
-***
-
-### started
-
-```ts
-started: boolean = false;
-```
-
-Defined in: [src/model/chain/process.ts:30](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L30)
-
-Whether this service has been started.
-
-#### Implementation of
-
-```ts
-ServiceHandle.started
-```
-
-***
-
-### type
-
-```ts
-readonly type: "process" = 'process';
-```
-
-Defined in: [src/model/chain/process.ts:26](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L26)
-
-Service type identifier.
-
-#### Implementation of
-
-```ts
-ServiceHandle.type
-```
-
-## Accessors
-
-### spec
-
-#### Get Signature
-
-```ts
-get spec(): ProcessOptions;
-```
-
-Defined in: [src/model/chain/process.ts:122](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L122)
-
-What it was declared as — what a facet reads to start it in a slot of its own.
-
-##### Returns
-
-[`ProcessOptions`](../type-aliases/ProcessOptions.md)
-
-***
-
-### url
-
-#### Get Signature
-
-```ts
-get url(): string;
-```
-
-Defined in: [src/model/chain/process.ts:127](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L127)
-
-The base URL it came up on — known only once it is started.
-
-##### Returns
-
-`string`
-
-## Methods
-
-### buildConnectionString()
-
-```ts
-buildConnectionString(host, port): string;
-```
-
-Defined in: [src/model/chain/process.ts:39](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L39)
-
-Build the connection string from host and port.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `host` | `string` |
-| `port` | `number` |
-
-#### Returns
-
-`string`
-
-#### Implementation of
-
-```ts
-ServiceHandle.buildConnectionString
-```
-
-***
-
-### createDatabaseAdapter()
-
-```ts
-createDatabaseAdapter(): DatabasePort | null;
-```
-
-Defined in: [src/model/chain/process.ts:43](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L43)
-
-Create a DatabasePort adapter (if this is a database). Returns null otherwise.
-
-#### Returns
-
-[`DatabasePort`](../type-aliases/DatabasePort.md) \| `null`
-
-#### Implementation of
-
-```ts
-ServiceHandle.createDatabaseAdapter
-```
-
-***
-
-### healthcheck()
-
-```ts
-healthcheck(): Promise<void>;
-```
-
-Defined in: [src/model/chain/process.ts:47](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L47)
-
-Verify the service is ready and accepting connections. Throws with context if not.
-
-#### Returns
-
-`Promise`\<`void`\>
-
-#### Implementation of
-
-```ts
-ServiceHandle.healthcheck
-```
-
-***
-
-### initialize()
-
-```ts
-initialize(): Promise<void>;
-```
-
-Defined in: [src/model/chain/process.ts:58](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L58)
-
-A process is not a container, so the orchestrator never starts it: the
-facet does, once its siblings are up and their connection strings are
-readable (startProcessServices).
-
-#### Returns
-
-`Promise`\<`void`\>
-
-#### Implementation of
-
-```ts
-ServiceHandle.initialize
-```
-
-***
-
-### isolation()
-
-```ts
-isolation(): IsolationStrategy;
-```
-
-Defined in: [src/model/chain/process.ts:70](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L70)
-
-Isolation is the RUN's, not the worker's — and a run here is one
-EVALUATION of the specification module. Under vitest's default
-isolation that is once per test file, so two files that import the same
-specification get a child each, with the id the facet minted for it.
-Nothing is acquired or reset between tests: the id is what tells two
-runs apart, never a label a spec samples.
-
-#### Returns
-
-[`IsolationStrategy`](../type-aliases/IsolationStrategy.md)
-
-#### Implementation of
-
-```ts
-ServiceHandle.isolation
-```
-
-***
-
-### reset()
-
-```ts
-reset(): Promise<void>;
-```
-
-Defined in: [src/model/chain/process.ts:84](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L84)
-
-Reset state between tests (truncate tables, flush cache, etc.)
-
-#### Returns
-
-`Promise`\<`void`\>
-
-#### Implementation of
-
-```ts
-ServiceHandle.reset
-```
-
-***
-
-### shutdown()
-
-```ts
-shutdown(): Promise<void>;
-```
-
-Defined in: [src/model/chain/process.ts:115](https://github.com/jterrazz/package-test/blob/main/src/model/chain/process.ts#L115)
-
-Terminate the process group. Idempotent.
-
-#### Returns
-
-`Promise`\<`void`\>

package/docs/reference/functions/defineContract.md

@@ -1,39 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Function: defineContract()
-
-```ts
-function defineContract(contract): Contract;
-```
-
-Defined in: [src/model/contracts/contract.ts:71](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/contract.ts#L71)
-
-Declare one contract. Identity function — its value is the enforced shape
-and the naming convention:
-
-## Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `contract` | [`Contract`](../type-aliases/Contract.md) |
-
-## Returns
-
-[`Contract`](../type-aliases/Contract.md)
-
-## Example
-
-```ts
-// specs/api/reports/contracts/openai/classify-article.ts
-  import { defineContract, openai } from '@jterrazz/test';
-
-  export default defineContract({
-      request: openai.responses({ user: PROMPT, tools: ['classify'] }),
-      response: openai.reply({ categories: ['TECH'] }),
-  });
-
-  // Dynamic — the response is computed from the observed request:
-  export default defineContract({
-      request: http.post('https://api.example.com/echo'),
-      response: (request) => http.json({ received: request.body }),
-  });
-```