dsh-pstack 0.1.0 → 0.2.0-beta.3

package/dist/pstack/skills/statechart/scripts/run.mjs

@@ -0,0 +1,440 @@
+import { LEVEL, PART, hasSection, must, ruleKey, stateRules } from "./ir.mjs";
+import { plainText } from "./backends/plain-text.mjs";
+import { boundRun, chartRun, configText } from "./backends/cfg.mjs";
+import { readConfig } from "./frontends/config.mjs";
+import { parseDot } from "./frontends/dot.mjs";
+import { readMessages } from "./frontends/messages.mjs";
+import { readCounterexample, readMarks } from "./frontends/marks.mjs";
+import { initialOnlyProperties, readChecks, readSany, readSpec } from "./frontends/spec.mjs";
+import { readTrace } from "./frontends/trace.mjs";
+import { readVerdict } from "./frontends/verdict.mjs";
+import { addPast, deadEnds, finder, lasso, mark } from "./passes/annotate.mjs";
+import { pathGraph } from "./passes/paths.mjs";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFile, spawn } from "node:child_process";
+import { inspect } from "node:util";
+import { Buffer } from "node:buffer";
+import { randomBytes } from "node:crypto";
+// runtime/skills/statechart/scripts/run.ts
+function* fileLines(file) {
+	const fd = fs.openSync(file, "r");
+	try {
+		let buf = Buffer.allocUnsafe(PART);
+		let kept = 0;
+		for (;;) {
+			if (kept === buf.length) buf = Buffer.concat([buf], buf.length * 2);
+			const n = fs.readSync(fd, buf, kept, buf.length - kept, null);
+			if (!n) break;
+			const end = kept + n;
+			const cut = buf.lastIndexOf(10, end - 1);
+			if (cut === -1) {
+				kept = end;
+				continue;
+			}
+			yield* buf.toString("utf8", 0, cut).split("\n");
+			kept = buf.copy(buf, 0, cut + 1, end);
+		}
+		yield buf.toString("utf8", 0, kept);
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+const TLC_TOOL = "http:tla2tools[url=https://github.com/tlaplus/tlaplus/releases/download/v1.7.4/tla2tools.jar,checksum=sha256:936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88]@1.7.4";
+const JAVA_TOOL = "java@temurin-25";
+const PINNED_FLAGS = [
+	"-workers",
+	"1",
+	"-fp",
+	"0",
+	"-lncheck",
+	"final"
+];
+const runChild = (file, args, options) => new Promise((resolve) => {
+	execFile(file, args, {
+		encoding: "utf8",
+		maxBuffer: 1 << 30,
+		...options
+	}, (error, stdout, stderr) => resolve({
+		status: error ? typeof error.code === "number" ? error.code : null : 0,
+		stdout,
+		stderr,
+		error: typeof error?.code === "string" ? error : void 0
+	}));
+});
+const killGroup = (pid) => new Promise((resolve) => spawn("/bin/sh", [
+	"-c",
+	"kill -s KILL -- \"-$1\"",
+	"sh",
+	String(pid)
+], { stdio: "ignore" }).on("exit", resolve));
+const messageOf = (error) => typeof error === "object" && error !== null && "message" in error && typeof error.message === "string" ? error.message : inspect(error);
+const joined = (files) => {
+	const fds = [];
+	const sizes = [];
+	for (const f of files) {
+		const fd = fs.openSync(f, "r");
+		fds.push(fd);
+		sizes.push(fs.fstatSync(fd).size);
+	}
+	return { *[Symbol.iterator]() {
+		for (let f = 0; f < fds.length; f++) for (let pos = 0; pos < sizes[f];) {
+			const buf = Buffer.allocUnsafe(Math.min(PART, sizes[f] - pos));
+			const n = fs.readSync(fds[f], buf, 0, buf.length, pos);
+			if (!n) break;
+			pos += n;
+			yield buf.subarray(0, n);
+		}
+	} };
+};
+const utf8 = new TextDecoder("utf-8", { ignoreBOM: true });
+function* outputLines(output) {
+	let rest = /* @__PURE__ */ new Uint8Array(0);
+	for (const part of output) {
+		const buf = rest.length ? Buffer.concat([rest, part]) : part;
+		const cut = buf.lastIndexOf(10);
+		if (cut === -1) {
+			rest = buf;
+			continue;
+		}
+		yield* utf8.decode(buf.subarray(0, cut)).split("\n");
+		rest = buf.subarray(cut + 1);
+	}
+	yield utf8.decode(rest);
+}
+const messagesOf = (output) => ({ [Symbol.iterator]: () => readMessages(outputLines(output)) });
+const runToFiles = (file, args, { out, ...options }) => new Promise((resolve) => {
+	const files = [`${out}.stdout`, `${out}.stderr`];
+	const fds = [];
+	for (const f of files) fds.push(fs.openSync(f, "w"));
+	let child;
+	try {
+		child = spawn(file, args, {
+			...options,
+			stdio: ["ignore", ...fds]
+		});
+	} finally {
+		for (const fd of fds) fs.closeSync(fd);
+	}
+	let error;
+	const settle = (code) => resolve({
+		status: error ? null : code,
+		stdout: files[0],
+		output: joined(files),
+		error
+	});
+	child.on("error", (e) => {
+		error = e;
+		if (child.pid === void 0) settle(null);
+	});
+	child.on("close", (code) => {
+		if (child.pid !== void 0) settle(code);
+	});
+});
+async function findTlc(cwd) {
+	const { TLA2TOOLS, JAVA } = process.env;
+	if (TLA2TOOLS) return {
+		jar: TLA2TOOLS,
+		java: JAVA || "java"
+	};
+	const mise = (...args) => runChild("mise", args, {
+		cwd,
+		env: {
+			...process.env,
+			MISE_CEILING_PATHS: cwd
+		}
+	});
+	const where = () => Promise.all([mise("where", TLC_TOOL), mise("which", "java", "--tool", JAVA_TOOL)]);
+	let found = await where();
+	if (found.some((r) => r.status !== 0)) {
+		const r = await mise("install", JAVA_TOOL, TLC_TOOL);
+		if (r.status !== 0) throw new Error(`Cannot find TLC: mise install failed: ${r.error?.message ?? r.stderr.trim()}\nOr set TLA2TOOLS to the path of tla2tools.jar, and JAVA to a java binary (Java 11 or later).`);
+		found = await where();
+	}
+	return {
+		jar: path.join(found[0].stdout.trim(), "tla2tools.jar"),
+		java: JAVA || found[1].stdout.trim()
+	};
+}
+const exitClass = (status) => status === 0 ? 0 : status === 11 || status === 12 || status === 13 ? 1 : 2;
+const tail = (r) => {
+	if (r.error) return r.error.message;
+	const kept = [];
+	let size = 0;
+	for (const chunk of plainText(messagesOf(r.output))) {
+		kept.push(chunk);
+		size += chunk.length;
+		while (size - kept[0].length >= 1 << 28) size -= kept.shift().length;
+	}
+	return kept.join("").trim().split("\n").slice(-30).join("\n");
+};
+const stopOf = (r) => {
+	const errors = [];
+	for (const m of r.error ? [] : messagesOf(r.output)) if (typeof m !== "string" && (m.level === LEVEL.ERROR || m.level === LEVEL.TLCBUG || errors.length && m.level === LEVEL.STATE)) errors.push(m);
+	if (!errors.length) return {
+		status: r.status,
+		message: tail(r)
+	};
+	const lines = [...plainText(errors)].join("").trim().split("\n");
+	if (lines.length > 40) lines.splice(40, Infinity, `... ${lines.length - 40} more lines`);
+	return {
+		status: r.status,
+		message: lines.join("\n")
+	};
+};
+const names = (rules, kind) => {
+	const found = [];
+	for (const rule of rules) if (rule.kind === kind) found.push(rule.name);
+	return found;
+};
+const brokenRule = (rules, broke) => {
+	if (broke.kind === "temporal") return void 0;
+	for (const rule of rules) if (rule.kind === broke.kind && (broke.kind === "deadlock" || rule.name === broke.name)) return rule;
+	if (broke.kind === "invariant") {
+		for (const rule of rules) if (rule.kind === "property" && rule.name === broke.name) return rule;
+	}
+};
+function* only(marks, rules) {
+	for (const { values, broken } of marks) {
+		const kept = [];
+		for (const name of broken) if (rules.has(name)) kept.push(name);
+		if (kept.length) yield {
+			values,
+			broken: kept
+		};
+	}
+}
+async function check(specFile, configFile) {
+	const cfg = readConfig({
+		file: configFile,
+		text: fs.readFileSync(configFile, "utf8")
+	});
+	const checks = readChecks({
+		configFile,
+		config: cfg
+	});
+	const folder = path.dirname(path.resolve(specFile));
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-"));
+	try {
+		const tlc = await findTlc(dir);
+		const config = (name, sections, extra) => {
+			fs.writeFileSync(path.join(dir, `${name}.cfg`), configText(sections, extra));
+			return [
+				`-metadir`,
+				path.join(dir, `meta-${name}`),
+				"-config",
+				path.join(dir, `${name}.cfg`)
+			];
+		};
+		const runJava = (name, main, args, jvm = []) => {
+			const tmp = path.join(dir, `tmp-${name}`);
+			fs.mkdirSync(tmp);
+			return runToFiles(tlc.java, [
+				`-Djava.io.tmpdir=${tmp}`,
+				`-DTLA-Library=${folder}`,
+				...jvm,
+				"-cp",
+				tlc.jar,
+				main,
+				...args
+			], {
+				cwd: dir,
+				out: path.join(dir, name),
+				env: process.platform === "darwin" ? process.env : {
+					...process.env,
+					LC_ALL: "C.UTF-8"
+				}
+			});
+		};
+		const xml = await runJava("sany", "tla2sany.xml.XMLExporter", [
+			"-o",
+			"-I",
+			folder,
+			path.resolve(specFile)
+		], ["-XX:TieredStopAtLevel=1"]);
+		if (xml.status !== 0) throw new Error(`SANY could not read ${specFile} (exit ${xml.status}):\n${tail(xml)}`);
+		const sany = readSany(fs.readFileSync(xml.stdout, "utf8"));
+		const module = path.basename(specFile, ".tla");
+		const spec = {
+			...readSpec({
+				module,
+				sany,
+				checks
+			}),
+			folder
+		};
+		const rules = stateRules(spec);
+		const all = [...rules];
+		for (const name of spec.properties) all.push({
+			kind: "property",
+			name
+		});
+		const verdicts = /* @__PURE__ */ new Map();
+		const decide = (rule, outcome, r) => verdicts.set(ruleKey(rule), {
+			rule,
+			outcome,
+			messages: r && messagesOf(r.output)
+		});
+		const judge = async () => {
+			const groups = [all];
+			let first;
+			let stop;
+			const states = {
+				distinct: 0,
+				initial: 0,
+				complete: false,
+				cut: false
+			};
+			for (let k = 1; groups.length;) {
+				const group = [];
+				for (const rule of groups[0]) if (!verdicts.has(ruleKey(rule))) group.push(rule);
+				if (first && !group.length) {
+					groups.shift();
+					continue;
+				}
+				const name = `verdict-${k++}`;
+				const extra = [];
+				const invariants = names(group, "invariant");
+				const properties = names(group, "property");
+				if (invariants.length) extra.push(`INVARIANT ${invariants.join(" ")}`);
+				if (properties.length) extra.push(`PROPERTY ${properties.join(" ")}`);
+				const bounded = first !== void 0 && !states.complete;
+				if (bounded) extra.push("CONSTRAINT ChartBound");
+				const r = await runJava(name, "tlc2.TLC", [
+					"-tool",
+					...PINNED_FLAGS,
+					...names(group, "deadlock").length ? [] : ["-deadlock"],
+					...config(name, spec.written, extra),
+					bounded ? "ChartBound" : spec.module
+				]);
+				first ??= r;
+				const { broke, distinct, initial } = readVerdict(messagesOf(r.output));
+				states.distinct = Math.max(states.distinct, distinct);
+				states.initial = Math.max(states.initial, initial);
+				const rule = broke && brokenRule(group, broke);
+				const cut = bounded && distinct >= 1e5;
+				if (exitClass(r.status) === 2) {
+					stop = stopOf(r);
+					break;
+				} else if (rule) decide(rule, "broken", r);
+				else if (cut && (r.status === 0 || broke?.kind === "temporal")) {
+					states.cut = true;
+					for (const rule of group) decide(rule, "not checked");
+				} else if (r.status === 0) {
+					states.complete = true;
+					for (const rule of group) decide(rule, "holds");
+				} else if (broke && properties.length) {
+					if (broke.kind === "temporal") {
+						states.complete = true;
+						for (const rule of group) if (rule.kind !== "property") decide(rule, "holds");
+					}
+					const pending = [];
+					const rest = [];
+					for (const rule of group) if (rule.kind === "property") pending.push([rule]);
+					else if (!verdicts.has(ruleKey(rule))) rest.push(rule);
+					if (pending.length === 1) decide(pending[0][0], "broken", r);
+					else groups.splice(0, 1, rest, ...pending);
+				} else throw new Error(`TLC exited ${r.status} on ${specFile}, but its output names no rule that broke:\n${tail(r)}`);
+			}
+			for (const rule of all) if (!verdicts.has(ruleKey(rule))) decide(rule, "not checked");
+			return {
+				first,
+				stop,
+				states
+			};
+		};
+		fs.writeFileSync(path.join(dir, "ChartBound.tla"), boundRun(spec.module));
+		const judged = await judge();
+		const exit = exitClass(judged.first.status);
+		const failed = (r) => /* @__PURE__ */ new Error(`TLC could not check ${specFile} (exit ${r.status}):\n${stopOf(r).message}`);
+		const initialOnly = initialOnlyProperties(sany, spec);
+		const propertiesWith = (bugOf) => {
+			const properties = [];
+			for (const rule of all) {
+				if (rule.kind !== "property") continue;
+				const v = must(verdicts, ruleKey(rule));
+				properties.push({
+					...v,
+					bug: v.outcome === "broken" && v.messages ? bugOf(readTrace(v.messages)) : void 0,
+					initialOnly: initialOnly.has(rule.name)
+				});
+			}
+			return properties;
+		};
+		if (exit === 2) throw failed(judged.first);
+		const checked = [];
+		for (const rule of rules) checked.push(must(verdicts, ruleKey(rule)));
+		const common = {
+			spec,
+			exit,
+			stop: judged.stop,
+			states: judged.states,
+			messages: messagesOf(judged.first.output),
+			rules: checked
+		};
+		if (judged.states.distinct <= 500) {
+			const tag = `chart-${randomBytes(16).toString("hex")}`;
+			fs.writeFileSync(path.join(dir, "ChartRun.tla"), chartRun(spec, tag));
+			const drawn = await runJava("ChartRun", "tlc2.TLC", [
+				"-tool",
+				...PINNED_FLAGS,
+				"-deadlock",
+				...config("ChartRun", spec.written, ["INVARIANT ChartMark", "CONSTRAINT ChartBudget"]),
+				"-dump",
+				"dot,actionlabels",
+				path.join(dir, "graph"),
+				"ChartRun"
+			]);
+			const file = path.join(dir, "graph.dot");
+			if (!fs.existsSync(file)) throw failed(drawn);
+			if (readVerdict(messagesOf(drawn.output)).distinct <= 500) {
+				const graph = parseDot(fileLines(file));
+				const find = finder(graph, spec.variables);
+				const drawing = drawn.status === 0 ? void 0 : { status: drawn.status };
+				const broken = /* @__PURE__ */ new Set();
+				for (const { rule, outcome } of verdicts.values()) if (rule.kind === "invariant" && outcome === "broken") broken.add(rule.name);
+				const marks = only(readMarks(readMessages(fileLines(drawn.stdout)), tag), broken);
+				const past = mark(graph, marks, spec.variables, rules, find);
+				const excludes = hasSection(spec, "ACTION_CONSTRAINT");
+				for (const rule of rules) {
+					const { outcome, messages } = must(verdicts, ruleKey(rule));
+					if (rule.kind === "deadlock" && outcome === "broken" && !drawing && !hasSection(spec, "CONSTRAINT", "ACTION_CONSTRAINT")) deadEnds(graph, rule);
+					if (outcome !== "broken" || !messages) continue;
+					const counterexample = readCounterexample(messages);
+					if (!drawing || lasso(graph, {
+						seq: counterexample,
+						loop: void 0
+					}, spec.variables, find)) addPast(graph, counterexample, spec.variables, rule, past, excludes, find);
+				}
+				const properties = propertiesWith((trace) => lasso(graph, trace, spec.variables, find));
+				return {
+					...common,
+					graph,
+					paths: void 0,
+					properties,
+					drawing
+				};
+			}
+		}
+		const drawn = pathGraph(spec.variables);
+		const paths = [];
+		for (const rule of rules) {
+			const { outcome, messages } = must(verdicts, ruleKey(rule));
+			if (outcome === "broken" && messages) paths.push(drawn.bug(rule, readCounterexample(messages)));
+		}
+		return {
+			...common,
+			graph: drawn.graph,
+			paths,
+			properties: propertiesWith(drawn.lasso),
+			drawing: void 0
+		};
+	} finally {
+		fs.rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+export { PINNED_FLAGS, check, fileLines, killGroup, messageOf };

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

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { killGroup, messageOf } from "./run.mjs";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+// runtime/skills/statechart/scripts/statechart.ts
+const USAGE = `Usage: statechart SPEC.tla [--config FILE] [--view FILE] [--out DIR]
+
+Checks SPEC.tla with TLC and draws its state graph as Mermaid. Above 500 states, the chart
+draws only the paths to the rules that break, and with no rule broken there is no chart.mmd.
+  --config FILE  TLC config. Default: SPEC.cfg beside the spec.
+  --view FILE    A module that exports state(vars) and, if you want, step(action, from, to),
+                 group(vars), colors, and title. state() returns a string for a flat chart, an
+                 array for parent states, or an object for regions. Default: each state's values.
+                 colors gives each group blue, orange, purple, yellow, teal, tan, or pink.
+  --out DIR      Where to write report.md, chart.mmd, tlc.out, and tlc-RULE.out for each
+                 property that breaks and each rule that breaks off the chart. The folder must
+                 be new or empty. Default: SPEC-chart.
+Exit code: TLC's own on the config as written: 0 when every rule holds, 1 when a rule breaks,
+and 2 when TLC stops with an error, a signal kills the check, or the command cannot run. 130 or
+143 when SIGINT or SIGTERM stops the check. Only exits 0 and 1 write output.`;
+let stop;
+const stopped = new Promise((resolve) => {
+	for (const name of ["SIGINT", "SIGTERM"]) process.on(name, () => {
+		stop ??= name;
+		resolve();
+	});
+});
+let flags;
+let specFile;
+try {
+	const args = parseArgs({
+		allowPositionals: true,
+		options: {
+			config: { type: "string" },
+			view: { type: "string" },
+			out: { type: "string" }
+		}
+	});
+	flags = args.values;
+	[specFile] = args.positionals;
+	if (args.positionals.length !== 1) throw new Error("Give one SPEC.tla.");
+} catch (error) {
+	console.error(`${messageOf(error)}\n\n${USAGE}`);
+	process.exit(2);
+}
+const codeOf = (error) => error instanceof Error && "code" in error ? error.code : void 0;
+try {
+	const configFile = flags.config ?? specFile.replace(/\.tla$/, ".cfg");
+	if (!fs.existsSync(configFile)) throw new Error(`Cannot find the TLC config ${configFile}. Pass --config FILE.`);
+	const out = flags.out ?? specFile.replace(/\.tla$/, "-chart");
+	let entries = [];
+	let dest;
+	try {
+		entries = fs.readdirSync(out);
+		dest = fs.realpathSync(out);
+	} catch (error) {
+		if (codeOf(error) !== "ENOENT") throw new Error(`${out} cannot be the output folder. ${messageOf(error)}. Pass --out with a new folder.`, { cause: error });
+		if (fs.lstatSync(out, { throwIfNoEntry: false })) throw new Error(`${out} cannot be the output folder. It is a broken link. Pass --out with a new folder.`, { cause: error });
+		dest = path.resolve(out);
+	}
+	if (entries.length) throw new Error(`${out} is not empty. It has ${entries.sort()[0]}. The command writes only to a new or empty folder. Pass --out with a new folder.`);
+	let base = path.dirname(dest);
+	while (!fs.existsSync(base)) base = path.dirname(base);
+	const stage = fs.mkdtempSync(path.join(base, `.${path.basename(dest)}.statechart-`));
+	const done = path.join(stage, "done");
+	let tmp;
+	let janitor;
+	let exitCode;
+	try {
+		tmp = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-"));
+		const runtime = process.versions.deno ? [
+			"run",
+			"--quiet",
+			"--no-prompt",
+			"--allow-read",
+			"--allow-write",
+			"--allow-run",
+			"--allow-env"
+		] : process.execArgv;
+		const worker = spawn(process.execPath, [
+			...runtime,
+			path.join(import.meta.dirname, import.meta.url.endsWith(".ts") ? "worker.ts" : "worker.mjs"),
+			stage,
+			specFile,
+			configFile,
+			...flags.view ? [flags.view] : []
+		], {
+			detached: true,
+			stdio: [
+				"ignore",
+				"inherit",
+				"inherit"
+			],
+			env: {
+				...process.env,
+				TMPDIR: tmp
+			}
+		});
+		janitor = spawn("/bin/sh", [
+			"-c",
+			"while read -r line; do :; done; kill -s KILL -- \"-$1\"; rm -rf -- \"$2\" \"$3\"",
+			"sh",
+			String(worker.pid),
+			stage,
+			tmp
+		], {
+			detached: true,
+			stdio: [
+				"pipe",
+				"ignore",
+				"ignore"
+			]
+		});
+		const exited = new Promise((resolve) => worker.on("exit", (code) => resolve(code ?? 2)));
+		await Promise.race([stopped, exited]);
+		await killGroup(worker.pid);
+		const verdict = await exited;
+		if (stop) {
+			console.error(`${stop} stopped the check, so the command wrote nothing.`);
+			exitCode = 128 + os.constants.signals[stop];
+		} else if (worker.signalCode) {
+			console.error(`${worker.signalCode} killed the check, so the command wrote nothing.`);
+			exitCode = 2;
+		} else if ((verdict === 0 || verdict === 1) && fs.existsSync(done)) {
+			fs.mkdirSync(path.dirname(dest), { recursive: true });
+			try {
+				fs.renameSync(done, dest);
+			} catch (error) {
+				if (codeOf(error) !== "ENOTEMPTY" && codeOf(error) !== "EEXIST") throw error;
+				throw new Error(`${path.join(out, fs.readdirSync(dest).sort()[0])} appeared while the check ran, so the command wrote nothing. Pass --out with a new folder.`, { cause: error });
+			}
+			process.stdout.write(fs.readFileSync(path.join(dest, "report.md")));
+			console.log(`\nWrote ${out}`);
+			exitCode = verdict;
+		} else exitCode = 2;
+	} finally {
+		fs.rmSync(stage, {
+			recursive: true,
+			force: true
+		});
+		if (tmp) fs.rmSync(tmp, {
+			recursive: true,
+			force: true
+		});
+		janitor?.kill("SIGKILL");
+	}
+	process.exit(exitCode);
+} catch (error) {
+	console.error(messageOf(error));
+	process.exit(2);
+}
+export {};