@jterrazz/test 16.0.0 → 16.1.0

package/docs/decisions/006-the-catalogue-reaches-a-file-by-its-role.md

@@ -0,0 +1,245 @@
+# ADR-006: The catalogue reaches a file by its role, states its reach, and is born on a count
+
+**Status:** Accepted
+**Date:** 2026-09-20
+
+## Context
+
+The catalogue of 15.x held sixty-odd rows and could not answer three questions
+a reader asks of any one of them: which files does this reach, what do I do
+about it, and what proves it is true.
+
+**Reach was a path segment.** Five rules gated on `parts.includes('specs')` or
+`includes('src')` — I2, I4, J2, d12w, d15w — and each of them drew the line in
+a slightly different place. The consequences were not theoretical: a sleep in a
+module test beside `src/` was invisible to J2, while the same sleep two folders
+away failed a build; a repository's consistency suite was an "orphan module
+test" to I2 because it sat under a folder called `specs`. The gate was also
+unreadable: nothing in a row said which files it judged, so the only way to
+find out was to read the implementation.
+
+**A row could not say what to do.** A ban with no destination is an argument
+rather than a rule, and forty-odd messages ended on `see docs/19-linting.md`
+with no fragment — a route to a chapter, not to a row. Nothing failed when a
+heading moved, so the routes rotted silently.
+
+**Nothing said which pass a finding came from.** The manifest's `channel` field
+was a union a row could name loosely, and three of the seven values (`type`,
+`meta`, `upstream`) had no rows at all: the conventions they stood for were
+held by tests nobody could find from the catalogue, or by nothing.
+
+**And a row could be born out of nothing.** The A-family's `allowedPrefixes`
+story is the warning: a rule shipped at `error` on a shape no consumer had ever
+been run against, and every consumer paid for it.
+
+## Decision
+
+### One gate, by role
+
+**One gate, by ROLE.** `roleOf(file)` returns `{ role, inSpecs, legacyDir }`,
+and the role is read from the SUFFIX: `.specification.ts(x)`, `.spec.yaml`,
+`.spec.ts`, `.test.tsx`, `.test.ts`, `vitest.config.*`, a ground ancestor, a
+`contracts/` ancestor. A statique rule reads those three fields and, where it
+must know where the file sits, the ONE package-bounded anchor every pass shares
+(`specsAnchor` in `src/lint/ast.ts`) — never a bare path segment. The rules
+that need it say so: C1, C4, C8, C13, F2, F3, I1, I4. Walking a TREE is the
+checker's — C1's depth, C12, C18, C20, C21w.
+
+### A row says what it reaches, and what to do
+
+**Every row states its REACH and its FIX**, both required by the type, and the
+fix is one imperative line the message carries too.
+
+### Seven channels, each answering for its rows
+
+**Seven channels, one per row** — `statique`, `upstream`, `checker`, `runtime`,
+`type`, `meta`, `process` — and each channel answers for its rows the way that
+channel can: a rule file and a fixture pair, an assertion on the resolved
+option, a bundled pass, a `// RUNTIME <ID>` marker above the spec that drives
+the refusal, an `@ts-expect-error` in `src/type-channel.test-d.ts`, a named
+meta-test. One meta-test holds that contract for all seven.
+
+**English, and anchored.** Every sentence the catalogue publishes is English
+(K5 holds the line with a deny-list of the tokens the manifest actually
+carried), and every message the PLUGIN ships ends with a generated
+`(<ID> — <chapter>#<rule>)` tail whose anchor is asserted to exist (K3). A
+checker finding carries its id and its chapter; several of its passes report
+under a family code (`d4`, `d4b`, `d10w`) rather than a row name, so the tail
+routes to the chapter and the id says which row.
+
+### A row is born on a count
+
+**A row is born on a COUNT.** A rule is written when its defect class has been
+seen once and its criterion is decidable. A class nobody has seen is a backlog
+line with its criterion written, coded on its first occurrence. The R8 dry run
+— the whole catalogue run over every clone of the workbench, read-only — is
+what settles which of the two a row is, and it is re-run whenever a criterion
+changes. The counts below are the run of 2026-09-20, re-run after the fix pass
+that bounded six false classes: 27 clones plus the estate's own `apps`,
+`packages` and `specs`, with each package's own violation FIXTURES excluded —
+they violate on purpose, and counting them would let a rule justify itself.
+`jterrazz-web-astro-react` and `signews-web-astro` are not repositories: they
+are clones of `jterrazz-web` and `signews-web` checked out on a merged
+experiment branch, counted here as the folders the run walked.
+
+| rule                          | total | where                                                                                                                                                                                                                                                                                                                                 |
+| ----------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `b4-given-then`               | 2569  | jterrazz-design 902, signews-mobile 532, archive 419, hoverfly-lsp 246, extensions 216, package-attestation 144, spwn 104, package-typescript 4, package-test 2                                                                                                                                                                       |
+| `b11-marker-one-line`         | 240   | package-test 160, signews-api 40, hoverfly-lsp 13, jterrazz-web-astro-react 5, jterrazz-web 5, archive 4, package-typescript 4, spwn 4, jterrazz-studio 3, jterrazz-os 2                                                                                                                                                              |
+| `i2-sibling-test-naming`      | 224   | archive 169, signews-mobile 35, hoverfly-lsp 15, package-typescript 2, jterrazz-design 1, package-test 1, spwn 1                                                                                                                                                                                                                      |
+| `c12-spec-file-name`          | 180   | spwn 40, package-test 37, jterrazz-web 22, jterrazz-web-astro-react 21, signews-api 15, package-typescript 9, signews-mobile 8, jterrazz-os 6, package-attestation 6, package-intelligence 3, signews-web 3, jterrazz-design 2, jterrazz-studio 2, spwn-web 2, cap01 1, package-analytics 1, package-broadcast 1, signews-web-astro 1 |
+| `j6w-given-in-the-test`       | 165   | archive 54, package-test 41, signews-api 19, package-typescript 17, hoverfly-lsp 14, jterrazz-os 6, spwn 6, package-telemetry 4, signews-mobile 2, package-analytics 1, package-intelligence 1                                                                                                                                        |
+| `d16w-ambient-value`          | 57    | signews-api 36, package-test 10, archive 6, hoverfly-lsp 2, jterrazz-os 2, signews-mobile 1                                                                                                                                                                                                                                           |
+| `e9w-env-assignment-in-test`  | 49    | package-test 47, jterrazz-os 2                                                                                                                                                                                                                                                                                                        |
+| `d18w-existence-only-oracle`  | 37    | package-test 14, hoverfly-lsp 10, archive 4, package-intelligence 2, signews-mobile 2, jterrazz-os 1, jterrazz-web-astro-react 1, jterrazz-web 1, package-typescript 1, signews-api 1                                                                                                                                                 |
+| `c1-domain-structure`         | 33    | jterrazz-os 26, package-typescript 7                                                                                                                                                                                                                                                                                                  |
+| `c18-module-test-under-facet` | 31    | package-typescript 27, jterrazz-web 2, spwn 2                                                                                                                                                                                                                                                                                         |
+| `i4-no-module-doubles`        | 23    | signews-mobile 13, archive 5, package-intelligence 2, jterrazz-web 1, package-typescript 1, signews-api 1                                                                                                                                                                                                                             |
+| `d19w-probe-cluster`          | 22    | package-typescript 7, spwn 6, jterrazz-os 3, jterrazz-web 3, archive 2, jterrazz-web-astro-react 1                                                                                                                                                                                                                                    |
+| `f2-no-test-imports-in-prod`  | 21    | package-test 13, jterrazz-design 3, archive 2, package-manifest 2, hoverfly-lsp 1                                                                                                                                                                                                                                                     |
+| `e3-config-present`           | 17    | archive 16, extensions 1                                                                                                                                                                                                                                                                                                              |
+| `d12w-response-body-probe`    | 14    | signews-api 9, archive 5                                                                                                                                                                                                                                                                                                              |
+| `d15w-status-only-probe`      | 14    | package-test 4, archive 3, jterrazz-os 3, jterrazz-web-astro-react 2, jterrazz-web 1, signews-api 1                                                                                                                                                                                                                                   |
+| `d5w-spec-pinned-value`       | 10    | jterrazz-os 9, package-test 1                                                                                                                                                                                                                                                                                                         |
+| `d8w-text-bypass`             | 9     | jterrazz-web-astro-react 3, jterrazz-web 3, archive 2, spwn 1                                                                                                                                                                                                                                                                         |
+| `c9-dead-fixtures`            | 8     | package-test 7, spwn 1                                                                                                                                                                                                                                                                                                                |
+| `d17w-double-only-oracle`     | 8     | signews-api 4, signews-mobile 4                                                                                                                                                                                                                                                                                                       |
+| `j2-no-sleep`                 | 8     | package-test 3, archive 2, jterrazz-os 1, signews-mobile 1, spwn 1                                                                                                                                                                                                                                                                    |
+| `w5w-scenario-settles`        | 8     | package-test 4, cap01 1, jterrazz-web-astro-react 1, jterrazz-web 1, signews-mobile 1                                                                                                                                                                                                                                                 |
+| `a1-specification-file`       | 7     | package-test 7                                                                                                                                                                                                                                                                                                                        |
+| `e2-preset-config`            | 6     | package-test 3, spwn 2, archive 1                                                                                                                                                                                                                                                                                                     |
+| `c21w-ground-owned-by-one`    | 5     | spwn 2, jterrazz-web-astro-react 1, package-attestation 1, signews-api 1                                                                                                                                                                                                                                                              |
+| `d5-spec-volatile-literal`    | 3     | package-test 3                                                                                                                                                                                                                                                                                                                        |
+| `e7w-include-prefix-exists`   | 3     | spwn 2, package-test 1                                                                                                                                                                                                                                                                                                                |
+| `f5-fixtures-only-from-tests` | 3     | jterrazz-design 3                                                                                                                                                                                                                                                                                                                     |
+| `f8-no-seam-dependency`       | 3     | archive 1, jterrazz-design 1, spwn 1                                                                                                                                                                                                                                                                                                  |
+| `b10-when-between-markers`    | 2     | archive 1, spwn 1                                                                                                                                                                                                                                                                                                                     |
+| `e4w-project-binding`         | 1     | package-test 1                                                                                                                                                                                                                                                                                                                        |
+| `f6-no-foreign-test-runtime`  | 1     | signews-web 1                                                                                                                                                                                                                                                                                                                         |
+
+Four rows were at zero with no new surface to be the boundary of, and the gate
+moved them to the backlog with their criteria written: **B12** (a marker inside
+a declarator chain), **C19** (backend ground under a screen facet — the
+component facet that was its reason stopped being a folder when component tests
+became colocated), **D21w** (a volatile literal in a golden: 108 findings, every
+one a publication date the PRODUCT pins rather than a value a run minted; once
+the criterion excludes midnight UTC, which a clock read never is, it falls to
+zero) and **D22w**. Three rows ship at zero as the boundary of a surface born
+with them: **W2** (the escape hatch nobody uses yet), **E8** (the literate door
+the `cli()` helper now defaults) and **C20** (folder = constructor, which the
+`integration` facet of 15.3 is the first new folder to answer to).
+
+Two rows ship at zero for a reason the re-run wrote itself. **D16** is the
+error half of a class d16w counts 57 times: the one occurrence the first run
+found was a test that PINS its clock and then reads it, which is what the rule
+tells an author to do — so the exemption that made it disappear is the rule
+working. **J9** has no occurrence because the toolchain's suppression gate
+reads `oxlint-disable*` and nothing else: the checker's own directive has never
+been held by anything, and the 16 of them on the workbench were written under
+no obligation to say why.
+
+Six false classes the re-run bounded, each of which had made a row look larger
+than it is: C18 read a spec importing `../x.specification` (no extension) as
+reaching no runner — 13 of its 44; C12 and C18 both claimed the same file, and
+`--fix` performed the wrong one; C21w counted a golden named through a template
+as no reader at all; W5w read a `db.select()` as a visitor's action and every
+component test as a screen scenario — 13 of its 26 were the estate's console;
+D18w called a precise negative (`not.toHaveBeenCalled()`) an existence check;
+D19w called three reads of one `value` a cluster.
+
+The chapters are renumbered ONCE, in the same release, so a link repointed by
+this change is repointed for good. The map it lands on runs the fork's own
+order: the spine, then the kinds of test from the one with no runner to the one
+that drives a simulator, then the shared references every kind links into, then
+the enforcement. Two chapters are BORN by it — 05, the majority kind that had no
+page, and 13, the element vocabulary two facet chapters were each holding half
+of — and every kind chapter is rewritten on one seven-section skeleton.
+
+| Old | New | Chapter                                   |
+| --- | --- | ----------------------------------------- |
+| 01  | 01  | Architecture                              |
+| 02  | 02  | Developing                                |
+| 03  | 03  | Testing                                   |
+| 04  | 04  | Operating                                 |
+| —   | 05  | Module tests (new)                        |
+| 17  | 06  | Integration specs                         |
+| 16  | 07  | Component specs                           |
+| 14  | 08  | Website specs                             |
+| 15  | 09  | Mobile specs                              |
+| 05  | 10  | API specs                                 |
+| 06  | 11  | Jobs specs                                |
+| 07  | 12  | CLI specs                                 |
+| —   | 13  | Elements (new)                            |
+| 08  | 14  | Assertions                                |
+| 09  | 15  | Tokens (+ update mode end to end)         |
+| 10  | 16  | Contracts (+ `intercept()`)               |
+| 11  | 17  | Services                                  |
+| 12  | 18  | Conventions                               |
+| 13  | 19  | Linting (carries the generated catalogue) |
+
+A rule message anchored at `docs/13-linting.md#<name>` now reads
+`docs/19-linting.md#<name>`; K3 holds that every one of them resolves, so a
+renumbering that missed a message fails the suite rather than a reader.
+
+## What the proof holds, and what it does not
+
+The release proof of this wave reads: the package's own tree green under
+`typescript check`, the `unit` project inside the budget
+[03 — Testing](../03-testing.md) states, the
+catalogue's own meta-tests holding freshness, completeness, reach and channel,
+and the R8 counts above re-derivable from the branch head. All of it holds.
+
+**Suppressions are the one stated exception**, and it has two halves, both
+counted. The proof as written asked for zero directives added to this package's
+own tree: `src/` and `specs/` carry 66 `oxlint-disable` outside fixtures and
+goldens where `main` carried 51, so the wave adds 15. They are three shapes,
+and none of them is debt: a test whose SUBJECT is the primitive the rule bans —
+the clock seam, `waitUntil`, the adapter deadlines, the marker rule's own
+one-line fixture; a negative spec whose violation IS the behaviour under test;
+and one skipped spec, the repro of the seam defect chapter 16 names, which
+leaves the day the seam answers. A rule cannot exempt the test that proves it
+without exempting the class it guards, so the directive carries the reason
+instead.
+
+The second half is the RATCHET, and it is debt rather than exemption: the wave
+absorbs 107 findings of this package's own rules into `oxlint.baseline.json` —
+`e9w` 39, `j6w` 37, `d18w` 14, `d16w` 10, `w5w` 4, `d15w` 3, beside the single
+`i1` line `main` already carried. A ratchet key names a convention, never a
+pass, so those are 107 lines a reader can spend one convention at a time, and
+the baseline may only fall.
+
+Both numbers are written here so the next release holds itself to them: 66
+directives and 107 absorbed findings, and a rise in either asks for the same
+reading.
+
+**Not done in this cut**, deliberately, each with the reason:
+
+- **The website and mobile duplicates**, and **the eight hand-written skill
+  references**, were both deferred from the catalogue cut to the renumbering
+  that follows it in the same release: the vocabulary had no page to move to
+  until chapter 13 existed, and the references had no generated card to be
+  replaced by. Both landed with it — 13 owns the vocabulary, and
+  `references/<kind>.md` is generated from the facet matrix.
+- **`response.body.cancel()`.** A seam defect, not a catalogue one: chapter 16
+  states it and M3's row names the one suppression it sanctions, with the repro
+  skipped beside the other intercept specs.
+- **W4 stays a runtime row** rather than a type one, for the reason written in
+  `src/type-channel.test-d.ts`.
+- **The three statuses.** ADR-006, 007 and 008 are `Proposed`; only the owner
+  writes `Accepted`, in the commit that cuts the version.
+
+## Consequences
+
+- A reader deciding whether a rule applies to the file in front of them reads
+  the row, never the implementation; a rule that wants a different reach must
+  change `roleOf`, where every rule sees it at once.
+- The three channels that were empty carry rows, and a row of any channel that
+  loses its proof fails a meta-test rather than going quietly stale.
+- The gate costs rules: four written, tested and fixtured rows went to the
+  backlog on the strength of the dry run. That is the price of the criterion,
+  and the criterion is the reason a consumer can trust a new `error`.
+- A count is evidence of a CLASS, not a migration estimate: `b4-given-then` at
+  2575 is narration debt that is already baselined everywhere, and no row's
+  tier is decided by how expensive it would be to fix.
+- Every consumer's first 16.0 run is a baseline update. The counts above are
+  what that update will hold.

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

@@ -0,0 +1,53 @@
+# 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

@@ -0,0 +1,75 @@
+# 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

@@ -0,0 +1,22 @@
+# 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

@@ -0,0 +1,120 @@
+<!-- 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`