@jterrazz/test 16.1.1 → 17.0.0

package/docs/01-architecture.md

@@ -1,95 +0,0 @@
-# 01 — Architecture
-
-What this package IS: one runner model behind six constructors, one chain that needs none, five source trees with declared edges, and seven channels through which its conventions are enforced — each row of the catalogue naming exactly one. The chapters that follow explain how to USE each facet; this one draws the lines they sit inside.
-
-| The shape                  | Held below                                                                       |
-| -------------------------- | -------------------------------------------------------------------------------- |
-| The runner model           | [The runner model](#the-runner-model) — constructor, handle, chain, result       |
-| The source trees           | [The five trees](#the-five-trees) — `model`, `facets`, `seams`, `runner`, `lint` |
-| How a convention is held   | [The seven enforcement channels](#the-seven-enforcement-channels)                |
-| What ships out of the tree | [What the tree publishes](#what-the-tree-publishes)                              |
-
-The rules themselves — what each family says, what a reviewer must judge — are the constitution, [18 — Conventions](18-conventions.md); their normative sentences are the generated catalogue, [19 — Linting](19-linting.md).
-
-## The runner model
-
-Every facet 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.
-
-Six constructors exist and the list is closed (`src/facets/specification.ts`):
-
-| Constructor                   | Handle destructures to             | Subject under test                               |
-| ----------------------------- | ---------------------------------- | ------------------------------------------------ |
-| `specification.api()`         | `{ api, cleanup, docker }`         | An HTTP API, built and served in this process    |
-| `specification.jobs()`        | `{ jobs, cleanup }`                | A background pipeline, triggered by name         |
-| `specification.cli()`         | `{ cli, cleanup, docker }`         | A command binary in a fresh temp directory       |
-| `specification.integration()` | `{ integration, cleanup, docker }` | 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              |
-
-The asymmetry in that column is the model, not an oversight: `jobs` never spawns a container, so it is handed no `docker`; `website` and `mobile` drive a browser and a simulator rather than an orchestrated stack, so they carry neither.
-
-**One facet has no constructor**, and the same reason explains it: a rendered component starts nothing. `component` ([07 — Component specs](07-component.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
-
-`SpecificationBuilder` (`src/model/chain/builder.ts`) holds the chain for every facet; each facet contributes its own setups and its own terminal actions on top. The infrastructure a chain needs is reached through **ports** — `src/model/ports/` declares eight of them (`browser`, `cli`, `container`, `database`, `device`, `isolation`, `server`, `service`) — and an integration 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: `playwright` for `.visit()`, `appium`/`webdriverio` for `.open()`, `@vitest/browser-playwright` + `vitest-browser-react` + `react` for `component.render()`, and — since 16.0 — `better-sqlite3`, `pg`, `redis` and `testcontainers` for the services a record declares. A project that tests no page, no component and no database installs none of them; `src/seams/peer.ts` owns the one message a missing peer produces, which names the facet that asked, the command, and under pnpm the `onlyBuiltDependencies` line a native binding needs.
-
-## The five trees
-
-The source tree is five trees with declared, one-directional edges. The map is not the linter's to assume — `i1-layer-boundaries` ships inert — so this package declares its own as `FRAMEWORK_LAYERS` in `oxlint.config.ts`, and that declaration is the enforced statement of what follows.
-
-| Tree      | May import                                                                                                                              | Holds                                                                                                                                                                                                                         |
-| --------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `model/`  | itself, the docker/process/yaml seams, the msw seam through two named lazy imports, `runner/update`, and each facet's `*.result` module | What every facet is made of: the chain and the orchestrator, the results and their accessors, the element vocabulary, the contracts and `intercept()`, the `{{token}}` engine, the goldens, the clock, the doubles, the ports |
-| `facets/` | `model/`, itself, the runner's project shape, and the one seam each constructor opens                                                   | Seven folders, the SAME four files in each: `<facet>.specification.ts` (the constructor), `<facet>.chain.ts`, `<facet>.result.ts`, `<facet>.project.ts` (the vitest helper), plus what is unique to the facet                 |
-| `seams/`  | its OWN external dependency, plus `model/` and the facet vocabulary an adapter projects into                                            | One folder per dependency: `postgres`, `redis`, `sqlite`, `testcontainers`, `docker`, `hono`, `playwright`, `vitest-browser`, `appium`, `msw`, `openai`, `anthropic`, `yaml`, `process`                                       |
-| `runner/` | `vitest`, `vite`, `@vitest/browser-playwright`, `model/`, `facets/`                                                                     | The CONFIG side of the runner coupling: the preset, update mode, the `literate()` plugin, the shape a node facet's project takes, and the project index                                                                       |
-| `lint/`   | itself, plus a short list of PURE `model/` modules                                                                                      | The tool-facing channel: the oxlint plugin, the conventions checker, the catalogue manifest and generator                                                                                                                     |
-
-**Every facet folder carries the same four files, whether or not it owns all four.** The setups and terminal actions of the six node facets are ONE builder, because a second copy of "declare a contract, seed a table, run the thing" is how two facets drift — so `api.chain.ts` and its five siblings are a named re-export of that builder rather than an implementation, and `jobs.result.ts` re-exports the shape the builder states. The shape is uniform so that a reader who has opened one facet has opened all seven; the re-export says, in the folder itself, which of the four a facet does not own.
-
-Three of those edges carry their reason in the declaration itself. `model/` reaches `seams/docker`, `seams/process` and the yaml parser because none of the three has a dependency of its own to leak, and it reaches each facet's `*.result` module because the ONE builder constructs all seven results — a value edge, stated rather than hidden. `lint/` reaches exactly the pure modules the runner also uses — the token list, the ground names, the root walk, the `<case>.spec.yaml` parser — so that the file the lint accepts is the file the runner runs, from ONE parser. And the runner is named in exactly TWO places outside a test, one per side of it: `runner/` for the config side — the preset, the project shape, the plugin — and `seams/vitest-browser/` for the page side, where the locators, the visitor, the golden commands and the page's own `vitest` primitives live. Swapping the runner would be a rewrite of those two folders and of nothing else; `model/` states what a render IS and never which runner performs it, which is why the layer map exempts that seam from the prod-import ban (F2) by name.
-
-The table's May-import column is a reading of `FRAMEWORK_LAYERS`, never a second statement of it: the declaration in `oxlint.config.ts` is what the linter enforces and what a change edits.
-
-There are TWO composition roots and neither names a layer. `src/index.ts` is node's: it wires the container integrations into the registry seam and re-exports the public surface. `src/browser/index.ts` is the page's, and `src/surface.ts` is what they agree on — see [What the tree publishes](#what-the-tree-publishes).
-
-## The seven enforcement channels
-
-A convention this package states is held by a **channel**, and every row of the catalogue names exactly one of seven. The guiding aim is that most enforcement is programmatic, not review-borne.
-
-- **statique** — the `jterrazz/*` oxlint plugin: one file per rule under `src/lint/rules/model/` or `src/lint/rules/<facet>/` — the tree the rule reaches, which is also the `facet` field of its manifest row — AST analysis, one diagnostic per file.
-- **upstream** — a convention an oxlint vitest-plugin rule already holds, set as an OPTION from the `testing` fragment rather than duplicated as a rule of ours ([ADR-005](decisions/005-the-doubles-ladder-is-closed.md)).
-- **checker** — passes of the `jterrazz-test-check` binary 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 `src/type-channel.test-d.ts`.
-- **meta** — what the framework's own suite holds about itself: the catalogue's freshness, its completeness, the reach of its rules — [03 — Testing](03-testing.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 `src/lint/manifest.ts`, the single source of truth from which the catalogue in [19 — Linting](19-linting.md) is generated. 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 `tsdown` into `dist/` and its shape follows how each entry is consumed. `index` and `vitest`, plus the `checker`/`catalog` CLIs, are ESM-only — vitest is ESM-only and the CLIs are invoked as `node dist/*.js`. The `oxlint` plugin ships dual, because oxlint loads it from a consumer project that may itself be CommonJS.
-
-**There are FOUR entries and no more**: `@jterrazz/test` for everything a spec uses, `@jterrazz/test/vitest` for what `vitest.config.ts` needs, `@jterrazz/test/oxlint` for the lint plugin, `@jterrazz/test/schema` for an editor validating a `<case>.spec.yaml`. That is rule F1 rather than a convention of taste, and the exemption is derived from the manifest's own `exports` map (`src/lint/package-exports.ts`), so a subpath is exempt the moment it is published and stops being exempt the moment it is withdrawn.
-
-**The root entry has two runtimes.** A component test renders in a real browser, and the node entry cannot load there: it wires `pg`, `better-sqlite3`, `testcontainers` and `node:fs` at import. So `exports["."]` carries a `browser` condition resolving to `dist/browser/index.js` — the same public surface, built for a page, where every node-only name (the six constructors, the services, the docker accessors, the results that walk a disk) is a stub that throws where it was called, naming the facet and saying it runs under node. The split is the RUNTIME's and never the facets': one specifier, so no spec has to remember which entry 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. What both agree on lives in `src/surface.ts`, and the `package-exports` meta-test compares the two builds' exported names on every run.
-
-Two committed projections leave the code and land in the corpus: the API reference under `docs/reference/` (typedoc, through `typescript docs`) and the rule catalogue spliced into [19 — Linting](19-linting.md) and `skills/jterrazz-test/references/rules.md`. A third, `schema/spec.schema.json`, is generated from the document grammar's own constants. Both `docs/` and `schema/` ship in the tarball — the reference included, since the corpus links into it — so a consumer reads the manual where the messages send them, inside the install ([04 — Operating](04-operating.md#what-leaves-the-tree)). All three are regenerated by one gesture and sync-checked — see [02 — Developing](02-developing.md).
-
-## Pitfalls
-
-- **Reaching for a dependency from `model/`.** A new external package belongs in a folder of `seams/` that imports it and nothing else; `model/` importing it directly is the one boundary this package cannot afford to blur, and `i1-layer-boundaries` refuses it.
-- **Adding a seventh constructor.** The six 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-facet.md).
-- **Writing a rule's normative sentence into a chapter.** It belongs in `src/lint/manifest.ts` beside the implementation; a chapter that restates it is the second copy the whole design exists to prevent.
-
-## Related
-
-[02 — Developing](02-developing.md) · [03 — Testing](03-testing.md) · [18 — Conventions](18-conventions.md) · [19 — Linting](19-linting.md)

package/docs/02-developing.md

@@ -1,351 +0,0 @@
-# 02 — Developing
-
-How a change is made. The first half is this repository's own loop — the toolchain, the order its gates demand, which file a change opens and what it owes when it lands. The second half is the walkthrough a consuming project follows, from `npm install` to two passing specs.
-
-## Changing this package
-
-### The loop
-
-| Task                             | Command                           |
-| -------------------------------- | --------------------------------- |
-| Install dependencies             | `npm install` (or `make install`) |
-| Build the bundle                 | `npm run build`                   |
-| Lint + format + typecheck + knip | `npm run lint`                    |
-| Auto-fix what a fixer can        | `npm run lint:fix`                |
-| Run every suite                  | `npm test`                        |
-| Run the fast suite only          | `npx vitest --run --project unit` |
-| Regenerate the projections       | `npm run docs` (or `make docs`)   |
-
-Each has a `make` alias that installs first, which is what CI calls — [03 — Testing](03-testing.md) § What CI runs.
-
-`better-sqlite3` is a native dependency, and an npm that does not run install scripts by default leaves it unbuilt: the `sqlite()` specs of the `unit` project then fail on a missing binding. `npm rebuild better-sqlite3` after the install fixes it, once per checkout.
-
-### The build comes first
-
-`oxlint.config.ts` loads this package's OWN plugin from `./dist/oxlint.js`, and the end-to-end lint specs load it too. Node's type-stripping does not resolve a `.js` specifier back to its `.ts` source, so **`npm run build` must precede `npm run lint`** and must precede the `unit` project. A lint run on a stale bundle judges the previous build's rules.
-
-That config is also where this repository DECLARES its own architecture: `i1-layer-boundaries` ships inert, and `FRAMEWORK_LAYERS` in `oxlint.config.ts` is the enforced statement of the five trees [01 — Architecture](01-architecture.md) describes.
-
-### Which file a change opens
-
-| Changing…                                         | Opens                                                                                      |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| A facet's chain, setups or terminal actions       | `src/facets/<facet>/`, over `model/chain/builder.ts`                                       |
-| What a result exposes                             | `src/model/result/` — accessors stay READ-ONLY                                             |
-| A matcher, or update-mode behaviour               | `src/model/goldens/` and `src/runner/` — the two sides of the runner coupling              |
-| An external dependency's adapter                  | `src/seams/<dep>/`, which imports that dep and `model/` and no more                        |
-| A `{{token}}` or the structural comparison        | `src/model/matching/`                                                                      |
-| The `<case>.spec.yaml` grammar                    | `src/model/literate/` — read by BOTH the runner and the checker                            |
-| A mechanized rule                                 | `src/lint/manifest.ts` **and** its implementation under `src/lint/rules/<facet-or-model>/` |
-| A principle, or a criterion no machine can settle | [18 — Conventions](18-conventions.md), the constitution                                    |
-
-### What a change owes
-
-Four things land in the SAME commit as the change that makes them true.
-
-- **The guard.** Every defect class discovered — in review, from a bug, during a migration — grows the thing that stops it recurring: a static rule, a meta-test, or a runtime refusal. That is rule K1, and it is what keeps the other channels growing instead of decaying. When no channel is possible, the change says so explicitly.
-- **The regenerated projections.** `npm run docs` rewrites them all at once — the API reference under `docs/reference/`, the rule catalogue spliced into [19 — Linting](19-linting.md) and `skills/jterrazz-test/references/rules.md`, the capability matrix, the domain vocabulary and the siblingless table in [03 — Testing](03-testing.md), the fork in [18 — Conventions](18-conventions.md), the signature cards, and `schema/spec.schema.json`. Never edit one by hand: `npm run lint` runs the sync check and the freshness meta-tests, and both fail on a hand edit.
-
-    **`docs/reference/` is regenerated from a plain CLONE, never from a worktree.** typedoc writes a `Defined in:` link per symbol from whatever the git origin resolves to, and a worktree under `home/<brand>/work/worktrees/` resolves it to a local path — which turns every `https://github.com/jterrazz/package-test/blob/main/…` into a bare path, a whole-file diff that looks like content and is only an address. So `Docs (sync)` is red on `docs/reference/` in a worktree BY CONSTRUCTION, and the projection is refreshed by regenerating it in a clone and committing what that writes.
-
-- **The chapter the behaviour falsified.** A page that still describes the old behaviour is a defect that ships. The corpus is mapped by [`docs/README.md`](README.md).
-- **The skill, when the public surface moved.** `skills/jterrazz-test/` routes agents into these chapters; `README.md` is the vitrine and moves with a public API change too.
-
-## Using the framework
-
-The rest of this chapter takes a consuming project from `npm install` to two passing specs: one HTTP API spec backed by a real Postgres container, and one CLI spec running a binary in a fresh temp directory. It also explains the one framework environment variable (`TEST_UPDATE`).
-
-### Install
-
-```bash
-npm install -D @jterrazz/test vitest
-```
-
-Peer dependencies:
-
-| Package  | Required | Needed for                                                    |
-| -------- | -------- | ------------------------------------------------------------- |
-| `vitest` | yes      | Everything — the framework registers its matchers into vitest |
-
-`msw` (outgoing HTTP interception for `.intercept()`) ships as a direct dependency — no separate install. API specs pass your web app to `server`; the adapter only needs an object with a `request()` method, so bring your own web framework (e.g. `hono`) in your project.
-
-**Docker** must be running for container-backed services (`postgres()`, `redis()`). `sqlite()` and plain CLI specs need no Docker.
-
-Trying an unreleased branch of the framework: install a `npm pack` tarball, never a `file:` link — a link makes the consumer resolve `vitest`'s types twice, and the matcher augmentation then lands on one copy and not the other, so `toMatch` types while `toBeEmpty` does not.
-
-Everything a spec needs imports from the single package root; the tool subpaths beside it are the ones the `exports` map publishes, and they are listed once — [01 § What the tree publishes](01-architecture.md#what-the-tree-publishes). F1 and F3 read that map, so a specifier it does not publish is refused:
-
-```typescript
-// the runners, the services, and what a chain stands on
-import { postgres, process, redis, specification, sqlite } from '@jterrazz/test';
-```
-
-```typescript
-// what a test says: contracts, dynamic values, doubles, time, assertions
-import { anthropic, clock, defineContract, http, intercept } from '@jterrazz/test';
-import { match, mockOf, openai, required, waitUntil } from '@jterrazz/test';
-```
-
-### The shape of every test
-
-A **specification file** (`*.specification.ts`, under `specs/`) creates a runner once per suite. A **test file** imports the runner and writes specs. Every spec is one chain: zero or more setups, then exactly one terminal action, resolving to a typed result you assert on with `expect()`.
-
-```
-specification.api(…)         → { api, cleanup, docker }
-specification.jobs(…)        → { jobs, cleanup }                       // no docker — jobs never spawn containers
-specification.cli(…)         → { cli, cleanup, docker }
-specification.integration(…) → { integration, cleanup }                // a module, against real services or a golden
-specification.website(…)     → { website, cleanup, url }               // no docker — a browser, not a container
-specification.mobile(…)      → { mobile, cleanup, udid }               // no docker — a simulator, not a container
-```
-
-The destructured names are canonical — no aliasing (`{ api: myApi }` is an error, rule A3) — and every specification file registers `afterAll(cleanup)` (rule A4).
-
-### First API spec
-
-```typescript
-// specs/api/api.specification.ts
-import { afterAll } from 'vitest';
-import { specification, postgres } from '@jterrazz/test';
-import { createApp } from '../../src/app.js';
-
-export const { api, cleanup } = await specification.api({
-    services: {
-        db: postgres(), // reported as "db"; its init reads docker/db/ (chapter 17)
-    },
-    server: ({ db }) => createApp({ databaseUrl: db.connectionString }),
-    // root: absent — auto-discovered by walking up to the nearest package.json
-});
-
-afterAll(cleanup);
-```
-
-```http
-### specs/api/users/_requests/create-user.http — the COMPLETE request
-POST /users
-Content-Type: application/json
-
-{ "name": "Alice" }
-```
-
-```http
-### specs/api/users/_expected/user-created.http — status + header subset + body
-HTTP/1.1 201 Created
-Content-Type: application/json
-
-{ "id": "{{uuid}}", "name": "Alice" }
-```
-
-```typescript
-// specs/api/users/users.spec.ts
-import { expect, test } from 'vitest';
-import { api } from '../api.specification.js';
-
-test('creates a user', async () => {
-    // Given - empty database
-    const result = await api.request('create-user.http');
-
-    // Then - response matches the fixture; row landed in the database
-    expect(result.response).toMatch('user-created.http');
-    await expect(result.table('users')).toMatchRows({
-        columns: ['name'],
-        rows: [['Alice']],
-    });
-});
-```
-
-`{{uuid}}` is a placeholder from the unified [token grammar](15-tokens.md) — the response body must contain _a_ UUID there, whatever its value.
-
-### First CLI spec
-
-```typescript
-// specs/cli/cli.specification.ts
-import { resolve } from 'node:path';
-import { afterAll } from 'vitest';
-import { specification } from '@jterrazz/test';
-
-export const { cli, cleanup } = await specification.cli(
-    resolve(import.meta.dirname, '../../bin/my-cli.sh'),
-);
-
-afterAll(cleanup);
-```
-
-```typescript
-// specs/cli/help/help.spec.ts
-import { expect, test } from 'vitest';
-import { cli } from '../cli.specification.js';
-
-test('shows help', async () => {
-    // Given
-    const result = await cli.exec('--help');
-
-    // Then - full snapshot of stdout against _expected/help.txt
-    expect(result.exitCode).toBe(0);
-    expect(result.stdout).toMatch('help.txt');
-});
-```
-
-```
-### specs/cli/help/_expected/help.txt — tokens work in text snapshots too
-my-cli v{{semver}}
-Started at {{iso8601}} in {{workdir}}
-Done in {{duration}}
-```
-
-Each CLI spec runs in a fresh, empty temp directory. ANSI escape sequences are stripped before comparison by default (rule D6) — you never snapshot color codes.
-
-### vitest config: the preset
-
-`vitest.config.ts` starts from `defineSpecConfig()` — the shared preset, imported from the tool subpath beside `literate()`. What you pass is a plain vite/vitest config merged **over** the defaults, so one call gives you the ecosystem's common ground and you still state whatever you want:
-
-```typescript
-// vitest.config.ts
-import { api, component, defineSpecConfig, unit, website } from '@jterrazz/test/vitest';
-
-export default defineSpecConfig({
-    test: {
-        projects: [
-            unit(), // `**/*.test.ts` outside specs/ — no browser, no pipeline
-            component({ vite: './vite.config.ts', wrap: './src/providers.tsx' }),
-            website(), // `specs/website/**` — the served product, in its own group
-            api(), // `specs/api/**/*.spec.ts` — the app through HTTP, in-process
-        ],
-    },
-});
-```
-
-What every helper accepts, on top of the project it already is:
-
-| Option                | Does                                                                                                                                   |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `include` / `exclude` | Replace the canonical globs. A default `exclude` guards the default `include`, so state both or neither                                |
-| `timeout`             | Raise (or lower) the preset's 30 s for this project alone                                                                              |
-| `serial`              | `fileParallelism: false` — the project's files run one at a time, for a facet whose files share one server, one database file, one app |
-
-`component()` takes four more that are the APP's — `vite`, `wrap`, `viewport`, `timezone`/`locale`, and the `root` its relative paths are read against — and [07 — Component specs](07-component.md) owns them; `unit()` takes `roots`.
-
-`unit()` and `component()` are a pair by construction: `unit()` collects `**/*.test.ts` outside `specs/` and excludes `**/*.test.tsx`, `component()` collects exactly those, so the suffix beside a file decides which project runs it and which rules judge it. `unit()` takes `roots?` where the modules are not at the repository root, or `include?` for the globs outright; the facet helpers collect `specs/<facet>/**/*.spec.ts` — the word for the assembled product (C12). All three carry `sequence.groupOrder` — node 0, `website` 1, `component` 2 — so the two browser projects never open two Chromiums at once on a 2-vCPU runner. What `component()` sets — the provider pinned to the runner's exact version, the msw worker served from this package's own install, the JSX transform the current Vite uses, the dependencies a cold cache must pre-bundle, the artefact directories, the group order that keeps two Chromiums apart — is [07 — Component specs](07-component.md)'s. `component()` is async, and a project may be a promise: `projects: [component({ … })]` needs no `await`.
-
-#### What the preset sets
-
-| Setting                          | Value                                                | Why                                                                                                                                                                                                                                                                                                    |
-| -------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `cacheDir`                       | `.artifacts/vitest`                                  | The artefact convention below — vite's transform cache leaves `node_modules/`                                                                                                                                                                                                                          |
-| `test.coverage.reportsDirectory` | [the artefact path](#artefacts-live-under-artifacts) | Where a tool writes what it generates is the toolchain's convention ([`@jterrazz/typescript` — Developing](https://github.com/jterrazz/package-typescript/blob/main/docs/02-developing.md)); the preset sets it so no consumer writes it. The **provider is yours to install** (`@vitest/coverage-v8`) |
-| `test.testTimeout`               | `30_000`                                             | Vitest's 5s never survived a container boot, a `prisma db push` or a `next build`                                                                                                                                                                                                                      |
-| `test.hookTimeout`               | `30_000`                                             | Same reason, for the `beforeAll` that starts the infrastructure                                                                                                                                                                                                                                        |
-| `test.exclude`                   | vitest's defaults + `**/_fixtures/**`                | What a spec stands on is an input, never a suite — a repository must not run its own counter-examples                                                                                                                                                                                                  |
-| `test.attachmentsDir`            | `.artifacts/vitest/attachments`                      | Vitest 5 writes `context.annotate()` attachments to `.vitest/` at the repository root                                                                                                                                                                                                                  |
-| `test.outputFile`                | `.artifacts/vitest/{json,junit,html,blob}`           | Vitest 5 turned the json and junit reporters into FILE writers; all four are artefacts                                                                                                                                                                                                                 |
-| `test.retry`                     | `0`                                                  | A flaky test is fixed or deleted — a retry turns a real defect into a slow one and hides it                                                                                                                                                                                                            |
-| `test.restoreMocks`              | `true`                                               | A `vi.spyOn` a test forgets to restore fails a LATER file, one that did nothing wrong                                                                                                                                                                                                                  |
-| `test.unstubGlobals`             | `true`                                               | Same for `vi.stubGlobal` — and it is what lets a test be written without an `afterEach` (rule J6w)                                                                                                                                                                                                     |
-| `test.unstubEnvs`                | `true`                                               | Same for `vi.stubEnv`, which is the sanctioned way to state a module's env contract (rule E9w)                                                                                                                                                                                                         |
-| `plugins`                        | `literate()`, when `literate:` is given              | Turns every matching `<case>.spec.yaml` into a test file (see [12 — CLI specs](12-cli.md))                                                                                                                                                                                                             |
-
-It deliberately sets **nothing else**. `fileParallelism` is a per-project truth (a container-lifecycle suite is serial, an isolated one is not), stated by the project rather than by the preset — a helper states it for you when you pass `serial`, and a hand-written project states it itself; so do `reporters`, `environment`, `env`, `globalSetup` and every `include` — a preset that guessed those would be wrong more often than right.
-
-**Why the artefact paths are the preset's.** Every one of them is a path the TOOL pins and a consumer never writes: a repository does not choose where `context.annotate()` lands, it discovers it one CI run later, as an untracked `.vitest/` beside `.artifacts/`. Moving them here is the same rule the estate applies to every tool — what a tool generates lives at `.artifacts/<tool>/` — applied once instead of in fourteen configs.
-
-Two behaviours worth knowing:
-
-- **Projects inherit the defaults too.** Vitest resolves each project as its own config and it inherits nothing from the root, so the preset merges the budgets, the exclusions and the cache dir into every inline project. A project declared as a glob string, a promise or a function is handed back untouched.
-- **Each glob is stated once.** A project's `exclude` REPLACES vitest's own defaults, so every project carries the preset's list in full; the root's list, which vitest concatenates into each project on top of that, then holds only what YOU stated there. The no-tests banner is the one place a consumer ever reads that list, and it read as three merges of the same three globs.
-- **Arrays are ADDITIVE.** Vite's merge concatenates them, so your `exclude` adds to the preset's — you never spread `configDefaults.exclude` again — and your `plugins` join `literate()` rather than replacing it. Scalars (`testTimeout`, `name`, …) are plain overrides: what you state wins.
-
-With `projects`, put `literate()` in the ONE project that collects those documents — its glob has to join that project's include — rather than in the top-level `literate:` key:
-
-```typescript
-import { defineSpecConfig, literate } from '@jterrazz/test/vitest';
-
-export default defineSpecConfig({
-    test: {
-        projects: [
-            {
-                plugins: [literate({ specification: './specs/cli/cli.specification.ts' })],
-                test: { name: 'cli', include: ['specs/cli/**/*.spec.ts'] },
-            },
-        ],
-    },
-});
-```
-
-#### Migrating a hand-rolled config
-
-Swap the import, drop what the preset already says, keep what is yours:
-
-```diff
--import { configDefaults, defineConfig } from 'vitest/config';
--import { literate } from '@jterrazz/test/vitest';
-+import { defineSpecConfig, literate } from '@jterrazz/test/vitest';
-
--export default defineConfig({
-+export default defineSpecConfig({
-     test: {
--        testTimeout: 30_000,
--        hookTimeout: 30_000,
-
-         projects: [
-             {
-                 test: {
-                     name: 'api',
-                     include: ['specs/api/**/*.spec.ts'],
--                    exclude: [...configDefaults.exclude, '**/_fixtures/**', 'specs/api/heavy/**'],
-+                    exclude: ['specs/api/heavy/**'],
--                    testTimeout: 30_000,
-                 },
-             },
-         ],
-     },
- });
-```
-
-Then add `.artifacts/` to `.gitignore` and drop `node_modules/.vite` from it if it was listed. A project whose timeouts were LOWER than 30s, or higher, keeps stating them — the preset is a floor to start from, not a ceiling.
-
-### Artefacts live under `.artifacts/`
-
-The `.artifacts/<tool>/` convention is [`@jterrazz/typescript`](https://github.com/jterrazz/package-typescript/blob/main/docs/02-developing.md)'s, and its `check` enforces it: one folder per tool at the project root, one line in `.gitignore`, one `rm -rf .artifacts` for a clean slate. What this framework writes there is the only part this chapter answers for.
-
-What this framework writes there:
-
-| Path                                             | Written by                   | Lifetime                        |
-| ------------------------------------------------ | ---------------------------- | ------------------------------- |
-| `.artifacts/vitest/`                             | vite's transform cache       | Reused across runs              |
-| `.artifacts/vitest/coverage/`                    | v8, which the preset selects | Rewritten per coverage run      |
-| `.artifacts/vitest/sqlite/template-<key>.sqlite` | `sqlite()`'s schema template | Reused until the schema changes |
-
-What it does **not** write there: the fresh temp directory each CLI spec runs in, the per-worker SQLite copies, the profile dirs a browser or a simulator needs. Those are per-RUN scratch, they stay in the OS temp dir, and moving them into the project would only put a `package.json` above a spec that must not see one.
-
-### Framework environment variables
-
-You set exactly one variable, prefixed `TEST_` (rule E1): `TEST_UPDATE=1` turns on update mode, which [15 — Tokens § Update mode](15-tokens.md#update-mode-tokens-are-preserved) owns whole — what it writes, what it preserves, and the discipline it asks of a reviewer. The framework also reads vitest's own `VITEST_POOL_ID` (set by vitest, not you) to isolate each parallel worker's database schema and index.
-
-### Directory layout at a glance
-
-```
-specs/
-├── api/
-│   ├── api.specification.ts
-│   └── users/
-│       ├── users.spec.ts          # <aspect>.spec.ts inside its domain (rule C1)
-│       ├── _seeds/                 # *.sql
-│       ├── _requests/              # *.http — complete requests (inputs)
-│       ├── contracts/             # <name>.contracts.ts facade + <provider>/<name>.ts units + their data
-│       └── _expected/              # all expected fixtures, flat — incl. response *.http (a slash in the name creates a subfolder)
-└── cli/
-    ├── cli.specification.ts       # runner at the facet root (rule C1)
-    └── help/
-        └── help.spec.ts           # under specs/, the suffix is .spec.ts (rule C12)
-```
-
-## Pitfalls
-
-- **Renaming the destructured runner** (`const { api: usersApi } = …`). The canonical names `api`, `jobs`, `cli`, `website`, `mobile` are enforced (rule A3).
-- **Forgetting `afterAll(cleanup)`.** Infrastructure leaks across suites; rule A4 requires it in every specification file.
-- **Importing from a subpath the `exports` map does not publish** (`@jterrazz/test/services`). Everything a spec needs comes from `@jterrazz/test` (rule F1).
-- **Writing `// Given` without `// Then`** (or vice versa). Every test carries both comments (rule B4); `// When` only when the action is not obvious — the chain _is_ the when.
-
-## Related
-
-[10 — API specs](10-api.md) · [12 — CLI specs](12-cli.md) · [14 — Assertions](14-assertions.md) · [18 — Conventions](18-conventions.md) · [08 — Website specs](08-website.md) · [09 — Mobile specs](09-mobile.md)