@jterrazz/test 16.1.1 → 17.0.0

package/dist/shared-route-coverage.global-setup.js

@@ -0,0 +1,187 @@
+import { t as isRecord } from "./shared-json-shape.js";
+import { n as refusal } from "./shared-refusal.js";
+import { a as readLedgers, i as measure, n as clearLedgers, r as markPartial, s as shardLedgersDir, t as ROUTES_DIR, u as shouldUpdateSnapshots } from "./shared-ledger.js";
+import { u as parseYamlSource } from "./shared-yaml-document.js";
+import { r as testSettingsAt } from "./shared-test-section.js";
+import { t as setupEntry } from "./shared-setup-entry.js";
+import { n as heldUnreached, r as recordUnreached, t as ROUTES_LEDGER } from "./shared-test-baseline.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/specifications/api/routes/methodless.ts
+function shapeOf(path) {
+	return path.replaceAll(/:[^/]+/gu, ":");
+}
+function methodlessDrift(table, methodless) {
+	const named = new Set(methodless.map((path) => shapeOf(path)));
+	const any = [...new Map(table.filter((route) => route.method === "ALL").map((route) => [shapeOf(route.path), route.path]))];
+	const taken = new Set(any.map(([shape]) => shape));
+	const missed = any.filter(([shape]) => !named.has(shape)).map(([, path]) => `  ALL ${path}: the app takes it on any method, and the list misses it, so add '${path}' with why the app takes it on any method`);
+	const stale = methodless.filter((path) => !taken.has(shapeOf(path))).map((path) => table.some((route) => shapeOf(route.path) === shapeOf(path)) ? `  ${path}: the list names it, and the app takes it on its own methods only, so remove '${path}'` : `  ${path}: the list names it, and the app's table holds no such route, so remove '${path}'`);
+	return [...missed, ...stale];
+}
+function methodlessDrifted(drift) {
+	return {
+		fix: "state in `test: { methodless }` exactly the routes the app takes on any method, each with its reason",
+		found: `api routes: \`test: { methodless }\` in jterrazz.config.ts drifted from the app's table:\n${drift.join("\n")}`,
+		read: "docs/guides/api-specs.md#a-route-taken-on-any-method",
+		why: "`test: { methodless }` names the routes the app takes on any method, which the checker files by their path, whatever verb a spec sends."
+	};
+}
+//#endregion
+//#region src/specifications/api/routes/routes.ts
+const METHODS = /* @__PURE__ */ new Set([
+	"delete",
+	"get",
+	"head",
+	"options",
+	"patch",
+	"post",
+	"put",
+	"trace"
+]);
+const BRACED_PARAMETER = /^\{[^}]+\}$/u;
+function isParameter(segment) {
+	return segment.startsWith(":") || BRACED_PARAMETER.test(segment);
+}
+function takesSegment(declared, sent, template) {
+	if (sent === void 0) return false;
+	if (template && isParameter(sent)) return isParameter(declared);
+	return isParameter(declared) ? sent.length > 0 && !template : sent === declared;
+}
+/** A template request is matched by its template, any other by its path; `ALL` takes any method, a `*` tail the rest. */
+function reachesRoute(route, sent) {
+	if (route.method !== "ALL" && route.method !== sent.method) return false;
+	const template = sent.template !== void 0;
+	const declared = route.path.split("/");
+	const segments = ((sent.template ?? sent.path).split("?")[0] ?? "").split("/");
+	if (declared.at(-1) === "*") return declared.slice(0, -1).every((segment, index) => takesSegment(segment, segments[index], template));
+	return declared.length === segments.length && declared.every((segment, index) => takesSegment(segment, segments[index], template));
+}
+function unreachedRoutes(declared, reached) {
+	const seen = /* @__PURE__ */ new Set();
+	return declared.filter((route) => {
+		const key = `${route.method} ${route.path}`;
+		if (seen.has(key) || reached.some((sent) => reachesRoute(route, sent))) return false;
+		seen.add(key);
+		return true;
+	});
+}
+function openApiRoutes(text, json) {
+	const parsed = json ? JSON.parse(text) : parseYamlSource(text).document.toJSON();
+	const paths = isRecord(parsed) ? parsed.paths : void 0;
+	if (!isRecord(paths)) return [];
+	return Object.entries(paths).flatMap(([path, item]) => isRecord(item) ? Object.keys(item).filter((method) => METHODS.has(method)).map((method) => ({
+		method: method.toUpperCase(),
+		path
+	})) : []);
+}
+async function declaredRoutes(root) {
+	const { routes } = await testSettingsAt(root);
+	if (routes === void 0) return;
+	return openApiRoutes(readFileSync(join(root, routes), "utf8"), routes.endsWith(".json"));
+}
+async function declaredMethodless(root) {
+	const { methodless } = await testSettingsAt(root);
+	return [...methodless];
+}
+//#endregion
+//#region src/specifications/api/routes/route-judge.ts
+const UNKNOWN_TABLE = {
+	fix: "hand `server` the Hono app itself (its `app.routes` is the table), or declare the routes as an OpenAPI document: `test: { routes: './openapi.yaml' }` in jterrazz.config.ts",
+	found: "api routes: an app specification.api() started exposes no route table",
+	read: "docs/guides/api-specs.md#an-app-that-is-not-hono",
+	why: "A route is judged reached against the table the app declares."
+};
+function spelled(route) {
+	return `${route.method} ${route.path}`;
+}
+const SHARD_UNJUDGED = "api routes: not judged, since a shard's ledgers are a part of the run's and the route ratchet is judged only over every shard's ledgers (docs/guides/api-specs.md)";
+const PARTIAL_UNJUDGED = "api routes: not judged, since a partial run (--changed, a file filter or -t) reaches only some routes";
+async function judgeRoutes(root, directory, run) {
+	return await judgeLedgers(root, readLedgers(directory), run);
+}
+function unjudgedRun({ failed, scope, update }) {
+	if (scope === "shard") return { line: SHARD_UNJUDGED };
+	if (scope === "partial") return { line: PARTIAL_UNJUDGED };
+	if (failed === 0) return;
+	const why = `${failed} file(s) of the run failed, and a failed file may not have sent its requests`;
+	return update ? { failure: {
+		fix: "make the run green, then record with TEST_UPDATE=1",
+		found: `api routes: not recorded: ${why}`,
+		read: "docs/guides/api-specs.md#when-a-run-is-not-judged",
+		why: "The route ratchet is recorded only from a run that is green and whole."
+	} } : { line: `api routes: not judged: ${why}` };
+}
+function ratchetMoved(missing, held, named) {
+	return missing > held ? {
+		fix: "send each from a spec, or record them with TEST_UPDATE=1",
+		found: `api routes: ${missing} declared route(s) no test reached, and the ratchet holds ${held}:\n${named}`,
+		read: "docs/guides/api-specs.md#the-ratchet",
+		why: "A route no test reached fails the run, beyond the count the ratchet holds."
+	} : {
+		fix: "the debt fell: record it with TEST_UPDATE=1",
+		found: `api routes: ${missing} declared route(s) no test reached, below the ${held} the ratchet holds`,
+		read: "docs/guides/api-specs.md#the-ratchet",
+		why: "The ratchet is exact in both directions."
+	};
+}
+async function judgeLedgers(root, ledgers, { failed, scope, update }) {
+	if (ledgers.length === 0) return {};
+	const unjudged = unjudgedRun({
+		failed,
+		scope,
+		update
+	});
+	if (unjudged !== void 0) return unjudged;
+	const run = measure(ledgers);
+	const table = await declaredRoutes(root) ?? run.declared;
+	if (table === void 0) return { failure: UNKNOWN_TABLE };
+	const drift = run.declared === void 0 ? [] : methodlessDrift(run.declared, await declaredMethodless(root));
+	if (drift.length > 0) return { failure: methodlessDrifted(drift) };
+	const declared = [...new Map(table.map((route) => [spelled(route), route])).values()];
+	const missing = unreachedRoutes(declared, run.reached);
+	const named = missing.map((route) => `  ${spelled(route)}`).join("\n");
+	if (update) {
+		recordUnreached(root, missing.length);
+		return { line: `api routes: ${missing.length} unreached recorded under ${ROUTES_LEDGER}` };
+	}
+	const held = heldUnreached(root);
+	if (missing.length !== held) return { failure: ratchetMoved(missing.length, held, named) };
+	return { line: missing.length === 0 ? `api routes: all ${declared.length} declared routes reached` : `api routes: ${missing.length} unreached, held by ${ROUTES_LEDGER}:\n${named}` };
+}
+//#endregion
+//#region src/specifications/api/routes/route-coverage.global-setup.ts
+async function scopeOf(project) {
+	if (project.vitest.config.shard !== void 0) return "shard";
+	if (project.vitest.config.testNamePattern !== void 0) return "partial";
+	const ran = new Set(project.vitest.state.getFiles().filter((file) => file.projectName === project.name).map((file) => file.filepath));
+	const { testFiles } = await project.globTestFiles();
+	return testFiles.every((file) => ran.has(file)) ? "whole" : "partial";
+}
+function routeCoverageSetup() {
+	return setupEntry(import.meta.dirname, "route-coverage");
+}
+function setupRoutes(project) {
+	const { root } = project.config;
+	const shard = project.vitest.config.shard;
+	const directory = join(root, shard === void 0 ? ROUTES_DIR : shardLedgersDir(shard));
+	clearLedgers(directory);
+	if (shard !== void 0 && project.vitest.config.testNamePattern !== void 0) markPartial(directory);
+	project.provide("routesLedger", directory);
+	return async () => {
+		const { failure, line } = await judgeRoutes(root, directory, {
+			failed: project.vitest.state.getFailedFilepaths().length,
+			scope: await scopeOf(project),
+			update: shouldUpdateSnapshots()
+		});
+		if (failure !== void 0) throw new Error(refusal(failure));
+		if (line !== void 0) process.stdout.write(`${line}\n`);
+	};
+}
+function setup(project) {
+	return setupRoutes(project);
+}
+//#endregion
+export { setup as n, setupRoutes as r, routeCoverageSetup as t };
+
+//# sourceMappingURL=shared-route-coverage.global-setup.js.map

package/dist/shared-scenario-failure.js

@@ -0,0 +1,198 @@
+import { n as refusal$1 } from "./shared-refusal.js";
+import { lessonParts, refusalBlock } from "@jterrazz/typescript/rules";
+//#region src/visitor/targets/as-written.ts
+const FUNCTION_NAME_OF_KIND = {
+	banner: "banner",
+	button: "button",
+	complementary: "complementary",
+	contentinfo: "contentinfo",
+	dialog: "dialog",
+	field: "field",
+	form: "form",
+	heading: "heading",
+	link: "link",
+	listitem: "listitem",
+	main: "main",
+	navigation: "navigation",
+	option: "option",
+	region: "region",
+	row: "row",
+	search: "search",
+	status: "status",
+	table: "table",
+	testId: "testId",
+	text: "content"
+};
+/** Spoken in the vocabulary the author wrote, never playwright's: an option appears only when the author stated one. */
+function asWritten(target) {
+	const bare = asWrittenUnscoped(target);
+	return target.scope ? `within(${asWritten(target.scope)}, ${bare})` : bare;
+}
+function asWrittenUnscoped(target) {
+	const args = [];
+	if (target.name !== void 0) args.push(JSON.stringify(target.name));
+	if (target.exact !== void 0) args.push(`{ exact: ${String(target.exact)} }`);
+	return `${FUNCTION_NAME_OF_KIND[target.kind]}(${args.join(", ")})`;
+}
+//#endregion
+//#region src/visitor/matching/landmark-of-tag.ts
+const LANDMARK_ELEMENTS = {
+	banner: "header",
+	complementary: "aside",
+	contentinfo: "footer",
+	form: "form",
+	main: "main",
+	navigation: "nav",
+	region: "section",
+	search: "search"
+};
+const LANDMARK_SELECTOR = Object.entries(LANDMARK_ELEMENTS).flatMap(([kind, tag]) => [tag, `[role="${kind}"]`]).join(", ");
+function isLandmarkKind(value) {
+	return Object.hasOwn(LANDMARK_ELEMENTS, value);
+}
+function landmarkOfTagOrRole(value) {
+	const kind = Object.entries(LANDMARK_ELEMENTS).find(([, tag]) => tag === value)?.[0] ?? value;
+	return isLandmarkKind(kind) ? kind : void 0;
+}
+//#endregion
+//#region src/visitor/matching/ambiguous.ts
+function landmarkOf(match) {
+	const kind = landmarkOfTagOrRole(match.context ?? "");
+	if (kind !== "region") return kind === void 0 ? void 0 : `${FUNCTION_NAME_OF_KIND[kind]}()`;
+	return match.contextName === void 0 ? void 0 : `${FUNCTION_NAME_OF_KIND.region}(${JSON.stringify(match.contextName)})`;
+}
+function formatMatch(match, index) {
+	const attribute = match.detail === void 0 ? "" : ` ${quoteDetail(match)}`;
+	const matchedOnLabel = match.accessibleName === void 0 || match.accessibleName === "" ? "" : `  named ${JSON.stringify(match.accessibleName)}`;
+	const context = match.context === void 0 || match.context === "" ? "" : `  in <${match.context}>`;
+	return `  ${index + 1}. <${match.tag}${attribute}>${match.text}</${match.tag}>${matchedOnLabel}${context}`;
+}
+function quoteDetail(match) {
+	return `${match.tag === "a" ? "href" : "name"}=${JSON.stringify(match.detail)}`;
+}
+function landmarkCounts(matches) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const match of matches) {
+		const landmark = landmarkOf(match);
+		if (landmark !== void 0) counts.set(landmark, (counts.get(landmark) ?? 0) + 1);
+	}
+	return [...counts].toSorted(([, a], [, b]) => a - b);
+}
+function formatFixes(target, matches) {
+	const fixes = [];
+	const landmarksThatCutTheSet = landmarkCounts(matches).filter(([, count]) => count < matches.length);
+	if (!target.scope) {
+		const [first, ...rest] = landmarksThatCutTheSet;
+		const alsoHere = rest.length > 0 ? `   [also here: ${rest.map(([name]) => name).join(", ")}]` : "";
+		fixes.push(first === void 0 ? `scope it       within(<a container holding only this one>, ${asWrittenUnscoped(target)})` : `scope it       within(${first[0]}, ${asWrittenUnscoped(target)})   [leaves ${first[1]} of ${matches.length}]${alsoHere}`);
+	}
+	if (target.exact === false) {
+		const remaining = matches.filter((match) => match.text === target.name).length;
+		if (remaining > 0 && remaining < matches.length) fixes.push(`exact name     ${asWrittenUnscoped({
+			...target,
+			exact: true
+		})}   [leaves ${remaining} of ${matches.length}]`);
+	}
+	fixes.push("other element  a heading(), button() or field() may name one thing where this does not");
+	return fixes;
+}
+function ambiguityError(options) {
+	const { target, fixes, lines, where } = options;
+	return new Error(refusal$1("target-matches-one-element", {
+		fix: ["designate one of them:", ...fixes.map((fix) => `  • ${fix}`)].join("\n"),
+		found: [`Ambiguous element: ${asWritten(target)} matched ${lines.length} elements on ${where}:`, ...lines].join("\n")
+	}));
+}
+function ambiguousTargetError(options) {
+	const { target, matches, url } = options;
+	return ambiguityError({
+		target,
+		fixes: formatFixes(target, matches),
+		lines: matches.map((match, index) => formatMatch(match, index)),
+		where: url
+	});
+}
+function shortened(text) {
+	return text.replaceAll(/\s+/gu, " ").trim().slice(0, 80);
+}
+const CANDIDATE_LIMITS = {
+	landmarks: LANDMARK_SELECTOR,
+	limit: 10,
+	textLength: 80
+};
+/** Serialized into the page by playwright: it reads nothing from module scope. */
+function candidatesOf(nodes, { landmarks, limit, textLength }) {
+	const landmarkOf = (node) => {
+		const landmark = node.parentElement?.closest(landmarks);
+		if (landmark === null || landmark === void 0) return {
+			context: void 0,
+			contextName: void 0
+		};
+		const labelledBy = (landmark.getAttribute("aria-labelledby") ?? "").split(/\s+/u).filter((id) => id !== "").map((id) => document.querySelector(`#${CSS.escape(id)}`)?.textContent ?? "").join(" ");
+		const name = (landmark.getAttribute("aria-label") ?? labelledBy).replaceAll(/\s+/gu, " ").trim();
+		return {
+			context: landmark.getAttribute("role") ?? landmark.tagName.toLowerCase(),
+			contextName: name === "" ? void 0 : name
+		};
+	};
+	return nodes.slice(0, limit).map((node) => {
+		const detail = node.getAttribute("href") ?? node.getAttribute("name");
+		const text = (node.textContent ?? "").replaceAll(/\s+/gu, " ").trim().slice(0, textLength);
+		const label = node.getAttribute("aria-label")?.trim();
+		const { context, contextName } = landmarkOf(node);
+		return {
+			accessibleName: label === void 0 || label === "" || label === text ? void 0 : label,
+			context,
+			contextName,
+			detail: detail ?? void 0,
+			tag: node.tagName.toLowerCase(),
+			text
+		};
+	});
+}
+//#endregion
+//#region src/chain/refusals/scenario-failure.ts
+const SURFACE_OF = {
+	open: "screen",
+	visit: "page"
+};
+const CHAPTER_ANCHOR = /^docs\/[^#]+\.md#.+$/u;
+const isAnchor = (read) => CHAPTER_ANCHOR.test(read);
+function finishedLesson(error) {
+	if (!(error instanceof Error)) return;
+	const { fix = "", found = "", read, why = "" } = lessonParts(error.message) ?? {};
+	const anchor = String(read);
+	return [
+		fix,
+		found,
+		why
+	].includes("") || !isAnchor(anchor) ? void 0 : {
+		fix,
+		found,
+		read: anchor,
+		why
+	};
+}
+function scenarioFailure(error, evidence, verb) {
+	const suffix = evidence === null ? "" : `\nEvidence: ${evidence}`;
+	const lesson = finishedLesson(error);
+	if (error instanceof Error && lesson !== void 0) {
+		error.message = refusalBlock({
+			...lesson,
+			found: `${lesson.found}${suffix}`
+		});
+		return error;
+	}
+	const message = error instanceof Error ? error.message : String(error);
+	const surface = SURFACE_OF[verb];
+	return new Error(refusal$1({
+		fix: `correct the step that failed, or the ${surface} it drives`,
+		found: `the ${verb} scenario failed:\n  ${message.replaceAll("\n", "\n  ")}${suffix}`,
+		read: verb === "visit" ? "docs/guides/website-specs.md#visit-scenarios-the-when" : "docs/guides/mobile-specs.md#open-scenarios-the-when",
+		why: `${verb === "visit" ? "A" : "An"} ${verb} scenario drives the ${surface} step by step, and the first step that fails ends it.`
+	}), { cause: error });
+}
+//#endregion
+export { ambiguityError as a, asWrittenUnscoped as c, shortened as i, CANDIDATE_LIMITS as n, ambiguousTargetError as o, candidatesOf as r, asWritten as s, scenarioFailure as t };
+
+//# sourceMappingURL=shared-scenario-failure.js.map