@jterrazz/test 14.3.0 → 15.1.0

package/README.md

@@ -87,7 +87,7 @@ runs:
           Error: no my-cli.yaml in the current directory
 ```
 
-Same engine as the chain, same `{{token}}` grammar, same `TEST_UPDATE=1` — which rewrites each run's exit code and streams, and nothing else. A JSON Schema ships at `@jterrazz/test/schema` so an editor validates as you type. Full grammar: [docs/04-cli.md](docs/04-cli.md#spec-documents--casespecyaml).
+Same engine as the chain, same `{{token}}` grammar, same `TEST_UPDATE=1` — which rewrites each run's exit code and streams, and nothing else. A JSON Schema ships at `@jterrazz/test/schema` so an editor validates as you type. Full grammar: [docs/07-cli.md](docs/07-cli.md#spec-documents--casespecyaml).
 
 ### Website testing (browser)
 
@@ -210,7 +210,7 @@ A `JobHandle` is `{ name: string; execute: () => Promise<void> }`.
 
 ### `specification.cli(bin, { root?, services?, docker?, transform?, env?, serve? })`
 
-Runs a command binary against fixture projects in fresh temp directories. `env` (named environment sets) and `serve` (named servers) are the registries a [`<case>.spec.yaml`](docs/04-cli.md#spec-documents--casespecyaml) names by word. With `services`, connection URLs are injected into the child env automatically: `<KEY>_URL` per record key (CONSTANT_CASE at camelCase boundaries — `analyticsDb` → `ANALYTICS_DB_URL`), plus `DATABASE_URL` (exactly one SQL database) and `REDIS_URL` (exactly one redis). `.env()` overrides; `null` unsets.
+Runs a command binary against fixture projects in fresh temp directories. `env` (named environment sets) and `serve` (named servers) are the registries a [`<case>.spec.yaml`](docs/07-cli.md#spec-documents--casespecyaml) names by word. With `services`, connection URLs are injected into the child env automatically: `<KEY>_URL` per record key (CONSTANT_CASE at camelCase boundaries — `analyticsDb` → `ANALYTICS_DB_URL`), plus `DATABASE_URL` (exactly one SQL database) and `REDIS_URL` (exactly one redis). `.env()` overrides; `null` unsets.
 
 ```typescript
 export const { cli, cleanup } = await specification.cli('my-migrate-tool', {
@@ -239,7 +239,7 @@ const page = await website.visit('/', async (visitor) => {
 });
 ```
 
-The handle destructures to `{ website, cleanup, url }` — no `docker`, no `orchestrator`. `.visit()` needs playwright (`npm install -D playwright && npx playwright install chromium`) — an optional peer dependency, only loaded when a spec actually renders a page. Full reference: [docs/11-website.md](docs/11-website.md).
+The handle destructures to `{ website, cleanup, url }` — no `docker`, no `orchestrator`. `.visit()` needs playwright (`npm install -D playwright && npx playwright install chromium`) — an optional peer dependency, only loaded when a spec actually renders a page. Full reference: [docs/14-website.md](docs/14-website.md).
 
 ### `specification.mobile({ app, device, backend?, root? })`
 
@@ -258,7 +258,7 @@ const result = await mobile.open('news://events', async (visitor) => {
 });
 ```
 
-The handle destructures to `{ mobile, cleanup, udid }` (plus `backendUrl` with `backend: { port? }` — a declared stub backend whose URL the CALLER wires into its own bundler env; the framework never touches Metro). The element vocabulary is the website facet's, unchanged — `button`, `field`, `content`, `testId`, `within` — landmarks excepted (an iOS screen has no ARIA regions; they refuse at runtime). Requires the app installed on the simulator plus the optional peers: `npm install -D appium webdriverio && npx appium driver install xcuitest`. Full reference: [docs/12-mobile.md](docs/12-mobile.md).
+The handle destructures to `{ mobile, cleanup, udid }` (plus `backendUrl` with `backend: { port? }` — a declared stub backend whose URL the CALLER wires into its own bundler env; the framework never touches Metro). The element vocabulary is the website facet's, unchanged — `button`, `field`, `content`, `testId`, `within` — landmarks excepted (an iOS screen has no ARIA regions; they refuse at runtime). Requires the app installed on the simulator plus the optional peers: `npm install -D appium webdriverio && npx appium driver install xcuitest`. Full reference: [docs/15-mobile.md](docs/15-mobile.md).
 
 ### Root auto-discovery
 
@@ -284,7 +284,7 @@ export default defineSpecConfig({
 | `test.testTimeout` / `hookTimeout` | `30_000`                                               |
 | `test.exclude`                     | vitest's defaults **+** `**/_fixtures/**`              |
 
-Nothing else: `fileParallelism`, `reporters`, `environment` and every `include` stay yours. Inline `projects` inherit the same defaults (vitest gives a project nothing from the root), arrays are concatenated rather than replaced, and scalars you state win. Full walkthrough, including migrating a hand-rolled config: [docs/01-getting-started.md](docs/01-getting-started.md#vitest-config-the-preset).
+Nothing else: `fileParallelism`, `reporters`, `environment` and every `include` stay yours. Inline `projects` inherit the same defaults (vitest gives a project nothing from the root), arrays are concatenated rather than replaced, and scalars you state win. Full walkthrough, including migrating a hand-rolled config: [docs/02-developing.md](docs/02-developing.md#vitest-config-the-preset).
 
 Every artefact a run produces lands under `.artifacts/<tool>/` — one `.gitignore` line, one `rm -rf`. Per-run scratch (a CLI spec's temp cwd, a browser profile) stays in the OS temp dir.
 
@@ -296,7 +296,7 @@ Every artefact a run produces lands under `.artifacts/<tool>/` — one `.gitigno
 | --------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------- |
 | `.seed("file.sql", { database? })`      | all          | Load SQL from `_seeds/` — `database` is the record key (mandatory with ≥ 2 databases, forbidden with 1)     |
 | `.fixture("file")`                      | cli          | Copy the feature-local `_fixtures/file` into the working directory                                          |
-| `.fixture("$FIXTURES/name/")`           | cli          | Spread the shared `specs/_fixtures/name/` project into the cwd (trailing `/` = contents; layers)            |
+| `.fixture("$FIXTURES/name/")`           | cli          | Spread the shared `specs/_fixtures/<name>/` project into the cwd (trailing `/` = contents; layers)          |
 | `.env({ KEY: "value" })`                | cli          | Set env vars on the child (`null` unsets, `$WORKDIR` expands, calls merge)                                  |
 | `.headers({ "Accept-Language": "fr" })` | api, website | Set HTTP request headers (merge on top of `.http` file headers, or on the browser context)                  |
 | `.intercept(contracts)`                 | all but cli  | Declare the world: a `defineContracts(...)` composite — MSW on api/jobs, the stub backend on website/mobile |
@@ -378,7 +378,7 @@ Location: /orders/{{uuid#order}}
 }
 ```
 
-See [docs/06-tokens.md](docs/06-tokens.md) for the canonical accepted form of every token.
+See [docs/09-tokens.md](docs/09-tokens.md) for the canonical accepted form of every token.
 
 ## Contracts
 
@@ -413,7 +413,7 @@ export const withRatesDown = () =>
 const result = await jobs.intercept(pipeline).trigger('nightly-report');
 ```
 
-Selection is first-match, one queue for every facet: `times` bounds how often a contract serves (omitted = unlimited, so retries and re-renders replay it), `required: true` fails the chain if it was never requested. Provider string filters are **exact** — the loose forms are explicit (`RegExp`, `match.includes('…')`). Failure simulation: `openai.error(429)`, `anthropic.timeout()`, `openai.malformed('not json')`. MSW ships as a direct dependency — no separate install. Full chapter: [docs/07-contracts.md](docs/07-contracts.md).
+Selection is first-match, one queue for every facet: `times` bounds how often a contract serves (omitted = unlimited, so retries and re-renders replay it), `required: true` fails the chain if it was never requested. Provider string filters are **exact** — the loose forms are explicit (`RegExp`, `match.includes('…')`). Failure simulation: `openai.error(429)`, `anthropic.timeout()`, `openai.malformed('not json')`. MSW ships as a direct dependency — no separate install. Full chapter: [docs/10-contracts.md](docs/10-contracts.md).
 
 ## Docker-aware CLIs
 
@@ -442,7 +442,7 @@ test('deploy spawns a labelled container', async () => {
 
 `docker/compose.test.yaml` is the single source of truth for test infrastructure; `docker/<service>/init.sql` runs when the corresponding service starts. Parallel isolation is automatic per vitest worker: postgres clones a schema, redis assigns a database index, sqlite copies the template file, compose mode gets a dedicated project.
 
-`sqlite()` caches its schema template inside the project — `.artifacts/vitest/sqlite/template-<key>.sqlite` — so two checkouts never share one, and workers racing for a cold cache wait for the one that is building rather than all building at once. Details: [docs/08-services.md](docs/08-services.md#where-the-template-lives).
+`sqlite()` caches its schema template inside the project — `.artifacts/vitest/sqlite/template-<key>.sqlite` — so two checkouts never share one, and workers racing for a cold cache wait for the one that is building rather than all building at once. Details: [docs/11-services.md](docs/11-services.md#where-the-template-lives).
 
 ## Mocking utilities
 
@@ -457,7 +457,7 @@ import { mockOf, mockOfDate } from '@jterrazz/test';
 
 ## Conventions
 
-Normative rules live in the constitution ([docs/09-conventions.md](docs/09-conventions.md)); the generated per-rule catalogue is [docs/10-linting.md](docs/10-linting.md). A facet (`specs/<facet>/`) carries its runner(s) at its root and holds domain folders; the folder follows the assets:
+Normative rules live in the constitution ([docs/12-conventions.md](docs/12-conventions.md)); the generated per-rule catalogue is [docs/13-linting.md](docs/13-linting.md). A facet (`specs/<facet>/`) carries its runner(s) at its root and holds domain folders; the folder follows the assets:
 
 ```
 specs/<facet>/                  # api | jobs | cli | integrations | lint
@@ -477,7 +477,7 @@ Every test contains `// Given -` and `// Then -` comments (always both; `// When
 
 ### Convention enforcement — the shipped lint plugin
 
-These conventions are not just prose: the package ships an oxlint plugin (`@jterrazz/test/oxlint`) with ~40 AST rules, plus a `jterrazz-test-check` binary (the conventions checker) that reads the data fixtures and cross-file relationships oxlint cannot. Wire the plugin into your `oxlint.config.ts` and run `jterrazz-test-check specs` in CI — the full four-channel catalogue (each rule, its channel and rationale) is generated into [docs/10-linting.md](docs/10-linting.md).
+These conventions are not just prose: the package ships an oxlint plugin (`@jterrazz/test/oxlint`) with ~40 AST rules, plus a `jterrazz-test-check` binary (the conventions checker) that reads the data fixtures and cross-file relationships oxlint cannot. Wire the plugin into your `oxlint.config.ts` and run `jterrazz-test-check specs` in CI — the full four-channel catalogue (each rule, its channel and rationale) is generated into [docs/13-linting.md](docs/13-linting.md).
 
 ## Requirements
 

package/dist/ambiguity.js

@@ -1,4 +1,4 @@
-//#region src/core/specification/website/ambiguity.ts
+//#region src/specification/facets/website/ambiguity.ts
 /**
 * The ambiguity refusal — CONVENTIONS W3.
 *
@@ -119,7 +119,7 @@ function describeAmbiguity(options) {
 		"Disambiguate with one of:",
 		...fixes,
 		"",
-		"Docs: docs/11-website.md#designating-exactly-one-element (CONVENTIONS W3)"
+		"Docs: docs/14-website.md#designating-exactly-one-element (CONVENTIONS W3)"
 	].join("\n");
 }
 //#endregion

package/dist/appium.adapter.js

@@ -2,7 +2,7 @@ import { r as formatElement, t as AmbiguousElementError } from "./ambiguity.js";
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { tmpdir } from "node:os";
-//#region src/core/specification/mobile/ambiguity.ts
+//#region src/specification/facets/mobile/ambiguity.ts
 /**
 * The ambiguity refusal, mobile edition — CONVENTIONS W3.
 *
@@ -71,13 +71,13 @@ function describeMobileAmbiguity(options) {
 		"Disambiguate with one of:",
 		...fixes,
 		"",
-		"Docs: docs/12-mobile.md#designating-exactly-one-element (CONVENTIONS W3)"
+		"Docs: docs/15-mobile.md#designating-exactly-one-element (CONVENTIONS W3)"
 	].join("\n");
 }
 //#endregion
-//#region src/core/specification/mobile/projection.ts
-const TAG_PATTERN = /<(?<openTag>[A-Za-z][\w.]*)(?<rawAttributes>(?:\s+[\w:.-]+="[^"]*")*)\s*(?<selfClosing>\/?)>|<\/(?<closeTag>[\w.]*)\s*>/g;
-const ATTRIBUTE_PATTERN = /(?<key>[\w:.-]+)="(?<value>[^"]*)"/g;
+//#region src/specification/facets/mobile/projection.ts
+const TAG_PATTERN = /<(?<openTag>[A-Za-z][\w.]*)(?<rawAttributes>(?:\s+[\w:.-]+="[^"]*")*)\s*(?<selfClosing>\/?)>|<\/(?<closeTag>[\w.]*)\s*>/gu;
+const ATTRIBUTE_PATTERN = /(?<key>[\w:.-]+)="(?<value>[^"]*)"/gu;
 const NAMED_ENTITIES = {
 	"&amp;": "&",
 	"&apos;": "'",
@@ -87,7 +87,7 @@ const NAMED_ENTITIES = {
 };
 /** Decode the XML entities an attribute value can carry. */
 function decodeEntities(value) {
-	return value.replace(/&(?:#x(?<hex>[\dA-Fa-f]+)|#(?<decimal>\d+)|(?<named>amp|apos|gt|lt|quot));/g, (entity, hex, decimal) => {
+	return value.replaceAll(/&(?:#x(?<hex>[\dA-Fa-f]+)|#(?<decimal>\d+)|(?<named>amp|apos|gt|lt|quot));/gu, (entity, hex, decimal) => {
 		if (hex) return String.fromCodePoint(Number.parseInt(hex, 16));
 		if (decimal) return String.fromCodePoint(Number(decimal));
 		return NAMED_ENTITIES[entity] ?? entity;
@@ -113,8 +113,9 @@ function parsePageSource(xml) {
 			children: [],
 			tag: openTag
 		};
-		if (stack.length === 0) root = node;
-		else stack[stack.length - 1].children.push(node);
+		const parent = stack.at(-1);
+		if (parent === void 0) root = node;
+		else parent.children.push(node);
 		if (!selfClosing) stack.push(node);
 	}
 	if (!root) throw new Error("projectScreen(): the page source contains no XML element");
@@ -122,11 +123,11 @@ function parsePageSource(xml) {
 }
 /** The substance of a node — what survives projection, or nothing. */
 function substance(node) {
-	const label = node.attributes["label"] || void 0;
-	const value = node.attributes["value"] || void 0;
-	const identifier = node.attributes["name"] || void 0;
+	const label = node.attributes.label || void 0;
+	const value = node.attributes.value || void 0;
+	const identifier = node.attributes.name || void 0;
 	return {
-		type: node.tag.replace(/^XCUIElementType/, ""),
+		type: node.tag.replace(/^XCUIElementType/u, ""),
 		...label === void 0 ? {} : { label },
 		...value === void 0 || value === label ? {} : { value },
 		...identifier === void 0 || identifier === label ? {} : { identifier }
@@ -151,9 +152,9 @@ function projectNode(node) {
 }
 /** Collect the visible texts in document order, collapsing consecutive repeats. */
 function collectTexts(node, texts) {
-	if (node.attributes["visible"] === "true") {
-		const text = node.attributes["label"] || node.attributes["value"] || void 0;
-		if (text !== void 0 && texts[texts.length - 1] !== text) texts.push(text);
+	if (node.attributes.visible === "true") {
+		const text = node.attributes.label || node.attributes.value || void 0;
+		if (text !== void 0 && texts.at(-1) !== text) texts.push(text);
 	}
 	for (const child of node.children) collectTexts(child, texts);
 }
@@ -164,7 +165,8 @@ function collectTexts(node, texts) {
 */
 function projectScreen(xml) {
 	let root = parsePageSource(xml);
-	if (root.tag === "AppiumAUT" && root.children.length === 1) root = root.children[0];
+	const [onlyChild] = root.children;
+	if (root.tag === "AppiumAUT" && root.children.length === 1 && onlyChild !== void 0) root = onlyChild;
 	const texts = [];
 	for (const child of root.children) collectTexts(child, texts);
 	const own = substance(root);
@@ -185,7 +187,9 @@ const POLL_INTERVAL_MS = 500;
 const MAX_REPORTED_MATCHES = 10;
 /** WebDriverAgent builds once per simulator — the first session is the slow one. */
 const DEFAULT_WDA_LAUNCH_TIMEOUT_MS = 24e4;
-const delay = (ms) => new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+const delay = async (ms) => {
+	await new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+};
 /** Escape a name for an NSPredicate single-quoted string literal. */
 function escapePredicate(value) {
 	return value.replaceAll("\\", String.raw`\\`).replaceAll("'", String.raw`\'`);
@@ -234,9 +238,9 @@ async function captureMatch(element) {
 		element.getAttribute("value"),
 		element.getAttribute("name")
 	]);
-	const shortLabel = label ? label.replaceAll(/\s+/g, " ").trim().slice(0, 80) : void 0;
+	const shortLabel = label ? label.replaceAll(/\s+/gu, " ").trim().slice(0, 80) : void 0;
 	return {
-		type: (type ?? "Unknown").replace(/^XCUIElementType/, ""),
+		type: (type ?? "Unknown").replace(/^XCUIElementType/u, ""),
 		...shortLabel === void 0 ? {} : { label: shortLabel },
 		...value && value !== label ? { value } : {},
 		...identifier && identifier !== label ? { identifier } : {}
@@ -353,10 +357,10 @@ var AppiumAdapter = class {
 			const count = await matches.length;
 			if (count === 0) {
 				if (options?.tryScroll) {
-					const offscreen = await scope.$$(`-ios predicate string:${compilePredicate(level, { anyVisibility: true })}`);
-					if (await offscreen.length > 0) try {
+					const first = (await scope.$$(`-ios predicate string:${compilePredicate(level, { anyVisibility: true })}`))[0];
+					if (first !== void 0) try {
 						await driver.executeScript("mobile: scroll", [{
-							elementId: offscreen[0].elementId,
+							elementId: first.elementId,
 							toVisible: true
 						}]);
 					} catch {}
@@ -368,7 +372,9 @@ var AppiumAdapter = class {
 				element: level,
 				matches: await this.captureMatches(matches)
 			}));
-			scope = matches[0];
+			const next = matches[0];
+			if (next === void 0) return null;
+			scope = next;
 		}
 		return scope;
 	}
@@ -376,7 +382,10 @@ var AppiumAdapter = class {
 	async captureMatches(matches) {
 		const count = Math.min(await matches.length, MAX_REPORTED_MATCHES);
 		const evidence = [];
-		for (let index = 0; index < count; index++) evidence.push(await captureMatch(matches[index]));
+		for (let index = 0; index < count; index++) {
+			const match = matches[index];
+			if (match !== void 0) evidence.push(await captureMatch(match));
+		}
 		return evidence;
 	}
 	/** Screenshot the failing state into a temp file; never masks the original error. */
@@ -394,7 +403,7 @@ var AppiumAdapter = class {
 		let excerpt = "";
 		try {
 			const source = await driver.getPageSource();
-			const labels = [...new Set([...source.matchAll(/label="(?<label>[^"]{2,60})"/g)].map((match) => match.groups?.["label"] ?? ""))].slice(0, 15);
+			const labels = [...new Set([...source.matchAll(/label="(?<label>[^"]{2,60})"/gu)].map((match) => match.groups?.label ?? ""))].slice(0, 15);
 			if (labels.length > 0) excerpt = `\nCurrently on screen: ${labels.join(" | ")}`;
 		} catch {}
 		return /* @__PURE__ */ new Error(`${verb}(${formatElement(element)}) timed out after ${this.actionTimeoutMs}ms — no visible match.${excerpt}`);