dsh-pstack 0.2.0-beta.1 → 0.2.0

package/dist/pstack/skills/statechart/scripts/backends/mermaid.mjs

@@ -0,0 +1,186 @@
+import { append, byText, tupleKey } from "../ir.mjs";
+// runtime/skills/statechart/scripts/backends/mermaid.ts
+const BLANK = /\p{White_Space}/u;
+const SAFE = /^[\p{L}\p{N} !'()+,\-./=?[\]"_|@{}:\\^%<>]$/u;
+const HAZARD = /:(?=:|$|\S*#)|\\(?=n)|%(?=%)|<(?=[\p{L}/!?])|_(?![\p{L}\p{N}])|(?<![\p{L}\p{N}])_/giu;
+const DIRECTION = /(direction)\s+(?=LR|RL|TB|BT)/gi;
+const DOUBLE_BRACKET = /\[(?=\[)/g;
+const C4 = /C4(?=Container|Component|Dynamic|Deployment)/g;
+const UNDRAWN = /[\0\x80-\x9f]/;
+const REWRITTEN = ["fl°", "¶ß"];
+const MARKER = /(?<=marker-end=)"/g;
+const firstOf = /* @__PURE__ */ new Map();
+for (const pair of REWRITTEN) {
+	const [first, second] = [...pair].map((c) => c.codePointAt(0) ?? 0);
+	firstOf.set(second, first);
+}
+const KEPT = 0;
+const BLANKED = 1;
+const DROPPED = 2;
+const CODED = 3;
+const JOINS = 4;
+const kindOf = (n) => {
+	const c = String.fromCodePoint(n);
+	const kind = c === " " ? KEPT : BLANK.test(c) ? BLANKED : UNDRAWN.test(c) ? DROPPED : SAFE.test(c) ? KEPT : CODED;
+	return firstOf.has(n) ? kind | JOINS : kind;
+};
+const ASCII = Uint8Array.from({ length: 128 }, (_, n) => kindOf(n));
+const wide = /* @__PURE__ */ new Map();
+const kindAt = (n) => {
+	if (n < 128) return ASCII[n];
+	let kind = wide.get(n);
+	if (kind === void 0) wide.set(n, kind = kindOf(n));
+	return kind;
+};
+const encode = (s, ref) => {
+	let out = "";
+	let run = 0;
+	let last = -1;
+	for (let i = 0; i < s.length;) {
+		let n = s.charCodeAt(i);
+		let width = 1;
+		if (n >= 55296 && n <= 57343) {
+			const low = s.charCodeAt(i + 1);
+			if (n <= 56319 && low >= 56320 && low <= 57343) {
+				n = 65536 + (n - 55296 << 10) + (low - 56320);
+				width = 2;
+			} else n = 65533;
+		}
+		let kind = kindAt(n);
+		if (kind === DROPPED) {
+			out += s.slice(run, i);
+			run = i + width;
+		} else {
+			const joined = kind >= JOINS && firstOf.get(n) === last;
+			kind &= -5;
+			if (joined || kind !== KEPT) {
+				out += s.slice(run, i);
+				if (joined) out += ref(8288);
+				if (kind === KEPT) run = i;
+				else {
+					out += kind === BLANKED ? " " : ref(n);
+					run = i + width;
+				}
+			}
+			last = n;
+		}
+		i += width;
+	}
+	return out + s.slice(run);
+};
+const code = (s, ref) => encode(s, ref).replace(MARKER, `${ref(8288)}"`).replace(HAZARD, (c) => ref(c.charCodeAt(0)));
+const esc = (s, quoted = false) => {
+	const plain = code(s, (n) => `#${n};`);
+	const out = quoted ? plain.replaceAll("\"", "#34;") : plain;
+	if (!out.trim()) return "#32;";
+	const turned = out.replace(DIRECTION, "$1#32;");
+	const opened = turned.includes("[[") ? turned.replace(DOUBLE_BRACKET, "#91;") : turned;
+	return opened.includes("C4") ? opened.replace(C4, "C#52;") : opened;
+};
+const or = (names) => [...names].sort(byText).join(" or ");
+const MARK_STYLES = {
+	breaks: "fill:#ffecee,stroke:#e72e3b,stroke-width:2.5px,color:#cd2834",
+	mayBreak: "fill:#fff3e6,stroke:#e8730c,stroke-width:2.5px,color:#b85a06"
+};
+function mermaidLines(chart) {
+	let next = 0;
+	const marks = [];
+	const used = /* @__PURE__ */ new Set();
+	const rules = {
+		breaks: /* @__PURE__ */ new Set(),
+		mayBreak: /* @__PURE__ */ new Set()
+	};
+	const region = (r) => {
+		const out = [];
+		const topIds = /* @__PURE__ */ new Map();
+		const nestedIds = /* @__PURE__ */ new Map();
+		const id = (path) => {
+			const top = path.length === 1;
+			const named = top ? topIds : nestedIds;
+			const k = top ? path[0] : tupleKey(path);
+			let s = named.get(k);
+			if (s === void 0) named.set(k, s = `s${next++}`);
+			return s;
+		};
+		const known = /* @__PURE__ */ new Map();
+		const idOf = (path) => {
+			let s = known.get(path);
+			if (s === void 0) known.set(path, s = id(path));
+			return s;
+		};
+		const tree = (prefix, indent, below) => {
+			const heads = /* @__PURE__ */ new Map();
+			for (const s of below) append(heads, s.path[prefix.length], s);
+			for (const [head, under] of heads) {
+				const path = [...prefix, head];
+				let leaf;
+				const inner = [];
+				for (const s of under) if (s.path.length > path.length) inner.push(s);
+				else leaf = s;
+				if (inner.length) {
+					out.push(`${indent}state "${esc(head, true)}" as ${id(path)} {`);
+					tree(path, indent + "  ", inner);
+					out.push(`${indent}}`);
+				} else if (leaf) {
+					const sid = idOf(leaf.path);
+					out.push(`${indent}${sid}: ${esc(head)}`);
+					let mark = leaf.breaks.length && !leaf.works ? "mayBreak" : void 0;
+					if (mark) {
+						for (const b of leaf.breaks) if (b.always) mark = "breaks";
+					}
+					if (mark) for (const b of leaf.breaks) rules[mark].add(b.rule.name);
+					const trail = [leaf.lead && "bugPath", leaf.repeats && "repeats"];
+					const color = leaf.group === void 0 ? void 0 : chart.colors[String(leaf.group)];
+					for (const cls of [
+						color,
+						mark,
+						...trail
+					]) if (cls) {
+						used.add(cls);
+						marks.push(`  class ${sid} ${cls}`);
+					}
+				}
+			}
+		};
+		tree([], "  ", r.states);
+		for (const s of r.states) if (s.start) out.push(`  [*] --> ${idOf(s.path)}`);
+		for (const s of r.steps) out.push(`  ${idOf(s.from)} --> ${idOf(s.to)}: ${esc(s.label + (s.when ? ` [${s.when}]` : ""))}`);
+		return out;
+	};
+	let body;
+	if (chart.regions.length > 1) {
+		body = [`  state "At the same time" as all {`];
+		for (const [i, r] of chart.regions.entries()) {
+			if (i) body.push("    --");
+			body.push(`    state "${esc(r.name, true)}" as r${i} {`);
+			for (const line of region(r)) body.push(`    ${line}`);
+			body.push("    }");
+		}
+		body.push("  }");
+	} else body = region(chart.regions[0]);
+	const legend = [];
+	for (const entry of [
+		...Object.entries(chart.colors),
+		[`Breaks ${or(rules.breaks)}`, "breaks"],
+		[`Breaks ${or(rules.mayBreak)} in some cases`, "mayBreak"],
+		[`Path to the ${or(chart.paths)} bug`, "bugPath"],
+		[`Repeats forever, so ${or(chart.loops)} breaks`, "repeats"]
+	]) if (used.has(entry[1])) legend.push(entry);
+	const lines = [];
+	const title = chart.title && code(chart.title, (n) => `fl°°${n}¶ß`).replaceAll("<", "fl°°60¶ß");
+	if (title) lines.push("---", `title: ${JSON.stringify(title)}`, "---");
+	lines.push("stateDiagram-v2");
+	if (chart.regions.length > 1) lines.push("  direction LR");
+	if (legend.length) {
+		lines.push(`  state "Legend" as legend {`);
+		for (const [i, [text]] of legend.entries()) lines.push(`    lg${i}: ${esc(text)}`);
+		lines.push("  }");
+		for (const [i, [, cls]] of legend.entries()) lines.push(`  class lg${i} ${cls}`);
+	}
+	for (const line of body) lines.push(line);
+	for (const [cls, style] of Object.entries(MARK_STYLES)) if (used.has(cls)) lines.push(`  classDef ${cls} ${style}`);
+	for (const line of marks) lines.push(line);
+	return lines;
+}
+const mermaid = (chart) => mermaidLines(chart).join("\n");
+export { mermaid, mermaidLines };

package/dist/pstack/skills/statechart/scripts/backends/plain-text.mjs

@@ -0,0 +1,62 @@
+import { EC, LEVEL } from "../ir.mjs";
+// runtime/skills/statechart/scripts/backends/plain-text.ts
+const PREFIX = {
+	[LEVEL.ERROR]: "Error: ",
+	[LEVEL.TLCBUG]: "TLC Bug: ",
+	[LEVEL.WARNING]: "Warning: ",
+	[LEVEL.STATE]: "State "
+};
+const MINUTE = 6e4;
+const HOUR = 36e5;
+const DAY = 864e5;
+const pad = (n) => String(n).padStart(2, "0");
+function runtime(ms) {
+	const t = new Date(ms > DAY ? ms - DAY : ms);
+	const [hh, mm, ss] = [
+		t.getUTCHours(),
+		t.getUTCMinutes(),
+		t.getUTCSeconds()
+	].map(pad);
+	if (ms > DAY) return `${Math.floor((t.getTime() - Date.UTC(t.getUTCFullYear(), 0, 1)) / DAY) + 1}d ${hh}h`;
+	if (ms > HOUR) return `${hh}h ${mm}min`;
+	if (ms > MINUTE) return `${mm}min ${ss}s`;
+	return `${ss}s`;
+}
+const firstLine = ({ code, level }, line) => {
+	if (code === EC.TLC_BACK_TO_STATE) return line.replace(/^(\d+): Back to state: /, "Back to state $1: ");
+	if (code === EC.TLC_FINISHED) return line.replace(/^Finished in (\d+)ms/, (_, ms) => `Finished in ${runtime(Number(ms))}`);
+	return (PREFIX[level] ?? "") + line;
+};
+const render = (m) => (m.beforeMarker ?? "") + firstLine(m, m.body.map((part) => typeof part === "string" ? part : render(part)).join("\n"));
+function* printed(parts) {
+	let warned = false;
+	let progress;
+	for (const part of parts) {
+		if (progress?.body.length && (typeof part === "string" || part.code !== EC.TLC_STATS)) yield render(progress);
+		progress = void 0;
+		if (typeof part === "string") {
+			yield part;
+			continue;
+		}
+		if (part.code === EC.TLC_SANY_START || part.code === EC.TLC_SANY_END) continue;
+		if (part.code === EC.TLC_PROGRESS_STATS) progress = part;
+		else if (part.body.length) yield render(part);
+		if (part.level === LEVEL.WARNING && !warned) {
+			yield "(Use the -nowarning option to disable this warning.)";
+			warned = true;
+		}
+	}
+	if (progress?.body.length) yield render(progress);
+}
+function* plainText(parts) {
+	let chunk = "";
+	for (const line of printed(parts)) {
+		chunk += `${line}\n`;
+		if (chunk.length >= 16777216) {
+			yield chunk;
+			chunk = "";
+		}
+	}
+	if (chunk) yield chunk;
+}
+export { plainText, runtime };

package/dist/pstack/skills/statechart/scripts/backends/report.mjs

@@ -0,0 +1,84 @@
+import { RERUN_STATES, hasSection, list, must, ruleKey } from "../ir.mjs";
+// runtime/skills/statechart/scripts/backends/report.ts
+const stepsOf = (story) => {
+	const path = [];
+	for (const { step, state } of story) {
+		const parts = [];
+		for (const [name, names] of Object.entries(state)) parts.push((name ? `${name} ` : "") + names.join(" / "));
+		path.push({
+			step,
+			state: parts.join(", ")
+		});
+	}
+	return path;
+};
+const forever = (loop, stutters) => {
+	const quoted = /* @__PURE__ */ new Set();
+	for (const p of loop) quoted.add(`"${p.state}"`);
+	const runs = [...quoted];
+	if (stutters) return `The run stops in ${runs[0]} forever.`;
+	return runs.length === 1 ? `The run stays in ${runs[0]} forever.` : `The run loops through ${list(runs)} forever.`;
+};
+const fenced = (text) => [
+	"```",
+	text,
+	"```"
+].join("\n");
+function report({ spec, graph, paths, rules, properties, stop, drawing, states }, found, chart, stories) {
+	let size = 0;
+	let arrows = 0;
+	for (const r of chart?.regions ?? []) {
+		size += r.states.length;
+		arrows += r.steps.length;
+	}
+	let past = 0;
+	let pastSteps = 0;
+	let excluded = 0;
+	for (const s of graph.states.values()) if (s.excluded) excluded++;
+	else if (s.past) past++;
+	for (const t of graph.steps) if (must(graph.states, t.to).past) pastSteps++;
+	const includes = (n) => chart ? `, and the chart includes ${n === 1 ? "it" : "them"}` : "";
+	const out = [
+		`# ${spec.module}`,
+		"",
+		paths ? `TLC reached ${states.complete && !states.cut && states.distinct > 500 ? `${states.distinct.toLocaleString("en-US")} states, more than` : "more states than"} the chart budget of 500, so ${chart ? `the chart draws only the bug paths: ${size} states and ${arrows} arrows` : "the command wrote no chart.mmd"}.` : `TLC reached ${graph.states.size - past - excluded} states and ${graph.steps.length - pastSteps} steps. The chart draws ${size} states and ${arrows} arrows.`
+	];
+	if (drawing) out.push(`TLC stopped the drawing run with exit ${drawing.status}, so the chart draws only the states that it reached before it stopped.`);
+	if (!paths && !drawing && graph.states.size === past + excluded) out.push(states.initial ? "Every initial state is outside the constraints, so TLC explores none of them." : "TLC found no state that satisfies Init, so no state can break a rule.");
+	if (past) out.push(`${past === 1 ? "1 state outside the constraints ends" : `${past} states outside the constraints each end`} a rule's path${includes(past)}. TLC checks the rules in a state outside the constraints, but it does not explore past it.`);
+	if (excluded) out.push(`${excluded === 1 ? "1 step that the constraints exclude ends" : `${excluded} steps that the constraints exclude each end`} a rule's path${includes(excluded)}. TLC checks the rules after such a step, but it does not take the step.`);
+	if (chart?.inside) out.push(`The chart does not draw ${chart.inside} steps that stay in one chart state.`);
+	if (chart?.quiet) out.push(`The view hides ${chart.quiet} steps, so the chart does not draw them.`);
+	for (const { rule, outcome } of rules) if (!paths && rule.kind === "deadlock" && outcome === "broken" && (drawing || hasSection(spec, "CONSTRAINT", "ACTION_CONSTRAINT"))) out.push(drawing ? "The chart marks only the deadlock that TLC reports, because the drawing run stopped before it reached every state." : "The chart marks only the deadlock that TLC reports. Under a CONSTRAINT or an ACTION_CONSTRAINT, a state with no step in the chart can still have steps that the constraints leave out, and TLC does not count it as a deadlock.");
+	if (chart?.lie) out.push(`${chart.lie} So the chart draws parent states in place of regions.`);
+	out.push(...chart?.notes ?? []);
+	const merged = [];
+	for (const k of ["VIEW", "SYMMETRY"]) if (hasSection(spec, k)) merged.push(k);
+	if (chart && merged.length) out.push(`With ${list(merged)}, TLC keeps one representative for each group of states that it counts as the same. An arrow can lead to the representative rather than to the state that the step reaches.`);
+	for (const bug of found) {
+		const steps = `${bug.path.length} step${bug.path.length === 1 ? "" : "s"}`;
+		out.push("", `## ${bug.rule.name} breaks`);
+		out.push(bug.rule.kind === "property" ? `TLC's counterexample is in tlc-${bug.rule.name}.out. It has ${steps}:` : `The shortest path has ${steps}:`);
+		const path = stepsOf(must(stories, bug));
+		for (const [i, p] of path.entries()) out.push(`${i}. ${p.step ? `${p.step}: ` : ""}${p.state}`);
+		if (bug.loop !== void 0) out.push(forever(path.slice(bug.loop), bug.stutters));
+	}
+	const drawn = /* @__PURE__ */ new Set();
+	for (const b of found) drawn.add(ruleKey(b.rule));
+	const holds = [];
+	const unchecked = [];
+	for (const { rule, outcome, messages } of [...rules, ...properties]) if (outcome === "holds") holds.push(rule.name);
+	else if (outcome === "not checked") unchecked.push(rule.name);
+	else if (messages && !drawn.has(ruleKey(rule))) out.push("", `## ${rule.name} breaks`, `TLC found a counterexample. It is in tlc-${rule.name}.out.`);
+	if (holds.length) out.push("", "## Rules that hold", holds.join(", "));
+	if (unchecked.length) out.push("", "## Rules not checked", unchecked.join(", "));
+	if (unchecked.length && states.cut) out.push(`After the first break, each TLC run stops at ${RERUN_STATES.toLocaleString("en-US")} distinct states. A run reached that bound before it checked ${unchecked.length === 1 ? "this rule" : "these rules"} in every state.`);
+	if (stop) out.push(...unchecked.length ? [`TLC stopped with exit ${stop.status} before it checked ${unchecked.length === 1 ? "this rule" : "these rules"}:`] : [
+		"",
+		"## TLC stopped",
+		`TLC stopped with exit ${stop.status}:`
+	], fenced(stop.message));
+	for (const p of properties) if (p.outcome === "holds" && p.initialOnly) out.push(`TLC checked ${p.rule.name} only in the initial states, because it has no [], <>, or ~>. List it as an INVARIANT to check every state.`);
+	return out.join("\n");
+}
+export { report };

package/dist/pstack/skills/statechart/scripts/frontends/config.mjs

@@ -0,0 +1,268 @@
+import { CHECK_DEADLOCK } from "../ir.mjs";
+// runtime/skills/statechart/scripts/frontends/config.ts
+const isListField = (field) => field === "invariants" || field === "properties" || field === "constraints" || field === "actionConstraints";
+const SECTIONS = /* @__PURE__ */ new Map();
+for (const section of [
+	{
+		key: "CONSTANT",
+		plural: "CONSTANTS"
+	},
+	{
+		key: CHECK_DEADLOCK,
+		field: "checkDeadlock"
+	},
+	{
+		key: "INIT",
+		field: "init",
+		undefinedNoun: "initial predicate"
+	},
+	{
+		key: "NEXT",
+		field: "next",
+		undefinedNoun: "next state action"
+	},
+	{
+		key: "SPECIFICATION",
+		field: "spec",
+		undefinedNoun: "name"
+	},
+	{
+		key: "VIEW",
+		field: "view",
+		undefinedNoun: "view function"
+	},
+	{
+		key: "SYMMETRY",
+		field: "symmetry",
+		undefinedNoun: "symmetry function"
+	},
+	{
+		key: "TYPE",
+		field: "type"
+	},
+	{
+		key: "TYPE_CONSTRAINT",
+		field: "typeConstraint"
+	},
+	{
+		key: "INVARIANT",
+		plural: "INVARIANTS",
+		field: "invariants",
+		undefinedNoun: "invariant"
+	},
+	{
+		key: "PROPERTY",
+		plural: "PROPERTIES",
+		field: "properties",
+		undefinedNoun: "property"
+	},
+	{
+		key: "CONSTRAINT",
+		plural: "CONSTRAINTS",
+		field: "constraints",
+		undefinedNoun: "constraint"
+	},
+	{
+		key: "ACTION_CONSTRAINT",
+		plural: "ACTION_CONSTRAINTS",
+		field: "actionConstraints",
+		undefinedNoun: "action constraint"
+	}
+]) {
+	SECTIONS.set(section.key, section);
+	if (section.plural) SECTIONS.set(section.plural, section);
+}
+const NAME = /^\w*[A-Za-z]\w*$/;
+const WORD = /\w+/y;
+const CONFIG_HOLDS = "A config can hold only names, numbers, strings, comments, and the symbols { } ( ) [ ] , = ! <-.";
+const shown = (c) => {
+	const code = c.codePointAt(0) ?? 0;
+	const hex = `U+${code.toString(16).toUpperCase().padStart(4, "0")}`;
+	if (code < 32 || code === 127) return hex;
+	return code < 127 ? `"${c}"` : `"${c}" (${hex})`;
+};
+function tokenizeConfig(text, cannot) {
+	if (text.startsWith("")) throw cannot(1, "The file starts with a byte order mark. Save it as UTF-8 without one.");
+	const tokens = [];
+	let line = 1;
+	let last = 1;
+	let i = 0;
+	const skip = (to) => {
+		for (; i < to; i++) {
+			last = line;
+			if (text[i] === "\n" || text[i] === "\r" && text[i + 1] !== "\n") line++;
+		}
+	};
+	const push = (image) => {
+		tokens.push({
+			image,
+			line
+		});
+		skip(i + image.length);
+	};
+	while (i < text.length) {
+		const c = text[i];
+		const two = text.slice(i, i + 2);
+		const start = line;
+		if (c === " " || c === "	" || c === "\n" || c === "\r") skip(i + 1);
+		else if (two === "\\*") {
+			const end = text.slice(i).search(/[\n\r]/);
+			skip(end < 0 ? text.length : i + end);
+		} else if (two === "(*") {
+			const marks = /\(\*|\*\)/g;
+			let depth = 0;
+			do {
+				marks.lastIndex = i;
+				const m = marks.exec(text);
+				if (!m) throw cannot(start, "A comment starts here and does not end.");
+				depth += m[0] === "(*" ? 1 : -1;
+				skip(m.index + 2);
+			} while (depth);
+		} else if (c === "\"") {
+			let j = i + 1;
+			while (text[j] !== "\"") {
+				const ch = text[j];
+				if (ch === void 0) throw cannot(start, "A string starts here and does not end.");
+				if (ch === "\n" || ch === "\r") throw cannot(start, "A string starts here and does not end on its line. Write \\n for a line break in a string.");
+				if (ch === "\0") throw cannot(start, "A string has the character U+0000.");
+				if (ch === "\\" && text[j + 1] !== void 0 && !"\"\\ntrf".includes(text[j + 1])) throw cannot(start, `A string has a backslash before ${shown(text[j + 1])}. A string can use only the escapes \\" \\\\ \\n \\t \\r \\f.`);
+				j += ch === "\\" ? 2 : 1;
+			}
+			push(text.slice(i, j + 1));
+		} else if (/\w/.test(c)) {
+			WORD.lastIndex = i;
+			const word = WORD.exec(text)?.[0] ?? c;
+			if (/^[WS]F_/.test(word)) throw cannot(start, `TLC reads ${word.slice(0, 3)} at the start of a word as a TLA+ keyword, so it cannot read ${word} as a name.`);
+			if (!/[A-Za-z]/.test(word) && word !== "_") {
+				if (/\D/.test(word)) throw cannot(start, `TLC splits ${word} into ${word.match(/\d+|_/g)?.join(" ")}, because a name needs a letter.`);
+				if (Number(word) > 2147483647) throw cannot(start, `TLC cannot read a number above 2147483647, such as ${word}.`);
+			}
+			push(word);
+		} else if (two === "<-") push(two);
+		else if ([
+			"[]",
+			"]_",
+			"==",
+			"=<",
+			"!!"
+		].includes(two)) throw cannot(start, `TLC reads ${two} as one TLA+ symbol, and a config cannot hold it.`);
+		else if ("{}()[],=!".includes(c)) push(c);
+		else {
+			const ch = String.fromCodePoint(text.codePointAt(i) ?? 0);
+			const where = ch > "" ? " outside a string" : "";
+			throw cannot(start, `It cannot read the character ${shown(ch)}${where}. ${CONFIG_HOLDS}`);
+		}
+	}
+	return {
+		tokens,
+		end: last
+	};
+}
+function readConfig({ file, text }) {
+	const refuse = (line, words) => /* @__PURE__ */ new Error(`TLC refuses the config ${file} at line ${line}. ${words}`);
+	const cannot = (line, words) => /* @__PURE__ */ new Error(`The command cannot read the config ${file} at line ${line}. ${words}`);
+	const { tokens, end } = tokenizeConfig(text, cannot);
+	const eof = {
+		image: "",
+		line: end
+	};
+	let at = 0;
+	const next = () => tokens[at++] ?? eof;
+	let deferred;
+	const defer = (error) => deferred ??= error;
+	const defined = (t, undefinedNoun) => {
+		if (!NAME.test(t.image)) defer(refuse(t.line, `The ${undefinedNoun} ${t.image} specified in the configuration file is not defined in the specification.`));
+	};
+	const name = (t, what) => {
+		if (SECTIONS.has(t.image)) defer(cannot(t.line, `TLC would read the keyword ${t.image} as ${what}.`));
+		else if (!NAME.test(t.image)) defer(cannot(t.line, `TLC would read ${t.image} as ${what}, and it is not a name.`));
+	};
+	const value = (t) => {
+		if (t === eof) throw refuse(t.line, "It was expecting a value, but did not find it.");
+		if (t.image === "{") {
+			t = next();
+			if (t.image === "}") return;
+			value(t);
+			while ((t = next()).image === ",") value(next());
+			if (t.image !== "}") throw refuse(t.line, "It was expecting }, but did not find it.");
+		} else if (SECTIONS.has(t.image)) defer(cannot(t.line, `TLC would read the keyword ${t.image} as a value.`));
+		else if (!NAME.test(t.image) && !/^(\d+|".*")$/.test(t.image)) defer(cannot(t.line, `TLC would read ${t.image} as a value. A value is a name, a number, a string, or a set in braces.`));
+	};
+	const constant = (t, loc) => {
+		name(t, "a constant name");
+		for (t = next(); t.image === "!"; t = next()) name(t = next(), "a constant name");
+		if (t.image === "<-") {
+			t = next();
+			if (t.image === "[") {
+				t = next();
+				if (t === eof) throw refuse(t.line, "Expected an identifier after <-[.");
+				name(t, "a module name");
+				t = next();
+				if (t.image !== "]") throw refuse(t.line, "It was expecting ], but did not find it.");
+				t = next();
+				if (t === eof) throw refuse(t.line, "Expected an identifier after <-[mod].");
+			} else if (t === eof) throw refuse(t.line, "Expected an identifier after <-.");
+			name(t, "the name after <-");
+			return;
+		}
+		if (t.image === "(") {
+			value(next());
+			while ((t = next()).image === ",") value(next());
+			if (t.image !== ")") throw refuse(loc, "TLC gives no reason here. An operator's arguments are one or more values in ( ), with commas between them.");
+			t = next();
+		}
+		if (t.image !== "=") throw refuse(t.line, "It was expecting = or <-, but did not find it.");
+		t = next();
+		if (t.image === "[") {
+			t = next();
+			if (t === eof) throw refuse(t.line, "Expected an identifier after =[.");
+			name(t, "a module name");
+			t = next();
+			if (t.image !== "]") throw refuse(t.line, "It was expecting ], but did not find it.");
+			t = next();
+		}
+		value(t);
+	};
+	const config = {
+		sections: [],
+		invariants: [],
+		properties: [],
+		constraints: [],
+		actionConstraints: []
+	};
+	for (let t = next(); t !== eof;) {
+		const keyword = t;
+		const section = SECTIONS.get(keyword.image);
+		if (!section) throw refuse(t.line, "It was expecting a keyword, but did not find it.");
+		const { key, field, undefinedNoun } = section;
+		const begin = at;
+		if (field === void 0) for (t = next(); t !== eof && !SECTIONS.has(t.image); t = next()) constant(t, keyword.line);
+		else if (isListField(field)) for (t = next(); t !== eof && !SECTIONS.has(t.image); t = next()) {
+			config[field].push(t.image);
+			defined(t, undefinedNoun);
+		}
+		else {
+			t = next();
+			if (t === eof) throw refuse(keyword.line, `The keyword ${keyword.image} was not followed by an identifier.`);
+			if (field === "checkDeadlock" && t.image !== "TRUE" && t.image !== "FALSE") throw refuse(t.line, "It was expecting TRUE or FALSE, but did not find it.");
+			if (config[field] !== void 0) throw refuse(keyword.line, `The keyword ${keyword.image} appeared twice.`);
+			if (field === "checkDeadlock") config[field] = t.image === "TRUE";
+			else {
+				config[field] = t.image;
+				if (SECTIONS.has(t.image)) defer(cannot(t.line, `TLC would read the keyword ${t.image} as the name after ${key}.`));
+				else if (undefinedNoun) defined(t, undefinedNoun);
+			}
+			t = next();
+		}
+		const images = [];
+		for (let k = begin; k < (t === eof ? tokens.length : at - 1); k++) images.push(tokens[k].image);
+		config.sections.push({
+			key,
+			line: keyword.line,
+			tokens: images
+		});
+	}
+	if (deferred) throw deferred;
+	return config;
+}
+export { NAME, readConfig };

package/dist/pstack/skills/statechart/scripts/frontends/dot.mjs

@@ -0,0 +1,67 @@
+import { parseValue } from "./value.mjs";
+// runtime/skills/statechart/scripts/frontends/dot.ts
+const unescapeDot = (s) => {
+	let i = s.indexOf("\\");
+	if (i === -1) return s;
+	let out = "";
+	let from = 0;
+	for (; i !== -1 && i + 1 < s.length; i = s.indexOf("\\", i)) {
+		const c = s[i + 1];
+		if (c === "\n" || c === "\r" || c === "\u2028" || c === "\u2029") {
+			i++;
+			continue;
+		}
+		out += s.slice(from, i) + (c === "n" ? "\n" : c);
+		i += 2;
+		from = i;
+	}
+	return out + s.slice(from);
+};
+const parseState = (label, parsed = /* @__PURE__ */ new Map()) => {
+	const pairs = [];
+	for (const part of (label.startsWith("/\\ ") ? label.slice(3) : label).split("\n/\\ ")) {
+		let pair = parsed.get(part);
+		if (!pair) {
+			const [, name, value] = /^(\w+)\s*=\s*([\s\S]*)$/.exec(part) ?? [];
+			if (!name) throw new Error(`cannot read the TLC state line "${part}"`);
+			parsed.set(part, pair = [name, parseValue(value)]);
+		}
+		pairs.push(pair);
+	}
+	return Object.fromEntries(pairs);
+};
+const linesOf = (input) => typeof input === "string" ? input.split("\n") : input;
+function parseDot(input) {
+	const states = /* @__PURE__ */ new Map();
+	const steps = /* @__PURE__ */ new Map();
+	const parsed = /* @__PURE__ */ new Map();
+	const owned = /* @__PURE__ */ new Map();
+	const own = (s) => {
+		let copy = owned.get(s);
+		if (copy === void 0) owned.set(copy = String(JSON.parse(JSON.stringify(s))), copy);
+		return copy;
+	};
+	for (const line of linesOf(input)) {
+		const edge = /^(-?\d+) -> (-?\d+) \[label="([^"]*)"/.exec(line);
+		if (edge) {
+			steps.set(edge.slice(1).join(" "), {
+				from: own(edge[1]),
+				to: own(edge[2]),
+				action: own(edge[3])
+			});
+			continue;
+		}
+		const node = /^(-?\d+) \[label="((?:[^"\\]|\\.)*)"(,style = filled)?/.exec(line);
+		if (node) states.set(own(node[1]), {
+			vars: parseState(unescapeDot(node[2]), parsed),
+			start: !!node[3],
+			breaks: []
+		});
+	}
+	for (const loose of steps.values()) if (!states.has(loose.from) || !states.has(loose.to)) throw new Error(`The TLC graph dump has a step ${loose.action} to or from a state that it does not list.`);
+	return {
+		states,
+		steps: [...steps.values()]
+	};
+}
+export { linesOf, parseDot, parseState };