@jterrazz/test 16.1.1 → 17.0.0

package/docs/reference/type-aliases/IntegrationSpecificationOptions.md

@@ -1,42 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: IntegrationSpecificationOptions\<Services\>
-
-```ts
-type IntegrationSpecificationOptions<Services> = object;
-```
-
-Defined in: [src/facets/integration/integration.specification.ts:17](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.specification.ts#L17)
-
-Options for startIntegration \| specification.integration.
-
-## Type Parameters
-
-| Type Parameter | Default type |
-| ------ | ------ |
-| `Services` *extends* [`ServiceRecord`](ServiceRecord.md) | [`ServiceRecord`](ServiceRecord.md) |
-
-## Properties
-
-### root?
-
-```ts
-optional root?: string;
-```
-
-Defined in: [src/facets/integration/integration.specification.ts:19](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.specification.ts#L19)
-
-Project-root override — see the `root` option of `specification.api()`.
-
-***
-
-### services?
-
-```ts
-optional services?: Services;
-```
-
-Defined in: [src/facets/integration/integration.specification.ts:25](https://github.com/jterrazz/package-test/blob/main/src/facets/integration/integration.specification.ts#L25)
-
-Named infrastructure the module is specified AGAINST — a real database,
-a real cache, a `process()` it talks to. Omit it for the other half of
-the facet: a pure module whose oracle is a golden.

package/docs/reference/type-aliases/Intercept.md

@@ -1,19 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: Intercept
-
-```ts
-type Intercept = (contracts, options?) => Promise<InterceptScope> & (request, response, options?) => Promise<InterceptScope>;
-```
-
-Defined in: [src/model/contracts/intercept.ts:54](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/intercept.ts#L54)
-
-The module-scope network double. Resolves once the engine is listening —
-which is why it is a promise, and why the canonical form awaits it:
-
-```typescript
-await using _ = await intercept(http.get(url), http.json({ ok: true }));
-```
-
-Without that `await` the subject could reach the real network before the
-first handler is in place, so the shape refuses the racy spelling: a promise
-is not an `AsyncDisposable`, and the compiler says so.

package/docs/reference/type-aliases/InterceptOptions.md

@@ -1,28 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: InterceptOptions
-
-```ts
-type InterceptOptions = object;
-```
-
-Defined in: [src/model/contracts/intercept.ts:29](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/intercept.ts#L29)
-
-What a scope may state about the network it declares.
-
-## Properties
-
-### origin?
-
-```ts
-optional origin?: string;
-```
-
-Defined in: [src/model/contracts/intercept.ts:39](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/intercept.ts#L39)
-
-The base a RELATIVE request resolves against, for the life of the scope.
-
-A module that calls `fetch('/api/posts')` is browser code: under node the
-URL cannot be parsed at all, so the request fails before any contract can
-answer it and the test's only way out was to replace `fetch` itself. With
-an origin stated, the relative call resolves here and the declared
-contracts — path form or absolute — match it as they would any other.

package/docs/reference/type-aliases/InterceptScope.md

@@ -1,11 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: InterceptScope
-
-```ts
-type InterceptScope = AsyncDisposable;
-```
-
-Defined in: [src/model/contracts/intercept.ts:26](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/intercept.ts#L26)
-
-One block's worth of declared network. Disposed at the end of the scope that
-declared it: the handlers are dropped, and an unmatched request is thrown.

package/docs/reference/type-aliases/IsolationStrategy.md

@@ -1,75 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: IsolationStrategy
-
-```ts
-type IsolationStrategy = object;
-```
-
-Defined in: [src/model/ports/isolation.port.ts:11](https://github.com/jterrazz/package-test/blob/main/src/model/ports/isolation.port.ts#L11)
-
-Strategy for isolating service state across parallel test workers.
-
-Each service handle provides an isolation strategy. The framework
-calls `acquire()` once per vitest worker, `reset()` before each
-`spec.run()`, and `release()` when the worker shuts down.
-
-Implement this interface to support new service types (e.g. MongoDB,
-Elasticsearch, S3).
-
-## Properties
-
-### acquire
-
-```ts
-acquire: (workerId) => Promise<void>;
-```
-
-Defined in: [src/model/ports/isolation.port.ts:19](https://github.com/jterrazz/package-test/blob/main/src/model/ports/isolation.port.ts#L19)
-
-Create an isolated namespace for this worker.
-Called once when the worker starts — e.g. clone a template database,
-set a Redis key prefix.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `workerId` | `string` | Unique identifier for this vitest worker. |
-
-#### Returns
-
-`Promise`\<`void`\>
-
-***
-
-### release
-
-```ts
-release: () => Promise<void>;
-```
-
-Defined in: [src/model/ports/isolation.port.ts:31](https://github.com/jterrazz/package-test/blob/main/src/model/ports/isolation.port.ts#L31)
-
-Tear down the isolated namespace.
-Called once when the worker shuts down — e.g. drop the cloned database.
-
-#### Returns
-
-`Promise`\<`void`\>
-
-***
-
-### reset
-
-```ts
-reset: () => Promise<void>;
-```
-
-Defined in: [src/model/ports/isolation.port.ts:25](https://github.com/jterrazz/package-test/blob/main/src/model/ports/isolation.port.ts#L25)
-
-Fast reset within the namespace between `spec.run()` calls.
-E.g. truncate tables (without dropping the database).
-
-#### Returns
-
-`Promise`\<`void`\>

package/docs/reference/type-aliases/JobHandle.md

@@ -1,34 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: JobHandle
-
-```ts
-type JobHandle = object;
-```
-
-Defined in: [src/model/chain/builder.ts:36](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L36)
-
-A named job that can be triggered via jobs.trigger().
-
-## Properties
-
-### execute
-
-```ts
-execute: () => Promise<void>;
-```
-
-Defined in: [src/model/chain/builder.ts:38](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L38)
-
-#### Returns
-
-`Promise`\<`void`\>
-
-***
-
-### name
-
-```ts
-name: string;
-```
-
-Defined in: [src/model/chain/builder.ts:37](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L37)

package/docs/reference/type-aliases/JobsHandle.md

@@ -1,57 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: JobsHandle\<DatabaseKey\>
-
-```ts
-type JobsHandle<DatabaseKey> = object;
-```
-
-Defined in: [src/facets/jobs/jobs.specification.ts:37](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L37)
-
-The record returned by startJobs \| specification.jobs. Destructure
-with the canonical names (CONVENTIONS A3):
-
-    const { jobs, cleanup } = await specification.jobs(…);
-
-## Type Parameters
-
-| Type Parameter | Default type |
-| ------ | ------ |
-| `DatabaseKey` *extends* `string` | `string` |
-
-## Properties
-
-### cleanup
-
-```ts
-cleanup: () => Promise<void>;
-```
-
-Defined in: [src/facets/jobs/jobs.specification.ts:39](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L39)
-
-Stop all infrastructure started by this specification.
-
-#### Returns
-
-`Promise`\<`void`\>
-
-***
-
-### jobs
-
-```ts
-jobs: JobsSpecification<DatabaseKey>;
-```
-
-Defined in: [src/facets/jobs/jobs.specification.ts:40](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L40)
-
-***
-
-### orchestrator
-
-```ts
-orchestrator: null | Orchestrator;
-```
-
-Defined in: [src/facets/jobs/jobs.specification.ts:42](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L42)
-
-The orchestrator managing the test infrastructure lifecycle.

package/docs/reference/type-aliases/JobsResult.md

@@ -1,16 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: JobsResult
-
-```ts
-type JobsResult = Omit<BaseResult, "directory" | "file">;
-```
-
-Defined in: [src/model/chain/builder.ts:214](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L214)
-
-What a triggered job HANDS BACK.
-
-A job writes to a database, a cache, a queue — never to a working directory
-the spec then walks, because a job has none: it runs in this process, where
-the only filesystem is the repository's. So the two accessors that read one
-(`file()`, `directory()`) are not on this result. A pipeline that really
-produces files is a binary, and `specification.cli()` is its facet.

package/docs/reference/type-aliases/JobsSpecification.md

@@ -1,94 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: JobsSpecification\<DatabaseKey\>
-
-```ts
-type JobsSpecification<DatabaseKey> = object;
-```
-
-Defined in: [src/model/chain/builder.ts:216](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L216)
-
-## Type Parameters
-
-| Type Parameter | Default type |
-| ------ | ------ |
-| `DatabaseKey` *extends* `string` | `string` |
-
-## Properties
-
-### clock
-
-```ts
-clock: (iso) => JobsSpecification<DatabaseKey>;
-```
-
-Defined in: [src/model/chain/builder.ts:218](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L218)
-
-Pin the job's `Date` at `iso` for this chain — the calendar the job reads.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `iso` | `string` |
-
-#### Returns
-
-`JobsSpecification`\<`DatabaseKey`\>
-
-***
-
-### intercept
-
-```ts
-intercept: InterceptMethod<JobsSpecification<DatabaseKey>>;
-```
-
-Defined in: [src/model/chain/builder.ts:220](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L220)
-
-Declare outgoing calls — a contract, a list, a composite, or an inline request + response pair.
-
-***
-
-### seed
-
-```ts
-seed: (file, options?) => JobsSpecification<DatabaseKey>;
-```
-
-Defined in: [src/model/chain/builder.ts:222](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L222)
-
-Queue a SQL seed file from `_seeds/` to run before the action.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `file` | `string` |
-| `options?` | \{ `database?`: `DatabaseKey`; \} |
-| `options.database?` | `DatabaseKey` |
-
-#### Returns
-
-`JobsSpecification`\<`DatabaseKey`\>
-
-***
-
-### trigger
-
-```ts
-trigger: (name) => Promise<JobsResult>;
-```
-
-Defined in: [src/model/chain/builder.ts:225](https://github.com/jterrazz/package-test/blob/main/src/model/chain/builder.ts#L225)
-
-Execute the named job registered via the `jobs` option and resolve with the result.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `name` | `string` |
-
-#### Returns
-
-`Promise`\<[`JobsResult`](JobsResult.md)\>

package/docs/reference/type-aliases/JobsSpecificationOptions.md

@@ -1,56 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: JobsSpecificationOptions\<Services\>
-
-```ts
-type JobsSpecificationOptions<Services> = object;
-```
-
-Defined in: [src/facets/jobs/jobs.specification.ts:18](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L18)
-
-Options for startJobs \| specification.jobs.
-
-## Type Parameters
-
-| Type Parameter | Default type |
-| ------ | ------ |
-| `Services` *extends* [`ServiceRecord`](ServiceRecord.md) | [`ServiceRecord`](ServiceRecord.md) |
-
-## Properties
-
-### jobs
-
-```ts
-jobs: 
-  | ((services) => JobHandle[])
-  | JobHandle[];
-```
-
-Defined in: [src/facets/jobs/jobs.specification.ts:24](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L24)
-
-Named jobs triggerable via `jobs.trigger(name)` — a factory receiving
-the started services record, or a static array. Jobs run in-process by
-definition (CONVENTIONS A8).
-
-***
-
-### root?
-
-```ts
-optional root?: string;
-```
-
-Defined in: [src/facets/jobs/jobs.specification.ts:26](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L26)
-
-Project root override — see the `root` option of `specification.api()`.
-
-***
-
-### services?
-
-```ts
-optional services?: Services;
-```
-
-Defined in: [src/facets/jobs/jobs.specification.ts:28](https://github.com/jterrazz/package-test/blob/main/src/facets/jobs/jobs.specification.ts#L28)
-
-Named infrastructure record started via testcontainers.

package/docs/reference/type-aliases/LandmarkKind.md

@@ -1,20 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: LandmarkKind
-
-```ts
-type LandmarkKind = 
-  | "banner"
-  | "complementary"
-  | "contentinfo"
-  | "form"
-  | "main"
-  | "navigation"
-  | "region"
-  | "search";
-```
-
-Defined in: [src/model/ports/browser.port.ts:6](https://github.com/jterrazz/package-test/blob/main/src/model/ports/browser.port.ts#L6)
-
-The landmark roles — the standard set of page regions, and the only
-containers a scope can name. Closed on purpose: ARIA defines exactly these,
-so `within()` never becomes a second selector language.

package/docs/reference/type-aliases/LiterateRunFlags.md

@@ -1,27 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: LiterateRunFlags
-
-```ts
-type LiterateRunFlags = object;
-```
-
-Defined in: [src/facets/cli/literate.ts:66](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L66)
-
-Per-call options for runSpecDocument / `cli.run()`.
-
-## Properties
-
-### frozen?
-
-```ts
-optional frozen?: boolean;
-```
-
-Defined in: [src/facets/cli/literate.ts:75](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L75)
-
-Opt this document OUT of the update-mode rewrite. A frozen document is
-NEVER written under `TEST_UPDATE=1`: its mismatch still throws its diff.
-That is what makes a DELIBERATELY-WRONG `.spec.yaml` — one whose failure
-rendering is the subject of a negative test — survive an update run
-instead of being silently corrected into a passing file. The document's
-mirror of `toMatch(name, { frozen: true })`.

package/docs/reference/type-aliases/LiterateServeRegistration.md

@@ -1,70 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: LiterateServeRegistration
-
-```ts
-type LiterateServeRegistration = object;
-```
-
-Defined in: [src/facets/cli/literate.ts:51](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L51)
-
-A server a document may start by name (`serve: mcp`), registered once per app
-in the `serve` option of `specification.cli()`.
-
-## Properties
-
-### command
-
-```ts
-command: string;
-```
-
-Defined in: [src/facets/cli/literate.ts:53](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L53)
-
-Shell command that starts the server, run from the project root.
-
-***
-
-### env
-
-```ts
-env: string;
-```
-
-Defined in: [src/facets/cli/literate.ts:55](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L55)
-
-The variable the resolved URL is bound to in every run's child env.
-
-***
-
-### ready
-
-```ts
-ready: RegExp;
-```
-
-Defined in: [src/facets/cli/literate.ts:60](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L60)
-
-Matched against the server's output; the FIRST capture group is the port
-it chose — named (`(?<port>\d+)`) or not, it is group 1 either way.
-
-***
-
-### url
-
-```ts
-url: (port) => string;
-```
-
-Defined in: [src/facets/cli/literate.ts:62](https://github.com/jterrazz/package-test/blob/main/src/facets/cli/literate.ts#L62)
-
-Builds the URL bound to [env](#env) from the announced port.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `port` | `number` |
-
-#### Returns
-
-`string`

package/docs/reference/type-aliases/MatchFixtureOptions.md

@@ -1,27 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: MatchFixtureOptions
-
-```ts
-type MatchFixtureOptions = object;
-```
-
-Defined in: [src/model/result/match-options.ts:21](https://github.com/jterrazz/package-test/blob/main/src/model/result/match-options.ts#L21)
-
-Per-call options for the fixture-file `toMatch` subjects. `frozen` opts a
-single fixture OUT of update-mode rewriting: a frozen fixture is NEVER
-written under `TEST_UPDATE=1` (or vitest `-u`) — in update mode a frozen
-mismatch still throws its diff, and a frozen missing fixture still throws its
-"does not exist" error. This is what makes a DELIBERATELY-WRONG fixture (the
-subject of a negative test that asserts the mismatch/error rendering)
-survivable across update runs instead of being silently overwritten with the
-actual output.
-
-## Properties
-
-### frozen?
-
-```ts
-optional frozen?: boolean;
-```
-
-Defined in: [src/model/result/match-options.ts:22](https://github.com/jterrazz/package-test/blob/main/src/model/result/match-options.ts#L22)

package/docs/reference/type-aliases/MatchableRequest.md

@@ -1,61 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: MatchableRequest
-
-```ts
-type MatchableRequest = object;
-```
-
-Defined in: [src/model/contracts/types.ts:7](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L7)
-
-The observed outgoing request, reduced to what contract matchers inspect.
-Built once per request by the engine (MSW on api/jobs, the stub backend on
-website/mobile) and handed to [ContractRequest.match](ContractRequest.md#match) and to a
-[ContractResponder](ContractResponder.md).
-
-## Properties
-
-### body
-
-```ts
-body: unknown;
-```
-
-Defined in: [src/model/contracts/types.ts:9](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L9)
-
-Parsed JSON body when the payload is JSON, the raw text otherwise, or `null` when absent.
-
-***
-
-### headers
-
-```ts
-headers: Record<string, string>;
-```
-
-Defined in: [src/model/contracts/types.ts:11](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L11)
-
-Request headers, keyed by lowercased header name.
-
-***
-
-### method
-
-```ts
-method: string;
-```
-
-Defined in: [src/model/contracts/types.ts:13](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L13)
-
-Uppercased HTTP method of the observed request.
-
-***
-
-### url
-
-```ts
-url: string;
-```
-
-Defined in: [src/model/contracts/types.ts:15](https://github.com/jterrazz/package-test/blob/main/src/model/contracts/types.ts#L15)
-
-The request URL — fully-qualified, or origin-relative for the stub backend.

package/docs/reference/type-aliases/MatcherKind.md

@@ -1,34 +0,0 @@
-<!-- GENERATED by `typescript docs` — DO NOT EDIT -->
-# Type Alias: MatcherKind
-
-```ts
-type MatcherKind = 
-  | "any"
-  | "base64"
-  | "date"
-  | "duration"
-  | "email"
-  | "float"
-  | "hex"
-  | "includes"
-  | "int"
-  | "ip"
-  | "iso8601"
-  | "number"
-  | "path"
-  | "port"
-  | "ref"
-  | "regex"
-  | "semver"
-  | "sha"
-  | "string"
-  | "time"
-  | "ulid"
-  | "url"
-  | "uuid"
-  | "workdir";
-```
-
-Defined in: [src/model/matching/match.ts:12](https://github.com/jterrazz/package-test/blob/main/src/model/matching/match.ts#L12)
-
-The frozen token vocabulary (CONVENTIONS D4) plus the code-only kinds.