@jterrazz/test 16.1.1 → 18.0.0

package/dist/shared-spec-document.js

@@ -0,0 +1,303 @@
+import { a as RUN_KEYS, c as isRelativePath, i as PRESENCE, n as FILE_CONTENT_KEYS, r as FILE_STATES, s as SpecSyntaxError, t as DOCUMENT_KEYS } from "./shared-spec-grammar.js";
+import { a as isPair, c as nodeItems, f as yamlSyntaxErrors, i as isNode, l as nodePairs, o as isScalar, r as isMap, s as isSeq, u as parseYamlSource } from "./shared-yaml-document.js";
+import { GROUND_FIXTURES, isGroundFolder } from "@jterrazz/typescript/rules";
+//#region lint/kit/project/dedent.ts
+function indentOf(line) {
+	return /^[\t ]*/u.exec(line)?.[0].length ?? 0;
+}
+/** A text opening on a line break loses that break, the closing line's whitespace and the shared indentation. */
+function dedent(text) {
+	if (!text.startsWith("\n")) return text;
+	const lines = text.slice(1).split("\n");
+	if (lines.at(-1)?.trim() === "") lines[lines.length - 1] = "";
+	const indents = lines.filter((line) => line.trim() !== "").map((line) => indentOf(line));
+	const common = indents.length === 0 ? 0 : Math.min(...indents);
+	return lines.map((line) => line.slice(common)).join("\n");
+}
+//#endregion
+//#region lint/kit/project/spec-node.ts
+function fail(context, node, message) {
+	throw new SpecSyntaxError(context.fileName, lineOf(context, node), message);
+}
+/** A pair sits on its key's line; a node the parser never placed, on the first. */
+function lineOf(context, node) {
+	const placed = isPair(node) ? node.key : node;
+	return isNode(placed) && placed.range ? context.source.lineAt(placed.range[0]) : 1;
+}
+function contentLine(context, node) {
+	const start = lineOf(context, node);
+	return isScalar(node) && (node.type ?? "").startsWith("BLOCK") ? start + 1 : start;
+}
+function requireMap(context, node, what) {
+	if (!isMap(node)) fail(context, node ?? void 0, `${what} must be a mapping of keys to values`);
+	return node;
+}
+function closedPairs(context, map, allowed, what) {
+	const pairs = [];
+	for (const pair of nodePairs(map)) {
+		const key = scalarString(pair.key);
+		if (key === null) fail(context, pair, `${what}: a key must be a plain word`);
+		if (!allowed.includes(key)) fail(context, pair, `unknown key "${key}:" in ${what}; known keys: ${allowed.join(", ")}`);
+		pairs.push(pair);
+	}
+	return pairs;
+}
+function keyed(pairs) {
+	return new Map(pairs.map((pair) => [scalarString(pair.key) ?? "", pair]));
+}
+function holdPresence(context, found, { line, shape, subject = "" }) {
+	const at = (message, where = line) => {
+		throw new SpecSyntaxError(context.fileName, where, message);
+	};
+	for (const law of PRESENCE[shape]) if (law.law === "each") {
+		const missing = law.keys.find((key) => !found.has(key));
+		if (missing !== void 0) at(law.refusal(subject, missing));
+	} else if (law.law === "some") {
+		if (!law.keys.some((key) => found.has(key))) at(law.refusal(subject));
+	} else if (found.has(law.with)) {
+		const beside = law.keys.find((key) => found.has(key));
+		if (beside !== void 0) at(law.refusal(subject, beside), lineOf(context, found.get(beside)));
+	}
+}
+function held(found, key) {
+	const pair = found.get(key);
+	if (pair === void 0) throw new Error(`"${key}:" is required by a presence law and was not found`);
+	return pair;
+}
+function scalarString(node) {
+	return isScalar(node) && typeof node.value === "string" ? node.value : null;
+}
+function requireString(context, node, what) {
+	const value = scalarString(node);
+	if (value === null) fail(context, node, `${what} must be text`);
+	return value;
+}
+function requireInteger(context, node, what) {
+	const value = isScalar(node) ? node.value : void 0;
+	if (!Number.isInteger(value)) fail(context, node, `${what} must be a literal integer`);
+	return Number(value);
+}
+function stringList(context, node, what) {
+	if (isSeq(node)) return nodeItems(node).map((item) => ({
+		line: lineOf(context, item),
+		value: requireString(context, item, `each entry of ${what}`)
+	}));
+	return [{
+		line: lineOf(context, node),
+		value: requireString(context, node, what)
+	}];
+}
+//#endregion
+//#region lint/kit/project/spec-fields.ts
+function readStream(context, node, what) {
+	return {
+		line: contentLine(context, node),
+		text: requireString(context, node, what)
+	};
+}
+function readEnv(context, node) {
+	return stringList(context, node, "env:").map(({ line, value }) => {
+		const separator = value.indexOf("=");
+		if (separator === -1) return {
+			kind: "set",
+			line,
+			name: value
+		};
+		if (separator === 0) throw new SpecSyntaxError(context.fileName, line, `env: "${value}" has no variable name before the "="`);
+		return {
+			key: value.slice(0, separator),
+			kind: "pair",
+			line,
+			value: value.slice(separator + 1)
+		};
+	});
+}
+function readServeEntry(context, node) {
+	const name = scalarString(node);
+	if (name !== null) return {
+		env: {},
+		line: lineOf(context, node),
+		name
+	};
+	const map = requireMap(context, node, "a serve: entry");
+	if (map.items.length !== 1) fail(context, node, "a serve: entry names ONE server: `- <name>: { KEY: value }`");
+	const [pair] = nodePairs(map);
+	if (pair === void 0) fail(context, node, "a serve: entry names ONE server: `- <name>: { KEY: value }`");
+	const serverName = scalarString(pair.key);
+	if (serverName === null) fail(context, pair, "a serve: entry must name its server with a plain word");
+	const env = {};
+	const envMap = requireMap(context, pair.value, `serve: ${serverName}`);
+	for (const entry of nodePairs(envMap)) {
+		const key = scalarString(entry.key);
+		if (key === null) fail(context, entry, `serve: ${serverName} is no variable name, which must be a plain word`);
+		env[key] = requireString(context, entry.value, `serve: ${serverName}.${key}`);
+	}
+	return {
+		env,
+		line: lineOf(context, pair),
+		name: serverName
+	};
+}
+function readServe(context, node) {
+	return (isSeq(node) ? nodeItems(node) : [node]).map((item) => readServeEntry(context, item));
+}
+function readFiles(context, node) {
+	const map = requireMap(context, node, "files:");
+	return nodePairs(map).map((pair) => {
+		const path = scalarString(pair.key);
+		if (path === null) fail(context, pair, "files: each key is a path relative to the working directory");
+		const line = lineOf(context, pair);
+		const state = scalarString(pair.value);
+		if (state !== null) {
+			const kind = FILE_STATES.find((known) => known === state);
+			if (kind === void 0) fail(context, pair, `files: "${path}: ${state}" is not a state: write ${FILE_STATES.join(" or ")}, or a { ${FILE_CONTENT_KEYS.join(", ")} } assertion`);
+			return {
+				kind,
+				line,
+				path
+			};
+		}
+		const pairs = closedPairs(context, requireMap(context, pair.value, `files: ${path}`), FILE_CONTENT_KEYS, `files: ${path}`);
+		holdPresence(context, keyed(pairs), {
+			line,
+			shape: "files",
+			subject: path
+		});
+		const contains = [];
+		let equals = null;
+		for (const entry of pairs) {
+			if (scalarString(entry.key) === "contains") {
+				if (isSeq(entry.value)) for (const item of nodeItems(entry.value)) contains.push(readStream(context, item, `files: ${path}.contains`));
+				else contains.push(readStream(context, entry.value, `files: ${path}.contains`));
+				continue;
+			}
+			equals = readStream(context, entry.value, `files: ${path}.equals`);
+		}
+		return {
+			contains,
+			equals,
+			kind: "content",
+			line,
+			path
+		};
+	});
+}
+function readRun(context, node, isLast) {
+	const found = keyed(closedPairs(context, requireMap(context, node, "each entry of runs:"), RUN_KEYS, "a run"));
+	holdPresence(context, found, {
+		line: lineOf(context, node),
+		shape: "run"
+	});
+	const commandPair = found.get("command");
+	const exitPair = found.get("exit");
+	if (commandPair === void 0 || exitPair === void 0) fail(context, node, "a run states its command: and its exit:");
+	const command = requireString(context, commandPair.value, "command:");
+	const waitForPair = found.get("waitFor");
+	if (waitForPair !== void 0 && !isLast) fail(context, waitForPair, "waitFor: is only allowed on the LAST run, since a long-running command ends the session");
+	const stdout = found.get("stdout");
+	const stderr = found.get("stderr");
+	const stdin = found.get("stdin");
+	const timeout = found.get("timeout");
+	const files = found.get("files");
+	return {
+		command,
+		commandLine: lineOf(context, commandPair),
+		exitCode: requireInteger(context, exitPair.value, "exit:"),
+		files: files === void 0 ? [] : readFiles(context, files.value),
+		stderr: stderr === void 0 ? null : readStream(context, stderr.value, "stderr:"),
+		stdin: stdin === void 0 ? null : requireString(context, stdin.value, "stdin:"),
+		stdout: stdout === void 0 ? null : readStream(context, stdout.value, "stdout:"),
+		timeout: timeout === void 0 ? null : requireInteger(context, timeout.value, "timeout:"),
+		waitFor: waitForPair === void 0 ? null : requireString(context, waitForPair.value, "waitFor:")
+	};
+}
+function groundOf(path) {
+	return path.split("/").find((segment) => isGroundFolder(segment));
+}
+/** A fixture is laid from `__fixtures__/`, a file or a whole directory. */
+function readFixtures(context, node) {
+	return stringList(context, node, "fixture:").map(({ line, value }) => {
+		if (!isRelativePath(value)) throw new SpecSyntaxError(context.fileName, line, `fixture: "${value}" is not a relative path: name it from this document (./... or ../...)`);
+		const found = groundOf(value);
+		if (found !== GROUND_FIXTURES) {
+			const where = `./${GROUND_FIXTURES}/ beside the document, or in the ${GROUND_FIXTURES}/ of the lowest folder the leaves share (specs/${GROUND_FIXTURES}/ across specifications)`;
+			throw new SpecSyntaxError(context.fileName, line, `fixture: reads ${GROUND_FIXTURES}/, and "${value}" names ${found === void 0 ? `no ${GROUND_FIXTURES}/ folder` : `${found}/`}, so put the file in ${where} (verb-reads-its-ground-folder)`);
+		}
+		return {
+			line,
+			path: value
+		};
+	});
+}
+//#endregion
+//#region lint/kit/project/spec-document.ts
+/** The grammar alone: no path resolution, no command, no filesystem. The runner, the lint checker and the JSON Schema read the same constants. */
+/** `fileName` is used verbatim in refusals. Update mode rewrites the returned YAML source, never a re-serialisation. */
+function readSpecFile(content, fileName) {
+	const source = parseYamlSource(content);
+	const [syntax] = yamlSyntaxErrors(source);
+	if (syntax !== void 0) throw new SpecSyntaxError(fileName, syntax.line, syntax.message);
+	const context = {
+		fileName,
+		source
+	};
+	const root = source.document.contents;
+	if (root === null || isScalar(root) && root.value === null) throw new SpecSyntaxError(fileName, 1, "the document is empty");
+	const map = requireMap(context, root, "a spec document");
+	const found = keyed(closedPairs(context, map, DOCUMENT_KEYS, "a spec document"));
+	holdPresence(context, found, {
+		line: lineOf(context, map),
+		shape: "document"
+	});
+	return {
+		document: {
+			description: requireString(context, held(found, "description").value, "description:"),
+			descriptionLine: lineOf(context, found.get("description")),
+			...readCliFields(context, found)
+		},
+		source
+	};
+}
+function readCliFields(context, found) {
+	const runsNode = held(found, "runs");
+	if (!isSeq(runsNode.value) || runsNode.value.items.length === 0) fail(context, runsNode, "runs: is a list of at least one run");
+	const runItems = nodeItems(runsNode.value);
+	const fixturePair = found.get("fixture");
+	const envPair = found.get("env");
+	const servePair = found.get("serve");
+	return {
+		env: envPair === void 0 ? [] : readEnv(context, envPair.value),
+		fixtures: fixturePair === void 0 ? [] : readFixtures(context, fixturePair.value),
+		runs: runItems.map((item, index) => readRun(context, item, index === runItems.length - 1)),
+		serve: servePair === void 0 ? [] : readServe(context, servePair.value)
+	};
+}
+/** `stdin:` is an input and a description or command is prose: none appears here. */
+function assertedStreams(document) {
+	const streams = [];
+	for (const run of document.runs) {
+		if (run.stdout !== null) streams.push(run.stdout);
+		if (run.stderr !== null) streams.push(run.stderr);
+		for (const assertion of run.files) {
+			if (assertion.kind !== "content") continue;
+			streams.push(...assertion.contains);
+			if (assertion.equals !== null) streams.push(assertion.equals);
+		}
+	}
+	return streams;
+}
+function documentPaths(document) {
+	return document.fixtures.map(({ line, path }) => ({
+		key: "fixture",
+		kind: path.endsWith("/") ? "directory" : "file",
+		line,
+		path
+	}));
+}
+function parseSpecDocument(content, fileName) {
+	return readSpecFile(content, fileName).document;
+}
+//#endregion
+export { scalarString as a, readSpecFile as i, documentPaths as n, dedent as o, parseSpecDocument as r, assertedStreams as t };
+
+//# sourceMappingURL=shared-spec-document.js.map

package/dist/shared-spec-grammar.js

@@ -0,0 +1,66 @@
+//#region lint/kit/project/relative-path.ts
+function isRelativePath(value) {
+	return value.startsWith("./") || value.startsWith("../");
+}
+//#endregion
+//#region lint/kit/project/spec-grammar.ts
+const SPEC_EXTENSION = ".spec.yaml";
+const DOCUMENT_KEYS = [
+	"description",
+	"fixture",
+	"env",
+	"serve",
+	"runs"
+];
+const RUN_KEYS = [
+	"command",
+	"stdin",
+	"timeout",
+	"waitFor",
+	"exit",
+	"stdout",
+	"stderr",
+	"files"
+];
+const FILE_CONTENT_KEYS = ["contains", "equals"];
+const FILE_STATES = ["absent", "exists"];
+const PRESENCE = {
+	document: [{
+		keys: ["description"],
+		law: "each",
+		refusal: () => "missing \"description:\": every document is one test, and this is its title"
+	}, {
+		keys: ["runs"],
+		law: "each",
+		refusal: () => "missing \"runs:\": description and runs are mandatory"
+	}],
+	files: [{
+		keys: FILE_CONTENT_KEYS,
+		law: "some",
+		refusal: (path) => `files: ${path} asserts nothing: give it contains: or equals:`
+	}],
+	run: [{
+		keys: ["command", "exit"],
+		law: "each",
+		refusal: (_subject, key) => `a run is missing "${key}:": command and exit are mandatory`
+	}, {
+		keys: ["waitFor"],
+		law: "apart",
+		refusal: () => "waitFor: and stdin: cannot share a run: the pattern is watched on a process nobody closed the input of",
+		with: "stdin"
+	}]
+};
+var SpecSyntaxError = class extends Error {
+	line;
+	reason;
+	constructor(fileName, line, message) {
+		super(`${fileName}:${line}: ${message}`);
+		this.line = line;
+		this.reason = message;
+		this.name = "SpecSyntaxError";
+	}
+};
+//#endregion
+export { RUN_KEYS as a, isRelativePath as c, PRESENCE as i, FILE_CONTENT_KEYS as n, SPEC_EXTENSION as o, FILE_STATES as r, SpecSyntaxError as s, DOCUMENT_KEYS as t };
+
+//# sourceMappingURL=shared-spec-grammar.js.map

package/dist/shared-specifications.js

@@ -0,0 +1,26 @@
+import { basename } from "node:path";
+//#region lint/kit/project/specifications.ts
+const SPECIFICATIONS = /* @__PURE__ */ new Set([
+	"api",
+	"cli",
+	"integration",
+	"job",
+	"lint",
+	"mobile",
+	"website"
+]);
+const IMPORT_SOURCE = /(?:\bfrom|\bimport|\brequire)\s*\(?\s*['"](?<source>[^'"]+)['"]/gu;
+const CONSTRUCTS = /\bspecification\.[a-z]+\s*\(/u;
+/** Constructing the runner in the file counts: a refusal spec proves the constructor that must fail to start, and has no specification module to import. */
+function reachesRunner(text) {
+	for (const match of text.matchAll(IMPORT_SOURCE)) {
+		const { source = "" } = match.groups ?? {};
+		if (source === "@jterrazz/test" || source.startsWith("@jterrazz/test/")) return true;
+		if (basename(source).includes(".specification")) return true;
+	}
+	return CONSTRUCTS.test(text);
+}
+//#endregion
+export { reachesRunner as n, SPECIFICATIONS as t };
+
+//# sourceMappingURL=shared-specifications.js.map