simulci 0.2.0 → 0.3.0

package/dist/index.js

@@ -28797,7 +28797,7 @@ function verdictOf(gates) {
 //#endregion
 //#region ../engine/src/version.ts
 /** The simulci version. release-please updates it with every release. */
-const VERSION = "0.2.0";
+const VERSION = "0.3.0";
 /** The schema version of every JSON document the engine emits or reads. A breaking change bumps it. */
 const SCHEMA_VERSIONS = {
 	scenario: 1,
@@ -32235,7 +32235,134 @@ function diskSnapshotStore(root) {
 	};
 }
 //#endregion
+//#region src/args.ts
+/**
+* A command line as citty reads it, with two of its gaps filled. citty 0.2 parses with node:util's parseArgs and no
+* `multiple`, so a flag given twice keeps only its last value: a `repeated` flag keeps them all. And a string flag
+* given no value takes the next flag as one: a `bare` flag that stands last, or before another flag, takes its bare
+* value instead.
+*/
+function readArgs(rawArgs, def, opts) {
+	const raw = withBareValues(rawArgs, def, opts.bare ?? {});
+	const repeated = new Set(opts.repeated);
+	const values = {};
+	for (const t of optionTokens(raw, def)) if (repeated.has(t.key)) (values[t.key] ??= []).push(t.value ?? "");
+	return {
+		...parseArgs$2([...raw], def),
+		...values
+	};
+}
+/** A bare flag, as `--flag=<its bare value>`. */
+function withBareValues(raw, def, bare) {
+	const out = [...raw];
+	for (const t of optionTokens(raw, def)) {
+		const value = bare[t.key];
+		if (value !== void 0 && !t.inline && (t.value === void 0 || t.value.startsWith("-"))) out[t.index] = `--${kebab(t.key)}=${value}`;
+	}
+	return out;
+}
+/** The flags of a command line, tokenized as citty's parser sees them: without its `--no-` negations. */
+function optionTokens(raw, def) {
+	const { options, keys } = optionsOf(def);
+	const end = raw.indexOf("--");
+	const kept = raw.flatMap((arg, i) => (end === -1 || i < end) && arg.startsWith("--no-") ? [] : [i]);
+	const { tokens } = parseArgs({
+		args: kept.map((i) => raw[i]),
+		options,
+		strict: false,
+		allowPositionals: true,
+		tokens: true
+	});
+	return tokens.flatMap((t) => {
+		const key = t.kind === "option" ? keys.get(t.name) : void 0;
+		if (t.kind !== "option" || key === void 0) return [];
+		return [{
+			key,
+			index: kept[t.index],
+			value: t.value,
+			inline: t.inlineValue === true
+		}];
+	});
+}
+/** The options citty declares for a command's args: each name, its kebab- and camelCase forms and its aliases, typed. */
+function optionsOf(def) {
+	const options = {};
+	const keys = /* @__PURE__ */ new Map();
+	for (const [key, arg] of Object.entries(def)) {
+		if (arg.type === "positional") continue;
+		const type = arg.type === "boolean" ? "boolean" : "string";
+		const aliases = "alias" in arg ? [arg.alias ?? []].flat() : [];
+		for (const name of /* @__PURE__ */ new Set([
+			key,
+			kebab(key),
+			camel(key),
+			...aliases
+		])) {
+			options[name] = { type };
+			keys.set(name, key);
+		}
+		const short = aliases.find((a) => a.length === 1);
+		if (short !== void 0) options[key] = {
+			type,
+			short
+		};
+	}
+	return {
+		options,
+		keys
+	};
+}
+const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+const camel = (name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+/** A flag given a value it does not take: the command prints the message and exits 2. */
+var FlagError = class extends Error {
+	name = "FlagError";
+};
+/** `value` when it is one of `choices`; else a `FlagError` naming what `--<flag>` takes. */
+function oneOf(flag, value, choices) {
+	if (choices.some((c) => c === value)) return value;
+	throw new FlagError(`--${flag} takes ${spoken(choices)}, not '${String(value)}'`);
+}
+/** A list as a sentence says it: `a, b or c`. */
+const spoken = (items) => items.length > 1 ? `${items.slice(0, -1).join(", ")} or ${items.at(-1)}` : items.join("");
+/**
+* The exit code of a command's body; 2 when it throws, with the error's message on stderr (its stack under
+* `SIMULCI_DEBUG=1`). citty would print the stack and exit 1, which `simulci test` uses for a failed case.
+*/
+function exitCodeOf(body, io) {
+	try {
+		return body();
+	} catch (e) {
+		io.stderr(`${errorText(e, io.env.SIMULCI_DEBUG === "1")}\n`);
+		return 2;
+	}
+}
+function errorText(e, stack) {
+	if (!(e instanceof Error)) return String(e);
+	return stack && e.stack !== void 0 ? e.stack : e.message;
+}
+/** A flag's values as a list: none, one, or every one it was given. */
+const values = (v) => v === void 0 ? [] : Array.isArray(v) ? v : [v];
+/** The `--assume` entries and the `--assume-file` list; an `AssumeError` when one does not parse or the file cannot be read. */
+function assumeOf(assume, file) {
+	return parseAssume(values(assume), file === void 0 ? void 0 : readAssumeFile(file));
+}
+function readAssumeFile(file) {
+	try {
+		return readFileSync(resolve(file), "utf8");
+	} catch (e) {
+		throw new AssumeError(`--assume-file ${file}: ${e.code === "ENOENT" ? "no such file" : e.message}`);
+	}
+}
+//#endregion
 //#region src/plan.ts
+const FORMATS = [
+	"text",
+	"json",
+	"mermaid"
+];
+const DETAILS$1 = ["steps", "legs"];
+const AS_TEST = ["jobs", "steps"];
 /** Builds the scenario from the arguments: `key=value` lists become records, repeated flags become arrays. */
 function scenarioFromArgs(args) {
 	const s = { event: args.event };
@@ -32251,13 +32378,13 @@ function scenarioFromArgs(args) {
 		const v = args[key];
 		if (v !== void 0 && v !== "") s[key] = v;
 	}
-	const changed = list$1(args.changed);
+	const changed = list(args.changed);
 	if (changed.length) s.changed = changed;
-	const inputs = pairs(list$1(args.input));
+	const inputs = pairs(list(args.input));
 	if (Object.keys(inputs).length) s.inputs = Object.fromEntries(Object.entries(inputs).map(([k, v]) => [k, typed(v)]));
-	const vars = pairs(list$1(args.var));
+	const vars = pairs(list(args.var));
 	if (Object.keys(vars).length) s.vars = vars;
-	const secrets = list$1(args.secret);
+	const secrets = list(args.secret);
 	if (secrets.length) s.secrets = secrets;
 	if (args.actor !== void 0 || args.fork) {
 		s.actor = {};
@@ -32266,7 +32393,7 @@ function scenarioFromArgs(args) {
 	}
 	return s;
 }
-const list$1 = (v) => (v === void 0 ? [] : Array.isArray(v) ? v : [v]).flatMap((x) => x.split(",")).map((x) => x.trim()).filter(Boolean);
+const list = (v) => values(v).flatMap((x) => x.split(",")).map((x) => x.trim()).filter(Boolean);
 function pairs(items) {
 	const out = {};
 	for (const item of items) {
@@ -32287,116 +32414,145 @@ function render(plan, format) {
 	if (format === "mermaid") return renderMermaid(plan);
 	return renderText(plan);
 }
+const PLAN_ARGS = {
+	dir: {
+		type: "string",
+		description: "The repository checkout",
+		default: "."
+	},
+	event: {
+		type: "string",
+		description: "The event (push, pull_request, workflow_dispatch, …)",
+		default: "push"
+	},
+	action: {
+		type: "string",
+		description: "The activity type (opened, labeled, …)"
+	},
+	ref: {
+		type: "string",
+		description: "The git ref (refs/heads/main, or a branch name)"
+	},
+	branch: {
+		type: "string",
+		description: "The branch (refs/heads/<branch>)"
+	},
+	tag: {
+		type: "string",
+		description: "The tag (refs/tags/<tag>)"
+	},
+	base: {
+		type: "string",
+		description: "The base branch of a pull request"
+	},
+	head: {
+		type: "string",
+		description: "The head branch of a pull request"
+	},
+	changed: {
+		type: "string",
+		description: "Changed files, comma-separated or repeated"
+	},
+	input: {
+		type: "string",
+		description: "A workflow_dispatch input, name=value (repeatable)"
+	},
+	var: {
+		type: "string",
+		description: "A variable, NAME=value (repeatable)"
+	},
+	secret: {
+		type: "string",
+		description: "A secret that exists, by name (repeatable)"
+	},
+	actor: {
+		type: "string",
+		description: "The actor login"
+	},
+	fork: {
+		type: "boolean",
+		description: "The pull request comes from a fork",
+		default: false
+	},
+	message: {
+		type: "string",
+		description: "The head commit message"
+	},
+	format: {
+		type: "string",
+		description: spoken(FORMATS),
+		default: "text"
+	},
+	detail: {
+		type: "string",
+		description: spoken(DETAILS$1),
+		default: "steps"
+	},
+	assume: {
+		type: "string",
+		description: "A mock: build.unit=failure, build.unit.outputs.sha=abc (repeatable)"
+	},
+	"assume-file": {
+		type: "string",
+		description: "A YAML list of mocks"
+	},
+	"as-test": {
+		type: "string",
+		description: "Print a test case instead of the plan: jobs (also a bare --as-test) or steps"
+	},
+	workflow: {
+		type: "string",
+		description: "With --as-test: the workflow the case is about"
+	}
+};
 const planCommand = defineCommand({
 	meta: {
 		name: "plan",
 		description: "Which jobs and steps run for a scenario, and why"
 	},
-	args: {
-		dir: {
-			type: "string",
-			description: "The repository checkout",
-			default: "."
-		},
-		event: {
-			type: "string",
-			description: "The event (push, pull_request, workflow_dispatch, …)",
-			default: "push"
-		},
-		action: {
-			type: "string",
-			description: "The activity type (opened, labeled, …)"
-		},
-		ref: {
-			type: "string",
-			description: "The git ref (refs/heads/main, or a branch name)"
-		},
-		branch: {
-			type: "string",
-			description: "The branch (refs/heads/<branch>)"
-		},
-		tag: {
-			type: "string",
-			description: "The tag (refs/tags/<tag>)"
-		},
-		base: {
-			type: "string",
-			description: "The base branch of a pull request"
-		},
-		head: {
-			type: "string",
-			description: "The head branch of a pull request"
-		},
-		changed: {
-			type: "string",
-			description: "Changed files, comma-separated or repeated"
-		},
-		input: {
-			type: "string",
-			description: "A workflow_dispatch input, name=value (repeatable)"
-		},
-		var: {
-			type: "string",
-			description: "A variable, NAME=value (repeatable)"
-		},
-		secret: {
-			type: "string",
-			description: "A secret that exists, by name (repeatable)"
-		},
-		actor: {
-			type: "string",
-			description: "The actor login"
-		},
-		fork: {
-			type: "boolean",
-			description: "The pull request comes from a fork",
-			default: false
-		},
-		message: {
-			type: "string",
-			description: "The head commit message"
-		},
-		format: {
-			type: "string",
-			description: "text, json or mermaid",
-			default: "text"
-		},
-		detail: {
-			type: "string",
-			description: "legs or steps",
-			default: "steps"
-		},
-		assume: {
-			type: "string",
-			description: "A mock: build.unit=failure, build.unit.outputs.sha=abc (repeatable)"
-		},
-		assumeFile: {
-			type: "string",
-			description: "A YAML list of mocks"
-		},
-		asTest: {
-			type: "string",
-			description: "Print a test case instead of the plan: jobs or steps"
-		},
-		workflow: {
-			type: "string",
-			description: "With --as-test: the workflow the case is about"
-		}
-	},
-	run({ args }) {
-		const out = planOutput(args);
-		process.stdout.write(out.text);
-		if (out.code) process.exitCode = out.code;
+	args: PLAN_ARGS,
+	run({ rawArgs }) {
+		const io = {
+			stderr: (t) => process.stderr.write(t),
+			env: process.env
+		};
+		process.exitCode = exitCodeOf(() => {
+			const out = planOutput(planArgs(rawArgs));
+			(out.code ? process.stderr : process.stdout).write(out.text);
+			return out.code;
+		}, io);
 	}
 });
-/** What `simulci plan` prints, and the exit code when it cannot. */
+/**
+* The arguments of a `simulci plan` command line: every value of a repeated flag, and `jobs` for a bare `--as-test`.
+* A `FlagError` when `--format`, `--detail` or `--as-test` is given a value it does not take.
+*/
+function planArgs(rawArgs) {
+	const a = readArgs(rawArgs, PLAN_ARGS, {
+		repeated: [
+			"changed",
+			"input",
+			"var",
+			"secret",
+			"assume"
+		],
+		bare: { "as-test": "jobs" }
+	});
+	return {
+		...a,
+		format: oneOf("format", a.format, FORMATS),
+		detail: oneOf("detail", a.detail, DETAILS$1),
+		asTest: a.asTest === void 0 || a.asTest === false ? void 0 : oneOf("as-test", a.asTest, AS_TEST)
+	};
+}
+/** What `simulci plan` prints, and the exit code: 2, with the message, when it cannot. */
 function planOutput(a) {
 	const files = readWorkflowFiles(a.dir);
 	if (Object.keys(files).length === 0) return {
 		text: `no workflows under ${a.dir}/.github/workflows\n`,
 		code: 2
 	};
-	const assume = assumeOf(a);
+	const assume = mocksOf(a);
 	if (typeof assume === "string") return {
 		text: assume,
 		code: 2
@@ -32406,16 +32562,16 @@ function planOutput(a) {
 		const plan = simulate({
 			files,
 			scenario,
-			detail: a.detail === "legs" ? "legs" : "steps",
+			detail: a.detail,
 			mocks: { cli: assume }
 		});
-		if (a.asTest === void 0 || a.asTest === false) return {
+		if (a.asTest === void 0) return {
 			text: render(plan, a.format),
 			code: 0
 		};
 		return asTest(plan, a, scenario, assume);
 	} catch (e) {
-		if (!(e instanceof MocksError)) throw e;
+		if (!(e instanceof MocksError || e instanceof ScenarioError)) throw e;
 		return {
 			text: `${e.message}\n`,
 			code: 2
@@ -32423,9 +32579,9 @@ function planOutput(a) {
 	}
 }
 /** The `--assume` entries, or the message to print when they do not parse. */
-function assumeOf(a) {
+function mocksOf(a) {
 	try {
-		return parseAssume(a.assume === void 0 ? [] : Array.isArray(a.assume) ? a.assume : [a.assume], a.assumeFile === void 0 ? void 0 : readFileSync(a.assumeFile, "utf8"));
+		return assumeOf(a.assume, a.assumeFile);
 	} catch (e) {
 		if (!(e instanceof AssumeError)) throw e;
 		return `${e.message}\n`;
@@ -32439,19 +32595,26 @@ function asTest(plan, a, scenario, assume) {
 		text: "no workflow to write a test for\n",
 		code: 2
 	};
+	const path = workflow.startsWith(".github/workflows/") ? workflow : `.github/workflows/${workflow}`;
+	if (!plan.workflows.some((w) => w.depth === 0 && w.path === path)) return {
+		text: `--workflow ${workflow}: no ${path} in the checkout\n`,
+		code: 2
+	};
 	return {
 		text: fileFromPlan({
 			plan,
 			workflow,
 			scenario,
 			assume,
-			detail: a.asTest === "steps" ? "steps" : "jobs"
+			detail: a.asTest ?? "jobs"
 		}),
 		code: 0
 	};
 }
 //#endregion
 //#region src/test.ts
+/** `simulci test`: the route tests under `.github/simulci/tests`, or the files named. */
+const DETAILS = ["steps", "legs"];
 /** Runs the command; returns the exit code. */
 function runTestCommand(a, io) {
 	const ready = prepare(a, io);
@@ -32461,7 +32624,7 @@ function runTestCommand(a, io) {
 		ci: a.ci ?? io.env.CI === "true",
 		update: a.update ?? false,
 		strict: a.strict ?? false,
-		snapshotDetail: a.snapshotDetail === "legs" ? "legs" : "steps",
+		snapshotDetail: a.snapshotDetail ?? "steps",
 		snapshots: diskSnapshotStore(root)
 	};
 	if (a.filter !== void 0) options.filter = a.filter;
@@ -32480,7 +32643,7 @@ function runTestCommand(a, io) {
 /** The checkout, the test files, the project and the cli mocks; or the exit code when one of them is not there. */
 function prepare(a, io) {
 	const root = resolve(a.dir);
-	const files = discoverTests(root, list(a.files));
+	const files = discoverTests(root, values(a.files));
 	const misplaced = misplacedTests(files);
 	if (misplaced.length) {
 		io.stderr(`T000 ${misplaced.join(", ")}: a test file under .github/workflows would be run by GitHub; put it under ${TESTS_DIR}\n`);
@@ -32492,12 +32655,11 @@ function prepare(a, io) {
 		return 2;
 	}
 	try {
-		const fileText = a.assumeFile === void 0 ? void 0 : readFileSync(resolve(a.assumeFile), "utf8");
 		return {
 			root,
 			files,
 			project: loadFiles(workflows),
-			cli: parseAssume(list(a.assume), fileText)
+			cli: assumeOf(a.assume, a.assumeFile)
 		};
 	} catch (e) {
 		if (!(e instanceof AssumeError)) throw e;
@@ -32513,79 +32675,90 @@ function report(result, a, io) {
 		writeFileSync(resolve(a.junit), renderJUnit(result));
 	}
 }
-const list = (v) => v === void 0 ? [] : Array.isArray(v) ? v : [v];
+const TEST_ARGS = {
+	files: {
+		type: "positional",
+		description: "Test files (default: every *.test.yml under .github/simulci/tests)",
+		required: false
+	},
+	dir: {
+		type: "string",
+		description: "The repository checkout",
+		default: "."
+	},
+	junit: {
+		type: "string",
+		description: "Write a JUnit report to this file"
+	},
+	update: {
+		type: "boolean",
+		alias: "u",
+		description: "Write every snapshot and prune stale ones",
+		default: false
+	},
+	"snapshot-detail": {
+		type: "string",
+		description: spoken(DETAILS),
+		default: "steps"
+	},
+	filter: {
+		type: "string",
+		alias: "t",
+		description: "Run the cases whose name contains the text"
+	},
+	ci: {
+		type: "boolean",
+		description: "Never write snapshots; a missing one fails; only is an error (default when CI=true)"
+	},
+	strict: {
+		type: "boolean",
+		description: "Ignore allowMaybe; stale snapshots fail",
+		default: false
+	},
+	annotations: {
+		type: "boolean",
+		description: "Print GitHub annotations (default when GITHUB_ACTIONS=true)"
+	},
+	assume: {
+		type: "string",
+		description: "A mock for every case: build.unit=failure, build.unit.outputs.sha=abc (repeatable)"
+	},
+	"assume-file": {
+		type: "string",
+		description: "A YAML list of mocks for every case"
+	}
+};
 const testCommand = defineCommand({
 	meta: {
 		name: "test",
 		description: "Run the route tests under .github/simulci/tests"
 	},
-	args: {
-		files: {
-			type: "positional",
-			description: "Test files (default: every *.test.yml under .github/simulci/tests)",
-			required: false
-		},
-		dir: {
-			type: "string",
-			description: "The repository checkout",
-			default: "."
-		},
-		junit: {
-			type: "string",
-			description: "Write a JUnit report to this file"
-		},
-		update: {
-			type: "boolean",
-			alias: "u",
-			description: "Write every snapshot and prune stale ones",
-			default: false
-		},
-		snapshotDetail: {
-			type: "string",
-			description: "steps or legs",
-			default: "steps"
-		},
-		filter: {
-			type: "string",
-			alias: "t",
-			description: "Run the cases whose name contains the text"
-		},
-		ci: {
-			type: "boolean",
-			description: "Never write snapshots; a missing one fails; only is an error (default when CI=true)"
-		},
-		strict: {
-			type: "boolean",
-			description: "Ignore allowMaybe; stale snapshots fail",
-			default: false
-		},
-		annotations: {
-			type: "boolean",
-			description: "Print GitHub annotations (default when GITHUB_ACTIONS=true)"
-		},
-		assume: {
-			type: "string",
-			description: "A mock for every case: build.unit=failure, build.unit.outputs.sha=abc (repeatable)"
-		},
-		assumeFile: {
-			type: "string",
-			description: "A YAML list of mocks for every case"
-		}
-	},
-	run({ args }) {
-		const a = args;
-		const files = a._?.length ? a._ : a.files;
-		const code = runTestCommand({
-			...a,
-			...files === void 0 ? {} : { files }
-		}, {
+	args: TEST_ARGS,
+	run({ rawArgs }) {
+		const io = {
 			stdout: (t) => process.stdout.write(t),
 			stderr: (t) => process.stderr.write(t),
 			env: process.env
-		});
-		process.exitCode = code;
+		};
+		process.exitCode = exitCodeOf(() => runTestCommand(testArgs(rawArgs), io), io);
 	}
 });
+/**
+* The arguments of a `simulci test` command line: every test file named, and every `--assume`. A `FlagError` when
+* `--snapshot-detail` is given a value it does not take.
+*/
+function testArgs(rawArgs) {
+	const a = readArgs(rawArgs, TEST_ARGS, { repeated: ["assume"] });
+	const args = {
+		...a,
+		snapshotDetail: oneOf("snapshot-detail", a.snapshotDetail, DETAILS)
+	};
+	const files = a._;
+	return files.length ? {
+		...args,
+		files
+	} : args;
+}
 runMain(defineCommand({
 	meta: {
 		name: "simulci",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simulci",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Static simulator and test framework for GitHub Actions: which jobs and steps run for a scenario, and why.",
   "keywords": [
     "ci",