@pmelab/gtd 59.0.1 → 60.1.0

package/dist/steering.mjs

@@ -1,2 +1,2 @@
-import { A as parseThreads, C as unansweredNotes, D as THREAD_REPLY_ACTION_TITLE, E as FOOTNOTE_ACTION_TITLE, F as formatFinding, M as getParseCount, N as headingSectionBodies, O as openThreadFindings, P as headingSections, S as reviewSections, T as isAnswered, _ as REVIEW_SECTIONS, a as unansweredQuestions, b as reviewNotes, c as stripCodeThreads, d as FIX_BOX, f as NOISE_HEADING, g as ANSWER_WONT_FIX, h as ANSWER_LEAD, i as steeringFormatOrFreeForm, j as parseThreadsWithFindings, k as parseFootnotes, l as freeFormFormat, m as ANSWER_FIX, n as openThreads, o as viewOf, p as findingEntries, r as steeringFormatFor, s as parseCodeThreads, t as BUILT_IN_MODE_NAMES, u as applySteeringEdits, v as reviewChunks, w as FREE_TEXT_PLACEHOLDER, x as reviewRisks, y as reviewDecisions } from "./chunks/steering-CCNvngSH.mjs";
-export { ANSWER_FIX, ANSWER_LEAD, ANSWER_WONT_FIX, BUILT_IN_MODE_NAMES, FIX_BOX, FOOTNOTE_ACTION_TITLE, FREE_TEXT_PLACEHOLDER, NOISE_HEADING, REVIEW_SECTIONS, THREAD_REPLY_ACTION_TITLE, applySteeringEdits, findingEntries, formatFinding, freeFormFormat, getParseCount, headingSectionBodies, headingSections, isAnswered, openThreadFindings, openThreads, parseCodeThreads, parseFootnotes, parseThreads, parseThreadsWithFindings, reviewChunks, reviewDecisions, reviewNotes, reviewRisks, reviewSections, steeringFormatFor, steeringFormatOrFreeForm, stripCodeThreads, unansweredNotes, unansweredQuestions, viewOf };
+import { A as parseThreads, C as FREE_TEXT_PLACEHOLDER, D as findingEntries, E as NOISE_HEADING, N as formatFinding, O as openThreadFindings, S as unansweredNotes, T as FIX_BOX, _ as reviewChunks, a as sections, b as reviewRisks, c as openThreads, d as freeFormFormat, f as applySteeringEdits, g as REVIEW_SECTIONS, h as ANSWER_WONT_FIX, i as sectionBodies, j as parseThreadsWithFindings, k as parseFootnotes, l as steeringFormatFor, m as ANSWER_LEAD, n as stripCodeThreads, o as threads, p as ANSWER_FIX, r as openQuestions, t as parseCodeThreads, v as reviewDecisions, w as isAnswered, x as reviewSections, y as reviewNotes } from "./chunks/steering-DF_BMadH.mjs";
+export { ANSWER_FIX, ANSWER_LEAD, ANSWER_WONT_FIX, FIX_BOX, FREE_TEXT_PLACEHOLDER, NOISE_HEADING, REVIEW_SECTIONS, applySteeringEdits, findingEntries, formatFinding, freeFormFormat, isAnswered, openQuestions, openThreadFindings, openThreads, parseCodeThreads, parseFootnotes, parseThreads, parseThreadsWithFindings, reviewChunks, reviewDecisions, reviewNotes, reviewRisks, reviewSections, sectionBodies, sections, steeringFormatFor, stripCodeThreads, threads, unansweredNotes };

package/dist/testkit/gherkin.mjs

@@ -1,8 +1,8 @@
-import { n as testRepo, t as runsItsScript } from "../chunks/testkit-07Z_ENch.mjs";
+import { n as runsItsScript, r as testRepo } from "../chunks/testkit-BhTey1Do.mjs";
 import { resolve } from "node:path";
-import assert from "node:assert";
 import { pathToFileURL } from "node:url";
-import { Given, QuickPickleWorld, Then, When, setWorldConstructor } from "quickpickle";
+import { After, AfterAll, Given, QuickPickleWorld, Then, When, setWorldConstructor } from "quickpickle";
+import assert from "node:assert";
 //#region src/gherkin/messages.ts
 const CONTENT_LINES = 5;
 const reason = (error) => error instanceof Error ? error.message : String(error);
@@ -21,6 +21,7 @@ const beatLines = async (repo) => {
 		return [`unknown — gtd next failed: ${reason(error)}`];
 	}
 };
+const unreachedList = (steps) => steps.map(({ step, origin }) => `"${step}" (${origin})`).join(", ");
 /** Where the process rests, for a failed outcome to end with. Never throws: it describes a failure. */
 const restDescription = async (repo, neverUsed) => {
 	let lines;
@@ -34,7 +35,7 @@ const restDescription = async (repo, neverUsed) => {
 	} catch (error) {
 		lines = [`unknown — ${reason(error)}`];
 	}
-	if (neverUsed.length > 0) lines.push(`actors never used: ${neverUsed.map((step) => `"${step}"`).join(", ")}`);
+	if (neverUsed.length > 0) lines.push(`actors never used: ${unreachedList(neverUsed)}`);
 	return ["where the process rests:", ...lines.map((line) => `  ${line}`)].join("\n");
 };
 /** Both sides of a failed `contains`: the text looked for, and what was there. */
@@ -58,9 +59,14 @@ const assertContains = (where, text, content) => {
 const assertLacks = (where, text, content) => {
 	if (content === void 0 || content.includes(text)) assert.fail(containsFailure(where, text, content, false));
 };
+/** A rest at `step`; a stall there is no rest, so it points to the step that asserts one. */
+const assertRestsAt = (beat, step) => {
+	if (beat.kind === "stalled") assert.fail(`expected a rest at "${step}", but the process stalls at "${beat.state}" — assert a stall with: the process stalls at "${beat.state}"`);
+	assert.strictEqual(beat.state, step);
+};
 //#endregion
 //#region src/gherkin/index.ts
-const usedActors = /* @__PURE__ */ new WeakMap();
+const BACKGROUND_ACTORS = "gtdBackgroundActors";
 var TestkitWorld = class extends QuickPickleWorld {
 	constructor(context, info) {
 		super(context, info);
@@ -68,11 +74,15 @@ var TestkitWorld = class extends QuickPickleWorld {
 	gtdConfig = void 0;
 	env = {};
 	commands = [];
-	/** Per step, what its scripted actor does, in the order the scenario declared it. */
+	modules = {};
 	actions = /* @__PURE__ */ new Map();
 	verdicts = /* @__PURE__ */ new Map();
-	/** Per judge step, a verdict for each text its questions may contain; the first match answers. */
 	conditionalVerdicts = /* @__PURE__ */ new Map();
+	prompts = /* @__PURE__ */ new Map();
+	used = /* @__PURE__ */ new Set();
+	origins = /* @__PURE__ */ new Map();
+	backgroundScripted = /* @__PURE__ */ new Set();
+	excused = /* @__PURE__ */ new Set();
 	created = void 0;
 	configure(config) {
 		this.assertNotCreated("a gtd config");
@@ -92,6 +102,19 @@ var TestkitWorld = class extends QuickPickleWorld {
 		this.assertNotCreated(`the environment variable ${name}`);
 		this.env[name] = value;
 	}
+	/** Unlike `setEnv`, also once the repository exists: gtd sees it from its next call on. */
+	changeEnv(name, value) {
+		if (this.created === void 0) this.env[name] = value;
+		else this.created.setEnv(name, value);
+	}
+	/**
+	* Lets a config given as source import `module` as `specifier`. A support
+	* file may call it for every scenario, e.g. from a `Before` hook.
+	*/
+	importable(specifier, module) {
+		this.assertNotCreated(`the module ${specifier}`);
+		this.modules[specifier] = module;
+	}
 	assertNotCreated(what) {
 		if (this.created !== void 0) throw new Error(`${what} must be set before any step that touches the repository`);
 	}
@@ -100,16 +123,70 @@ var TestkitWorld = class extends QuickPickleWorld {
 		return this.created ??= testRepo({
 			workflow: this.gtdConfig,
 			env: this.env,
-			commands: this.commands
+			commands: this.commands,
+			modules: this.modules
 		});
 	}
+	scripting(step, replace = false) {
+		const fromBackground = (this.info.stepIdx ?? 0) < 0;
+		if (fromBackground) this.backgroundScripted.add(step);
+		if (!fromBackground || replace || !this.origins.has(step)) this.origins.set(step, fromBackground ? "Background" : "scenario");
+	}
+	/** Adds `action` to what `step`'s actor does at every visit. */
 	act(step, action) {
+		this.scripting(step);
 		this.actions.set(step, [...this.actions.get(step) ?? [], action]);
 	}
-	async drive() {
+	/** Drops every action and prompt queued for `step`, leaving `action` alone. */
+	rescript(step, action) {
+		this.scripting(step, true);
+		this.actions.set(step, [action]);
+		this.prompts.delete(step);
+	}
+	/** Drops every action and prompt queued for `step`, so a drive rests there. */
+	unscript(step) {
+		this.actions.delete(step);
+		this.prompts.delete(step);
+	}
+	/**
+	* `step`'s beat content must contain `text`. A scripted step is checked at
+	* every visit, before its actor acts; a step with nothing else scripted is
+	* not scripted at all, so a drive rests there and checks it at the rest.
+	*/
+	expectPrompt(step, text) {
+		this.scripting(step);
+		this.prompts.set(step, [...this.prompts.get(step) ?? [], text]);
+	}
+	/** Judge step `step` answers `verdict`, a JSON array. */
+	answer(step, verdict) {
+		this.scripting(step);
+		this.verdicts.set(step, verdict);
+	}
+	/** Judge step `step` answers `verdict` when its questions contain `text`; the first match answers. */
+	answerWhen(step, text, verdict) {
+		this.scripting(step);
+		this.conditionalVerdicts.set(step, [...this.conditionalVerdicts.get(step) ?? [], [text, verdict]]);
+	}
+	scripted() {
+		return /* @__PURE__ */ new Set([
+			...this.actions.keys(),
+			...this.verdicts.keys(),
+			...this.conditionalVerdicts.keys(),
+			...this.prompts.keys()
+		]);
+	}
+	/** The steps the scenario scripted, or expects a prompt at, that no drive has reached. */
+	neverUsed() {
+		return [...this.scripted()].filter((step) => !this.used.has(step)).map((step) => ({
+			step,
+			origin: this.origins.get(step) ?? "scenario"
+		}));
+	}
+	checkPrompts(step, content) {
+		for (const text of this.prompts.get(step) ?? []) if (!content.includes(text)) throw new Error(`step "${step}" was not prompted with "${text}":\n${content}`);
+	}
+	actors() {
 		const actors = {};
-		const used = usedActors.get(this) ?? /* @__PURE__ */ new Set();
-		usedActors.set(this, used);
 		for (const [step, actions] of this.actions) actors[step] = async (beat, repo) => {
 			for (const action of actions) await action(beat, repo);
 		};
@@ -126,32 +203,88 @@ var TestkitWorld = class extends QuickPickleWorld {
 				return hit[1];
 			};
 		}
-		const tracked = {};
-		for (const [step, actor] of Object.entries(actors)) tracked[step] = (beat, repo) => {
-			used.add(step);
-			return actor(beat, repo);
+		return actors;
+	}
+	/**
+	* `strict: false` lets what a strict drive refuses pass. Every drive leaves
+	* scripted steps it never reached to `assertReached`: an earlier step may
+	* script one for a later drive.
+	*/
+	async drive(options = {}) {
+		try {
+			const actors = this.actors();
+			const tracked = {};
+			for (const [step, actor] of Object.entries(actors)) tracked[step] = (beat, repo) => {
+				this.used.add(step);
+				this.checkPrompts(step, beat.content);
+				return actor(beat, repo);
+			};
+			const rest = await this.repo().drive(tracked, {
+				...options,
+				unreachedActors: "pass"
+			});
+			if (rest.kind !== "stalled" && this.prompts.has(rest.state) && !(rest.state in actors)) {
+				this.used.add(rest.state);
+				this.checkPrompts(rest.state, rest.content);
+			}
+		} catch (error) {
+			for (const step of this.scripted()) this.excused.add(step);
+			throw error;
+		}
+	}
+	/**
+	* Fails on a step a scenario step scripted, or expects a prompt at, that no
+	* drive reached. Run at scenario end. A Background's steps are left to the
+	* feature's end, and the steps a refused drive was handed are excused.
+	*/
+	async assertReached() {
+		const never = this.neverUsed();
+		const dead = never.filter(({ step, origin }) => origin === "scenario" && !this.excused.has(step));
+		if (dead.length === 0) return;
+		throw new Error(`at scenario end, no drive reached the steps scripted for ${unreachedList(dead)} — script a step only for a drive that reaches it, or in the Background when only some scenarios reach it\n\n${await restDescription(() => this.repo(), never)}`);
+	}
+	/** Records, for the feature's end, which Background-scripted steps this scenario reached. */
+	recordBackground() {
+		const record = this.common[BACKGROUND_ACTORS] ??= {
+			reached: /* @__PURE__ */ new Map(),
+			file: void 0
 		};
-		await this.repo().drive(tracked);
+		record.file ??= this.context?.task?.file;
+		const failed = this.info.errors.length > 0;
+		for (const step of this.backgroundScripted) record.reached.set(step, record.reached.get(step) === true || failed || this.used.has(step));
 	}
 };
+After(async (world) => {
+	if (!(world instanceof TestkitWorld)) return;
+	world.recordBackground();
+	if (world.info.errors.length === 0) await world.assertReached();
+});
+const allRan = (tasks) => tasks.every((task) => {
+	const t = task;
+	if (t.tasks !== void 0) return allRan(t.tasks);
+	return t.mode === "run" && t.result?.state !== "skip";
+});
+AfterAll((common) => {
+	const record = common[BACKGROUND_ACTORS];
+	if (record === void 0) return;
+	if (record.file?.tasks !== void 0 && !allRan(record.file.tasks)) return;
+	const dead = [...record.reached].filter(([, reached]) => !reached);
+	if (dead.length === 0) return;
+	throw new Error(`${common.info.feature}: no scenario reached the steps scripted for ${unreachedList(dead.map(([step]) => ({
+		step,
+		origin: "Background"
+	})))} — script a step in the Background only when some scenario reaches it`);
+});
 setWorldConstructor(TestkitWorld);
 const withNewline = (content) => content.endsWith("\n") ? content : `${content}\n`;
-const args = (list) => list.split(" ").filter((arg) => arg !== "");
-const neverUsed = (world) => {
-	const used = usedActors.get(world) ?? /* @__PURE__ */ new Set();
-	return [.../* @__PURE__ */ new Set([
-		...world.actions.keys(),
-		...world.verdicts.keys(),
-		...world.conditionalVerdicts.keys()
-	])].filter((step) => !used.has(step));
-};
+const args = (list) => [...list.matchAll(/(["'])(.*?)\1(?=\s|$)|\S+/g)].map(([word, quote, inner]) => quote === void 0 ? word : inner);
 /** An outcome step: a failure ends with where the process rests. */
 const outcome = (check) => async (world, ...rest) => {
 	try {
 		await check(world, ...rest);
 	} catch (error) {
 		const failure = error instanceof Error ? error : new Error(String(error));
-		failure.message += `\n\n${await restDescription(() => world.repo(), neverUsed(world))}`;
+		failure.message += `\n\n${await restDescription(() => world.repo(), world.neverUsed())}`;
 		throw failure;
 	}
 };
@@ -164,9 +297,15 @@ Given("a gtd config from the module {string}", async (world, path) => {
 Given("the gtd config ends with:", (world, source) => {
 	world.extendConfig(withNewline(source));
 });
-Given("an environment variable {string} set to {string}", (world, name, value) => {
+Given("the environment variable {string} is {string}", (world, name, value) => {
 	world.setEnv(name, value);
 });
+Given("from now on the environment variable {string} is {string}", (world, name, value) => {
+	world.changeEnv(name, value);
+});
+Given("the module {string} is importable as {string}", async (world, path, specifier) => {
+	world.importable(specifier, { ...await import(pathToFileURL(resolve(path)).href) });
+});
 Given("the command {string} exits {int}", (world, run, exit) => {
 	world.command({
 		run,
@@ -180,9 +319,25 @@ Given("the command {string} exits {int} with:", (world, run, exit, output) => {
 		output: withNewline(output)
 	});
 });
+Given("the command matching {string} exits {int}", (world, pattern, exit) => {
+	world.command({
+		run: new RegExp(pattern),
+		exit
+	});
+});
+Given("the command matching {string} exits {int} with:", (world, pattern, exit, output) => {
+	world.command({
+		run: new RegExp(pattern),
+		exit,
+		output: withNewline(output)
+	});
+});
 Given("a branch {string}", (world, name) => {
 	world.repo().branch(name);
 });
+Given("a branch {string} at {string}", (world, name, ref) => {
+	world.repo().branch(name, ref);
+});
 Given("{string} is checked out", (world, name) => {
 	world.repo().checkout(name);
 });
@@ -200,7 +355,7 @@ Given("the text {string} in {string} is replaced with {string}", (world, text, p
 	assert.ok(content.includes(text), `${path}: ${content}`);
 	world.repo().write(path, content.replace(text, () => replacement));
 });
-Given("{string} gets appended:", (world, path, text) => {
+Given("text is appended to {string}:", (world, path, text) => {
 	const content = world.repo().read(path) ?? "";
 	world.repo().write(path, `${content.trimEnd()}\n\n${text}\n`);
 });
@@ -214,10 +369,10 @@ Given("step {string} changes nothing", (world, step) => {
 	world.act(step, () => void 0);
 });
 Given("step {string} from now on changes nothing", (world, step) => {
-	world.actions.set(step, [() => void 0]);
+	world.rescript(step, () => void 0);
 });
 Given("step {string} is no longer scripted", (world, step) => {
-	world.actions.delete(step);
+	world.unscript(step);
 });
 Given("step {string} writes {string} with:", (world, step, path, content) => {
 	world.act(step, (_, repo) => repo.write(path, withNewline(content)));
@@ -243,11 +398,9 @@ Given("step {string} deletes {string}", (world, step, path) => {
 	world.act(step, (_, repo) => repo.remove(path));
 });
 Given("step {string} is prompted with {string}", (world, step, text) => {
-	world.act(step, (beat) => {
-		if (!beat.content.includes(text)) throw new Error(`step "${step}" was not prompted with "${text}":\n${beat.content}`);
-	});
+	world.expectPrompt(step, text);
 });
-Given("step {string} rewrites {string} with:", (world, step, path, content) => {
+Given("step {string} overwrites {string}, if it exists, with:", (world, step, path, content) => {
 	world.act(step, (_, repo) => {
 		if (repo.read(path) !== void 0) repo.write(path, withNewline(content));
 	});
@@ -255,11 +408,30 @@ Given("step {string} rewrites {string} with:", (world, step, path, content) => {
 Given("step {string} runs its script", (world, step) => {
 	world.act(step, runsItsScript);
 });
+/** A check step's script, every command it runs answering as `command` does. */
+const checkRuns = (world, step, command) => {
+	world.act(step, (beat, repo) => {
+		if (beat.actor !== "check") throw new Error(`step "${step}" is no check step; its actor is ${beat.actor}`);
+		repo.runScript(beat.content, { commands: [{
+			...command,
+			run: /[\s\S]*/
+		}] });
+	});
+};
+Given("check step {string} passes", (world, step) => {
+	checkRuns(world, step, {});
+});
+Given("check step {string} fails with:", (world, step, output) => {
+	checkRuns(world, step, {
+		exit: 1,
+		output: withNewline(output)
+	});
+});
 Given("judge step {string} answers:", (world, step, verdict) => {
-	world.verdicts.set(step, String(verdict));
+	world.answer(step, String(verdict));
 });
 Given("judge step {string}, when its questions contain {string}, answers:", (world, step, text, verdict) => {
-	world.conditionalVerdicts.set(step, [...world.conditionalVerdicts.get(step) ?? [], [text, String(verdict)]]);
+	world.answerWhen(step, text, String(verdict));
 });
 When("gtd starts workflow {string}", async (world, workflow) => {
 	await world.repo().start(workflow);
@@ -279,6 +451,9 @@ When("gtd lands", async (world) => {
 When("the process is driven", async (world) => {
 	await world.drive();
 });
+When("the process is driven leniently", async (world) => {
+	await world.drive({ strict: false });
+});
 Then("opening door {string} is refused with {string}", outcome(async (world, door, message) => {
 	await refusedWith(world.repo().door(door), message);
 }));
@@ -296,7 +471,26 @@ Then("driving the process is refused without {string}", outcome(async (world, me
 	if (got.includes(message)) assert.fail(`expected a refusal without "${message}", but it was refused with:\n${got}`);
 }));
 Then("the process rests at {string}", outcome(async (world, step) => {
-	assert.strictEqual((await world.repo().next()).state, step);
+	assertRestsAt(await world.repo().next(), step);
+}));
+Then("the process stalls at {string}", outcome(async (world, step) => {
+	const beat = await world.repo().next();
+	if (beat.kind !== "stalled" || beat.state !== step) assert.fail(`expected a stall at "${step}", but the process rests at "${beat.state}" (${beat.kind})`);
+}));
+/** A beat field by its dotted path (`model`, `access.write`), as text: a string as is, anything else as JSON. */
+const beatField = async (world, path) => {
+	let value = await world.repo().next();
+	for (const key of path.split(".")) value = typeof value === "object" && value !== null ? value[key] : void 0;
+	return value;
+};
+const asText = (value) => typeof value === "string" ? value : JSON.stringify(value) ?? "undefined";
+Then("the resting step's {word} is {string}", outcome(async (world, path, expected) => {
+	const value = asText(await beatField(world, path));
+	if (value !== expected) assert.fail(`the resting step's ${path} is not "${expected}"; it is:\n${value}`);
+}));
+Then("the resting step's {word} includes {string}", outcome(async (world, path, expected) => {
+	const value = await beatField(world, path);
+	if (!(Array.isArray(value) ? value.some((item) => asText(item) === expected) : typeof value === "string" && value.includes(expected))) assert.fail(`the resting step's ${path} does not include "${expected}"; it is:\n${asText(value)}`);
 }));
 Then("the resting step's content contains {string}", outcome(async (world, text) => {
 	assertContains("the resting step's content", text, (await world.repo().next()).content);
@@ -317,6 +511,18 @@ Then("the commit subjects end with:", outcome((world, list) => {
 	const expected = list.split("\n").filter((line) => line.trim() !== "");
 	assert.deepStrictEqual(world.repo().subjects().slice(-expected.length), expected);
 }));
+Then("the last commit body contains {string}", outcome((world, text) => {
+	assertContains("the last commit's message", text, world.repo().messages().at(-1));
+}));
+Then("the commit {string} has a body containing {string}", outcome((world, subject, text) => {
+	const matching = world.repo().commits().filter((commit) => commit.subject === subject);
+	assert.ok(matching.length > 0, `no commit "${subject}"`);
+	for (const { message } of matching) assertContains(`the commit "${subject}"`, text, message);
+}));
+Then("no commit body contains {string}", outcome((world, text) => {
+	const hit = world.repo().messages().find((message) => message.includes(text));
+	if (hit !== void 0) assert.fail(`a commit's message contains "${text}":\n${hit}`);
+}));
 const outputOf = async (world, list) => {
 	const result = await world.repo().gtd(...args(list));
 	assert.strictEqual(result.exitCode, 0, result.stderr);
@@ -347,6 +553,9 @@ Then("{string} contains the short hash of the commit {string}", outcome((world,
 	assert.ok(hash !== void 0, `no commit "${subject}"`);
 	assertContains(`"${path}"`, hash.slice(0, 7), repo.read(path));
 }));
+Then("{string} as committed at {string} contains {string}", outcome((world, path, ref, text) => {
+	assertContains(`"${path}" at ${ref}`, text, world.repo().show(ref, path));
+}));
 Then("{string} contains {string} exactly once", outcome((world, path, text) => {
 	const content = world.repo().read(path) ?? "";
 	const times = content.split(text).length - 1;

package/dist/testkit.mjs

@@ -1,2 +1,3 @@
-import { n as testRepo, r as InMemRepo, t as runsItsScript } from "./chunks/testkit-07Z_ENch.mjs";
-export { InMemRepo, runsItsScript, testRepo };
+import { H as installContext } from "./chunks/flows-DENt0uWV.mjs";
+import { a as verdictWhen, i as verdict, n as runsItsScript, o as whenPrompted, r as testRepo, t as inTurn } from "./chunks/testkit-BhTey1Do.mjs";
+export { inTurn, installContext, runsItsScript, testRepo, verdict, verdictWhen, whenPrompted };