@jterrazz/test 15.2.0 → 15.3.0

package/dist/intercept.js

@@ -1,4 +1,4 @@
-import { t as ContractQueue } from "./queue.js";
+import { a as isStreamBody, n as ContractQueue, t as toReadableStream } from "./stream.js";
 //#region src/integrations/msw/handlers.ts
 /**
 * What a chain with zero contracts gets where the facet's scope is KNOWN but
@@ -31,6 +31,14 @@ function toMswResponse(msw, response) {
 		},
 		status
 	});
+	if (isStreamBody(body)) return new msw.HttpResponse(toReadableStream(body), {
+		headers: {
+			...NEVER_CACHED,
+			"content-type": body.contentType,
+			...headers
+		},
+		status
+	});
 	if (typeof body === "string") return new msw.HttpResponse(body, {
 		headers: {
 			...NEVER_CACHED,

package/dist/oxlint.cjs

@@ -284,7 +284,7 @@ const RULE_DOCS = {
 	},
 	"a2-known-constructors": {
 		channel: "statique",
-		convention: "Cinq constructeurs et seulement cinq : `specification.api()`, `specification.jobs()`, `specification.cli(bin)`, `specification.website()`, `specification.mobile()` ; tout autre membre (`.app`, `.http`, `.stack`…) est une erreur.",
+		convention: "Six constructeurs et seulement six : `specification.api()`, `specification.jobs()`, `specification.cli(bin)`, `specification.integration()`, `specification.website()`, `specification.mobile()` ; tout autre membre (`.app`, `.http`, `.stack`…) est une erreur. Un composant rendu ne démarre rien : c’est une chaîne, pas un membre de ce record.",
 		family: "A",
 		id: "A2",
 		rationale: "Une surface fermée empêche l’invention de constructeurs parallèles et garde l’API mémorisable."
@@ -531,7 +531,7 @@ const RULE_DOCS = {
 	},
 	"f3-specs-public-entry": {
 		channel: "statique",
-		convention: "Depuis `specs/`, seul l’import en profondeur des INTERNES du framework est interdit : un chemin relatif résolvant dans `src/{specification,integrations,vitest,lint}/` du dépôt du framework, ou tout `@jterrazz/test/<subpath>` que la map `exports` du paquet ne publie pas — les subpaths publiés sont exemptés, LUS du manifeste comme en F1, qui en tient la liste. Les imports de la source de SA PROPRE app par un consommateur sont toujours permis (c’est le motif documenté) ; seul `specs/integrations/` peut importer en profondeur `src/integrations/**`.",
+		convention: "Depuis `specs/`, seul l’import en profondeur des INTERNES du framework est interdit : un chemin relatif résolvant dans `src/{specification,integrations,vitest,lint}/` du dépôt du framework, ou tout `@jterrazz/test/<subpath>` que la map `exports` du paquet ne publie pas — les subpaths publiés sont exemptés, LUS du manifeste comme en F1, qui en tient la liste. Les imports de la source de SA PROPRE app par un consommateur sont toujours permis (c’est le motif documenté). Aucune exception de dossier : une sonde qui ne peut pas atteindre son sujet par l’entrée publique est un test de module à côté de son module, pas une spec.",
 		family: "F",
 		id: "F3",
 		rationale: "Tester par la surface publique garde les specs découplées des chemins internes du framework, sans gêner le consommateur qui importe sa propre app."
@@ -623,6 +623,39 @@ const RULE_DOCS = {
 * visits data fixtures nor reads two files at once, so these ship separately.
 */
 const CHECKER_PASSES = [
+	{
+		channel: "checker",
+		convention: "Chaque membre du workspace qui a des tests À LUI (un script `test` qui ne délègue pas aux membres, ou un `*.test.ts(x)` hors de l’arbre d’un autre paquet) déclare une config vitest (`vitest.config.*`). La passe MEMBRE juge le membre lui-même, avec ou sans arbre `specs/` ; une racine qui ne fait que déléguer ne doit rien.",
+		facet: "shared",
+		family: "E",
+		fix: "Écrire `export default defineSpecConfig()` dans le membre — le préréglage porte les budgets, le dossier d’artefacts et l’exclusion de `_fixtures/`.",
+		id: "E3",
+		name: "e3-config-present",
+		rationale: "Sans config, le budget de 5 s de vitest et un `_fixtures/` non exclu font tourner les tests du membre : le défaut n’est pas choisi, il est hérité.",
+		reach: "config"
+	},
+	{
+		channel: "checker",
+		convention: "La passe MEMBRE relit la règle E5b là où oxlint peut ne pas atteindre la config d’un membre : `environment: 'happy-dom'|'jsdom'` dans un `vitest.config.*` est une erreur.",
+		facet: "component",
+		family: "E",
+		fix: "Supprimer `environment` et collecter le rendu avec `component()`.",
+		id: "E5b",
+		name: "e5b-no-simulated-dom-config-member",
+		rationale: "La passe statique ne voit que ce que la configuration oxlint du dépôt lui donne ; la passe membre part du manifeste racine et atteint chaque membre déclaré.",
+		reach: "config"
+	},
+	{
+		channel: "checker",
+		convention: "Un membre ne déclare aucune dépendance que `@jterrazz/test` porte déjà (`msw`, `vitest-mock-extended` ; `yaml` en devDependencies seulement — en dépendance de production c’est la bibliothèque du produit) ni aucun seam retiré (`happy-dom`, `jsdom`, `@testing-library/*`, `@playwright/test`, `mockdate`). Les peers optionnels — `playwright`, `vite`, `react`, `better-sqlite3`, `pg`, `redis`, `testcontainers`… — sont déclarés par le consommateur, à dessein.",
+		facet: "shared",
+		family: "F",
+		fix: "Retirer la déclaration : une transitive est déjà résolue par le paquet ; un seam retiré a une facette qui le remplace (`component()`, `website()`, `clock`, `intercept()`). Les deux cas ont leur propre phrase dans le diagnostic.",
+		id: "F8",
+		name: "f8-no-seam-dependency",
+		rationale: "Une déclaration en double laisse deux versions d’un même seam coexister, et un seam retiré garde un vocabulaire que le framework a remplacé.",
+		reach: "config"
+	},
 	{
 		channel: "checker",
 		convention: "Tout `{{token}}` dans une fixture `_expected/` — ou dans un flux attendu d’un document `<cas>.spec.yaml` — appartient au vocabulaire figé ; un token inconnu est une erreur.",
@@ -1023,19 +1056,22 @@ const a1SpecificationFile = {
 };
 //#endregion
 //#region src/lint/rules/a2-known-constructors.ts
-/** The five constructors, and only five (A2 — see docs/13-linting.md). */
+/** The six constructors, and only six (A2 — see docs/13-linting.md). */
 const KNOWN_CONSTRUCTORS = /* @__PURE__ */ new Set([
 	"api",
 	"cli",
+	"integration",
 	"jobs",
 	"mobile",
 	"website"
 ]);
 /**
 * CONVENTIONS A2 — `specification.api()`, `specification.jobs()`,
-* `specification.cli()`, `specification.website()` and
-* `specification.mobile()` are the only members. Any other access
-* (`specification.app`, `.http`, `.stack`, …) is flagged at the member site.
+* `specification.cli()`, `specification.integration()`,
+* `specification.website()` and `specification.mobile()` are the only
+* members. Any other access (`specification.app`, `.http`, `.stack`, …) is
+* flagged at the member site. A rendered component has no constructor: it
+* starts nothing, so it is a chain, not a member of this record.
 */
 const a2KnownConstructors = {
 	create(context) {
@@ -1052,7 +1088,7 @@ const a2KnownConstructors = {
 	},
 	meta: {
 		docs: RULE_DOCS["a2-known-constructors"],
-		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs(), specification.cli(), specification.website() and specification.mobile() (A2 — see docs/13-linting.md)." },
+		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs(), specification.cli(), specification.integration(), specification.website() and specification.mobile() (A2 — see docs/13-linting.md)." },
 		type: "problem"
 	}
 };
@@ -3262,16 +3298,14 @@ const FRAMEWORK_LAYERS = /* @__PURE__ */ new Set([
 *
 * Distinct from F1 (which judges the same specifiers from any file): F3 is the
 * specs-specific guard that also reaches relative framework-internal paths.
-* Documented exception: specs under `specs/integrations/` may deep-import the
-* integration module they cover (`src/integrations/**`).
+* There is no folder exception: a probe that cannot reach its subject through
+* the public entry is a module test beside its module, not a spec.
 */
 const f3SpecsPublicEntry = {
 	create(context) {
-		const anchor = specsAnchor(context.filename);
-		if (anchor === void 0) return {};
+		if (specsAnchor(context.filename) === void 0) return {};
 		const published = new Set(declaredSubpaths());
 		const exempt = published.size === 0 ? "none" : [...published].join(", ");
-		const underIntegrations = anchor.relative[0] === "integrations";
 		return { ...importSourceVisitor(({ node, source }) => {
 			if (source.startsWith(`${PACKAGE}/`)) {
 				if (published.has(source)) return;
@@ -3289,7 +3323,6 @@ const f3SpecsPublicEntry = {
 			if (marker === -1 && !source.startsWith("src/")) return;
 			const layer = (marker === -1 ? source.slice(4) : source.slice(marker + 5)).split("/")[0] ?? "";
 			if (!FRAMEWORK_LAYERS.has(layer)) return;
-			if (underIntegrations && layer === "integrations") return;
 			context.report({
 				data: {
 					published: exempt,
@@ -3302,7 +3335,7 @@ const f3SpecsPublicEntry = {
 	},
 	meta: {
 		docs: RULE_DOCS["f3-specs-public-entry"],
-		messages: { deepImport: "specs/ must not deep-import framework internals — reach the framework via its public entry (@jterrazz/test, or src/index.js in this repo), not \"{{source}}\" (F3 — see docs/13-linting.md). Exempt: the published subpaths {{published}}, and src/integrations/** from specs/integrations/." },
+		messages: { deepImport: "specs/ must not deep-import framework internals — reach the framework via its public entry (@jterrazz/test, or src/index.js in this repo), not \"{{source}}\" (F3 — see docs/13-linting.md). Exempt: the published subpaths {{published}}. A probe whose subject is not on the public entry is a module test beside its module." },
 		type: "problem"
 	}
 };

package/dist/oxlint.d.cts

@@ -7129,7 +7129,7 @@ type RuleDoc = {
    * The specification facet the rule guards — segments the catalogue like
    * the constructors segment the API. `'shared'` for cross-facet rules.
    */
-  facet?: 'api' | 'cli' | 'component' | 'jobs' | 'mobile' | 'shared' | 'website';
+  facet?: 'api' | 'cli' | 'component' | 'integration' | 'jobs' | 'mobile' | 'shared' | 'website';
   /** Convention family letter, e.g. `'A'`. */
   family: string;
   /** Convention code, e.g. `'A1'`. */

package/dist/oxlint.d.ts

@@ -7129,7 +7129,7 @@ type RuleDoc = {
    * The specification facet the rule guards — segments the catalogue like
    * the constructors segment the API. `'shared'` for cross-facet rules.
    */
-  facet?: 'api' | 'cli' | 'component' | 'jobs' | 'mobile' | 'shared' | 'website';
+  facet?: 'api' | 'cli' | 'component' | 'integration' | 'jobs' | 'mobile' | 'shared' | 'website';
   /** Convention family letter, e.g. `'A'`. */
   family: string;
   /** Convention code, e.g. `'A1'`. */

package/dist/oxlint.js

@@ -280,7 +280,7 @@ const RULE_DOCS = {
 	},
 	"a2-known-constructors": {
 		channel: "statique",
-		convention: "Cinq constructeurs et seulement cinq : `specification.api()`, `specification.jobs()`, `specification.cli(bin)`, `specification.website()`, `specification.mobile()` ; tout autre membre (`.app`, `.http`, `.stack`…) est une erreur.",
+		convention: "Six constructeurs et seulement six : `specification.api()`, `specification.jobs()`, `specification.cli(bin)`, `specification.integration()`, `specification.website()`, `specification.mobile()` ; tout autre membre (`.app`, `.http`, `.stack`…) est une erreur. Un composant rendu ne démarre rien : c’est une chaîne, pas un membre de ce record.",
 		family: "A",
 		id: "A2",
 		rationale: "Une surface fermée empêche l’invention de constructeurs parallèles et garde l’API mémorisable."
@@ -527,7 +527,7 @@ const RULE_DOCS = {
 	},
 	"f3-specs-public-entry": {
 		channel: "statique",
-		convention: "Depuis `specs/`, seul l’import en profondeur des INTERNES du framework est interdit : un chemin relatif résolvant dans `src/{specification,integrations,vitest,lint}/` du dépôt du framework, ou tout `@jterrazz/test/<subpath>` que la map `exports` du paquet ne publie pas — les subpaths publiés sont exemptés, LUS du manifeste comme en F1, qui en tient la liste. Les imports de la source de SA PROPRE app par un consommateur sont toujours permis (c’est le motif documenté) ; seul `specs/integrations/` peut importer en profondeur `src/integrations/**`.",
+		convention: "Depuis `specs/`, seul l’import en profondeur des INTERNES du framework est interdit : un chemin relatif résolvant dans `src/{specification,integrations,vitest,lint}/` du dépôt du framework, ou tout `@jterrazz/test/<subpath>` que la map `exports` du paquet ne publie pas — les subpaths publiés sont exemptés, LUS du manifeste comme en F1, qui en tient la liste. Les imports de la source de SA PROPRE app par un consommateur sont toujours permis (c’est le motif documenté). Aucune exception de dossier : une sonde qui ne peut pas atteindre son sujet par l’entrée publique est un test de module à côté de son module, pas une spec.",
 		family: "F",
 		id: "F3",
 		rationale: "Tester par la surface publique garde les specs découplées des chemins internes du framework, sans gêner le consommateur qui importe sa propre app."
@@ -619,6 +619,39 @@ const RULE_DOCS = {
 * visits data fixtures nor reads two files at once, so these ship separately.
 */
 const CHECKER_PASSES = [
+	{
+		channel: "checker",
+		convention: "Chaque membre du workspace qui a des tests À LUI (un script `test` qui ne délègue pas aux membres, ou un `*.test.ts(x)` hors de l’arbre d’un autre paquet) déclare une config vitest (`vitest.config.*`). La passe MEMBRE juge le membre lui-même, avec ou sans arbre `specs/` ; une racine qui ne fait que déléguer ne doit rien.",
+		facet: "shared",
+		family: "E",
+		fix: "Écrire `export default defineSpecConfig()` dans le membre — le préréglage porte les budgets, le dossier d’artefacts et l’exclusion de `_fixtures/`.",
+		id: "E3",
+		name: "e3-config-present",
+		rationale: "Sans config, le budget de 5 s de vitest et un `_fixtures/` non exclu font tourner les tests du membre : le défaut n’est pas choisi, il est hérité.",
+		reach: "config"
+	},
+	{
+		channel: "checker",
+		convention: "La passe MEMBRE relit la règle E5b là où oxlint peut ne pas atteindre la config d’un membre : `environment: 'happy-dom'|'jsdom'` dans un `vitest.config.*` est une erreur.",
+		facet: "component",
+		family: "E",
+		fix: "Supprimer `environment` et collecter le rendu avec `component()`.",
+		id: "E5b",
+		name: "e5b-no-simulated-dom-config-member",
+		rationale: "La passe statique ne voit que ce que la configuration oxlint du dépôt lui donne ; la passe membre part du manifeste racine et atteint chaque membre déclaré.",
+		reach: "config"
+	},
+	{
+		channel: "checker",
+		convention: "Un membre ne déclare aucune dépendance que `@jterrazz/test` porte déjà (`msw`, `vitest-mock-extended` ; `yaml` en devDependencies seulement — en dépendance de production c’est la bibliothèque du produit) ni aucun seam retiré (`happy-dom`, `jsdom`, `@testing-library/*`, `@playwright/test`, `mockdate`). Les peers optionnels — `playwright`, `vite`, `react`, `better-sqlite3`, `pg`, `redis`, `testcontainers`… — sont déclarés par le consommateur, à dessein.",
+		facet: "shared",
+		family: "F",
+		fix: "Retirer la déclaration : une transitive est déjà résolue par le paquet ; un seam retiré a une facette qui le remplace (`component()`, `website()`, `clock`, `intercept()`). Les deux cas ont leur propre phrase dans le diagnostic.",
+		id: "F8",
+		name: "f8-no-seam-dependency",
+		rationale: "Une déclaration en double laisse deux versions d’un même seam coexister, et un seam retiré garde un vocabulaire que le framework a remplacé.",
+		reach: "config"
+	},
 	{
 		channel: "checker",
 		convention: "Tout `{{token}}` dans une fixture `_expected/` — ou dans un flux attendu d’un document `<cas>.spec.yaml` — appartient au vocabulaire figé ; un token inconnu est une erreur.",
@@ -1019,19 +1052,22 @@ const a1SpecificationFile = {
 };
 //#endregion
 //#region src/lint/rules/a2-known-constructors.ts
-/** The five constructors, and only five (A2 — see docs/13-linting.md). */
+/** The six constructors, and only six (A2 — see docs/13-linting.md). */
 const KNOWN_CONSTRUCTORS = /* @__PURE__ */ new Set([
 	"api",
 	"cli",
+	"integration",
 	"jobs",
 	"mobile",
 	"website"
 ]);
 /**
 * CONVENTIONS A2 — `specification.api()`, `specification.jobs()`,
-* `specification.cli()`, `specification.website()` and
-* `specification.mobile()` are the only members. Any other access
-* (`specification.app`, `.http`, `.stack`, …) is flagged at the member site.
+* `specification.cli()`, `specification.integration()`,
+* `specification.website()` and `specification.mobile()` are the only
+* members. Any other access (`specification.app`, `.http`, `.stack`, …) is
+* flagged at the member site. A rendered component has no constructor: it
+* starts nothing, so it is a chain, not a member of this record.
 */
 const a2KnownConstructors = {
 	create(context) {
@@ -1048,7 +1084,7 @@ const a2KnownConstructors = {
 	},
 	meta: {
 		docs: RULE_DOCS["a2-known-constructors"],
-		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs(), specification.cli(), specification.website() and specification.mobile() (A2 — see docs/13-linting.md)." },
+		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs(), specification.cli(), specification.integration(), specification.website() and specification.mobile() (A2 — see docs/13-linting.md)." },
 		type: "problem"
 	}
 };
@@ -3258,16 +3294,14 @@ const FRAMEWORK_LAYERS = /* @__PURE__ */ new Set([
 *
 * Distinct from F1 (which judges the same specifiers from any file): F3 is the
 * specs-specific guard that also reaches relative framework-internal paths.
-* Documented exception: specs under `specs/integrations/` may deep-import the
-* integration module they cover (`src/integrations/**`).
+* There is no folder exception: a probe that cannot reach its subject through
+* the public entry is a module test beside its module, not a spec.
 */
 const f3SpecsPublicEntry = {
 	create(context) {
-		const anchor = specsAnchor(context.filename);
-		if (anchor === void 0) return {};
+		if (specsAnchor(context.filename) === void 0) return {};
 		const published = new Set(declaredSubpaths());
 		const exempt = published.size === 0 ? "none" : [...published].join(", ");
-		const underIntegrations = anchor.relative[0] === "integrations";
 		return { ...importSourceVisitor(({ node, source }) => {
 			if (source.startsWith(`${PACKAGE}/`)) {
 				if (published.has(source)) return;
@@ -3285,7 +3319,6 @@ const f3SpecsPublicEntry = {
 			if (marker === -1 && !source.startsWith("src/")) return;
 			const layer = (marker === -1 ? source.slice(4) : source.slice(marker + 5)).split("/")[0] ?? "";
 			if (!FRAMEWORK_LAYERS.has(layer)) return;
-			if (underIntegrations && layer === "integrations") return;
 			context.report({
 				data: {
 					published: exempt,
@@ -3298,7 +3331,7 @@ const f3SpecsPublicEntry = {
 	},
 	meta: {
 		docs: RULE_DOCS["f3-specs-public-entry"],
-		messages: { deepImport: "specs/ must not deep-import framework internals — reach the framework via its public entry (@jterrazz/test, or src/index.js in this repo), not \"{{source}}\" (F3 — see docs/13-linting.md). Exempt: the published subpaths {{published}}, and src/integrations/** from specs/integrations/." },
+		messages: { deepImport: "specs/ must not deep-import framework internals — reach the framework via its public entry (@jterrazz/test, or src/index.js in this repo), not \"{{source}}\" (F3 — see docs/13-linting.md). Exempt: the published subpaths {{published}}. A probe whose subject is not on the public entry is a module test beside its module." },
 		type: "problem"
 	}
 };

package/dist/playwright.adapter.js

@@ -222,6 +222,7 @@ var PlaywrightAdapter = class {
 		}
 		try {
 			const page = await context.newPage();
+			if (options.clock !== void 0) await page.clock.setFixedTime(new Date(options.clock));
 			const consoleMessages = [];
 			page.on("console", (message) => {
 				consoleMessages.push({

package/dist/{queue.js → stream.js}

@@ -86,6 +86,35 @@ function contractsOf(input) {
 	return flatten([input]);
 }
 //#endregion
+//#region src/specification/contracts/types.ts
+/**
+* The marker that tells a STREAMED body from a value that happens to be an
+* object. A body reaches three different engines (msw's server, msw's worker,
+* the `node:http` stub) and each of them serialises "an object" as JSON, so a
+* stream declared as a plain value arrives as `{}`. The tag is what each
+* engine recognises before it reaches for `JSON.stringify`.
+*/
+const STREAM_BODY = "@jterrazz/test:stream";
+/** Is this body a declared stream rather than a value to serialise? */
+function isStreamBody(body) {
+	return typeof body === "object" && body !== null && "kind" in body && body.kind === "@jterrazz/test:stream";
+}
+//#endregion
+//#region src/specification/timing/pause.ts
+/**
+* One answer to "wait" — the only `setTimeout` the model owns.
+*
+* Two things in the framework genuinely have to wait: the spacing between the
+* pieces of a declared stream, and the poll behind `waitUntil`. Everything
+* else that waits is a spec doing it by hand, which is what J2 refuses. Stated
+* once so there is one place to look when time stops behaving.
+*/
+async function pause(ms) {
+	await new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+//#endregion
 //#region src/specification/contracts/queue.ts
 /**
 * The ONE contract queue — pure, engine-agnostic (no MSW, no node:http).
@@ -259,4 +288,34 @@ var ContractQueue = class {
 	}
 };
 //#endregion
-export { isContract as a, defineContracts as i, contractsOf as n, isContracts as o, defineContract as r, ContractQueue as t };
+//#region src/specification/contracts/stream.ts
+/**
+* A declared stream, made real — ONE serialisation for all three engines.
+*
+* msw's server and msw's worker take a `ReadableStream` body verbatim
+* (https://mswjs.io/docs/http/mocking-responses/streaming) and the `node:http`
+* stub pipes one into its response, so what "arriving in pieces" MEANS —
+* the order, the spacing, the close after the last chunk — is stated here and
+* nowhere else. A second copy of it would be a second answer to "what does the
+* subject read", and the facets would drift.
+*/
+/**
+* The pieces of `body`, in order, `delayBetweenChunks` milliseconds apart,
+* closing after the last one.
+*/
+function toReadableStream(body) {
+	const encoder = new TextEncoder();
+	let index = 0;
+	return new ReadableStream({ async pull(controller) {
+		const chunk = body.chunks[index];
+		if (chunk === void 0) {
+			controller.close();
+			return;
+		}
+		if (body.delayBetweenChunks > 0 && index > 0) await pause(body.delayBetweenChunks);
+		index += 1;
+		controller.enqueue(encoder.encode(chunk));
+	} });
+}
+//#endregion
+export { isStreamBody as a, defineContracts as c, STREAM_BODY as i, isContract as l, ContractQueue as n, contractsOf as o, pause as r, defineContract as s, toReadableStream as t, isContracts as u };

package/dist/vitest.d.ts

@@ -71,11 +71,13 @@ declare function defineSpecConfig(config?: SpecConfig): ViteUserConfig;
  * states only what is theirs.
  */
 /** What every helper accepts on top of its canonical project. */
-type CommonOptions = {
+type FacetProjectOptions = {
   /**
-   * Replace the canonical `exclude` globs. A helper whose canonical
-   * `exclude` only guards its canonical `include` drops it when you state
-   * `include` alone, so state both or neither.
+   * Globs this project stays out of. On a facet helper they ADD to the
+   * preset's (`_fixtures/` and vitest's own), because vite concatenates. On
+   * `unit()` and `component()`, whose canonical `exclude` exists only to
+   * guard their canonical `include`, stating one replaces it — so state
+   * both or neither there.
    */
   exclude?: string[];
   /** Replace the canonical `include` globs. */
@@ -90,7 +92,7 @@ type CommonOptions = {
   timeout?: number;
 };
 /** `unit()` — module tests, beside the modules they cover (CONVENTIONS I2). */
-type UnitProjectOptions = CommonOptions & {
+type UnitProjectOptions = FacetProjectOptions & {
   /**
    * The trees module tests live in, when they do not live in `src/`. Each
    * root becomes `<root>/**\/*.test.ts`; `include` states the globs outright.
@@ -98,7 +100,7 @@ type UnitProjectOptions = CommonOptions & {
   roots?: string[];
 };
 /** `website()` — the assembled product, met through a served page. */
-type WebsiteProjectOptions = CommonOptions;
+type WebsiteProjectOptions = FacetProjectOptions;
 /** `component()` — rendered units, beside the components they cover. */
 type ComponentProjectOptions = {
   /** Freeze the page's `Date` for every render of the project. */
@@ -130,7 +132,7 @@ type ComponentProjectOptions = {
    * provider). A router belongs on the chain instead: it is a test's Given.
    */
   wrap?: string;
-} & CommonOptions;
+} & FacetProjectOptions;
 /**
  * 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
@@ -154,5 +156,33 @@ declare function website(options?: WebsiteProjectOptions): TestProjectInlineConf
  * your own `include` and the exclusion is yours to state too.
  */
 declare function component(options?: ComponentProjectOptions): Promise<TestProjectInlineConfiguration>;
+/** `api()` — the app met through HTTP. */
+declare function api(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+/** `jobs()` — what a name triggers in-process. */
+declare function jobs(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+/** `integration()` — a module against real services, or against a golden. */
+declare function integration(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+/**
+ * `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).
+ */
+declare function mobile(options?: FacetProjectOptions): TestProjectInlineConfiguration;
+/** `cli()` — a binary, and the documents that specify it. */
+type CliProjectOptions = FacetProjectOptions & {
+  /**
+   * The literate door, wired by default: every `specs/cli/**\/*.spec.yaml`
+   * becomes a test file bound to `specs/cli/cli.specification.ts`. State
+   * `specification` to name another runner, `include` to narrow the glob, or
+   * `false` to collect no documents at all.
+   */
+  literate?: false | Partial<LiterateOptions>;
+};
+/**
+ * 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.
+ */
+declare function cli(options?: CliProjectOptions): TestProjectInlineConfiguration;
 //#endregion
-export { type ComponentProjectOptions, type LiterateOptions, type LiteratePlugin, type SpecConfig, type UnitProjectOptions, type WebsiteProjectOptions, component, defineSpecConfig, literate, unit, website };
+export { type CliProjectOptions, type ComponentProjectOptions, type FacetProjectOptions, type LiterateOptions, type LiteratePlugin, type SpecConfig, type UnitProjectOptions, type WebsiteProjectOptions, api, cli, component, defineSpecConfig, integration, jobs, literate, mobile, unit, website };

package/dist/vitest.js

@@ -535,5 +535,63 @@ async function component(options = {}) {
 	};
 	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);
+}
+/** `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);
+}
+/**
+* `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).
+*/
+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"];
+/**
+* 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;
+	return mergeConfig(project, { plugins: [literate({
+		include: literateOptions?.include ?? CLI_DOCUMENTS,
+		specification: literateOptions?.specification ?? CLI_SPECIFICATION
+	})] });
+}
 //#endregion
-export { component, defineSpecConfig, literate, unit, website };
+export { api, cli, component, defineSpecConfig, integration, jobs, literate, mobile, unit, website };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/test",
-    "version": "15.2.0",
+    "version": "15.3.0",
     "description": "Declarative testing framework for HTTP APIs, CLIs, background jobs, websites, mobile apps and rendered components — one entry point, real infrastructure and a real browser, golden-file assertions, plus an oxlint convention plugin.",
     "keywords": [
         "api-testing",