pi-pstack-native 0.0.0-stage → 1.0.0

package/skills/statechart/scripts/test/sync.mmd

@@ -0,0 +1,19 @@
+stateDiagram-v2
+  state "Notes app" as App {
+    state "Connection" as Connection {
+      [*] --> Online
+      Online --> Offline : the network drops
+      Offline --> Online : the network returns
+    }
+    --
+    state "Sync badge" as Sync {
+      state "Synced" as Synced
+      state "Waiting to sync" as Pending
+      [*] --> Synced
+      Synced --> Pending : you edit a note
+      Synced --> Pending : the network drops
+      Pending --> Synced : the server confirms
+    }
+  }
+  [*] --> App
+  %% never NeverSyncedWhileOffline: Offline & Synced -- You never see "Synced" while you are offline.

package/skills/statechart/scripts/test/tlc-out.test.ts

@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { plainText } from "../backends/plain-text.ts";
+import { readMessages } from "../frontends/messages.ts";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const corpus = path.join(here, "corpus");
+const skip = !process.env.TLA2TOOLS && "set TLA2TOOLS to the path of tla2tools.jar to run TLC";
+const read = (file: string) => fs.readFileSync(file, "utf8");
+const maybe = (file: string) => (fs.existsSync(file) ? read(file) : "");
+const plain = (text: string) => [...plainText(readMessages(text))].join("");
+
+const steady = (text: string) =>
+  text
+    .replace(/"chart-[0-9a-f]{32}"/g, '"chart"')
+    .replace(/\bfp \d+ and seed -?\d+/g, "fp _ and seed _")
+    .replace(/\[pid: \d+\]/g, "[pid: _]")
+    .replace(/\d{4}-\d\d-\d\d \d\d:\d\d:\d\d/g, "_")
+    .replace(/ \([\d,]+ d?s\/min\)/g, "")
+    .replace(/ in (?:\d+d \d\dh|\d\dh \d\dmin|\d\dmin \d\ds|\d\ds) at /g, " in _ at ");
+
+test(
+  "each corpus spec's TLC output reads as plain TLC prints it at -workers 1",
+  { skip, concurrency: 4 },
+  async (t) => {
+    await Promise.all(
+      fs.readdirSync(corpus).map((name) =>
+        t.test(name, async () => {
+          const dir = path.join(corpus, name);
+          const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-plain-"));
+          const [tool, twin, out] = ["tool", "plain", "out"].map((f) => path.join(tmp, f));
+          fs.mkdirSync(tool);
+          fs.mkdirSync(twin);
+          const view = path.join(dir, "view.mjs");
+          const child = spawn(
+            process.execPath,
+            [
+              path.join(here, "../statechart.ts"),
+              path.join(dir, `${name}.tla`),
+              ...(fs.existsSync(view) ? ["--view", view] : []),
+              "--out",
+              out,
+            ],
+            {
+              env: {
+                ...process.env,
+                JAVA: path.join(here, "java.ts"),
+                STATECHART_JAVA: process.env.JAVA ?? "java",
+                STATECHART_RECORD: tool,
+                STATECHART_PLAIN: twin,
+              },
+              stdio: ["ignore", "ignore", "pipe"],
+            },
+          );
+          let stderr = "";
+          child.stderr.on("data", (chunk: Buffer) => (stderr += chunk));
+          await once(child, "close");
+          assert.equal(stderr, "");
+          const runs = fs.readdirSync(twin).filter((f) => f.endsWith(".out"));
+          assert.ok(runs.includes("ChartRun.out"), "the drawing run has a plain twin");
+          for (const run of runs) {
+            const exit = run.replace(/\.out$/, ".exit");
+            assert.equal(maybe(path.join(tool, exit)), maybe(path.join(twin, exit)), exit);
+            assert.equal(
+              steady(plain(read(path.join(tool, run)))),
+              steady(read(path.join(twin, run))),
+              run,
+            );
+          }
+          assert.equal(
+            steady(read(path.join(out, "tlc.out"))),
+            steady(`${read(path.join(twin, "verdict-1.out"))}\n`),
+          );
+          const verdicts = new Set<string>();
+          for (const run of runs)
+            if (run.startsWith("verdict-")) verdicts.add(steady(`${read(path.join(twin, run))}\n`));
+          for (const f of fs.readdirSync(out))
+            if (/^tlc-\w+\.out$/.test(f))
+              assert.ok(verdicts.has(steady(read(path.join(out, f)))), f);
+        }),
+      ),
+    );
+  },
+);

package/skills/statechart/scripts/test/tlc.ts

@@ -0,0 +1,158 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PINNED_FLAGS } from "../run.ts";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const jar = process.env.TLA2TOOLS;
+export const skip = !jar && "set TLA2TOOLS to the path of tla2tools.jar to run TLC";
+
+const RULES = /^(INVARIANTS?|PROPERTY|PROPERTIES|CHECK_DEADLOCK)$/;
+
+const exitClass = (status: number | null) =>
+  status === 0 ? 0 : status === 11 || status === 12 || status === 13 ? 1 : 2;
+
+const stepsIn = (text: string) =>
+  Math.max((text.match(/^State \d+: (?!Stuttering$)/gm)?.length ?? 0) - 1, 0) +
+  (text.match(/^Back to state \d+: </gm)?.length ?? 0);
+
+function properties(cfg: string) {
+  const names: string[] = [];
+  let section = "";
+  for (const line of cfg.split("\n")) {
+    section = line.match(/^[A-Z_]+/)?.[0] ?? section;
+    if (/^PROPERT(Y|IES)$/.test(section))
+      for (const word of line.trim().split(/\s+/)) if (word && word !== section) names.push(word);
+  }
+  return names;
+}
+
+function tlc(dir: string, module: string, cfg: string) {
+  const run = `alone-${fs.readdirSync(dir).length}`;
+  const file = path.join(dir, `${run}.cfg`);
+  fs.writeFileSync(file, cfg);
+  const tmp = path.join(dir, `${run}-tmp`);
+  fs.mkdirSync(tmp);
+  const r = spawnSync(
+    process.env.JAVA ?? "java",
+    [
+      `-Djava.io.tmpdir=${tmp}`,
+      "-cp",
+      jar ?? "",
+      "tlc2.TLC",
+      ...PINNED_FLAGS,
+      "-config",
+      file,
+      "-metadir",
+      path.join(dir, `${run}-meta`),
+      module,
+    ],
+    { cwd: dir, encoding: "utf8" },
+  );
+  const out = r.stdout + r.stderr;
+  const temporal = properties(cfg);
+  const broke =
+    out.match(/^Error: (?:Invariant|Action property|Property) (\S+) is violated/m)?.[1] ??
+    (/^Error: Deadlock reached\./m.test(out) ? "NoDeadlock" : undefined) ??
+    (/^Error: Temporal properties were violated\./m.test(out) && temporal.length === 1
+      ? temporal[0]
+      : undefined);
+  return { status: r.status, out, broke, steps: stepsIn(out) };
+}
+
+function alone(cfg: string, rule: string) {
+  const lines: string[] = [];
+  let section = "";
+  for (const line of cfg.split("\n")) {
+    section = line.match(/^[A-Z_]+/)?.[0] ?? section;
+    if (!RULES.test(section)) lines.push(line);
+  }
+  if (rule !== "NoDeadlock")
+    lines.push(
+      `${properties(cfg).includes(rule) ? "PROPERTY" : "INVARIANT"} ${rule}`,
+      "CHECK_DEADLOCK FALSE",
+    );
+  return `${lines.join("\n")}\n`;
+}
+
+export type Verdict = {
+  status: number | null;
+  breaks: Map<string, number>;
+  holds: string[];
+  unchecked: string[];
+  chart: string;
+  report: string;
+};
+
+export function agrees(module: string, files: { [name: string]: string[] }, cfg: string): Verdict {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-plain-"));
+  try {
+    for (const [name, lines] of Object.entries(files))
+      fs.writeFileSync(path.join(dir, `${name}.tla`), `${lines.join("\n")}\n`);
+    fs.writeFileSync(path.join(dir, `${module}.cfg`), cfg);
+    const out = path.join(dir, "out");
+    const cli = spawnSync(
+      process.execPath,
+      [path.join(here, "../statechart.ts"), path.join(dir, `${module}.tla`), "--out", out],
+      { encoding: "utf8" },
+    );
+    const plain = tlc(dir, module, cfg);
+    const report = fs.existsSync(out) ? fs.readFileSync(path.join(out, "report.md"), "utf8") : "";
+    const shown = `${cli.stderr}${report}`;
+    assert.equal(
+      cli.status,
+      exitClass(plain.status),
+      `TLC says:\n${plain.out}\nThe command says:\n${shown}`,
+    );
+    assert.doesNotMatch(shown, /Chart\w*Mark/);
+    if (cli.status !== 2) assert.equal(cli.stderr, "");
+    if (!report) assert.match(cli.stderr, /TLC could not check/);
+    if (cli.status === 2) {
+      const error = plain.out.match(/^Error: .*$/m)?.[0];
+      assert.ok(
+        error && shown.includes(error),
+        `TLC says:\n${plain.out}\nThe command says:\n${shown}`,
+      );
+    }
+
+    const breaks = new Map<string, number>();
+    const bounded = new Set<string>();
+    for (const [, rule, body] of report.matchAll(/^## (\S+) breaks\n(.*)$/gm)) {
+      const said = body.match(/has (\d+) steps?:/)?.[1];
+      const file = body.match(/ is in (tlc-\S+\.out)\./)?.[1];
+      if (!file) {
+        breaks.set(rule, Number(said));
+        continue;
+      }
+      const text = fs.readFileSync(path.join(out, file), "utf8");
+      if (said) assert.equal(Number(said), stepsIn(text), rule);
+      if (/^Semantic processing of module ChartBound$/m.test(text)) bounded.add(rule);
+      breaks.set(rule, stepsIn(text));
+    }
+    const list = (title: string) =>
+      report
+        .match(new RegExp(`^## ${title}\\n(.*)$`, "m"))?.[1]
+        .split(", ")
+        .sort() ?? [];
+    const holds = list("Rules that hold");
+    const unchecked = list("Rules not checked");
+    const chartFile = path.join(out, "chart.mmd");
+    const chart = fs.existsSync(chartFile) ? fs.readFileSync(chartFile, "utf8") : "";
+    if (plain.broke) assert.equal(breaks.get(plain.broke), plain.steps, shown);
+    for (const rule of holds) {
+      const r = tlc(dir, module, alone(cfg, rule));
+      assert.equal(r.status, 0, `${rule} holds in the report, but TLC says:\n${r.out}`);
+    }
+    for (const [rule, steps] of breaks) {
+      const r = tlc(dir, module, alone(cfg, rule));
+      assert.equal(r.broke, rule, `${rule} breaks in the report, but TLC says:\n${r.out}`);
+      if (!bounded.has(rule)) assert.equal(steps, r.steps, rule);
+    }
+    return { status: cli.status, breaks, holds, unchecked, chart, report };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}

package/skills/statechart/scripts/test/upload.mmd

@@ -0,0 +1,16 @@
+stateDiagram-v2
+  state "Nothing chosen" as Idle
+  state "Uploading" as Uploading {
+    state "Sending the file" as Sending
+    state "Checking the file" as Checking
+    [*] --> Sending
+    Sending --> Checking : the last byte arrives
+  }
+  state "Uploaded" as Done
+  state "Upload failed" as Failed
+  [*] --> Idle
+  Idle --> Uploading : you choose a file
+  Checking --> Done : the check passes
+  Uploading --> Failed : the network drops
+  Failed --> Uploading : you retry
+  Uploading --> Idle : you cancel

package/skills/statechart/scripts/tlc-to-chart-args.mjs

@@ -0,0 +1,52 @@
+import process from "node:process";
+
+export const args = {
+  traces: [],
+  fixedTraces: [],
+  againstTraces: [],
+  fixedRules: [],
+  againstRules: [],
+  specs: [],
+  next: [],
+  view: "customer",
+  highlight: 1,
+};
+for (let i = 2; i < process.argv.length; i++) {
+  const a = process.argv[i];
+  const next = () => process.argv[++i];
+  if (a === "--dot") args.dot = next();
+  else if (a === "--map") args.map = next();
+  else if (a === "--traces") args.traces.push(next());
+  else if (a === "--broken") args.broken = next();
+  else if (a === "--fixed-dot") args.fixedDot = next();
+  else if (a === "--fixed-traces") args.fixedTraces.push(next());
+  else if (a === "--fixed-rules") args.fixedRules.push(...next().split(","));
+  else if (a === "--fixed-broken") args.fixedBroken = next();
+  else if (a === "--against-dot") args.againstDot = next();
+  else if (a === "--against-traces") args.againstTraces.push(next());
+  else if (a === "--against-broken") args.againstBroken = next();
+  else if (a === "--against-rules") args.againstRules.push(...next().split(","));
+  else if (a === "--listed") args.listed = next();
+  else if (a === "--label") args.label = next();
+  else if (a === "--spec") args.specs.push(next());
+  else if (a === "--next") args.next.push(next());
+  else if (a === "--view") args.view = next();
+  else if (a === "--highlight") args.highlight = Number(next());
+  else if (a === "--path-only") args.pathOnly = true;
+  else if (a === "--full-labels") args.fullLabels = true;
+  else if (a === "--flat") args.flat = true;
+  else if (a === "--loops") args.loops = true;
+  else if (a === "--regions") args.regions = true;
+  else if (a === "--proof") args.proof = next();
+  else if (a === "--regions-all") args.regionsAll = next();
+  else if (a === "--cover") args.cover = true;
+  else if (a === "--title") args.title = next();
+  else if (a === "--out") args.out = next();
+  else if (a === "--story") args.story = next();
+  else if (a === "--summary") args.summary = next();
+  else {
+    console.error(`unknown argument ${a}.`);
+    process.exit(2);
+  }
+}
+if (args.listed !== undefined) args.listed = JSON.parse(args.listed);