@jterrazz/test 16.1.1 → 17.0.0

package/docs/README.md

@@ -1,36 +1,82 @@
-# @jterrazz/test — the corpus
-
-The manual of this repository: what the framework is, how it is changed, what proves a change, how it is released, and one chapter per subject it holds. The vitrine is the root `README.md`; the brief a session opens first is the root `AGENTS.md`.
-
-| Chapter                                     | Holds                                                                                                                                                             |
-| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [01 — Architecture](01-architecture.md)     | The runner model behind the six constructors, the five source trees and their edges, the seven enforcement channels, the four entries, what the tarball publishes |
-| [02 — Developing](02-developing.md)         | The repository's own loop and what a change owes; then install, first specs, the vitest preset and its helpers                                                    |
-| [03 — Testing](03-testing.md)               | The vitest projects, the generated capability matrix, the layered reading, the coverage ratchet, the meta-test channel, what CI runs                              |
-| [04 — Operating](04-operating.md)           | The npm release; the peers a consumer brings — required, optional, the provider's exact pin, the native seams; Node 24; the ARIA dialect                          |
-| [05 — Module tests](05-module-tests.md)     | The majority kind: what a `*.test.ts` beside its module may and may not do — `mockOf`, `vi.fn`, `clock`, `intercept`, `vi.stubEnv`, `*.fixtures.ts`, `test.each`  |
-| [06 — Integration specs](06-integration.md) | `specification.integration()`: a module against real services or a golden — `.call()`, `value`/`error`, the `integration()` project                               |
-| [07 — Component specs](07-component.md)     | `component`: a rendered unit in Chromium — the chain, the visitor, `tree`/`html`, the `component()` project, the hook and DOM-function recipes                    |
-| [08 — Website specs](08-website.md)         | `specification.website()`: `.fetch()` / `.visit()`, visit scenarios, declared backends, the `head` golden                                                         |
-| [09 — Mobile specs](09-mobile.md)           | `specification.mobile()`: `.open()`, simulator resolution, open scenarios, the `screen` golden                                                                    |
-| [10 — API specs](10-api.md)                 | `specification.api()`: options, the in-process app, `.http` request files, inline actions, seeds, intercepts                                                      |
-| [11 — Jobs specs](11-jobs.md)               | `specification.jobs()`: in-process pipelines, `.trigger()`, provider error cases                                                                                  |
-| [12 — CLI specs](12-cli.md)                 | `specification.cli()`: `.exec()`, `.env()`, fixtures and projects, `<case>.spec.yaml` documents, the three doors, services, Docker-aware mode                     |
-| [13 — Elements](13-elements.md)             | The one element vocabulary: descriptors, modifiers, verbs, `see()` semantics, W3 and its evidence, `within()`, exact names, `testId`                              |
-| [14 — Assertions](14-assertions.md)         | The reference: every matcher, grouped by subject, sync/async rules, `toMatch` resolution, diffs                                                                   |
-| [15 — Tokens](15-tokens.md)                 | The `{{token}}` grammar: all 21 tokens, `#ref` captures, `match.*`, and update mode end to end                                                                    |
-| [16 — Contracts](16-contracts.md)           | `defineContract` / `defineContracts`, the facade layout, selection, provider builders, `intercept()` and its origin, streams, the browser transport               |
-| [17 — Services](17-services.md)             | `postgres` / `redis` / `sqlite` / `process`, the services record, init scripts, per-worker isolation, the optional peer each one names                            |
-| [18 — Conventions](18-conventions.md)       | The constitution: the principles, the fork, the doubles ladder, the rule families, the backlog, what stays human, the naming recap, retro-propagation (K1)        |
-| [19 — Linting](19-linting.md)               | The oxlint plugin (`@jterrazz/test/oxlint`), the conventions checker, and the GENERATED seven-channel rule catalogue                                              |
-
-The decisions this package alone took stand in [`decisions/`](decisions/), numbered in the order they were taken, the mold `_template.md` beside them. A decision that spans several repositories belongs to the corpus that spans them. The generated API reference is [`reference/`](reference/) — a projection of the source, never authored by hand.
-
-## How to read it
-
-- **01 to 04 are the spine**, and they answer for the repository itself: what it is, how it is changed, what proves a change, how it ships.
-- **05 to 12 are the kinds of test, in the order the fork asks them.** A module test needs no runner and has no folder (05); everything below it is an assembled product met through an entry. Read 02, then the one chapter matching what you specify.
-- **13 to 17 are shared references.** The element vocabulary reaches every rendered surface; assertions and the token grammar reach every facet; contracts apply wherever a facet meets the network, services wherever it has a database. The kind chapters link into them and restate nothing.
-- **18 and 19 cover enforcement.** 18 is the constitution — the principles and the criteria no machine settles. 19 documents the static plugin and the checker, and carries the generated catalogue, sourced from `src/lint/manifest.ts`. The chapters explain and illustrate; the constitution and the catalogue decide.
-
-Every kind chapter (05 to 12) is written on the same seven sections — **What it specifies · The constructor · The chain · The result · Unique here · Pitfalls · Related** — so the reader who learned one facet already knows where to look in the next. All examples use the Given/Then comment convention the framework itself enforces (rule B4).
+# @jterrazz/test: the manual
+
+How to test with `@jterrazz/test`, and how this repository is built. New here: [Getting started](start/getting-started.md), then the guide of the kind of test you are writing. The front page is the root `README.md`; the brief an agent opens first is the root `AGENTS.md`.
+
+The pages follow the package's four export families (what is tested, what surrounds the subject, acting on a screen, judging the result). The first is a guide per kind, the other three are reference.
+
+## Start
+
+| Page                                          | Answers                                                                                                    |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| [Getting started](start/getting-started.md)   | What the framework is and why, the five ideas behind it, a first spec, and which kind of test to write     |
+| [Set up a project](start/set-up-a-project.md) | What to install, the vitest config and its project helpers, turning the conventions on, where a run writes |
+
+## Guides
+
+### What is tested: one guide per kind
+
+| Guide                                            | The subject                                                                             |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| [Module tests](guides/module-tests.md)           | One module, in its folder's `__tests__/`, nothing started: `<file>.test.ts`             |
+| [Integration specs](guides/integration-specs.md) | A module against real services, or against a golden: `specification.integration()`      |
+| [Component specs](guides/component-specs.md)     | A rendered unit in a real Chromium, in its folder's `__tests__/`: the `component` chain |
+| [Website specs](guides/website-specs.md)         | A served page, fetched or driven in a browser: `specification.website()`                |
+| [Mobile specs](guides/mobile-specs.md)           | A native app on an iOS simulator: `specification.mobile()`                              |
+| [API specs](guides/api-specs.md)                 | An HTTP app, in-process, through complete requests: `specification.api()`               |
+| [Job specs](guides/job-specs.md)                 | A pipeline triggered by name: `specification.job()`                                     |
+| [CLI specs](guides/cli-specs.md)                 | A binary in a fresh working directory: `specification.cli()`                            |
+| [Spec documents](guides/spec-documents.md)       | A CLI session written as data: the `<case>.spec.yaml` format                            |
+| [Lint specs](guides/lint-specs.md)               | The rules a project ships, over fixture trees: `specification.lint()`, `ruleTester()`   |
+
+### Developing this repository
+
+| Guide                        | Answers                                                                                                 |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
+| [Develop](guides/develop.md) | The loop, which file a change opens, what a change owes, how a page of this manual is written           |
+| [Test](guides/test.md)       | The vitest projects, the generated capability matrix, coverage, the meta-tests, the package's own rules |
+| [Release](guides/release.md) | The npm release, what leaves the tree, the footprint in a project                                       |
+
+## Concepts
+
+| Page                                     | Answers                                                                                                       |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| [Conventions](concepts/conventions.md)   | The principles: which test earns its place, one file one subject, the naming of a spec tree, what stays human |
+| [Architecture](concepts/architecture.md) | The runner model, the source trees and their edges, the enforcement channels, what the tarball publishes      |
+
+## Reference
+
+### What surrounds the subject
+
+| Page                                              | Holds                                                                                  |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| [Stubs](reference/stubs.md)                       | The network, declared: `defineStub`, the builders, `.intercept()` and `intercept()`    |
+| [Services](reference/services.md)                 | Real databases, caches and processes: `postgres()`, `redis()`, `sqlite()`, `process()` |
+| [Time and doubles](reference/time-and-doubles.md) | `clock`, `mockOf()`, and the doubles ladder                                            |
+
+The disk a subject reads is laid by its chain: `.fixture()`, `.link()` and, for what git cannot carry, `.prepare()` on a CLI ([CLI specs](guides/cli-specs.md#file-state-is-the-shape-of-a-fixture-tree)) and a lint spec ([Lint specs](guides/lint-specs.md)). Every path a test names is spelled with `file()` or `directory()` ([Conventions § The naming recap](concepts/conventions.md#the-naming-recap)).
+
+### Acting on a screen
+
+| Page                                | Holds                                                                                                                    |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| [The visitor](reference/visitor.md) | The verbs (`click`, `fill`, `see` ...), the targets (`button()`, `field()` ...), scoping, and how one element is matched |
+
+### Judging the result
+
+| Page                                  | Holds                                                                      |
+| ------------------------------------- | -------------------------------------------------------------------------- |
+| [Assertions](reference/assertions.md) | Every result subject and its matchers, goldens, sync and async             |
+| [Tokens](reference/tokens.md)         | The `{{token}}` grammar for values that move, `#ref` captures, update mode |
+
+### The rules and the words
+
+| Page                              | Answers                                                                                            |
+| --------------------------------- | -------------------------------------------------------------------------------------------------- |
+| [Linting](reference/linting.md)   | The oxlint plugin, the conventions checker, the ratchet, and the generated catalogue of every rule |
+| [Glossary](reference/glossary.md) | The words this manual uses: kind, runner, chain, oracle, golden, ground, seam, ratchet, door       |
+
+The examples use made-up products: `shoply`, a shop CLI; a news app with an events feed; and hosts under `.test` and `.example`, which never resolve on the internet.
+
+## Decisions
+
+The decisions this package alone took are in [`decisions/`](decisions/), numbered in the order they were taken, beside the `_template.md` they follow. Neither [Test](guides/test.md) nor `decisions/` ships in the tarball: from inside an install, read them at <https://github.com/jterrazz/package-test/tree/main/docs>. The API itself is the types the package publishes, and no page restates it: they are browsed as the root `README.md` says, `dist/index.d.ts` first.

package/docs/concepts/architecture.md

@@ -0,0 +1,118 @@
+# Architecture
+
+How the package is built: the runner model every kind of test shares, the source trees and the one direction their imports go, the channels a convention is enforced through, and what the tarball publishes. What a test looks like from the outside is [Getting started](../start/getting-started.md); this page is for changing the package.
+
+The rules themselves (what they say and why) are [Conventions](conventions.md); their normative sentences are the generated catalogue, [Linting](../reference/linting.md).
+
+## The runner model
+
+Every specification (the code behind one kind of test) is the same four steps. A **constructor** takes options and returns a **handle**; the handle opens a **chain** of zero or more setups closed by exactly one terminal action; the action executes and resolves to a **typed result**; the result is asserted through vitest's `expect()`. Nothing else is public: there is no imperative escape hatch, because a spec that can do anything proves nothing in particular.
+
+Seven constructors exist and the list is closed (`src/specifications/specification.ts`):
+
+| Constructor                   | Handle destructures to      | Subject under test                             |
+| ----------------------------- | --------------------------- | ---------------------------------------------- |
+| `specification.api()`         | `{ api, cleanup, docker }`  | An HTTP API, built and served in this process  |
+| `specification.job()`         | `{ job, cleanup }`          | A background pipeline, triggered by name       |
+| `specification.cli()`         | `{ cli, cleanup, docker }`  | A command binary in a fresh temp directory     |
+| `specification.integration()` | `{ integration, cleanup }`  | A module against real services, or a golden    |
+| `specification.website()`     | `{ website, cleanup, url }` | A rendered page, fetched or driven in chromium |
+| `specification.mobile()`      | `{ mobile, cleanup, udid }` | A native screen on an iOS simulator            |
+| `specification.lint()`        | `{ lint, cleanup }`         | The rules a project ships, over a fixture tree |
+
+The asymmetry in that column is the model, not an oversight: `docker` reads a container the subject itself started, and neither a pipeline triggered by name nor a module called in-process is specified by the containers it starts, so `job` and `integration` are handed none; `website` and `mobile` drive a browser and a simulator rather than an orchestrated stack, so they carry neither; and `lint` starts nothing at all, its `cleanup` releasing nothing.
+
+**One specification has no constructor**, and the same reason explains it: a rendered component starts nothing. `component` ([Component specs](../guides/component-specs.md)) is a chain the package exports directly (`component.intercept(...).render(<X />)`), so there is no handle to destructure and no `cleanup` to pass to `afterAll`. What every render of a project shares (the providers, the Vite pipeline, the viewport) is the PROJECT's, stated once by `component()` in `vitest.config.ts`.
+
+A runner is created **once per suite**, in a `*.specification.ts` file, and imported by the test files beside it. That split is what makes the container lifecycle affordable (one Postgres per suite, not one per test), and it is why `afterAll(cleanup)` belongs in the specification file and nowhere else.
+
+### The seam under the chain
+
+A specification's chain is COMPOSED: `src/specifications/<specification>/<specification>.composition.ts` lists the setups (each a `*.capability.ts`) and the terminal actions (each a `*.action.ts`) it is made of and the adapter each one is armed through, `defineSpecification` opens the chain, and every action runs through the one pipeline of `src/chain/perform.ts`. Every specification (`job`, `api`, `website`, `integration`, `cli`, `mobile` and `component`) is composed, and there is no other chain. The infrastructure a chain needs is reached through **ports**, each a `*.port.ts` beside the area or the specification that owns it (`database`, `service`, `container`, `isolation` under `src/services/`; `fixture`, `link` under `src/disk/`; `server`, `cli`, `browser`, `device` in their specification), and an adapter implements one. So the chain knows "a database exists"; it never knows Postgres.
+
+Every seam is opened lazily rather than imported, and each one is an optional peer loaded by the one module that owns it, so a project that tests no page, no component and no database installs none of them. Which peer each specification and each service needs, and what its refusal says, is [Set up a project § What to install](../start/set-up-a-project.md#what-to-install)'s list; a service's refusal is built by `src/services/peer.ts`, and a specification's by the adapter that loads its peer.
+
+## The source trees
+
+The code is trees with declared, one-directional edges: the product under `src/`, and `lint/` at the repository root beside it, the rules the package ships (the spine: `src/`, `lint/`, `specs/`, `docs/`, `skills/`). The map is the project's to declare, so this package declares its own as `FRAMEWORK_LAYERS` in `lint/self/checks/layers.ts`; `lint/self/checks/architecture.ts` compiles it, with the library owners, the specification faces and the direction of `lint/`, into the dependency-cruiser rules `jterrazz.config.ts` hands the toolchain's Architecture pass, and that declaration is the enforced statement of what follows, each crossing named at its import.
+
+The root reads the sentence of a test. A test opens a **specification** on its subject, sets up what **surrounds** it (the stubs, the services, the disk, the clock, the doubles), has a **visitor** act on it, and judges the result with **expectations**; the **chain** is the machinery that composes all of it, and **vitest** the runner that runs it. Each word is one tree at the root of `src/`, beside the three entries and their tests in `__tests__/`, and a lock of this repository's own holds the list closed.
+
+| Tree              | May import                                                                                                                                            | Holds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chain/`          | itself, `lint/kit/`; `paths/` reaches `vitest`                                                                                                        | The machinery that composes a specification and knows none: at its root `defineSpecification`, the setup and action contracts, `perform`, the chain state and config, the computed chain type and `pause.ts` (the one wait); `context/` (`.headers()` and `.with()`, what a file shares), `paths/` (the stack reader, where a global setup sits, scratch and temp roots), `refusals/`                                                                                                                                                  |
+| `visitor/`        | `chain/`, `lint/kit/`, itself                                                                                                                         | What acts on a screen, one part per section of [The visitor](../reference/visitor.md): `verbs.ts` (`VisitorVerbs`, the verbs every surface shares), `targets/` (the `Target` type, the roles, the landmarks with `within()` and the scope walk, the modifiers, how a target is spelled in messages), `matching/` (each candidate the refusal lists, the tag-to-landmark table, and `ambiguous.ts`, the refusal of a target matching several), `matrix.ts` (which verb and target each surface offers)                                  |
+| `expectations/`   | `chain/`, `lint/kit/`, itself, `vitest`; `result.ts` reaches `services/database-option`, the goldens reach how `disk/` names and resolves a path      | How a result is judged: the base result and its accessors (`text/`, `disk/`, `table/`, `http/`, `command/`), the goldens and matchers, the `{{token}}` engine (`tokens/`), update mode (`in-place/`), `required` and `waitUntil` (`conditions/`)                                                                                                                                                                                                                                                                                       |
+| `stubs/`          | `chain/`, `lint/kit/`, itself, `msw`; a stub's request filter reaches `expectations/tokens/`, one `match.*` grammar                                   | What the outside world replies: public at its top, `stub.ts`, `exchange.ts`, the builders (`kinds/`), the intercept setup and scope (`intercept/`); internal below, the queue and the route grammar (`matching/`), the three deliveries and what they share (`delivery/`: `same-process/` msw's server, `browser-page/` msw's worker, `other-process/` the stub backend; at its root msw's handlers and the stream body on the wire)                                                                                                   |
+| `services/`       | `chain/`, `lint/kit/`, itself, each service its own library, `vitest`; `.seed()` reaches how `disk/` names and resolves a path                        | The real infrastructure a run starts: the services record, postgres, redis, sqlite, processes, containers and their startup, seeding, and `database-option.ts` (`database-named-only-when-several-at-runtime`'s check, shared by `.seed()` and `.table()`)                                                                                                                                                                                                                                                                             |
+| `disk/`           | `chain/`, `lint/kit/`, itself                                                                                                                         | How a test names the disk and what a chain lays on it before its action: `file()` and `directory()` (`spec-path.ts`) and their resolution from the spec file (`resolved-spec-path.ts`), `.fixture()` and `.link()`, their ports and the file-system adapters behind them                                                                                                                                                                                                                                                               |
+| `clock/`          | `chain/`, `lint/kit/`, itself, `vitest`                                                                                                               | The pinned clock and `.clock()`, the instant grammar, the process clock adapter                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `mocks/`          | `chain/`, `lint/kit/`, itself, `vitest`, `vitest-mock-extended`                                                                                       | `mockOf()`, the one double of a port                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `specifications/` | `chain/`, every notion above, `lint/kit/`, each specification its own library; a specification's project reaches the runner config (`vitest/project`) | What is tested, one slice per constructor: `<specification>.face.ts` (the names it publishes), `<specification>.composition.ts` (the composition), `<specification>.handle.ts` (the constructor), `<specification>.project.ts` (its Vitest project), and its concept folders (`request/`, `server/`, `routes/`, `documents/`, `render/`, `device/` ...); the lint specification holds `rule-tester.ts` beside them, `ruleTester()`, the other half of the kit to test a rule; at its root, `specification.ts`, the seven as one record |
+| `vitest/`         | itself, `chain/`, `lint/kit/`, update mode's setup, `vitest`, never a specification                                                                   | What every Vitest project receives, knowing no specification: `preset.ts` (the root config), `project.ts` (the defaults every project is built on, `specificationProject`) and `unit.project.ts` (`unit()`), which wire the global setups their owners provide and resolve (`expectations/in-place/`, `chain/paths/temp-root`); a specification's own setups (`services/containers/`, `specifications/mobile/session/`) ride on its project                                                                                            |
+| `standard/`       | `@jterrazz/typescript/config`, nothing of the tree                                                                                                    | The defaults of the `test` section, data only: `standard.ts`, which the `test()` preset hands on as written ([`@jterrazz/typescript`'s Configuration § The standard](https://github.com/jterrazz/package-typescript/blob/main/docs/reference/configuration.md#the-standard))                                                                                                                                                                                                                                                           |
+| `lint/`           | itself and `src/standard/`, never the rest of `src/`: `self/` alone reads the product it holds to account                                             | At the root, not under `src/`: the tool-facing channel, laid out below. The layer map names its files `lint/**`, and cruises it beside `src/`                                                                                                                                                                                                                                                                                                                                                                                          |
+
+**`lint/` is split by audience first.**
+
+| Module or folder of `lint/` | Holds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.oxlint.ts`           | what ships at `./oxlint`, where `consumer/` meets `kit/` for the plugin: `recommendedRules`, the plugin as the default export, and `materialAt`/`testPackageOf`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `index.config.ts`           | what ships at `./config`: `test()`, the one preset this package hands a project (its section's defaults from `src/standard/`, its oxlint rules, the import and naming rules it hands the toolchain, the sections of `.jterrazz/baseline.json` it owns), and the `TestSettings` type its section merges into `@jterrazz/typescript/config`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `index.checker.ts`          | the `#checker` private import, where `consumer/` meets `kit/` for the conventions: the `Contribution` the `test()` preset names as its checks (the conventions pass `kit/checker/` builds from the registry of `consumer/checks/checker.ts`, the `test` section it holds, and its `baseline` command), which `@jterrazz/typescript`'s checker program runs on `typescript check`, `fix` and `baseline`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `consumer/`                 | the declarations every consumer is held to, and nothing else: `catalogue/` (one row per rule in `manifest.ts`, its family in `families.ts`, the chapter's markers in `chapter.ts`, the fork), `rulebook/` (the `test()` preset, and the overrides it sets on upstream rules, one file per upstream plugin), `rules/` (our oxlint rules, `rules/<family>/<name>.ts` beside its test, assembled by `plugin.ts`), `checks/` (one file per checker pass, listed by `checker.ts`, the registry of the tree, ground, document and member passes and of the fixes a `--fix` applies)                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `self/`                     | the declarations only this repository is held to, never shipped: `catalogue/` (the self rows, the self chapter), `rules/`, `checks/` (the layer map and the rules it compiles to, the library owners, the source locks, and `checker.ts`, their registry), `corpus/` (the meta-tests), and `self.cli.ts`, which composes them with the kit (the self checks the `self()` preset names and the generated chapters), beside `preset.ts`, the `self()` preset, and `plugin.ts`, its plugin's entry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `kit/`                      | what this package alone runs, on top of the rules kit it reads from `@jterrazz/typescript/rules`. The lesson, the rule rows, the chapter tables, the baseline sections and their judges, the git tree, the members, the ground folders and the suppression directives are the kit's: `project/` (how a rule or a pass reads a spec tree: the module parser, the file role, the subject, the siblings, the spec documents, the specs roots), `baseline/` (the `test` section of `.jterrazz/baseline.json`: the checker's counts, the route key the run keeps), `checker/` (what a check spots, taught into the kit's finding by its row, the oxlint run, the rewrites a fix makes, and the passes handed a registry for the kit's `runChecker`: the tree, ground, document and member runs, the conventions pass and its `baseline` command, the self pass held at zero), `catalogue/` (the row's channels, specifications and reaches, the catalogue chapter those render into, and its page) |
+
+Two laws keep the audiences apart, the same in every repository that keeps the tree, and `@jterrazz/typescript`'s Names pass holds both. **Declarations only:** `consumer/` and `self/` hold a rule, a check, a decision on an upstream rule, a catalogue entry, or their tests; a module there hands another module no function but one named for its file, and the code declarations share is `lint/kit/`'s. **The kit knows no declaration:** it is handed the rows, the chapter they are read at, the families and the checks, and an entry at the root of `lint/` (the plugin, the config, the checks) hands them.
+
+An import in `lint/` goes one way: `lint/kit/` imports nothing of `consumer/`, `self/` or an entry at the root of `lint/`; `consumer/catalogue/` only `lint/kit/`, since it is the list every rule and pass reads its sentence from; `self/catalogue/` `lint/kit/` and the consumer catalogue it extends; `consumer/rulebook/`, `consumer/rules/` and `consumer/checks/` the catalogue and `lint/kit/`, never each other; the entry any of them. A catalogue's own tests are test material, and read the declarations they audit. That direction is not this package's to state: it is the law of every `lint/` tree, carried by `@jterrazz/typescript`'s base preset, which the Architecture pass holds this repository to with no line of its own. This repository keeps one difference, set aside in the open under `optOuts` in `jterrazz.config.ts`, with its reason and counted by the drift report: the self folders other than the catalogue read each other: the corpus audits the self checker and plugin by importing them.
+
+`lint/` and `src/` import each other one way only, and a module both need has one owner. The shipped `lint/` never reads the product: what the runner and the lint both read lives in `lint/kit/` or in the kit it builds on. That is the ground names, the root walk and the git tree it walks, the yaml document and the `<case>.spec.yaml` grammar, the token kinds, the stub kinds, the relative-path law, the settings file's `test` section, the artefact paths, the route-coverage key, and the four-part lesson a runtime refusal and a finding both print (`refusalBlock` and `refusal` of `@jterrazz/typescript/rules`). A runtime refusal is the product's own: `src/chain/refusals/` holds `refusal()`, the four-part block the product throws (built from a refusal row's sentence and the catalogue page it is read at, or from a lesson naming the chapter that explains it), `invariant()`, the one message of what only the framework can cause, and `rows.ts`, the refusal rows and the runtime channel of the catalogue, which the chapter projection reads from there. `src/` imports `lint/kit/` and nothing else of `lint/`. `self/`, never shipped, may read `src/`: it judges the repository's own product; the shipped `lint/` never reads `src/`. The same law holds in `@jterrazz/typescript`, whose `src/` is the command that runs its `lint/`, and the base preset carries it for both: `src-reads-no-declaration` and `shipped-lint-reads-no-self`, printed as `architecture/<law>` at the import.
+
+**A setup is defined once, whatever the specification.** A second copy of "declare a stub, seed a table, run the thing" is how two specifications drift, so a specification never implements one: it composes the definition and names the adapter it is armed through, and its chain type is computed from the same list (`src/chain/chain.ts`), each chain published as an interface so a compiler message prints its name. Every specification's `<specification>.composition.ts` names that chain beside its composition, so the specification's own folder says what its constructor hands out; `component`, which has no constructor, is opened once by its own page face, `specifications/component/component.face.browser.ts`, which the page's entry re-exports.
+
+The edges point one way: `chain ← visitor · expectations · stubs · services · disk · clock · mocks ← vitest ← specifications ← the entries`: the machinery at the bottom, the notions of the sentence beside each other and apart, the specifications composing them, the entries publishing the specifications. Some carry their reason in the declaration itself. `expectations/result.ts` reaches `services/database-option` because a table read names its database by the rule a seed names it by. `stubs/` reaches `expectations/tokens/` because a stub's request filter IS an expectation on the outgoing request, one `match.*` and `{{token}}` grammar, never a second. A specification's `<specification>.project.ts` reaches `vitest/project` because the runner config runs only in the Vitest main process, never in test code; `vitest/` knows no specification, so the one vite plugin a specification owns, the cli's literate door, reaches the preset through the entry that composes them. The runner reaches `lint/kit/` for exactly what it shares with the lint (the token list, the ground names, the stub kinds, the root walk and the tree it walks, that is the kit's git tree of what git does not ignore, and the `<case>.spec.yaml` parser), so that the file the lint accepts is the file the runner runs, from ONE parser. The map holds more than the layer edges, each a rule of `ARCHITECTURE` named at its import: a specification never imports another (`specification-imports-no-other-specification`), a concept folder is reached only from inside its specification, the entries through its face (`specification-entered-by-its-face*`), and each third-party library is imported by exactly one slice (`library-*-has-one-owner`: `playwright` by `specifications/website/`, `webdriverio` by `specifications/mobile/`, `msw` by `stubs/delivery/`, `pg` by `services/postgres/` ...); a node builtin is no library, and each slice spawns only the program its own concept owns ([ADR-009](../decisions/009-node-builtins-are-not-libraries.md)). What the map cannot express is held by the self checker passes under `lint/self/checks/`, one file per pass over the walk `lint/kit/project/source.ts` shares, each finding at the entry, the import or the folder it names: the source root holds the entries, their tests and the trees of the sentence alone, the stubs are entered by what they publish (a specification reaches a delivery only through an edge `DELIVERY_READERS` declares), and a folder under `src/` is named for a concept, never a role ([Test § The package's own rules](../guides/test.md#the-packages-own-rules) lists each). Swapping the runner would be a rewrite of `vitest/`, its entry, the specifications' projects, the component's page and the few bricks built on a vitest primitive (the clock: `vi`; the scratch directory: `onTestFinished`; the doubles: `vitest-mock-extended`; and the goldens, whose matchers are registered on vitest's `expect`), and of nothing else.
+
+This package's product IS test tooling, so `no-test-code-in-production` (which keeps a consumer's production away from test material) is turned off by path wherever that is the job: `vitest/` and its entry, each specification's project, the run's global setups, the component's page, the website's playwright adapter, the stubs' deliveries (`stubs/delivery/`), the clock, the doubles, the scratch directory, the goldens and update mode. Every other module is held to it, the entries and the specification constructors included, which is why a constructor is named `<specification>.handle.ts` and never by a suffix `no-test-code-in-production` reads as test material; and no module a bundle is built from may be test material, which the `package-exports` meta-test reads from the build's source maps.
+
+The table's May-import column is a reading of `FRAMEWORK_LAYERS`, never a second statement of it: the declaration in `lint/self/checks/layers.ts` is what the Architecture pass enforces and what a change edits. Where a grant names one subpath of a package (`@jterrazz/typescript/config`), the layer is granted the package: dependency-cruiser judges where an import lands, and a package's `exports` land every subpath in the package's own folder; only a subpath that lands in a folder of its own (`vitest/browser`) keeps an owner apart from its package.
+
+The composition roots are the entries, and none names a layer. `src/index.ts` is node's: re-exports only, each specification's face (`src/specifications/<specification>/<specification>.face.ts`, the names that specification contributes) and the modules of the other layers by path. `src/index.services.ts` publishes the services and their types (`@jterrazz/test/services`), and `src/index.stubs.ts` the stubs, their builders and `intercept()` (`@jterrazz/test/stubs`). Each of the three has a page twin, `src/index.browser.ts`, `src/index.services.browser.ts` and `src/index.stubs.browser.ts`: it publishes its node entry's types whole and every value a page can run, refusing the node-only ones (see [What the tree publishes](#what-the-tree-publishes)). The page values of all three live in `src/index.browser.ts`, and the two subpath twins re-export theirs from it: the toolchain writes the chunks two page builds share beside the node build's, under the same names, so page code split across three page builds would be overwritten by its node namesake. `src/index.vitest.ts` is the runner config's, `@jterrazz/test/vitest`: it publishes `unit()` and every specification's project beside the preset, derives `vitestConfig` from the declared projects with those helpers, and hands the preset the cli's literate plugin, so `vitest/` never reaches a specification.
+
+## The eight enforcement channels
+
+A convention this package states is held by a **channel**, and every row of the catalogue names exactly one of eight. The guiding aim is that most enforcement is programmatic, not review-borne.
+
+- **static:** the `jterrazz/*` oxlint plugin: one file per rule under `lint/consumer/rules/<family>/`, the folder of its catalogue family; AST analysis, one diagnostic per file.
+- **upstream:** a convention an oxlint vitest-plugin rule already holds, set as an OPTION by the `test()` preset rather than duplicated as a rule of ours ([ADR-005](../decisions/005-the-doubles-ladder-is-closed.md)).
+- **toolchain:** the import and naming rules the `test()` preset hands `@jterrazz/typescript`'s dependency-cruiser and ls-lint passes, printed as `architecture/<rule>` and `names/<rule>`: a project that declares the preset in its `jterrazz.config.ts` is held to them by `typescript check`.
+- **checker:** passes of the conventions checks `test()` brings to `typescript check`, reading what an AST cannot: the `{{token}}` grammar of `__requests__/` and `__expected__/` fixtures, the `<case>.spec.yaml` document family, cross-file analyses that cross a `*.specification.ts` with its tests, and the member pass that judges a package rather than a tree.
+- **runtime:** the framework refuses incorrect usage as it executes, where static analysis abstains (a non-literal argument) or cannot reach (the network, a container lifecycle).
+- **type:** what the compiler refuses with no rule at all, proven by a consumer's module compiled against the installed declarations (`specs/cli/tsc/`).
+- **meta:** what the framework's own suite holds about itself: the catalogue's freshness, its completeness, the reach of its rules. [Test](../guides/test.md) owns the channel.
+- **process:** the judgement no single channel settles: asset-driven grouping, golden-file discipline, retro-propagation.
+
+The channel a rule sits on is not prose here: it is a field of `lint/consumer/catalogue/manifest.ts`, the single source of truth from which the catalogue in [Linting](../reference/linting.md) is generated. So is its audience: a `consumer` rule is what a project using the package meets and is listed there, a `self` rule holds only this package's own suite, has its row in `lint/self/catalogue/manifest.ts`, and is listed in [Test § The package's own rules](../guides/test.md#the-packages-own-rules). A rule and its normative sentence live together in the code, so the two cannot drift.
+
+## What the tree publishes
+
+The bundle is built by `typescript build`, from the manifest and the names of the modules loaded by path, into `dist/`, and its shape follows how each entry is consumed. `dist/` carries the entries (`index`, `services`, `stubs` and `vitest`, ESM-only since vitest is), plus `checker` (`lint/index.checker.ts`, the `#checker` private import) and the global setups the specifications hand vitest by path, each a `*.global-setup.ts` shipped under its own name; the package ships no CLI. The repository's own programs (`schema`, `route-split` and the `self` program, `lint/self/self.cli.ts`, that is the self checks `typescript check` runs and the pages), with the `self()` preset and its plugin at the root of `lint/self/`, are built into `.artifacts/dev/` and are absent from `dist/` by construction. The `oxlint` plugin ships dual, because oxlint loads it from a consumer project that may itself be CommonJS.
+
+**There are SEVEN entries and no more**: `@jterrazz/test` for what writes a spec (the constructors and their faces, `ruleTester()`, the targets, `match` and the tokens, `clock`, `mockOf()`, `packed()`), `@jterrazz/test/services` for the services a specification starts, `@jterrazz/test/stubs` for what the network replies, `@jterrazz/test/vitest` for the project helpers and the `vitestConfig` the derived `vitest.config.ts` awaits, `@jterrazz/test/oxlint` for the lint plugin, `@jterrazz/test/config` for the `test()` preset a `jterrazz.config.ts` lists, `@jterrazz/test/schema` for an editor validating a `<case>.spec.yaml`. That is rule `no-unpublished-subpath` rather than a convention of taste, and the exemption is derived from the manifest's own `exports` map (the kit's `declaredSubpaths`), so a subpath is exempt the moment it is published and stops being exempt the moment it is withdrawn. A service or a stub imported from the root is rule `service-or-stub-from-its-subpath`, whose fix moves the import: the root then loads no service constructor and no stub builder, though it still carries the startup a specification runs over the services it is handed.
+
+**Each spec entry has two runtimes.** A component test renders in a real browser, and the node entry cannot load there: it imports node builtins at load (`node:fs` and `node:child_process` among them), while the native seams (`pg`, `better-sqlite3`, `testcontainers`) are lazy peers, opened on first use. So `exports["."]`, `exports["./services"]` and `exports["./stubs"]` each carry a `browser` condition, resolving to `dist/browser/index.js`, `dist/browser/services.js` and `dist/browser/stubs.js`: the same public surface, built for a page, where every node-only name (the seven constructors, `ruleTester()`, the services, the docker accessors, the results that walk a disk) is a stub that throws where it was called, naming the specification and saying it runs under node. The split is the RUNTIME's and never the specifications': one specifier per entry, so no spec has to remember which build it may import.
+
+`types` is stated once, and it is the node build's, so the two runtimes are ONE type surface and a name cannot exist on one side only. Each page entry takes its types from its node entry (`export type *`), so they cannot drift, and `specs/cli/node/names.spec.ts`, over the packed tarball, records every build's names and fails a value a page build lacks.
+
+The API is the types the package publishes, and nothing re-states it. What the code does project into the corpus is a set of generated tables and `schema/spec.schema.json`, generated from the document grammar's own constants; which tables, and the one gesture that writes them, is [Develop § What a change owes](../guides/develop.md#what-a-change-owes)'s list. Both `docs/` and `schema/` ship in the tarball, `docs/` less the two pages that are this repository's own, so a consumer reads the manual where the messages send them, inside the install ([Release](../guides/release.md#what-leaves-the-tree) names the two). All of them are held fresh by meta-tests.
+
+## Pitfalls
+
+- **Reaching for a dependency from `chain/`.** A new external package belongs to the ONE slice that needs it (a notion (`stubs/`, `services/` ...) or a specification) and nowhere else. Only a library every layer truly shares sits behind the chain, in the one folder `FRAMEWORK_LAYERS` grants it to: vitest's test hooks in `paths/`; the `yaml` library and the toolchain's config types sit in `lint/kit/project/`, which the chain reaches. Anything else the chain imports is the boundary this package cannot afford to blur, and the layer map and the library-ownership rules refuse it.
+- **Adding an eighth constructor.** The seven are the closed vocabulary the conventions, the linter and the documentation are all shaped around. A new SUBJECT to specify is a design decision, and it earns a record in [`decisions/`](../decisions/) before it earns a constructor, as `integration` did in [ADR-004](../decisions/004-a-module-against-real-services-or-a-golden-is-the-integration-specification.md) and `lint` in [ADR-015](../decisions/015-a-rule-a-project-ships-is-the-lint-specification.md).
+- **Writing a rule's normative sentence into a chapter.** It belongs in `lint/consumer/catalogue/manifest.ts` beside the implementation; a chapter that restates it is the second copy the whole design exists to prevent.
+
+## Related
+
+[Develop](../guides/develop.md) · [Test](../guides/test.md) · [Conventions](conventions.md) · [Linting](../reference/linting.md)