@jterrazz/test 15.3.0 → 16.1.0

package/dist/vitest.js

@@ -1,11 +1,12 @@
-import { c as GROUND_EXPECTED } from "./match.js";
-import { a as specDescription, r as VITEST_ARTIFACTS_DIR, t as COVERAGE_DIR } from "./artifacts.js";
+import { i as GROUND_EXPECTED } from "./fixtures.js";
+import { i as SCREENSHOTS_DIR, n as COVERAGE_DIR, o as VITEST_ARTIFACTS_DIR, r as REPORTER_OUTPUT_FILES, t as ATTACHMENTS_DIR } from "./artifacts.js";
+import { n as specDescription } from "./literate.js";
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { configDefaults, mergeConfig } from "vitest/config";
-//#region src/vitest/literate-plugin.ts
+//#region src/runner/literate-plugin.ts
 /**
 * The `literate()` vite plugin — door one of the spec-document format.
 *
@@ -70,7 +71,7 @@ function literate(options) {
 	};
 }
 //#endregion
-//#region src/vitest/preset.ts
+//#region src/runner/preset.ts
 /**
 * `defineSpecConfig()` — the shared vitest config every repository of the
 * ecosystem starts from.
@@ -116,6 +117,27 @@ const HOOK_TIMEOUT_MS = 3e4;
 */
 const EXCLUDE = [...configDefaults.exclude, "**/_fixtures/**"];
 /**
+* What a test may never carry into the next one, and the one policy the
+* framework states rather than lints.
+*
+* `retry: 0` is the policy: a flaky test is fixed or deleted, never re-rolled
+* until it passes. A retry turns a real defect into a slow one and hides the
+* day it becomes permanent.
+*
+* The three restores are the other half of the same idea. `vi.spyOn`,
+* `vi.stubGlobal` and `vi.stubEnv` each own a teardown, and a test that forgets
+* one leaks into whatever runs next — a failure that appears in a FILE that did
+* nothing wrong and disappears when that file is run alone. Turning them on
+* here is what lets `clock.at()` and `vi.stubEnv()` be written without an
+* `afterEach`, which is the shape rule J6w asks for.
+*/
+const HYGIENE = {
+	restoreMocks: true,
+	retry: 0,
+	unstubEnvs: true,
+	unstubGlobals: true
+};
+/**
 * Defaults a vitest PROJECT accepts. `coverage` and `reporters` are root-only
 * options (vitest omits them from a project's config), so they are absent here
 * on purpose — setting them would be silently dropped.
@@ -130,24 +152,122 @@ function projectDefaults() {
 	return {
 		cacheDir: VITEST_ARTIFACTS_DIR,
 		test: {
+			attachmentsDir: ATTACHMENTS_DIR,
 			exclude: EXCLUDE,
 			hookTimeout: HOOK_TIMEOUT_MS,
+			...HYGIENE,
 			testTimeout: TEST_TIMEOUT_MS
 		}
 	};
 }
+/**
+* Coverage, when `--coverage` asks for it.
+*
+* `v8` because it is the runtime's own counter: no instrumentation pass, no
+* second transform of every file, and the numbers do not move when the bundler
+* does. The provider is an OPTIONAL peer (`@vitest/coverage-v8`), so a project
+* that never asks for coverage never installs it.
+*
+* `json-summary` is not a taste: it is the machine-readable report the ratchet
+* reads. `text` is for the human running the command, and `html` for the one
+* chasing a line. All three land under `.artifacts/vitest/coverage/`, the one
+* directory the toolchain's page owns.
+*
+* What is EXCLUDED is the shape of the answer, not a way to raise the number:
+* a type-only module has nothing to execute (v8 reports it as 0/0 or, worse,
+* as uncovered lines that cannot be covered), and the CLI entries are proven
+* by running the binary, not by importing it.
+*/
+const COVERAGE = {
+	exclude: [
+		"**/node_modules/**",
+		"specs/**",
+		"**/_fixtures/**",
+		"**/*.d.ts",
+		"**/*.test-d.ts",
+		"**/*.fixtures.ts",
+		"dist/**",
+		".artifacts/**",
+		"**/*.config.ts",
+		"**/*.config.mts"
+	],
+	provider: "v8",
+	reporter: [
+		"text",
+		"html",
+		"json-summary"
+	],
+	reportsDirectory: COVERAGE_DIR
+};
 /** Defaults for the root config — the project ones, plus what only a root carries. */
 function rootDefaults() {
 	return {
 		cacheDir: VITEST_ARTIFACTS_DIR,
 		test: {
-			coverage: { reportsDirectory: COVERAGE_DIR },
+			attachmentsDir: ATTACHMENTS_DIR,
+			coverage: COVERAGE,
 			exclude: EXCLUDE,
 			hookTimeout: HOOK_TIMEOUT_MS,
+			...HYGIENE,
+			outputFile: REPORTER_OUTPUT_FILES,
 			testTimeout: TEST_TIMEOUT_MS
 		}
 	};
 }
+/** A glob list with its repeats taken out, or nothing where there is no list. */
+function eachOnce(globs) {
+	return globs === void 0 ? void 0 : [...new Set(globs)];
+}
+/**
+* The glob lists vite CONCATENATES rather than overrides, each glob kept once.
+*
+* A project built ON the defaults and then merged INTO them by
+* `defineSpecConfig` carried every default twice. Glob matching is idempotent,
+* so nothing collected differently — but 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.
+*/
+function statedOnce(test) {
+	const exclude = eachOnce(test.exclude);
+	const include = eachOnce(test.include);
+	return {
+		...test,
+		...exclude === void 0 ? {} : { exclude },
+		...include === void 0 ? {} : { include }
+	};
+}
+/**
+* Build a project ON the defaults — the ONE way a project is built here.
+*
+* @internal
+*/
+function onProjectDefaults(stated) {
+	const merged = mergeConfig(projectDefaults(), stated);
+	return merged.test === void 0 ? merged : {
+		...merged,
+		test: statedOnce(merged.test)
+	};
+}
+/**
+* Is every project an inline object — one this preset merged its defaults into?
+* A project named by a glob or handed as a promise carries a config this call
+* never saw, and the root's exclusions are the only ones it gets from here.
+*/
+function allInline(projects) {
+	return projects.every((project) => typeof project === "object" && project !== null && !("then" in project));
+}
+/**
+* The root's exclusions, beside projects that already carry them.
+*
+* With `projects`, the root collects nothing itself: its `exclude` only travels
+* INTO each project, where vitest CONCATENATES it with the project's own — so
+* every preset glob reached the banner twice. The preset's own are dropped
+* here, since each inline project states them in full; what the CONSUMER stated
+* at the root stays, because no project holds a copy of that.
+*/
+function rootExcludeBeside(projects, exclude) {
+	return allInline(projects) ? exclude.filter((glob) => !EXCLUDE.includes(glob)) : exclude;
+}
 /**
 * A project inherits NOTHING from the root `test` block — vitest resolves each
 * project as its own config — so the defaults are merged into every inline one.
@@ -156,24 +276,71 @@ function rootDefaults() {
 */
 function withProjectDefaults(project) {
 	if (typeof project !== "object" || project === null || "then" in project) return project;
-	return mergeConfig(projectDefaults(), project);
+	return onProjectDefaults(project);
 }
 function defineSpecConfig(config = {}) {
 	const { literate: literateOptions, ...userConfig } = config;
 	const stated = literateOptions ? mergeConfig({ plugins: [literate(literateOptions)] }, userConfig) : userConfig;
 	const merged = mergeConfig(rootDefaults(), stated);
-	const projects = merged.test?.projects;
-	if (!projects) return merged;
+	const root = merged.test === void 0 ? void 0 : statedOnce(merged.test);
+	if (root === void 0) return merged;
+	const { projects } = root;
+	if (projects === void 0) return {
+		...merged,
+		test: root
+	};
+	const inline = projects.map(withProjectDefaults);
 	return {
 		...merged,
 		test: {
-			...merged.test,
-			projects: projects.map(withProjectDefaults)
+			...root,
+			...root.exclude === void 0 ? {} : { exclude: rootExcludeBeside(inline, root.exclude) },
+			projects: inline
 		}
 	};
 }
 //#endregion
-//#region src/integrations/vitest-browser/commands.ts
+//#region src/runner/facet-project.ts
+/** The globs a node facet collects, and the ones a caller stated instead. */
+function facetProject(facet, options) {
+	return onProjectDefaults({ test: {
+		...options.exclude === void 0 ? {} : { exclude: options.exclude },
+		include: options.include ?? [`specs/${facet}/**/*.spec.ts`],
+		...options.serial === true ? { fileParallelism: false } : {},
+		name: facet,
+		sequence: { groupOrder: 0 },
+		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+	} });
+}
+//#endregion
+//#region src/facets/api/api.project.ts
+/** `api()` — the app met through HTTP. */
+function api(options = {}) {
+	return facetProject("api", options);
+}
+//#endregion
+//#region src/facets/cli/cli.project.ts
+/** The literate defaults — the path convention `cli()` assumes when nothing says otherwise. */
+const CLI_SPECIFICATION = "./specs/cli/cli.specification.ts";
+const CLI_DOCUMENTS = ["specs/cli/**/*.spec.yaml"];
+/**
+* A cli project collects the facet's `.test.ts` files AND its documents: a
+* `<case>.spec.yaml` is a test file of its own (docs/07 § the literate door),
+* so the plugin's glob has to join the include of the project that collects
+* them — which is this one, never the root config.
+*/
+function cli(options = {}) {
+	const { literate: literateOptions, ...common } = options;
+	const project = facetProject("cli", common);
+	if (literateOptions === false) return project;
+	const documents = literateOptions?.include ?? CLI_DOCUMENTS;
+	return mergeConfig(project, { plugins: [literate({
+		include: documents,
+		specification: literateOptions?.specification ?? CLI_SPECIFICATION
+	})] });
+}
+//#endregion
+//#region src/seams/vitest-browser/commands.ts
 /** Where a golden sits: `_expected/<name>` beside the test that asked for it. */
 function goldenPath(testPath, name) {
 	if (testPath === void 0) throw new Error("golden: the command carries no test path — a golden is read from a test file.");
@@ -205,7 +372,7 @@ const COMPONENT_COMMANDS = {
 	goldenWrite
 };
 //#endregion
-//#region src/vitest/projects.ts
+//#region src/facets/component/component.project.ts
 /** The pipeline keys a consumer's Vite config contributes, and nothing else. */
 const PIPELINE_KEYS = [
 	"assetsInclude",
@@ -459,39 +626,6 @@ function componentGlobs(options) {
 	};
 }
 /**
-* A module test runs beside the module it covers: no DOM, no browser, no
-* pipeline. `.test.tsx` is excluded because a rendered thing is a component
-* test — a project's dependency scan reads every file its globs match, and a
-* `.tsx` collected here would be optimised for a page that never opens.
-*/
-function unit(options = {}) {
-	const fromRoots = options.roots?.map((root) => `${root.replace(/\/+$/u, "")}/**/*.test.ts`);
-	return mergeConfig(projectDefaults(), { test: {
-		exclude: options.exclude ?? ["specs/**", "**/*.test.tsx"],
-		include: options.include ?? fromRoots ?? ["**/*.test.ts"],
-		...options.serial === true ? { fileParallelism: false } : {},
-		name: "unit",
-		sequence: { groupOrder: 0 },
-		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
-	} });
-}
-/**
-* A website spec meets the assembled product through a served page, in the
-* Chromium playwright drives. It opens a browser, so it is scheduled before the
-* component project and never beside it: two Chromiums must not share a slot on
-* a 2-vCPU runner.
-*/
-function website(options = {}) {
-	return mergeConfig(projectDefaults(), { test: {
-		...options.exclude === void 0 ? {} : { exclude: options.exclude },
-		...options.serial === true ? { fileParallelism: false } : {},
-		include: options.include ?? ["specs/website/**/*.test.ts"],
-		name: "website",
-		sequence: { groupOrder: 1 },
-		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
-	} });
-}
-/**
 * A component test renders in a real Chromium — the browser the website facet
 * already drives through the same `playwright` peer.
 *
@@ -505,23 +639,23 @@ async function component(options = {}) {
 	const { playwright } = await import("@vitest/browser-playwright");
 	const pipeline = options.vite === void 0 ? {} : await reroot(options.vite, root);
 	const consumerPlugins = Array.isArray(pipeline.plugins) ? pipeline.plugins : [];
-	const project = {
+	return onProjectDefaults({
 		...pipeline,
 		...jsxPipeline(pipeline),
 		optimizeDeps: { include: SEAM_DEPENDENCIES.filter(resolves) },
 		plugins: [mswWorkerPlugin(), ...consumerPlugins],
 		test: {
-			attachmentsDir: `${VITEST_ARTIFACTS_DIR}/attachments`,
 			browser: {
 				commands: COMPONENT_COMMANDS,
 				enabled: true,
+				expect: { toMatchScreenshot: { screenshotDirectory: SCREENSHOTS_DIR } },
 				headless: true,
 				instances: [{ browser: "chromium" }],
 				provider: playwright({ contextOptions: {
 					locale: options.locale ?? "en-US",
 					timezoneId: options.timezone ?? "UTC"
 				} }),
-				screenshotDirectory: `${VITEST_ARTIFACTS_DIR}/screenshots`,
+				screenshotDirectory: SCREENSHOTS_DIR,
 				viewport: viewportOf(options)
 			},
 			...componentGlobs(options),
@@ -532,42 +666,22 @@ async function component(options = {}) {
 			sequence: { groupOrder: 2 },
 			...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
 		}
-	};
-	return mergeConfig(projectDefaults(), project);
-}
-/**
-* The node facets' canonical projects.
-*
-* Each one collects the facet's own tree, carries the preset's budgets and
-* artefact directory, and runs in group 0 — the browser facets follow, so two
-* Chromiums never share a slot on a two-vCPU runner. `{ include, exclude,
-* timeout, serial }` is what a repository states when its tree, its budget or
-* its parallelism differs;
-* everything else is the framework's.
-*/
-/** The globs a node facet collects, and the ones a caller stated instead. */
-function facetProject(facet, options) {
-	return mergeConfig(projectDefaults(), { test: {
-		...options.exclude === void 0 ? {} : { exclude: options.exclude },
-		include: options.include ?? [`specs/${facet}/**/*.test.ts`],
-		...options.serial === true ? { fileParallelism: false } : {},
-		name: facet,
-		sequence: { groupOrder: 0 },
-		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
-	} });
+	});
 }
-/** `api()` — the app met through HTTP. */
-function api(options = {}) {
-	return facetProject("api", options);
+//#endregion
+//#region src/facets/integration/integration.project.ts
+/** `integration()` — a module against real services, or against a golden. */
+function integration(options = {}) {
+	return facetProject("integration", options);
 }
+//#endregion
+//#region src/facets/jobs/jobs.project.ts
 /** `jobs()` — what a name triggers in-process. */
 function jobs(options = {}) {
 	return facetProject("jobs", options);
 }
-/** `integration()` — a module against real services, or against a golden. */
-function integration(options = {}) {
-	return facetProject("integration", options);
-}
+//#endregion
+//#region src/facets/mobile/mobile.project.ts
 /**
 * `mobile()` — the app on a simulator. A simulator is the one thing that
 * cannot share a machine with itself, so it runs last and alone (group 3).
@@ -575,23 +689,45 @@ function integration(options = {}) {
 function mobile(options = {}) {
 	return mergeConfig(facetProject("mobile", options), { test: { sequence: { groupOrder: 3 } } });
 }
-/** The literate defaults — the path convention `cli()` assumes when nothing says otherwise. */
-const CLI_SPECIFICATION = "./specs/cli/cli.specification.ts";
-const CLI_DOCUMENTS = ["specs/cli/**/*.spec.yaml"];
+//#endregion
+//#region src/facets/website/website.project.ts
 /**
-* A cli project collects the facet's `.test.ts` files AND its documents: a
-* `<case>.spec.yaml` is a test file of its own (docs/07 § the literate door),
-* so the plugin's glob has to join the include of the project that collects
-* them — which is this one, never the root config.
+* A website spec meets the assembled product through a served page, in the
+* Chromium playwright drives. It opens a browser, so it is scheduled before the
+* component project and never beside it: two Chromiums must not share a slot on
+* a 2-vCPU runner.
 */
-function cli(options = {}) {
-	const { literate: literateOptions, ...common } = options;
-	const project = facetProject("cli", common);
-	if (literateOptions === false) return project;
-	return mergeConfig(project, { plugins: [literate({
-		include: literateOptions?.include ?? CLI_DOCUMENTS,
-		specification: literateOptions?.specification ?? CLI_SPECIFICATION
-	})] });
+function website(options = {}) {
+	return onProjectDefaults({ test: {
+		...options.exclude === void 0 ? {} : { exclude: options.exclude },
+		...options.serial === true ? { fileParallelism: false } : {},
+		include: options.include ?? ["specs/website/**/*.spec.ts"],
+		name: "website",
+		sequence: { groupOrder: 1 },
+		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+	} });
+}
+//#endregion
+//#region src/runner/projects.ts
+/**
+* A module test runs beside the module it covers: no DOM, no browser, no
+* pipeline. Its suffix is `.test.ts` and its place is OUTSIDE `specs/`, where
+* the assembled product is specified in `.spec.ts` — the two exclusions say
+* exactly that. `.test.tsx` is the third exclusion because a rendered thing is
+* a component test: a project's dependency scan reads every file its globs
+* match, and a `.tsx` collected here would be optimised for a page that never
+* opens.
+*/
+function unit(options = {}) {
+	const fromRoots = options.roots?.map((root) => `${root.replace(/\/+$/u, "")}/**/*.test.ts`);
+	return onProjectDefaults({ test: {
+		exclude: options.exclude ?? ["specs/**", "**/*.test.tsx"],
+		include: options.include ?? fromRoots ?? ["**/*.test.ts"],
+		...options.serial === true ? { fileParallelism: false } : {},
+		name: "unit",
+		sequence: { groupOrder: 0 },
+		...options.timeout === void 0 ? {} : { testTimeout: options.timeout }
+	} });
 }
 //#endregion
 export { api, cli, component, defineSpecConfig, integration, jobs, literate, mobile, unit, website };

package/docs/01-architecture.md

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