dsh-pstack 0.2.0-beta.1 → 0.2.0

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

@@ -0,0 +1,94 @@
+import { EC, memo } from "../ir.mjs";
+import { BRACKET, isSpace, parseValue, tokenEnd, unreadable } from "./value.mjs";
+import { actionOf, messageState } from "./messages.mjs";
+// runtime/skills/statechart/scripts/frontends/marks.ts
+const markTexts = (chunk, top, inner) => {
+	if (top.length !== 2) return void 0;
+	const [a, b] = top;
+	const open = chunk.indexOf("<<", a);
+	const close = chunk.lastIndexOf(">>", b);
+	const end = chunk.trimEnd().length - 2;
+	if (open < 0 || chunk.slice(a + 1, open).trim() || chunk.slice(close + 2, b).trim()) return void 0;
+	if (!chunk.startsWith(">>", end)) return void 0;
+	const cuts = [open + 1];
+	for (const k of inner) if (k > open && k < close) cuts.push(k);
+	cuts.push(close);
+	const texts = [];
+	for (let k = 1; k < cuts.length; k++) texts.push(chunk.slice(cuts[k - 1] + 1, cuts[k]));
+	return {
+		values: texts,
+		rules: chunk.slice(b + 1, end)
+	};
+};
+const ruleNames = (v) => {
+	if (typeof v !== "object" || v.kind !== "set") return void 0;
+	const names = [];
+	for (const m of v.members) {
+		if (typeof m !== "string") return void 0;
+		names.push(m);
+	}
+	return names;
+};
+function* readMarks(messages, tag) {
+	const read = memo(parseValue);
+	const start = `"${tag}",`;
+	let chunk = "";
+	let depth = 0;
+	let top = [];
+	let inner = [];
+	for (const line of messages) {
+		if (typeof line !== "string") continue;
+		if (!chunk) {
+			if (!line.startsWith("<<") || !line.slice(2).trimStart().startsWith(start)) continue;
+			depth = 0;
+			top = [];
+			inner = [];
+		}
+		const base = chunk.length;
+		chunk += line + "\n";
+		let i = 0;
+		let last = 0;
+		while (i < line.length) {
+			const c = line.charCodeAt(i);
+			if (isSpace(c)) {
+				i++;
+				continue;
+			}
+			const j = tokenEnd(line, i);
+			if (j === -1) throw unreadable(line + "\n", last);
+			if (c === 44 && depth === 1) top.push(base + i);
+			else if (c === 44 && depth === 2) inner.push(base + i);
+			depth += BRACKET[c];
+			i = last = j;
+		}
+		if (depth > 0) continue;
+		const texts = markTexts(chunk, top, inner);
+		const values = [];
+		if (texts) for (const v of texts.values) values.push(read(v));
+		const broken = texts && ruleNames(read(texts.rules));
+		if (!broken) throw new Error(`TLC printed a mark that the command cannot read:\n${chunk.slice(0, 2e3)}`);
+		chunk = "";
+		yield {
+			values,
+			broken
+		};
+	}
+	if (chunk) throw new Error(`TLC's output ends inside a marked state, so the command cannot tell which rules it breaks:\n${chunk.slice(0, 2e3)}`);
+}
+function readCounterexample(messages) {
+	const trace = [];
+	for (const m of messages) {
+		if (typeof m === "string") continue;
+		const action = m.code === EC.TLC_STATE_PRINT2 ? actionOf(m) : void 0;
+		if (action !== void 0) trace.push({
+			action,
+			vars: messageState(m)
+		});
+		else if (m.code === EC.TLC_INVARIANT_VIOLATED_INITIAL || m.code === EC.TLC_PROPERTY_VIOLATED_INITIAL) trace.push({
+			action: "",
+			vars: messageState(m)
+		});
+	}
+	return trace;
+}
+export { readCounterexample, readMarks };

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

@@ -0,0 +1,48 @@
+import { linesOf, parseState } from "./dot.mjs";
+// runtime/skills/statechart/scripts/frontends/messages.ts
+const START = /@!@!@STARTMSG (\d+):(\d+) @!@!@$/;
+const END = /^@!@!@ENDMSG \d+ @!@!@$/;
+const isCutMarker = (lastLine) => lastLine.startsWith("@!@!@");
+function cutMessage(open) {
+	for (let i = open.length - 1; i > 0 && !open[i].body.length; i--) open[i - 1].body.pop();
+	return open[0]?.body.length ? open[0] : void 0;
+}
+function* readMessages(tlcOut) {
+	const lines = linesOf(tlcOut)[Symbol.iterator]();
+	const open = [];
+	try {
+		for (let next = lines.next(); !next.done;) {
+			const line = next.value;
+			next = lines.next();
+			if (next.done && (!line || isCutMarker(line))) break;
+			const start = START.exec(line);
+			if (start) {
+				const message = {
+					code: Number(start[1]),
+					level: Number(start[2]),
+					body: []
+				};
+				if (start.index) message.beforeMarker = line.slice(0, start.index);
+				open.at(-1)?.body.push(message);
+				open.push(message);
+			} else if (END.test(line)) {
+				const done = open.pop();
+				if (done && !open.length) yield done;
+			} else if (open.length) open[open.length - 1].body.push(line);
+			else yield line;
+		}
+	} finally {
+		lines.return?.();
+	}
+	const cut = cutMessage(open);
+	if (cut) yield cut;
+}
+const textOf = ({ body }) => body.filter((part) => typeof part === "string").join("\n");
+const actionOf = (m) => /^\d+: (?:Back to state: )?<([^\s>]+)/.exec(textOf(m))?.[1];
+const messageState = (m) => {
+	const lines = textOf(m).split("\n");
+	const body = [];
+	for (let i = 1; i < lines.length && lines[i].trim(); i++) body.push(lines[i]);
+	return parseState(body.join("\n"));
+};
+export { actionOf, messageState, readMessages, textOf };

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

@@ -0,0 +1,101 @@
+import { NAME } from "./config.mjs";
+// runtime/skills/statechart/scripts/frontends/spec.ts
+function readChecks({ configFile, config }) {
+	const refuse = (words) => /* @__PURE__ */ new Error(`TLC refuses the config ${configFile}. ${words}`);
+	if (config.spec && (config.init || config.next)) throw refuse("The configuration file cannot specify both INIT/NEXT and SPECIFICATION fields.");
+	if (!config.spec && !config.init) throw refuse("The configuration file did not specify the initial state predicate.");
+	const written = [];
+	for (const s of config.sections) if (![
+		"INVARIANT",
+		"PROPERTY",
+		"CHECK_DEADLOCK"
+	].includes(s.key)) written.push(s);
+	return {
+		invariants: config.invariants,
+		properties: config.properties,
+		deadlock: config.checkDeadlock !== false,
+		written
+	};
+}
+const ENTITIES = {
+	amp: "&",
+	apos: "'",
+	gt: ">",
+	lt: "<",
+	quot: "\""
+};
+const decode = (text) => text.replace(/&(#x?)?(\w+);/g, (_, number, name) => number ? String.fromCodePoint(Number.parseInt(name, number === "#x" ? 16 : 10)) : ENTITIES[name]);
+function parseXml(xml) {
+	const document = {
+		tag: "",
+		text: "",
+		children: []
+	};
+	const open = [document];
+	for (const [, close, tag, empty, text] of xml.matchAll(/<(\/?)([^\s/>?!]+)[^>]*?(\/?)>|<[?!][^>]*>|([^<]+)/g)) {
+		const parent = open[open.length - 1];
+		if (text !== void 0) parent.text += decode(text);
+		else if (close) open.pop();
+		else if (tag) {
+			const node = {
+				tag,
+				text: "",
+				children: []
+			};
+			parent.children.push(node);
+			if (!empty) open.push(node);
+		}
+	}
+	return document;
+}
+const child = (node, tag) => node?.children.find((c) => c.tag === tag);
+const textOf = (node, tag) => child(node, tag)?.text ?? "";
+const VARIABLE_KIND = "3";
+function readSany(xml) {
+	const modules = child(parseXml(xml), "modules");
+	const symbols = /* @__PURE__ */ new Map();
+	for (const entry of child(modules, "context")?.children ?? []) symbols.set(textOf(entry, "UID"), entry.children[1]);
+	const root = textOf(modules, "RootModule");
+	let module;
+	for (const node of symbols.values()) if (node.tag === "ModuleNode" && textOf(node, "uniquename") === root) module = node;
+	const definitions = /* @__PURE__ */ new Map();
+	const variables = [];
+	for (const ref of module?.children ?? []) {
+		if (ref.tag !== "OpDeclNodeRef" && ref.tag !== "UserDefinedOpKindRef") continue;
+		const uid = textOf(ref, "UID");
+		const node = symbols.get(uid);
+		if (!node) continue;
+		const name = textOf(node, "uniquename");
+		definitions.set(name, node);
+		if (node.tag === "OpDeclNode" && textOf(node, "kind") === VARIABLE_KIND) variables.push({
+			uid: Number(uid),
+			name
+		});
+	}
+	variables.sort((a, b) => a.uid - b.uid);
+	return {
+		variables: variables.map((v) => v.name),
+		definitions
+	};
+}
+function readSpec({ module, sany, checks }) {
+	return {
+		module,
+		variables: sany.variables,
+		...checks
+	};
+}
+const STATE_LEVEL = 1;
+function initialOnlyProperties({ definitions }, { written, properties }) {
+	const replaced = /* @__PURE__ */ new Map();
+	for (const s of written) if (s.key === "CONSTANT") {
+		for (let i = 1; i + 1 < s.tokens.length; i++) if (s.tokens[i] === "<-" && NAME.test(s.tokens[i + 1])) replaced.set(s.tokens[i - 1], s.tokens[i + 1]);
+	}
+	const names = /* @__PURE__ */ new Set();
+	for (const name of properties) {
+		const definition = definitions.get(replaced.get(name) ?? name);
+		if (definition && Number(textOf(definition, "level")) <= STATE_LEVEL) names.add(name);
+	}
+	return names;
+}
+export { initialOnlyProperties, readChecks, readSany, readSpec };

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

@@ -0,0 +1,39 @@
+import { EC } from "../ir.mjs";
+import { actionOf, messageState, textOf } from "./messages.mjs";
+// runtime/skills/statechart/scripts/frontends/trace.ts
+function readTrace(messages) {
+	const seq = [];
+	for (const m of messages) {
+		if (typeof m === "string") continue;
+		if (m.code === EC.TLC_STATE_PRINT3) return {
+			seq,
+			loop: seq.length - 1
+		};
+		const back = m.code === EC.TLC_BACK_TO_STATE && /^(\d+): Back to state: /.exec(textOf(m));
+		if (back) {
+			const loop = Number(back[1]) - 1;
+			seq.push({
+				action: actionOf(m) ?? "",
+				vars: seq[loop]?.vars
+			});
+			return {
+				seq,
+				loop
+			};
+		}
+		const action = m.code === EC.TLC_STATE_PRINT2 ? actionOf(m) : void 0;
+		if (action !== void 0) seq.push({
+			action,
+			vars: messageState(m)
+		});
+		else if (m.code === EC.TLC_INVARIANT_VIOLATED_INITIAL || m.code === EC.TLC_PROPERTY_VIOLATED_INITIAL) seq.push({
+			action: "",
+			vars: messageState(m)
+		});
+	}
+	return {
+		seq,
+		loop: void 0
+	};
+}
+export { readTrace };

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

@@ -0,0 +1,180 @@
+// runtime/skills/statechart/scripts/frontends/value.ts
+const BRACKET = /* @__PURE__ */ new Int8Array(128);
+for (const c of "<{[(") BRACKET[c.charCodeAt(0)] = 1;
+for (const c of ">}])") BRACKET[c.charCodeAt(0)] = -1;
+const PUNCT = /* @__PURE__ */ new Map([
+	[60, "<<"],
+	[62, ">>"],
+	[124, "|->"],
+	[58, ":>"],
+	[64, "@@"],
+	[46, ".."]
+]);
+const SPACE = /\s/;
+const isSpace = (c) => c === 32 || c >= 9 && c <= 13 || c > 127 && SPACE.test(String.fromCharCode(c));
+const isDigit = (c) => c >= 48 && c <= 57;
+const isWord = (c) => isDigit(c) || c >= 65 && c <= 90 || c >= 97 && c <= 122 || c === 95;
+const isLineEnd = (c) => c === 10 || c === 13 || c === 8232 || c === 8233;
+const tokenEnd = (s, i) => {
+	const c = s.charCodeAt(i);
+	if (c === 34) {
+		for (let j = i + 1; j < s.length; j++) {
+			const d = s.charCodeAt(j);
+			if (d === 34) return j + 1;
+			if (d === 92 && (++j >= s.length || isLineEnd(s.charCodeAt(j)))) return -1;
+		}
+		return -1;
+	}
+	const punct = PUNCT.get(c);
+	if (punct) return s.startsWith(punct, i) ? i + punct.length : -1;
+	if (BRACKET[c] || c === 44) return i + 1;
+	let j = i + 1;
+	if (c === 45 || isDigit(c)) {
+		while (isDigit(s.charCodeAt(j))) j++;
+		return c === 45 && j === i + 1 ? -1 : j;
+	}
+	if (!isWord(c)) return -1;
+	while (isWord(s.charCodeAt(j))) j++;
+	return j;
+};
+const unreadable = (text, pos) => /* @__PURE__ */ new Error(`cannot read TLA+ value at "${text.slice(pos, pos + 20)}"`);
+const INT = /^-?\d+$/;
+const NAME = /^\w*[A-Za-z]\w*$/;
+const UNESCAPED = {
+	"\"": "\"",
+	"\\": "\\",
+	n: "\n",
+	t: "	",
+	r: "\r",
+	f: "\f"
+};
+const models = /* @__PURE__ */ new Map();
+const model = (name) => {
+	let v = models.get(name);
+	if (v === void 0) models.set(name, v = {
+		kind: "model",
+		name
+	});
+	return v;
+};
+function parseValue(text) {
+	const tokens = [];
+	const starts = [];
+	for (let pos = 0;;) {
+		while (pos < text.length && isSpace(text.charCodeAt(pos))) pos++;
+		if (pos === text.length) break;
+		const end = tokenEnd(text, pos);
+		if (end === -1) throw unreadable(text, pos);
+		tokens.push(text.slice(pos, end));
+		starts.push(pos);
+		pos = end;
+	}
+	let i = 0;
+	const fail = () => {
+		throw unreadable(text, i < starts.length ? starts[Math.max(i - 1, 0)] : text.length);
+	};
+	const next = () => i < tokens.length ? tokens[i++] : fail();
+	const eat = (t) => {
+		if (next() !== t) fail();
+	};
+	const items = (close, item) => {
+		const out = [];
+		if (tokens[i] === close) {
+			i++;
+			return out;
+		}
+		for (;;) {
+			out.push(item());
+			const t = next();
+			if (t === close) return out;
+			if (t !== ",") fail();
+		}
+	};
+	const string = (t) => {
+		let s = "";
+		for (let j = 1, from = 1;;) {
+			const k = t.indexOf("\\", j);
+			if (k === -1 || k >= t.length - 1) return s + t.slice(from, -1);
+			const c = UNESCAPED[t[k + 1]];
+			if (c === void 0) fail();
+			s += t.slice(from, k) + c;
+			j = from = k + 2;
+		}
+	};
+	const value = () => {
+		const t = next();
+		switch (t) {
+			case "TRUE": return true;
+			case "FALSE": return false;
+			case "{": return {
+				kind: "set",
+				members: items("}", value)
+			};
+			case "<<": {
+				const values = items(">>", value);
+				const keys = [];
+				for (let k = 1; k <= values.length; k++) keys.push(k);
+				return {
+					kind: "function",
+					printedAs: "tuple",
+					keys,
+					values
+				};
+			}
+			case "[": {
+				const keys = [];
+				const values = [];
+				items("]", () => {
+					const name = next();
+					if (!NAME.test(name)) fail();
+					eat("|->");
+					keys.push(name);
+					values.push(value());
+				});
+				return {
+					kind: "function",
+					printedAs: "record",
+					keys,
+					values
+				};
+			}
+			case "(": {
+				const keys = [];
+				const values = [];
+				do {
+					keys.push(value());
+					eat(":>");
+					values.push(value());
+				} while (next() === "@@");
+				if (tokens[i - 1] !== ")") fail();
+				return {
+					kind: "function",
+					printedAs: "pairs",
+					keys,
+					values
+				};
+			}
+		}
+		if (t.charCodeAt(0) === 34) return string(t);
+		if (INT.test(t)) {
+			if (tokens[i] !== "..") return Number(t);
+			i++;
+			const hi = next();
+			if (!INT.test(hi)) fail();
+			return {
+				kind: "interval",
+				lo: Number(t),
+				hi: Number(hi)
+			};
+		}
+		if (NAME.test(t)) return model(t);
+		return fail();
+	};
+	const out = value();
+	if (i < tokens.length) {
+		i++;
+		fail();
+	}
+	return out;
+}
+export { BRACKET, isSpace, parseValue, tokenEnd, unreadable };

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

@@ -0,0 +1,40 @@
+import { EC } from "../ir.mjs";
+import { textOf } from "./messages.mjs";
+// runtime/skills/statechart/scripts/frontends/verdict.ts
+const NAMED = /* @__PURE__ */ new Map([
+	[EC.TLC_INVARIANT_VIOLATED_INITIAL, ["invariant", /^Invariant (.+) is violated by the initial/]],
+	[EC.TLC_INVARIANT_VIOLATED_BEHAVIOR, ["invariant", /^Invariant (.+) is violated\.$/m]],
+	[EC.TLC_PROPERTY_VIOLATED_INITIAL, ["property", /^Property (.+) is violated by the initial/]],
+	[EC.TLC_ACTION_PROPERTY_VIOLATED_BEHAVIOR, ["property", /^Action property (.+) is violated\.$/m]]
+]);
+const DISTINCT = /* @__PURE__ */ new Map([
+	[EC.TLC_INIT_GENERATED1, /(\d+) distinct states? generated/],
+	[EC.TLC_INIT_GENERATED2, /with (\d+) of them distinct/],
+	[EC.TLC_STATS, /(\d+) distinct states found/]
+]);
+function readVerdict(messages) {
+	let broke;
+	let distinct = 0;
+	let initial = 0;
+	for (const m of messages) {
+		if (typeof m === "string") continue;
+		const count = DISTINCT.get(m.code)?.exec(textOf(m));
+		if (count) distinct = Math.max(distinct, Number(count[1]));
+		if (m.code === EC.TLC_INIT_GENERATED1 || m.code === EC.TLC_INIT_GENERATED2) initial = Number(/(\d+) (?:distinct )?states? generated/.exec(textOf(m))?.[1] ?? 0);
+		if (broke) continue;
+		if (m.code === EC.TLC_DEADLOCK_REACHED) broke = { kind: "deadlock" };
+		else if (m.code === EC.TLC_TEMPORAL_PROPERTY_VIOLATED) broke = { kind: "temporal" };
+		const named = NAMED.get(m.code);
+		const name = named?.[1].exec(textOf(m))?.[1];
+		if (named && name) broke = {
+			kind: named[0],
+			name
+		};
+	}
+	return {
+		broke,
+		distinct,
+		initial
+	};
+}
+export { readVerdict };

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

@@ -0,0 +1,99 @@
+import { checked, list } from "../ir.mjs";
+// runtime/skills/statechart/scripts/frontends/view.ts
+const projected = /* @__PURE__ */ new WeakMap();
+const json = (v) => {
+	if (typeof v !== "object") return v;
+	if (v.kind === "model") return v.name;
+	let j = projected.get(v);
+	if (j === void 0) {
+		if (v.kind === "interval") {
+			const members = [];
+			for (let k = v.lo; k <= v.hi; k++) members.push(k);
+			j = members;
+		} else if (v.kind === "set") {
+			const members = [];
+			for (const m of v.members) members.push(json(m));
+			j = members;
+		} else {
+			const fields = [];
+			for (let i = 0; i < v.keys.length; i++) {
+				const k = json(v.keys[i]);
+				fields.push([typeof k === "object" ? JSON.stringify(k) : String(k), json(v.values[i])]);
+			}
+			j = Object.fromEntries(fields);
+		}
+		projected.set(v, j);
+	}
+	return j;
+};
+const projectedVars = /* @__PURE__ */ new WeakMap();
+const jsonVars = (vars) => {
+	let j = projectedVars.get(vars);
+	if (j === void 0) {
+		const fields = [];
+		for (const [name, v] of Object.entries(vars)) fields.push([name, json(v)]);
+		j = Object.fromEntries(fields);
+		projectedVars.set(vars, j);
+	}
+	return j;
+};
+const THEME_COLORS = [
+	"blue",
+	"orange",
+	"purple",
+	"yellow",
+	"teal",
+	"tan",
+	"pink"
+];
+const isFunction = (v) => typeof v === "function";
+const isPlainObject = (v) => {
+	if (typeof v !== "object" || v === null) return false;
+	const proto = Object.getPrototypeOf(v);
+	return proto === Object.prototype || proto === null;
+};
+const isString = (v) => typeof v === "string";
+const VIEW_EXPORTS = [
+	"state",
+	"step",
+	"group",
+	"colors",
+	"title"
+];
+function checkView(view, inspect) {
+	const literal = (v) => typeof v === "string" ? JSON.stringify(v) : inspect(v, { breakLength: Infinity });
+	const extra = [];
+	for (const name of Object.keys(view)) if (!VIEW_EXPORTS.includes(name)) extra.push(name);
+	if (extra.length) throw new Error(`The view exports ${list(extra)}, which the command does not read. Export only ${list(VIEW_EXPORTS)}.`);
+	const wrong = [];
+	const pick = (name, kind, fits) => {
+		const v = view[name];
+		if (v === void 0 || fits(v)) return v;
+		wrong.push(`${name} must be ${kind}`);
+	};
+	const state = pick("state", "a function", isFunction);
+	const step = pick("step", "a function", isFunction);
+	const group = pick("group", "a function", isFunction);
+	const exported = pick("colors", "a plain object", isPlainObject);
+	const title = pick("title", "a string", isString);
+	if (wrong.length) throw new Error(`The view's ${list(wrong)}.`);
+	if (group !== void 0 && exported === void 0) throw new Error("The view exports group() but no colors. Give each group a color in colors.");
+	const colors = Object.create(null);
+	const bad = [];
+	for (const [name, color] of Object.entries(exported ?? {})) if (typeof color === "string" && THEME_COLORS.includes(color)) colors[name] = color;
+	else bad.push(`${JSON.stringify(name)} the color ${literal(color)}`);
+	if (bad.length) throw new Error(`The view's colors give ${list(bad)}. Give each group ${list(THEME_COLORS, "or")}.`);
+	return {
+		state: state && ((vars) => state(jsonVars(vars))),
+		step: step && ((action, from, to) => step(action, jsonVars(from), jsonVars(to))),
+		group: group && ((vars) => {
+			const g = group(jsonVars(vars));
+			if (g !== void 0 && !Object.hasOwn(colors, typeof g === "symbol" ? g : String(g))) throw new Error(`The view's group() returned ${literal(g)}, which colors does not name. Give each group a color in colors.`);
+			return g;
+		}),
+		colors,
+		title,
+		[checked]: true
+	};
+}
+export { checkView, json };