pi-t3-pstack 0.0.0-stage → 0.1.0

package/pstack/skills/statechart/scripts/test/messages.test.ts

@@ -0,0 +1,212 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { plainText, runtime } from "../backends/plain-text.ts";
+import { readMessages } from "../frontends/messages.ts";
+
+const tool = (code: number, level: number, ...lines: string[]) =>
+  [`@!@!@STARTMSG ${code}:${level} @!@!@`, ...lines, `@!@!@ENDMSG ${code} @!@!@`].join("\n");
+
+const plain = (text: string) => [...plainText(readMessages(text))].join("");
+
+test("TLC's -tool output prints as plain TLC prints it", () => {
+  const text = [
+    tool(2262, 0, "TLC2 Version 2.19 of 08 August 2024 (rev: 5a47802)"),
+    tool(2401, 3, "Please run the Java VM with a throughput optimized garbage collector."),
+    tool(2220, 0, "Starting SANY..."),
+    "Parsing file /tmp/Spec.tla",
+    "<<",
+    '"chart",',
+    ">>",
+    tool(2219, 0, "SANY finished."),
+    tool(2154, 3, "The spec has no TypeOK."),
+    tool(2200, 0, "Progress(1) at 2026-10-25 12:58:36: 3 states generated."),
+    tool(2116, 1, "Temporal properties were violated.", ""),
+    tool(2217, 4, "1: <Initial predicate>", "/\\ x = 0", ""),
+    tool(2217, 4, "2: <Next line 5, col 9 to line 5, col 20 of module Spec>", "/\\ x = 1", ""),
+    tool(2122, 4, "1: Back to state: <Back line 6, col 9 to line 6, col 23 of module Spec>", ""),
+    tool(2218, 4, "3: Stuttering"),
+    tool(1000, 2, "This was a bug."),
+    tool(2200, 0, "Progress(2) at 2026-10-25 12:58:37: 3 states generated."),
+    tool(2199, 0, "3 states generated."),
+    tool(2186, 0, "Finished in 61000ms at (2026-10-25 12:58:37)"),
+    "",
+  ].join("\n");
+  assert.equal(
+    plain(text),
+    [
+      "TLC2 Version 2.19 of 08 August 2024 (rev: 5a47802)",
+      "Warning: Please run the Java VM with a throughput optimized garbage collector.",
+      "(Use the -nowarning option to disable this warning.)",
+      "Parsing file /tmp/Spec.tla",
+      "<<",
+      '"chart",',
+      ">>",
+      "Warning: The spec has no TypeOK.",
+      "Progress(1) at 2026-10-25 12:58:36: 3 states generated.",
+      "Error: Temporal properties were violated.",
+      "",
+      "State 1: <Initial predicate>",
+      "/\\ x = 0",
+      "",
+      "State 2: <Next line 5, col 9 to line 5, col 20 of module Spec>",
+      "/\\ x = 1",
+      "",
+      "Back to state 1: <Back line 6, col 9 to line 6, col 23 of module Spec>",
+      "",
+      "State 3: Stuttering",
+      "TLC Bug: This was a bug.",
+      "3 states generated.",
+      "Finished in 01min 01s at (2026-10-25 12:58:37)",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("a message that TLC prints inside another prints as plain TLC prints it", () => {
+  const assertion = "The first argument of Assert evaluated to FALSE; the second argument was:";
+  const text = [
+    tool(
+      2111,
+      1,
+      "Evaluating invariant Bad failed.",
+      tool(2179, 0, "The second argument of \\div is 0."),
+    ),
+    tool(2121, 1, "The behavior up to this point is:"),
+    tool(1000, 1, tool(2132, 0, assertion, '"left @!@!@STARTMSG 9999:1 @!@!@ right"')),
+    tool(1000, 1, tool(2132, 0, assertion, '"@!@!@ENDMSG 2103 @!@!@"')),
+    "",
+  ].join("\n");
+  assert.equal(
+    plain(text),
+    [
+      "Error: Evaluating invariant Bad failed.",
+      "The second argument of \\div is 0.",
+      "Error: The behavior up to this point is:",
+      `Error: ${assertion}`,
+      '"left @!@!@STARTMSG 9999:1 @!@!@ right"',
+      `Error: ${assertion}`,
+      '"@!@!@ENDMSG 2103 @!@!@"',
+      "",
+    ].join("\n"),
+  );
+});
+
+test("an end line closes the innermost message whatever code it names", () => {
+  const text = [
+    "@!@!@STARTMSG 2111:1 @!@!@",
+    "Evaluating invariant Bad failed: @!@!@STARTMSG 2179:0 @!@!@",
+    "The second argument of \\div is 0.",
+    "@!@!@ENDMSG 2179 @!@!@",
+    "@!@!@ENDMSG 2111 @!@!@",
+    tool(2186, 0, "Finished in 0ms at (T)"),
+    "",
+  ].join("\n");
+  assert.equal(
+    plain(text),
+    [
+      "Error: Evaluating invariant Bad failed: The second argument of \\div is 0.",
+      "Finished in 00s at (T)",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("a message that TLC starts at the end of a line of text prints on that line", () => {
+  const text = [
+    "@!@!@STARTMSG 1000:1 @!@!@",
+    "TLC threw an unexpected exception.",
+    "This was probably caused by an error in the spec or model.",
+    "See the User Output or TLC Console for clues to what happened.",
+    "The exception was a java.lang.RuntimeException",
+    ": tlc2.tool.EvalException: @!@!@STARTMSG 2179:0 @!@!@",
+    "The second argument of \\div is 0.",
+    "@!@!@ENDMSG 2179 @!@!@",
+    "@!@!@ENDMSG 1000 @!@!@",
+    "@!@!@STARTMSG 2103:1 @!@!@",
+    "The error occurred when TLC was evaluating the nested",
+    "expressions at the following positions:",
+    "0. Line 8, column 8 to line 8, column 25 in ConstraintEval",
+    "1. Line 8, column 8 to line 8, column 21 in ConstraintEval",
+    "",
+    "",
+    "@!@!@ENDMSG 2103 @!@!@",
+    "@!@!@STARTMSG 2200:0 @!@!@",
+    "Progress(2) at 2026-10-25 17:45:59: 3 states generated (598 s/min), 2 distinct states found (398 ds/min), 0 states left on queue.",
+    "@!@!@ENDMSG 2200 @!@!@",
+    "@!@!@STARTMSG 2199:0 @!@!@",
+    "3 states generated, 2 distinct states found, 0 states left on queue.",
+    "@!@!@ENDMSG 2199 @!@!@",
+    "@!@!@STARTMSG 2186:0 @!@!@",
+    "Finished in 304ms at (2026-10-25 17:45:59)",
+    "@!@!@ENDMSG 2186 @!@!@",
+    "",
+  ].join("\n");
+  assert.equal(
+    plain(text),
+    [
+      "Error: TLC threw an unexpected exception.",
+      "This was probably caused by an error in the spec or model.",
+      "See the User Output or TLC Console for clues to what happened.",
+      "The exception was a java.lang.RuntimeException",
+      ": tlc2.tool.EvalException: The second argument of \\div is 0.",
+      "Error: The error occurred when TLC was evaluating the nested",
+      "expressions at the following positions:",
+      "0. Line 8, column 8 to line 8, column 25 in ConstraintEval",
+      "1. Line 8, column 8 to line 8, column 21 in ConstraintEval",
+      "",
+      "",
+      "3 states generated, 2 distinct states found, 0 states left on queue.",
+      "Finished in 00s at (2026-10-25 17:45:59)",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("output that ends where TLC died prints as plain TLC's output cut at the same point", () => {
+  const computing = tool(2189, 0, "Computing initial states...");
+  const assertion = "The first argument of Assert evaluated to FALSE; the second argument was:";
+  const insideEnd = [
+    computing,
+    "@!@!@STARTMSG 2111:1 @!@!@",
+    "Evaluating invariant ChartMark failed.",
+    "@!@!@STARTMSG 2132:0 @!@!@",
+    assertion,
+    '"c went past eleven"',
+    "@!@!@ENDMSG 21",
+  ].join("\n");
+  assert.equal(
+    plain(insideEnd),
+    [
+      "Computing initial states...",
+      "Error: Evaluating invariant ChartMark failed.",
+      assertion,
+      '"c went past eleven"',
+      "",
+    ].join("\n"),
+  );
+  const afterStarts = [computing, "@!@!@STARTMSG 1000:1 @!@!@", "@!@!@STARTMSG 2132:0 @!@!@", ""];
+  assert.equal(plain(afterStarts.join("\n")), "Computing initial states...\n");
+});
+
+test("text outside TLC's messages, such as SANY's output, passes through unchanged", () => {
+  for (const text of ["", "\n", "a\n\nb\n", "Semantic errors:\n\n  line 1\n"])
+    assert.equal(plain(text), text);
+});
+
+test("TLC's run time prints as plain TLC prints it, with each field wrapping", () => {
+  for (const [ms, printed] of [
+    [0, "00s"],
+    [394, "00s"],
+    [59_999, "59s"],
+    [60_000, "00s"],
+    [60_001, "01min 00s"],
+    [3_599_999, "59min 59s"],
+    [3_600_000, "00min 00s"],
+    [3_600_001, "01h 00min"],
+    [86_400_000, "00h 00min"],
+    [86_400_001, "1d 00h"],
+    [90_000_000, "1d 01h"],
+    [366 * 86_400_000, "1d 00h"],
+  ] satisfies [number, string][])
+    assert.equal(runtime(ms), printed, String(ms));
+});

package/pstack/skills/statechart/scripts/test/pipeline.test.ts

@@ -0,0 +1,270 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { test } from "node:test";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { inspect } from "node:util";
+import { checkView } from "../frontends/view.ts";
+import {
+  type CheckResult,
+  EC,
+  LEVEL,
+  type Rule,
+  type Spec,
+  stateRules,
+  type Verdict,
+} from "../ir.ts";
+import { compile } from "../pipeline.ts";
+
+const scripts = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const sources = (target: string) => {
+  const full = path.join(scripts, target);
+  if (!fs.statSync(full).isDirectory()) return [target];
+  return fs
+    .readdirSync(full, { recursive: true, encoding: "utf8" })
+    .map((entry) => path.join(target, entry))
+    .filter((file) => fs.statSync(path.join(scripts, file)).isFile());
+};
+
+const RECORD = `
+import { registerHooks } from "node:module";
+const edges = [];
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    const resolved = nextResolve(specifier, context);
+    if (context.parentURL !== import.meta.url) edges.push([context.parentURL, resolved.url]);
+    return resolved;
+  },
+});
+for (const url of process.argv.slice(1)) await import(url);
+console.log(JSON.stringify(edges));
+`;
+const loads = (...targets: string[]) => {
+  const urls = targets.flatMap(sources).map((file) => pathToFileURL(path.join(scripts, file)).href);
+  const out = execFileSync(process.execPath, ["--input-type=module", "-e", RECORD, ...urls], {
+    encoding: "utf8",
+  });
+  const name = (url: string) =>
+    url.startsWith("file:") ? path.relative(scripts, fileURLToPath(url)) : url;
+  return (JSON.parse(out) as string[][]).map(([from, to]) => [name(from), name(to)]);
+};
+
+const COMMENT =
+  /("(?:[^"\\\n]|\\[\s\S])*"|'(?:[^'\\\n]|\\[\s\S])*'|`(?:[^`\\]|\\[\s\S])*`)|\/\/[^\n]*|\/\*[\s\S]*?\*\//g;
+const codeOf = (file: string) =>
+  fs.readFileSync(path.join(scripts, file), "utf8").replace(COMMENT, (_, text) => text ?? " ");
+
+const RUNTIME =
+  /\b(?:process|require|globalThis|global|Deno|Bun|Buffer|setImmediate|clearImmediate|fetch)\b|\bimport\s*\(/g;
+const TYPE_IMPORT =
+  /\b(?:import|export)\s+type\b\s*(?:[\w$]+|\*(?:\s*as\s+[\w$]+)?|\{[^}]*\})\s*from\s*["']([^"']*)["']/g;
+const typeImports = (file: string) =>
+  Array.from(codeOf(file).matchAll(TYPE_IMPORT), (m) => path.join(path.dirname(file), m[1]));
+
+test("ir.ts imports nothing", () => {
+  assert.deepEqual(loads("ir.ts"), []);
+  assert.deepEqual(typeImports("ir.ts"), []);
+});
+
+test("each pass imports only ir.ts", () => {
+  const files = sources("passes");
+  assert.deepEqual(
+    files.filter((file) => !file.endsWith(".ts")),
+    [],
+  );
+  const found = loads("passes");
+  assert.ok(found.length > 0);
+  for (const [from, to] of found) assert.equal(to, "ir.ts", `${from} imports ${to}`);
+  for (const file of files)
+    for (const to of typeImports(file))
+      assert.equal(to, "ir.ts", `${file} imports types from ${to}`);
+});
+
+test("pipeline.ts reaches no node: module", () => {
+  assert.deepEqual(
+    loads("pipeline.ts").filter(([, to]) => to.startsWith("node:")),
+    [],
+  );
+  for (const to of typeImports("pipeline.ts"))
+    assert.equal(to, "ir.ts", `pipeline.ts imports types from ${to}`);
+});
+
+test("ir.ts, the passes, pipeline.ts, the frontends, the backends, and every file they load are .ts files that name no listed runtime global and call no import()", () => {
+  const targets = ["ir.ts", "passes", "pipeline.ts", "frontends", "backends"];
+  const reached = loads(...targets).flatMap(([, to]) => (to.startsWith("node:") ? [] : [to]));
+  const files = [...new Set([...targets.flatMap(sources), ...reached])];
+  assert.deepEqual(
+    files.filter((file) => !file.endsWith(".ts")),
+    [],
+  );
+  for (const file of files) assert.deepEqual(codeOf(file).match(RUNTIME), null, file);
+});
+
+test("no frontend or backend loads a node: module when imported, even through another file", () => {
+  for (const folder of ["frontends", "backends"]) {
+    const files = fs
+      .readdirSync(path.join(scripts, folder), { encoding: "utf8", recursive: true })
+      .filter((f) => f.endsWith(".ts"));
+    assert.ok(files.length > 0, folder);
+    for (const f of files)
+      for (const [, to] of loads(path.join(folder, f)))
+        assert.ok(!to.startsWith("node:"), `${folder}/${f} reaches ${to}`);
+  }
+});
+
+const small: Rule = { kind: "invariant", name: "Small" };
+
+const noView = checkView({}, inspect);
+
+const holding = (spec: Spec) => {
+  const verdicts: Verdict[] = [];
+  for (const rule of stateRules(spec))
+    verdicts.push({ rule, outcome: "holds", messages: undefined });
+  return verdicts;
+};
+
+const twoStates = (breaks: Rule[], property = "Settles"): CheckResult => ({
+  spec: {
+    module: "Two",
+    variables: ["x"],
+    invariants: ["Small"],
+    properties: [property],
+    deadlock: false,
+    written: [],
+    folder: "",
+  },
+  paths: undefined,
+  graph: {
+    states: new Map([
+      ["1", { vars: { x: 0 }, start: true, breaks: [] }],
+      ["2", { vars: { x: 1 }, start: false, breaks }],
+    ]),
+    steps: [{ from: "1", to: "2", action: "Grow" }],
+  },
+  rules: [{ rule: small, outcome: breaks.length ? "broken" : "holds", messages: undefined }],
+  properties: [
+    {
+      rule: { kind: "property", name: property },
+      outcome: breaks.length ? "broken" : "holds",
+      messages: [
+        {
+          code: EC.TLC_STATE_PRINT2,
+          level: LEVEL.STATE,
+          body: ["1: <Initial predicate>", "x = 0"],
+        },
+      ],
+      bug: undefined,
+      initialOnly: false,
+    },
+  ],
+  exit: breaks.length ? 1 : 0,
+  stop: undefined,
+  drawing: undefined,
+  states: { distinct: 2, initial: 1, complete: true, cut: false },
+  messages: [{ code: EC.TLC_FINISHED, level: LEVEL.NONE, body: ["Finished in 394ms at (T)"] }],
+});
+
+const body = (files: Map<string, Iterable<string | Uint8Array>>, name: string) => {
+  let text = "";
+  for (const part of files.get(name) ?? [])
+    text += typeof part === "string" ? part : new TextDecoder().decode(part);
+  return text;
+};
+
+test("the pipeline turns a hand-built graph into the out folder's files with no TLC", () => {
+  const broken = compile(twoStates([small]), noView);
+  assert.equal(broken.exit, 1);
+  assert.deepEqual(
+    [...broken.files.keys()],
+    ["chart.mmd", "report.md", "tlc.out", "tlc-Settles.out"],
+  );
+  assert.equal(body(broken.files, "report.md"), broken.report);
+  assert.equal(body(broken.files, "tlc.out"), "Finished in 00s at (T)\n");
+  assert.equal(body(broken.files, "tlc-Settles.out"), "State 1: <Initial predicate>\nx = 0\n");
+  assert.equal(
+    broken.report,
+    [
+      "# Two",
+      "",
+      "TLC reached 2 states and 1 steps. The chart draws 2 states and 1 arrows.",
+      "",
+      "## Small breaks",
+      "The shortest path has 1 step:",
+      "0. 0",
+      "1. Grow: 1",
+      "",
+      "## Settles breaks",
+      "TLC found a counterexample. It is in tlc-Settles.out.",
+    ].join("\n"),
+  );
+  assert.match(
+    body(broken.files, "chart.mmd"),
+    /^ {2}(s\d+) --> (s\d+): Grow\n[\s\S]*^ {2}class \2 breaks$/m,
+  );
+
+  const holds = compile(twoStates([]), noView);
+  assert.equal(holds.exit, 0);
+  assert.deepEqual([...holds.files.keys()], ["chart.mmd", "report.md", "tlc.out"]);
+  assert.match(holds.report, /^## Rules that hold\nSmall, Settles$/m);
+  assert.doesNotMatch(body(holds.files, "chart.mmd"), /breaks/);
+});
+
+test("an invariant and a property with one name stay two rules", () => {
+  const reportWithSmallProperty = (breaks: Rule[]) => {
+    const result = twoStates(breaks);
+    const step = result.graph.steps[0];
+    result.spec.properties = ["Small"];
+    result.properties = [
+      {
+        rule: { kind: "property", name: "Small" },
+        outcome: "broken",
+        messages: [],
+        bug: { start: "1", path: [{ action: "Grow", state: "2", step }], loop: 1, stutters: true },
+        initialOnly: false,
+      },
+    ];
+    return compile(result, noView).report;
+  };
+  const both = reportWithSmallProperty([small]);
+  assert.match(both, /^## Small breaks\nThe shortest path has 1 step:$/m);
+  assert.match(
+    both,
+    /^## Small breaks\nTLC's counterexample is in tlc-Small\.out\. It has 1 step:$/m,
+  );
+  assert.match(reportWithSmallProperty([]), /^## Rules that hold\nSmall$/m);
+});
+
+test("a PROPERTY that breaks with no path writes TLC's counterexample", () => {
+  const result = twoStates([]);
+  result.properties[0].outcome = "broken";
+  const { report, files } = compile(result, noView);
+  assert.match(
+    report,
+    /^## Settles breaks\nTLC found a counterexample\. It is in tlc-Settles\.out\.$/m,
+  );
+  assert.equal(body(files, "tlc-Settles.out"), "State 1: <Initial predicate>\nx = 0\n");
+});
+
+test("a rule named NoDeadlock leaves the deadlock rule a name of its own", () => {
+  const holds = (result: CheckResult) => {
+    result.spec.deadlock = true;
+    result.rules = holding(result.spec);
+    return compile(result, noView).report.match(/^## Rules that hold\n(.*)$/m)?.[1];
+  };
+  const invariant = twoStates([]);
+  invariant.spec.invariants = ["NoDeadlock"];
+  assert.equal(holds(invariant), "NoDeadlock, CHECK_DEADLOCK, Settles");
+  assert.equal(holds(twoStates([], "NoDeadlock")), "Small, CHECK_DEADLOCK, NoDeadlock");
+  assert.equal(holds(twoStates([])), "Small, NoDeadlock, Settles");
+});
+
+test("a run that does not check for deadlock never names CHECK_DEADLOCK", () => {
+  const invariant = twoStates([]);
+  invariant.spec.invariants = ["Small", "NoDeadlock"];
+  for (const result of [invariant, twoStates([], "NoDeadlock")]) {
+    result.rules = holding(result.spec);
+    assert.doesNotMatch(compile(result, noView).report, /CHECK_DEADLOCK/);
+  }
+});