dsh-pstack 0.3.0-beta.1 → 0.3.1

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

@@ -1,440 +0,0 @@
-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

@@ -1,155 +0,0 @@
-#!/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 {};