@jterrazz/test 16.1.1 → 18.0.0

package/docs/guides/component-specs.md

@@ -0,0 +1,252 @@
+# Component specs (`component`)
+
+`component` tests one thing that draws itself (a React component, a React hook through a small host component written in the test, or a plain DOM function), rendered in a real headless Chromium through Vitest Browser Mode. It lives beside its code as `<file>.test.tsx`, starts nothing, and so has no constructor: the test calls the exported `component` chain directly.
+
+For a whole served page, use [Website specs](website-specs.md); for a module that draws nothing, a [module test](module-tests.md). Why a real browser rather than a simulated DOM: [ADR-003](https://github.com/jterrazz/package-test/blob/main/docs/decisions/003-a-rendered-component-is-a-specification-on-vitest-browser-mode.md).
+
+## What it specifies
+
+A component test answers one question: **given this network and this parent, what does the component put on the screen, and what does it report back?** Everything it reads is what a user or a parent can see (the accessibility tree, the rendered text, the markup, the console), and everything it does is what a user or a parent can do: click, fill, press, change the props, take it off the screen.
+
+It is a UNIT, so it lives with its subject, in the `__tests__/` of the subject's folder (`test-in-its-tests-folder`):
+
+```text
+src/presentation/posts/
+├── post-table.tsx
+├── use-modal-dialog.ts
+└── __tests__/
+    ├── post-table.test.tsx        # the component's spec; the `.tsx` suffix IS the kind
+    └── use-modal-dialog.test.tsx  # a hook's spec: its Host is written in the test file
+```
+
+The suffix decides which project collects the file and therefore which rules judge it: `unit()` takes `**/*.test.ts` and excludes `**/*.test.tsx`; `component()` takes the `.tsx`. A rendered thing in a `.test.ts` is rule `no-dom-in-module-test`'s error, and it names the move.
+
+## What it does not do
+
+The subject is a unit that draws itself IN A BROWSER, which leaves four neighbours outside the specification, each with a route, so none of them is a hole.
+
+| Not this                               | Because                                                                             | Route                                                                                     |
+| -------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| A React Native screen                  | The renderer is a real Chromium, and a native view never reaches one                | jest stays, until an experiment rendering it through `react-native-web` shows it can move |
+| An `.astro` page                       | A page is the assembled product, met through an address                             | a website spec: [Website specs](website-specs.md)                                         |
+| A React island inside an `.astro` page | The island is a rendered unit; only the file around it is not                       | a `.test.tsx` in the `__tests__/` of the island's folder, here                            |
+| A Next.js server component             | It renders on the server and reads what the server reads; there is no tree to mount | a website spec, through the served page                                                   |
+
+**What runs under node stays there.** In a page, each node-only name the entry publishes (the seven constructors, the services, the docker accessors, the results that walk a disk) refuses where it is called: a page has no filesystem, no child process and no socket.
+
+## The constructor: there is none
+
+Every other specification starts something (a server, a database, a binary, a simulator), so every other specification has a `*.specification.ts` holding what was started. A component has nothing to start. What a specification file WOULD have held splits by owner:
+
+| What                                               | Whose      | Where                                                           |
+| -------------------------------------------------- | ---------- | --------------------------------------------------------------- |
+| The providers every render is dressed in           | the app's  | the `component` project's `wrap`, in `jterrazz.config.ts`       |
+| The Vite pipeline the app builds with              | the app's  | its `vite`                                                      |
+| The viewport, the timezone, the locale             | the app's  | its `viewport`, `timezone`, `locale`                            |
+| The stubs, the wrapper, the instant, the page size | one test's | the chain: `.intercept()`, `.wrap()`, `.clock()`, `.viewport()` |
+
+```typescript
+// apps/web/jterrazz.config.ts: its test section
+const projects = {
+    component: {
+        reason: 'the app renders through its Vite pipeline, inside its providers',
+        vite: './web/vite.config.ts',
+        wrap: './web/src/providers.tsx',
+    },
+};
+```
+
+**A relative `vite` or `wrap` is the project's path.** Both are resolved against the component project's `root`, which is the directory holding `jterrazz.config.ts` unless the project states one, so the two paths above mean `apps/web/web/<path>`. A `root` the project states is read from that same directory.
+
+`wrap` is a MODULE PATH whose default export is `(ui) => ReactNode`: a page imports a URL, not a function, so the providers cross as a setup file the project generates under `.artifacts/`. Nothing imports the module itself, so `test()` names it to knip as an entry: the project declares none. A router does not belong here: which routes exist is a test's Given, and it goes on the chain.
+
+| Option                | Description                                                                                                               |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `wrap`                | Module path, default-exporting `(ui) => ReactNode`: the app's own providers, around every render of the project           |
+| `vite`                | The app's pipeline: a config path, the object, or the function a framework exports. Only the PIPELINE is adopted (below)  |
+| `clock`               | An ISO instant pinned for every render, for a project whose components stamp the time                                     |
+| `viewport`            | `{ width, height }` of the page. Default `1280 × 720`                                                                     |
+| `timezone` / `locale` | The browser context's. Defaults `'UTC'` and `'en-US'`                                                                     |
+| `root`                | The directory `vite` and `wrap` are resolved against. Default: the directory holding `jterrazz.config.ts`                 |
+| `include` / `exclude` | The globs. Derived: `specs/component/**/*.test.tsx`, and each root holding a `*.test.tsx`; state your own to replace them |
+| `timeout`             | Raise (or lower) the preset's 30 s for this project alone                                                                 |
+| `serial`              | `fileParallelism: false`: the project's renders run one file at a time                                                    |
+
+**Only the pipeline of `vite` is adopted.** An app's config says where the app LIVES (its `root`, its `build`, its `server.port`, its `publicDir`), and adopting those re-roots the run so the project collects nothing. The kept keys are an allow-list (`plugins`, `resolve`, `esbuild`/`oxc`, `css`, `define`, `assetsInclude`, `envPrefix`, `json`, `optimizeDeps`), and the consumer's `plugins` are concatenated after `component()`'s own, never assigned over them. So is its `optimizeDeps.include`, joined to the project's own: every dependency a component imports belongs there, since one Vite first finds when a test imports it is optimised mid-run, and the reload fails the tests already loading.
+
+**One transformer key, chosen from the installed Vite.** Vite 8 compiles with oxc and warns for every `esbuild` option handed to it beside an `oxc` one; Vite 6 and 7 compile with esbuild and have no `oxc` key at all. `component()` reads the installed major, states the JSX default on the key that Vite actually reads, and drops the other from the adopted pipeline, and the one it states yields to yours: a `jsxImportSource` or a classic runtime is the app's statement, not the project's to overwrite.
+
+**A framework's config function is called as a dev server under test.** `component()` calls it with `{ command: 'serve', mode: 'test', isSsrBuild: false }` and adopts what it returns through the same allow-list, so an Astro app hands over its whole pipeline: its integrations' plugins, React's and Tailwind's among them, its `import.meta.env` defines, its `tsconfig` paths:
+
+```typescript
+// jterrazz.config.ts of an Astro app: its component project
+import { getViteConfig } from 'astro/config';
+
+const component = {
+    reason: 'the app builds with Astro, whose config function hands over its pipeline',
+    vite: getViteConfig({}, { root: import.meta.dirname }),
+};
+```
+
+Both arguments are Astro's. The first is required: Astro reads the app's `root` off it. The second's `root` is the one the project's `root` cannot give: Astro looks for `astro.config.*` in the CWD, not beside the config that calls it, so a config loaded from elsewhere (knip or `typescript check` at a repository root, an app nested in a workspace) finds none, warns `Missing pages directory`, and hands back a pipeline without the app's integrations, its defines or its plugins. Nothing fails then; a component that needed them renders wrong.
+
+**A `resolve.alias` is an unlisted dependency.** An alias tells the bundler where a specifier resolves; it tells knip nothing, so a package reached only through an alias reads as undeclared, and a `paths`-less `tsconfig` makes the compiler disagree with the bundler besides. Mirror the alias in the `tsconfig`'s `paths` (the compiler and the bundler then answer alike), or name the package in `knip.ignoreDependencies` with the alias as the reason.
+
+## The chain
+
+```tsx
+import { button, component, content, file } from '@jterrazz/test';
+import { defineStub, http } from '@jterrazz/test/stubs';
+import { describe, expect, test } from 'vitest';
+
+import { PostTable } from './post-table.js';
+
+const listing = defineStub({
+    request: http.get('/api/posts'),
+    response: http.json({ posts: [{ id: 1, title: 'A first post' }], total: 200 }),
+});
+
+describe('PostTable', () => {
+    test('says how much of the collection the table is showing', async () => {
+        // Given - a page of one row answering for a collection of two hundred
+        const result = await component.intercept(listing).render(<PostTable />, async (visitor) => {
+            await visitor.see(content('Showing 1 of 200 posts'));
+        });
+
+        // Then - the table is qualified by what it is not showing
+        await expect(result.tree).toMatch(file('./__expected__/one-of-two-hundred.aria.yaml'));
+        expect(result.console.text).toBe('');
+    });
+});
+```
+
+Every setup returns a NEW chain, so the handle a spec imports never carries the previous test's state.
+
+| Setup             | Does                                                                                                                                                     |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.intercept(...)` | Declares what the network replies: the same stubs and the same queue as every other specification                                                        |
+| `.wrap(fn)`       | Wraps every render of this chain: a router stub, a `<StrictMode>`, a provider one test needs                                                             |
+| `.clock(iso)`     | Pins the page's `Date` for this render                                                                                                                   |
+| `.viewport(size)` | The page size THIS render gets: the Given of a component that reads `matchMedia` or a container query. The project's size is restored when the test ends |
+
+| Terminal action               | Mounts                                                                        |
+| ----------------------------- | ----------------------------------------------------------------------------- |
+| `.render(<X />, scenario?)`   | A React tree                                                                  |
+| `.render((container) => ...)` | A DOM function, handed a fresh container; its optional return is the teardown |
+
+The scenario is the When, and assertions stay in the Then (rule `no-expect-in-scenario`). Its verbs are the page's (`click` `fill` `check` `select` `hover` `press` `see` `gone`, each owned and described by [The visitor § Verbs](../reference/visitor.md#verbs)), plus the two only a parent has:
+
+| Verb           | Description                                               |
+| -------------- | --------------------------------------------------------- |
+| `rerender(ui)` | What a PARENT does: new props, same mount                 |
+| `unmount()`    | What a parent does when it takes the thing off the screen |
+
+`goto()` does not exist here, because a component has no address. The visitor's vocabulary is the page's too, modifiers included: [The visitor § Modifiers](../reference/visitor.md#modifiers) owns them all, with the `target-matches-one-element` refusal and the exact-name rule.
+
+## The result
+
+| Member                  | Type           | Description                                                                                                                                                                               |
+| ----------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `result.tree`           | `RenderedText` | The ARIA snapshot of the rendered body, the outline a golden pins                                                                                                                         |
+| `result.content`        | `RenderedText` | The RENDERED text of the document body (`innerText`): what a reader sees, so a stylesheet's source and a node the page does not display are not in it                                     |
+| `result.visibleContent` | `RenderedText` | The same text without the text of an element drawn at `opacity: 0`. `innerText` keeps it, a reader of an animation does not see it, so a golden of a reel frame pins what the frame shows |
+| `result.html`           | `RenderedText` | The mounted markup, the escape hatch for a class or an attribute                                                                                                                          |
+| `result.console`        | `RenderedText` | Every console message, one `[type] text` line per message, and every uncaught exception as ONE `[error] Uncaught ...` line                                                                |
+| `result.errors`         | `RenderedText` | Console errors only, plus any uncaught page error, once (`Uncaught Error: ...`)                                                                                                           |
+
+`toMatch(file(...))` is **awaited** on all five, because each is a `RenderedText`, a `TextAccessor` whose golden lives on the node side: a golden captured inside a page is read back through a server command, so the file crosses from the page to the node side. Which matchers are IO (and therefore awaited) is [Assertions](../reference/assertions.md)'s to state; a directory subject is the other one, and it is awaited for the same kind of reason (it walks a disk).
+
+```typescript
+await expect(result.tree).toMatch(file('./__expected__/two-of-two-hundred.aria.yaml'));
+expect(result.html.text).toContain('row row--live');
+expect(result.errors.text).toBe('');
+```
+
+The ARIA tree is the golden a rendered surface wants: it is the outline a screen reader walks, it is deterministic where a screenshot is not, and it is the SAME dialect [Website specs](website-specs.md) produces for a whole page. Goldens live in `__expected__/` beside the test and are written by `TEST_UPDATE=1`, exactly as everywhere else ([Tokens](../reference/tokens.md)).
+
+## Unique here
+
+- **The hook recipe.** A hook has no surface, so its Given is a **Host component written in the test file**, carrying the states the test needs: an opener, a fallback target, a handler that can be swapped. The visitor drives the Host; `rerender` swaps the handler; `unmount` is the parent walking away. There is no hook-specific runner and there is no need for one.
+
+```tsx
+import { button, component, dialog, focused } from '@jterrazz/test';
+import { useState } from 'react';
+import { describe, expect, test, vi } from 'vitest';
+
+// The Given of a hook spec is a Host, written HERE: the component carrying the
+// States the test needs is part of the test, not of the app.
+function Host({ onClose }: { onClose: () => void }) {
+    const [open, setOpen] = useState(false);
+
+    const show = (): void => {
+        setOpen(true);
+    };
+
+    const dismiss = (): void => {
+        setOpen(false);
+        onClose();
+    };
+
+    if (!open) {
+        return (
+            <button onClick={show} type="button">
+                Open
+            </button>
+        );
+    }
+
+    return (
+        <dialog aria-label="Host" open>
+            <button onClick={dismiss} type="button">
+                Close
+            </button>
+        </dialog>
+    );
+}
+
+describe('focus', () => {
+    test('gives the keyboard back to whatever opened it', async () => {
+        // Given - a dialog opened from a button and then dismissed
+        const onClose = vi.fn<() => void>();
+
+        await component.render(<Host onClose={onClose} />, async (visitor) => {
+            await visitor.click(button('Open'));
+            await visitor.see(dialog('Host'));
+            await visitor.click(button('Close'));
+            await visitor.gone(dialog('Host'));
+            await visitor.see(focused(button('Open')));
+        });
+
+        // Then - the owner heard the dismissal exactly once
+        expect(onClose).toHaveBeenCalledOnce();
+    });
+});
+```
+
+- **A DOM function is still a component.** `renderSessionRows(container, rows)` renders; it just does not use React. `.render((container) => ...)` mounts it in the same Chromium under the same visitor, and `result.html` reads what it drew. No React is loaded. Write the body BRACED: a concise arrow hands back the void the render function returns, and `typescript/no-confusing-void-expression` refuses that.
+
+```tsx
+const result = await component.render((container) => {
+    renderSessionRows(container, rows);
+});
+```
+
+- **A router is a test's Given.** A screen that renders `<Link>` or reads `useParams()` throws without a router. `createRoutesStub([...])` on `.wrap()` is that Given: React Router's own guidance, and the fork's: a route module is a website spec, a presentation component is a component spec, a loader is a module test.
+- **Strictness is total.** A component that fetches something no stub declared fails the render, naming the request, including a component given NO stub at all, which is how "this subject has no network" is said. The request is the failure the render reports even when the scenario then failed for want of what it asked for: the cause, not the symptom. There is no bypass and no default handler. The api specification's `network-strict-after-first-stub` stops at a known scope because it shares a process with everything else the test does; a page does not, so here it is total. It follows that a module-scope `intercept()` opened around a `.render()` is shadowed: the render's own registration is installed last and answers everything. Declare a render's network on the chain; `intercept()` in a `.test.tsx` is for code the test calls itself ([Stubs](../reference/stubs.md#intercept-the-same-double-with-no-chain)).
+- **The clock is the page's.** `.clock(iso)` pins `Date` and nothing else: faking the page's timers would stop React's scheduler and nothing would ever render.
+
+## Pitfalls
+
+- **Reaching for `@testing-library/react` or `happy-dom`.** Rule `no-second-test-runtime` refuses both, and the second is the reason the specification exists: a simulated DOM behaves almost like a browser, and what ships is judged by a real one.
+- **Writing a `*.specification.ts` for it.** There is nothing to start. The project holds what every render shares; the chain holds what one test needs.
+- **Hand-rolling `browser:` in a config.** A derived config has no place for it: the provider is pinned to the runner's EXACT version, the service worker is served from the framework's own install, the JSX transform follows the Vite in use, and a cold dependency cache must be pre-bundled or the first run reloads the tester under the test. `component()` owns all four.
+- **Putting a rendered test in a `.test.ts`.** Rule `no-dom-in-module-test` refuses the DOM globals it would need. Rename it `.test.tsx`, in the `__tests__/` of its component's folder; the project that collects it opens a browser.
+- **Asserting focus with a golden.** The tree carries no focus; [The visitor § Modifiers](../reference/visitor.md#modifiers) says what asserts it.
+- **Expecting `toMatch(file(...))` to be synchronous here.** It is not: `await expect(result.tree).toMatch(file('./__expected__/<name>.aria.yaml'))`. A bare call still runs the assertion, but off the test's lifetime: a failure surfaces as an `Unhandled Errors` entry attributed to no test, the test itself is reported PASSED, and the run exits non-zero anyway. Under `TEST_UPDATE=1` the write happens outside the test too.
+- **Reading the `target-matches-one-element` refusal as a suggestion.** When two elements carry the SAME whole name, the refusal names the accessible name each candidate matched on and offers a landmark; read that before scoping, because the landmark it offers is the one that narrows, not necessarily the one you meant. Exact-by-default and its `{ exact: false }` escape are [The visitor § A name designates the accessible name WHOLE](../reference/visitor.md#a-name-designates-the-accessible-name-whole)'s.
+- **Pointing `wrap` at a router.** `wrap` is the app's frame, around every render of the project. Which routes exist changes per test, so it belongs on the chain.
+- **Giving the project the app's whole Vite config and expecting the app's root.** Only the pipeline is adopted; the project's root stays the directory of `vitest.config.ts`, which is what makes its `include` globs mean what they say.
+
+## Related
+
+[Set up a project](../start/set-up-a-project.md) · [Website specs](website-specs.md) · [Stubs](../reference/stubs.md) · [The visitor](../reference/visitor.md) · [Assertions](../reference/assertions.md)

package/docs/guides/develop.md

@@ -0,0 +1,97 @@
+# Develop
+
+How a change to this repository is made: the toolchain, the order its gates demand, which file a change opens and what it owes when it lands. How a consuming project installs and configures the framework is [Set up a project](../start/set-up-a-project.md).
+
+## The loop
+
+The repository answers six `make` targets, the same six every repository of its author answers:
+
+| Target         | Does                                                                                                                                                                           |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `make install` | Install the dependencies (`npm ci`, again only when the lockfile moves)                                                                                                        |
+| `make build`   | Build the bundle, before `lint` and before the `unit` project; an unchanged tree restores it from the build cache instead                                                      |
+| `make lint`    | Typecheck, lint, format check, knip, then the conventions checker and the self checker (the source tree's structure locks)                                                     |
+| `make fix`     | Build, then `npx typescript fix`, which runs the conventions' fixes and the self checks first, then oxlint's and the formatter, so the formatter formats what the checks wrote |
+| `make test`    | Every suite, through `npx typescript test`, which answers a tree it already proved green from that proof                                                                       |
+| `make check`   | The whole verdict: build, lint, test, then the mutation verdict (`make mutation`, incremental); a stage whose inputs it already proved green answers from its proof            |
+
+A stage keeps its green as a proof keyed by the content of everything it reads, under `.artifacts/proven/`, and answers the same key from it: `make lint`, `make test` and `make mutation` run nothing on a tree they already proved green, on a laptop as on a runner ([the toolchain's Quality checks § A tree proven green](https://github.com/jterrazz/package-typescript/blob/main/docs/reference/quality-checks.md#a-tree-proven-green)). `check` asks no stage cold; a run that must ignore its proofs says so itself, `make mutation MUTATION_ARGS=--cold`.
+
+Every target installs first. CI calls `build`, `lint`, `test`, then `make mutation` ([Test § What CI runs](test.md#what-ci-runs)).
+
+`make mutation` is `typescript mutation`: [Stryker](https://stryker-mutator.io), from the config the toolchain derives with `typescript.mutation`, twice. The first run is the `unit` project over `src/` and the shipped `lint/` code that carries a module test; the second is every node project, against a build of the instrumented sources, over every mutant the module tests let live and the changed lines (the change not yet committed or, on a clean tree, the branch since its merge-base with the default branch) that no module test runs. Every process a spec spawns is handed the active mutant. It fails on any mutant a test runs and none detects ([its verdict](https://github.com/jterrazz/package-typescript/blob/main/docs/reference/quality-checks.md#every-mutant-a-test-runs-is-detected)). `lint/self/` is not mutated: its audits run over this repository's own corpus, which they hold clean, so a mutant that loosens one survives by construction. A run mutates a sandbox copy under `.artifacts/stryker/tmp/`, never the checkout, and leaves its reports in `.artifacts/stryker/`, which git ignores.
+
+It is incremental: Stryker re-runs only the mutants whose source or tests changed since the report it left, so a run over a day's changes takes roughly two to four minutes, and a first module run in a fresh clone, with no report yet, takes 75 minutes, once ([measured by ADR-020](https://github.com/jterrazz/package-typescript/blob/main/docs/decisions/020-mutation-measures-the-whole-suite-over-a-change.md#consequences)). A survivor whose covering test was removed keeps its result until its source changes, so a report that disagrees with a fresh read is cleared by deleting `.artifacts/stryker/incremental.json`, and `.artifacts/stryker/suite-incremental.json` for the suite's, whose stale entries the suite run reuses.
+
+The everyday loop, and the targets beyond the six:
+
+| Gesture                           | Does                                                                                                                                                                                                                                                                                                       |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `npx vitest --run --project unit` | The fast suite, with no infrastructure                                                                                                                                                                                                                                                                     |
+| `npm run docs`                    | Regenerate the generated tables                                                                                                                                                                                                                                                                            |
+| `make test-changed`               | Only the tests the uncommitted changes reach (`vitest --changed`): the local loop, never a verdict. Like any partial run, it judges no route ratchet ([API specs](api-specs.md#when-a-run-is-not-judged))                                                                                                  |
+| `make test-mobile`                | The mobile specs on a real iOS simulator; no CI job runs it, and [Test](test.md) says when it is owed                                                                                                                                                                                                      |
+| `make check-links`                | Every link of `README.md`, `docs/` and `skills/`, remote ones included, with [lychee](https://lychee.cli.rs). It needs the network and a lychee on the machine, and fails where there is none. Never part of `check`: the gate reads local links offline, as `@jterrazz/typescript`'s Markdown pass states |
+| `make test-merge`                 | Read the blob reports of a sharded run back as one, then judge the route ratchet on it ([Test § What CI runs](test.md#what-ci-runs) says how a run is split)                                                                                                                                               |
+| `make rehearse`                   | The release gate on Linux, on the commit to tag, before the tag ([Releasing](release.md) says when). It needs docker and the network; never part of `check`                                                                                                                                                |
+
+The `sqlite()` specs of the `unit` project need no rebuild after `npm ci`: this repository runs the `better-sqlite3` line whose native binding ships prebuilt. [Set up a project § What to install](../start/set-up-a-project.md#what-to-install) says which line that is, and what an older one costs.
+
+## The build comes first
+
+The lint loads this package's OWN plugin and presets from its build (`test()` from `dist/config.js`, the plugin from `dist/oxlint.js`, `self()` and its checks from `.artifacts/dev/`), and the end-to-end lint specs load them 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.
+
+`npm run build` is `typescript build`: the toolchain derives the bundle from the manifest (every `exports`, `imports` and `bin` target from its source) and from the names of the modules loaded by path: each `*.global-setup.ts` a specification hands vitest is shipped in `dist/` under its own name, and the programs only this repository runs (each `*.cli.ts`: `schema`, `route-split`, `self`; and the modules at the root of `lint/self/`: `preset`, `plugin`) are built into `.artifacts/dev/` and never shipped.
+
+This repository's presets are its own build, and the build reads `jterrazz.config.ts` before there is one: the file lists `test()` and `self()` through `ownPresets` ([`@jterrazz/typescript`'s Configuration](https://github.com/jterrazz/package-typescript/blob/main/docs/reference/configuration.md#a-repository-held-to-its-own-presets)), so a fresh clone's first build reads the declaration alone, and every later run reads the presets too. Any other command over an unbuilt tree (a lint, a test, an editor's language server) is refused in four parts naming `npm run build`, so none of them passes on nothing.
+
+This repository's `jterrazz.config.ts` declares it a `library` on `node`, lists `test()`, as every consumer does ([Linting § What the preset carries](../reference/linting.md#what-the-preset-carries)), then `self()`, the one preset only this repository declares, and states only its exceptions (how four test projects depart from the ones its tree derives, a mutation exclusion, the lint rules it sets apart, the `schema/` root), each with its reason, and under `optOuts` the two laws it sets aside: a base law, and its own preset's network seam, since the module test of the handlers that wrap msw drives msw itself; `self()` restates that seam's law for every other test file of the repository. `self()` is `lint/self/preset.ts`, built as `.artifacts/dev/preset.js`, and it carries everything this repository adds to its own tree: its layers, `ARCHITECTURE` in `lint/self/checks/architecture.ts`, which compiles `FRAMEWORK_LAYERS` (`lint/self/checks/layers.ts`) and the library owners into dependency-cruiser rules: the enforced statement of the trees [Architecture](../concepts/architecture.md) describes, the direction of `lint/` being the toolchain's standard's; the one name rule only this repository is held to ([Test](test.md#the-packages-own-rules)); the self plugin and its rules. Its `oxlint.config.ts`, `oxfmt.config.ts`, `tsconfig.json` and `vitest.config.ts` are the lines the toolchain derives.
+
+## Which file a change opens
+
+| Changing...                                         | Opens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A specification's chain, setups or terminal actions | `src/specifications/<specification>/<specification>.composition.ts` and the `*.capability.ts` or `*.action.ts` it composes, in the specification's concept folders, or in the notion it sets up (`src/stubs/`, `src/services/`, `src/disk/`, `src/clock/`) and `src/chain/context/` for a setup every specification shares                                                                                                                                                                                                                                                                                                                                                  |
+| What a result exposes                               | `src/expectations/` for an accessor, or the `*.result.ts` in the specification's concept folder; accessors stay READ-ONLY                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| A matcher, or update-mode behaviour                 | `src/expectations/goldens/` and `src/expectations/in-place/`; `src/vitest/` only for the hook that wires them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| An external dependency's adapter                    | the ONE slice that owns the library: a notion (`src/services/<db>/`, `src/stubs/delivery/` ...) or a specification's concept folder (`src/specifications/website/browser/` ...), and no other                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| A `{{token}}` or the structural comparison          | `src/expectations/tokens/`, the list of kinds in `lint/kit/project/tokens.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| A verb, a target, a landmark, or how one matches    | `src/visitor/`: `verbs.ts` (`VisitorVerbs`, the verbs every surface shares), `targets/` (the `Target` type in `target.ts`, `roles.ts` and `landmarks.ts` (`within()` and the scope walk with it), each with the private factory it builds targets from, `modifiers.ts`, how a target is spelled in `as-written.ts`), `matching/` (the `target-matches-one-element` refusal in `ambiguous.ts`, what it lists of each candidate in `candidates.ts`, the tag-to-landmark table in `landmark-of-tag.ts`), `matrix.ts` (which verb and target each surface offers)                                                                                                               |
+| A runner-config default, or a project helper        | `src/vitest/preset.ts`, `src/vitest/project.ts` and `src/vitest/unit.project.ts`, or the specification's own `<specification>.project.ts` for its project, published by `src/index.vitest.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| The `<case>.spec.yaml` grammar                      | `lint/kit/project/spec-document.ts`, read by BOTH the runner and the checker                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| How a cli document runs                             | `src/specifications/cli/documents/literate.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| A mechanized rule                                   | its row in `lint/consumer/catalogue/manifest.json` (`lint/self/catalogue/manifest.ts` for a self rule), its audience stated, **and** its implementation by channel: a static rule at `lint/consumer/rules/<family>/<name>.ts`, wired in `lint/consumer/rules/plugin.ts`; a checker pass at `lint/consumer/checks/<name>.ts`, listed in the registry `lint/consumer/checks/checker.ts`, which `lint/index.checker.ts` hands the kit; an option on an upstream rule in `lint/consumer/rulebook/`; a self rule or pass under `lint/self/rules/<family>/` or `lint/self/checks/`, listed in the `plugin.ts` or `checker.ts` beside them, which `lint/self/self.cli.ts` composes |
+| A principle, or a criterion no machine can settle   | [Conventions](../concepts/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. It is what keeps the other channels growing instead of decaying. When no channel is possible, the change says so explicitly.
+- **The regenerated tables.** `npm run docs` rewrites every `GENERATED` block at once, and `schema/spec.schema.json`. The blocks are, in [Test](test.md), the layered reading (`layers`), the siblingless table (`siblings`), the capability matrix (`matrix`), the meta-test channel (`meta-tests`) and the package's own rules (`self-rules`); the rule catalogue in [Linting](../reference/linting.md) (`catalogue`); the fork in [Getting started](../start/getting-started.md) (`fork`). Never edit one by hand: the freshness meta-tests fail on a hand edit.
+- **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/SKILL.md` is hand-written and short (which kind, the pitfalls, the chapter to read next), and a meta-test fails when it names a symbol the entries do not export or a chapter that is not on disk; `README.md` is the front page and moves with a public API change too.
+
+## The oxlint plugin API is alpha
+
+Oxlint's JS-plugin API is **alpha**. The plugin takes oxlint's types from `@oxlint/plugins` (the context, the report, the fixer, the comments, a node's span) and keeps one view of its own (`lint/kit/project/rule.ts`): a rule reads a node by its `type` and its span, every other field defensively, so a change to oxlint's generated ESTree union is not a change to the rules. Every rule is written in oxlint's `createOnce` form: its visitor is built once per run, and its `before` hook resets what the rule keeps for one file and returns `false` for a file the rule does not judge, which oxlint then skips. What every rule asks of a file (its role, whether it is production, its `specs/` anchor) is answered once per file for all of them (`lint/kit/project/linted-file.ts`). `lint/self/corpus/__tests__/rule-state.test.ts` holds each rule to both: no state a `before` leaves unreset, and the same verdicts from a file linted alone or after the rest of its corpus. Expect to re-validate the plugin on oxlint majors; the E2E specs (`specs/lint/**`, one violation/compliant fixture pair per rule) run the real binary and are the canary.
+
+## Pitfalls
+
+- **Linting before building.** The lint loads this package's own plugin from `dist/`, so a lint on a stale bundle judges the previous build's rules ([The build comes first](#the-build-comes-first)).
+- **Editing a generated table by hand.** The next `npm run docs` overwrites it, and the freshness meta-test fails until it does ([What a change owes](#what-a-change-owes)).
+- **A stale plugin in the editor after a rebuild.** The oxlint language server loads `dist/oxlint.js` once and keeps it for the life of the server, so after `npm run build` the editor still lints against the old bundle. The command line is authoritative; restart the editor's oxlint server to resync.
+
+## Writing the manual
+
+The manual is cut into the four sections the [map](../README.md) lists; how a page is written:
+
+- **One owner per fact.** Each fact is stated on one page; the others link to it.
+- **The kind guides share one outline** (what it specifies, the constructor, the chain, the result, unique here, pitfalls), so the reader who learned one kind knows where to look in the next.
+- **Rules live in the code.** A rule's normative sentence is written in `lint/consumer/catalogue/manifest.json` and generated into [Linting](../reference/linting.md); the pages explain and illustrate, and the catalogue decides.
+- **Every example compiles.** A meta-test typechecks each block that imports only the framework, so a sample cannot drift from the API.
+- **A block that starts at `test(...)` is an excerpt.** In its file, that test sits inside the file's one `describe`, which a block showing a whole file writes out.
+
+## Related
+
+[Architecture](../concepts/architecture.md) · [Test](test.md) · [Release](release.md) · [Set up a project](../start/set-up-a-project.md) · [Linting](../reference/linting.md)

package/docs/guides/integration-specs.md

@@ -0,0 +1,181 @@
+# Integration specs: a module against the real thing
+
+`specification.integration()` tests a module (a function your test calls) against the real things it depends on: a database, a cache, a process, a declared stub. It also takes a module whose expected answer is a golden file. There is no HTTP, no binary and no page here; what makes this a spec rather than a module test beside the code is what the module stands on.
+
+```typescript
+// specs/integration/integration.specification.ts
+import { specification } from '@jterrazz/test';
+import { postgres } from '@jterrazz/test/services';
+import { afterAll } from 'vitest';
+
+export const { cleanup, integration } = await specification.integration({
+    services: { db: postgres() },
+});
+
+afterAll(cleanup);
+```
+
+```typescript
+// specs/integration/orders/orders.spec.ts
+import { file } from '@jterrazz/test';
+import { describe, expect, test } from 'vitest';
+
+import { listOrders } from '../../../src/orders/orders.js';
+import { integration } from '../integration.specification.js';
+
+describe('orders', () => {
+    test('reads the orders the day left behind', async () => {
+        // Given - two orders in the real database, from the seed beside the test
+        const result = await integration
+            .seed(file('./__seeds__/two-orders.sql'))
+            .call(async ({ db }) => await listOrders(db.connectionString));
+
+        // Then - the module answered with both, compared whole
+        expect(result.value).toMatch([
+            { id: 1, reference: 'ORD-1', total: 42 },
+            { id: 2, reference: 'ORD-2', total: 108 },
+        ]);
+    });
+});
+```
+
+## What it specifies
+
+An integration spec answers one question: **given these real services, what does this module return, throw, or leave in the database?** Two kinds of subject land here, the two halves of the fork's eighth question:
+
+- **a module on a real service:** a repository against Postgres, a cache client against Redis;
+- **a module whose oracle is a golden:** a renderer, a parser, a formatter whose output is long enough to be read as a file.
+
+A subject that answers HTTP, runs as a binary or draws a screen belongs to that kind instead; a module that needs neither a service nor a golden is a module test ([the fork](../start/getting-started.md#which-kind-of-test)). Why this is a kind of its own: [ADR-004](https://github.com/jterrazz/package-test/blob/main/docs/decisions/004-a-module-against-real-services-or-a-golden-is-the-integration-specification.md).
+
+## The constructor
+
+| Option     | Means                                                                                                                                |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `services` | the named record the module is specified against: `postgres()`, `redis()`, `sqlite()`, `process()`. Omit it for the golden-only half |
+| `root`     | project-root override (rule `no-redundant-root`), auto-discovered from the calling file                                              |
+
+The handle is `{ integration, cleanup }`, destructured with those names (rule `no-runner-alias`) and cleaned up with `afterAll(cleanup)` (rule `cleanup-passed-to-after-all`).
+
+## The chain
+
+Setups: `.seed()`, `.intercept()`, `.clock()`, and `integration.with({ clock })`, a view whose every chain starts at the instant the whole file shares ([Conventions](../concepts/conventions.md#what-a-file-shares)). Terminal action: `.call(subject)` (rule `one-terminal-action-per-chain`).
+
+| Setup                                 | Means                                                                                                   |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `.seed(file('./__seeds__/rows.sql'))` | run that `.sql` file, named from the spec file, before the call; `{ database }` targets one of several  |
+| `.intercept(stubs)`                   | declare what the outside world replies ([Stubs](../reference/stubs.md))                                 |
+| `.clock('2026-03-04T09:30:00Z')`      | pin the module's `Date` for this chain ([Time and doubles](../reference/time-and-doubles.md#the-clock)) |
+
+`.call(subject)` hands the STARTED services record to the subject, so the module is built with the real connection strings rather than with a double:
+
+```typescript
+const result = await integration.call(async ({ db }) => await listOrders(db.connectionString));
+```
+
+Databases reset at the start of every chain, exactly as on api and job (rules `one-terminal-action-per-chain`, `sequence-expressed-by-seeding`): one spec is one call, and no spec depends on a previous one.
+
+## The result
+
+Two readings, never both.
+
+| Accessor         | Is                                                                                                                                           |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `result.value`   | what the call RETURNED: a `TextAccessor` for a string, a `JsonAccessor<T>` for anything else, the union of both for a `T` that may be either |
+| `result.error`   | what it THREW, as text: an `Error`'s message, or the value itself. Empty when it returned                                                    |
+| `result.table()` | a table of a declared database, for row-level assertions                                                                                     |
+
+A refusal is a reading, never a `try`/`catch`:
+
+```typescript
+test('refuses an order that is not one', async () => {
+    // Given - the module asked to record an order worth nothing
+    const result = await integration.call(
+        async ({ db }) => await placeOrder(db.connectionString, { reference: 'ORD-4', total: 0 }),
+    );
+
+    // Then - what it threw is the reading, and nothing was written
+    expect(result.error).toMatch('an order of 0 is not an order: reference ORD-4');
+    await expect(result.table('orders')).toBeEmpty();
+});
+```
+
+That is what keeps a spec of a refusal the same size as a spec of a success, and what stops an "it should throw" spec from passing when nothing throws at all. `expect(result.error.text).toBe('')` is how a chain says "and it did not refuse": `result.error` is empty rather than absent when the call returned, so the empty text is the whole answer.
+
+`.call<T>()` carries `T` through to the result, so one field can be read where one field is what the spec means (`expect(result.value.value.ok).toBe(true)` for JSON, `result.value.text` for a string), beside the comparison of the whole value, never instead of it (rule `result-compared-whole`).
+
+**The accessor follows the value, and the type says so.** A subject typed exactly `string` reads as a `TextAccessor`; one that can never be a string reads as a `JsonAccessor<T>`; one that MAY be a string (`string | undefined`, `string | number`) is typed as the union of the two, and the spec narrows it, because only the value in hand decides, and a type that guessed handed back a `JsonAccessor` whose `.value` was silently `undefined` while the runtime had built a `TextAccessor`.
+
+**What crosses is JSON, not the object.** A non-string value is serialised, so a `Map`, a `Set`, a `Date` or a class instance arrives as the plain JSON it serialises to (`{}`, `{}`, an ISO string, an object of its own fields), while `T` still claims the original type. A call whose answer is one of those projects it to plain data INSIDE the call, where the projection is visible:
+
+```typescript
+// the Map is projected where the spec can see it, not silently at the seam
+const result = await integration.call(async () => Object.fromEntries(await loadIndex()));
+```
+
+Both accessors are the package's ordinary subjects, compared whole: to the value written in place (`toMatch({ ... })` for a json, `toMatch('...')` for a text) or to `file('./__expected__/<name>.json')` when several tests share it; the `{{token}}` grammar for what moves, `{ frozen }`, and `TEST_UPDATE=1`, which writes the value into the test ([Tokens](../reference/tokens.md), [Assertions](../reference/assertions.md)).
+
+A call that a declared stub never accepted fails the CHAIN rather than becoming `result.error`: a refusal the module chose is the subject's behaviour, an undeclared outgoing call is the spec's own mistake (rule `network-strict-after-first-stub`).
+
+## Unique here
+
+### The golden half: a pure module, no services at all
+
+`specification.integration()` with no options is the pure-module runner: nothing starts, and what earns the folder is the golden.
+
+```typescript
+export const { cleanup, integration } = await specification.integration();
+```
+
+A table of cases is one `.call()` inside `test.each`, which is what turns fifty-three hand-paired fixture files into one spec:
+
+```typescript
+test.each(CASES)('renders $name', async ({ name, input }) => {
+    // Given - one case of the table
+    const result = await integration.call(() => render(input));
+
+    // Then - the golden for that case
+    expect(result.value).toMatch(file(`./__expected__/${name}.json`));
+    expect(result.error.text).toBe('');
+});
+```
+
+The golden is named by a template literal, and the checker's `no-unused-ground` dead-fixture pass reads that form: a golden whose name matches the literal's static ends is one the table could have asked for, so a wall of `__expected__/` files stays alive without a hand-written literal each.
+
+### The `integration()` project
+
+The `integration` specification is the canonical project: a `specs/integration/` folder makes it, it collects `specs/integration/**/*.spec.ts`, carries the preset's budgets and artefact directory, and runs in group 0 with the other node specifications. `jterrazz.config.ts` states nothing for it until it departs from that.
+
+An env-gated sub-suite is an option of `test.projects.integration`, not a second project: the whole point of `{ include, exclude, timeout }`:
+
+```typescript
+const integration = {
+    exclude: process.env.E2E_NETWORK ? [] : ['specs/integration/network/**'],
+    reason: 'the network specs reach the internet, which a run turns on with E2E_NETWORK',
+};
+```
+
+### Folder layout
+
+```text
+specs/integration/
+├── integration.specification.ts   # the runner, at the specification root
+├── pure.specification.ts          # a second runner: no services, goldens only
+└── orders/                        # a domain
+    ├── orders.spec.ts             # under specs/, the suffix is .spec.ts (rule `file-suffix-matches-place`)
+    ├── __seeds__/two-orders.sql       # ground: database state, beside its one test, or the tests of the leaf that share it
+    └── __expected__/                  # ground: a golden several tests share; one test's is written in place (`ground-shared-or-inline`)
+```
+
+**`required` is verified per `.call()`.** A chain's scope is ONE terminal action: the stubs it declared are checked when that call ends, and a stub declared `required` that was never requested fails there. A second `.call()` is a second chain with a second verification: it does not inherit the first's obligations.
+
+## Pitfalls
+
+- **Reaching for `try`/`catch`.** A thrown error is `result.error`. A `try` around `.call()` brings back the shape where a spec passes because nothing threw.
+- **Writing a module test here.** A module alone, with no service and no golden, belongs in the `__tests__/` of its folder as `<file>.test.ts` (rule `test-in-its-tests-folder`). The folder is not a home for tests that were hard to place.
+- **Goldening a volatile value.** An id, a timestamp or a duration inside `result.value` is tokened (`{{int}}`, `{{iso8601}}`), or pinned with `.clock()`. A literal that moves is a test that fails tomorrow (rule `no-volatile-literal`).
+- **Asserting on a double.** The specification exists so the subject meets the real thing. A `mockOf<T>()` inside `.call()` is a module test that started a container for nothing.
+
+## Related
+
+[Module tests](module-tests.md) · [Stubs](../reference/stubs.md) · [Services](../reference/services.md) · [Assertions](../reference/assertions.md) · [Tokens](../reference/tokens.md)