raga-cli 0.0.0-stage → 0.9.0

package/bundled-skills/skills/peak/references/statechart/scripts/chart-to-tla.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { parseMermaid } from "./lib.mjs";
+
+const USAGE = "Usage: node chart-to-tla.mjs CHART.mmd --module NAME [--dir OUT]";
+const HELP = `${USAGE}
+
+Writes a TLA+ spec, a TLC config, and a reader mapping from a Mermaid stateDiagram-v2.
+statechart.mjs from-chart runs it, then checks each INVARIANT in NAME.cfg alone.
+
+Each region becomes one variable whose values are the region's states. Each transition label
+becomes one action. Regions that share a label move together: every region that can take it does,
+and the others stay. A "%% when" line after a transition is its guard: the region can take that
+transition only while the other regions are in, or with "not" are not in, the states it names. An
+unlabeled transition is its own action. Each
+"%% never NAME: A & B -- sentence" line becomes the invariant NAME == ~(A /\\ B). A name in a
+never line is a state, or a composite that stands for every state inside it.
+
+  --module NAME  The TLA+ module name. Required.
+  --dir OUT      The folder for the files. Default: the chart's folder.
+  -h, --help     Print this help, and exit 0.
+
+Writes NAME.tla, NAME.cfg, and NAME.map.mjs into OUT, and replaces files with those names.
+NAME.cfg has SPECIFICATION Spec, INVARIANT TypeOK, and one INVARIANT per never line.
+NAME.map.mjs gives tlc-to-chart.mjs the reader's words: the region states joined by " | ".
+
+Exit codes
+  0  It wrote the files.
+  1  It cannot read the chart. The error says why.
+  2  A bad argument.`;
+const more = "Run node chart-to-tla.mjs --help for the flags.";
+
+const args = {};
+for (let i = 2; i < process.argv.length; i++) {
+  const a = process.argv[i];
+  if (a === "-h" || a === "--help") {
+    console.log(HELP);
+    process.exit(0);
+  } else if (a === "--module") args.module = process.argv[++i];
+  else if (a === "--dir") args.dir = process.argv[++i];
+  else if (!a.startsWith("-") && !args.chart) args.chart = a;
+  else {
+    console.error(`unknown argument ${a}. ${more}`);
+    process.exit(2);
+  }
+}
+if (!args.chart || !/^[A-Za-z][A-Za-z0-9_]*$/.test(args.module ?? "")) {
+  console.error(`${USAGE}\n${more}`);
+  process.exit(2);
+}
+const dir = args.dir ?? path.dirname(args.chart);
+const { regions, nevers } = parseMermaid(fs.readFileSync(args.chart, "utf8"));
+
+const RESERVED = new Set(["vars", "Init", "Next", "Spec", "TypeOK", "Settled"]);
+const taken = new Set(RESERVED);
+function ident(words, lower) {
+  const parts = words
+    .normalize("NFKD")
+    .replace(/[^A-Za-z0-9]+/g, " ")
+    .trim()
+    .split(" ")
+    .filter(Boolean);
+  let id =
+    parts
+      .map((p, i) => (lower && i === 0 ? p[0].toLowerCase() : p[0].toUpperCase()) + p.slice(1))
+      .join("") || "Step";
+  if (/^[0-9]/.test(id)) id = `${lower ? "r" : "S"}${id}`;
+  let unique = id;
+  for (let n = 2; taken.has(unique); n++) unique = `${id}${n}`;
+  taken.add(unique);
+  return unique;
+}
+const str = (s) => `"${s.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+const set = (xs) => `{${[...xs].map(str).join(", ")}}`;
+
+const vars = Object.entries(regions).map(([name, r]) => {
+  if (r.states.size === 0) throw new Error(`region ${name} has no states`);
+  if (r.initial.size === 0) throw new Error(`region ${name} has no [*] --> start`);
+  return { name, v: ident(name, true), ...r };
+});
+
+function guardOf(g) {
+  if (!g) return null;
+  const parts = Object.entries(g.states).map(([name, states]) => {
+    const { v } = vars.find((x) => x.name === name);
+    return states.length === 1 ? `${v} = ${str(states[0])}` : `${v} \\in ${set(states)}`;
+  });
+  return g.not ? `~(${parts.join(" \\/ ")})` : parts.join(" /\\ ");
+}
+
+const actions = [];
+const byLabel = new Map();
+for (const [ri, r] of vars.entries()) {
+  for (const t of r.transitions) {
+    let a = t.label ? byLabel.get(t.label) : null;
+    if (!a) {
+      a = { label: t.label, moves: new Map() };
+      actions.push(a);
+      if (t.label) byLabel.set(t.label, a);
+    }
+    if (!a.moves.has(ri)) a.moves.set(ri, []);
+    const moves = a.moves.get(ri);
+    const when = guardOf(t.guard);
+    if (!moves.some((m) => m.from === t.from && m.to === t.to && m.when === when))
+      moves.push({ from: t.from, to: t.to, when });
+  }
+}
+for (const a of actions) {
+  const only = a.label ? null : [...a.moves.values()][0][0];
+  a.name = ident(a.label || `${only.from} to ${only.to}`, false);
+}
+
+const out = [];
+const conjuncts = (lines) => lines.map((l) => `    /\\ ${l}`);
+out.push(`---- MODULE ${args.module} ----`);
+out.push(`\\* Generated by chart-to-tla.mjs from ${path.basename(args.chart)}.`);
+out.push("\\* Each region is one variable and each transition label is one action.");
+out.push("\\* Once you add guards and variables from the real code, this file is the source.");
+out.push(
+  `\\* statechart.mjs from-chart ${path.basename(args.chart)} keeps it, checks it, and compares it with the chart.`,
+);
+out.push("");
+out.push(`VARIABLES ${vars.map((x) => x.v).join(", ")}`);
+out.push(`vars == <<${vars.map((x) => x.v).join(", ")}>>`);
+out.push("");
+for (const x of vars)
+  out.push(`\\* Region ${x.name}`, `${x.v}States == ${set([...x.states].sort())}`);
+out.push("");
+out.push("TypeOK ==", ...conjuncts(vars.map((x) => `${x.v} \\in ${x.v}States`)));
+out.push("");
+out.push(
+  "Init ==",
+  ...conjuncts(
+    vars.map((x) =>
+      x.initial.size === 1 ? `${x.v} = ${str([...x.initial][0])}` : `${x.v} \\in ${set(x.initial)}`,
+    ),
+  ),
+);
+const enabled = (v, m) => `${v} = ${str(m.from)}${m.when ? ` /\\ ${m.when}` : ""}`;
+function whetherTakes(a, ri) {
+  const { v } = vars[ri];
+  const moves = a.moves.get(ri);
+  if (moves.every((m) => !m.when)) {
+    const from = set(new Set(moves.map((m) => m.from)));
+    return { can: `${v} \\in ${from}`, cannot: `${v} \\notin ${from}` };
+  }
+  const any = moves.map((m) => `(${enabled(v, m)})`).join(" \\/ ");
+  return { can: any, cannot: `~(${any})` };
+}
+for (const a of actions) {
+  out.push("");
+  if (a.label) out.push(`\\* ${a.label}`);
+  out.push(`${a.name} ==`);
+  const moving = [...a.moves.keys()];
+  const shared = moving.length > 1;
+  if (shared) out.push(`    /\\ (${moving.map((ri) => whetherTakes(a, ri).can).join(" \\/ ")})`);
+  for (const ri of moving) {
+    const { v } = vars[ri];
+    const ds = a.moves.get(ri).map((m) => `(${enabled(v, m)} /\\ ${v}' = ${str(m.to)})`);
+    if (shared) ds.push(`(${whetherTakes(a, ri).cannot} /\\ UNCHANGED ${v})`);
+    out.push(`    /\\ \\/ ${ds[0]}`);
+    for (const d of ds.slice(1)) out.push(`       \\/ ${d}`);
+  }
+  const still = vars.filter((_, ri) => !a.moves.has(ri)).map((x) => x.v);
+  if (still.length) out.push(`    /\\ UNCHANGED <<${still.join(", ")}>>`);
+}
+out.push("");
+out.push(
+  actions.length ? `Next == ${actions.map((a) => a.name).join(" \\/ ")}` : "Next == UNCHANGED vars",
+);
+out.push("");
+out.push("Spec == Init /\\ [][Next]_vars");
+
+function resolve(item) {
+  const hits = [];
+  for (const [ri, x] of vars.entries()) {
+    const inside = x.states.has(item)
+      ? [item]
+      : [...x.states].filter((s) => s.startsWith(`${item}.`));
+    if (inside.length) hits.push({ ri, inside });
+  }
+  if (hits.length === 0)
+    throw new Error(`never line names "${item}", which is not a state in the chart`);
+  if (hits.length > 1)
+    throw new Error(
+      `never line names "${item}", which is a state in regions ${hits.map((h) => vars[h.ri].name).join(" and ")}; rename one`,
+    );
+  return hits[0];
+}
+const invariants = [];
+for (const n of nevers) {
+  if (taken.has(n.name)) throw new Error(`never name ${n.name} is already used in the spec`);
+  taken.add(n.name);
+  const parts = n.states.map(resolve);
+  const regionsUsed = new Set(parts.map((p) => p.ri));
+  if (regionsUsed.size !== parts.length)
+    throw new Error(
+      `never ${n.name} names two states of one region; one region is in one state at a time`,
+    );
+  const cond = parts.map((p) =>
+    p.inside.length === 1
+      ? `${vars[p.ri].v} = ${str(p.inside[0])}`
+      : `${vars[p.ri].v} \\in ${set(p.inside)}`,
+  );
+  out.push("");
+  if (n.sentence) out.push(`\\* ${n.sentence}`);
+  out.push(`${n.name} == ~(${cond.join(" /\\ ")})`);
+  invariants.push(n.name);
+}
+out.push("", "====", "");
+
+const rules = ["TypeOK", ...invariants];
+const cfg = ["SPECIFICATION Spec", ...rules.map((r) => `INVARIANT ${r}`), ""];
+
+const labels = Object.fromEntries(actions.map((a) => [a.name, a.label]));
+const map = [
+  `// Generated by chart-to-tla.mjs from ${path.basename(args.chart)}. Reader states are the chart's own states.`,
+  `export const regions = ${JSON.stringify(vars.map((x) => x.v))};`,
+  `const LABELS = ${JSON.stringify(labels, null, "\t")};`,
+  "",
+  "// The actions the reader takes. facts.settled needs them. Add cause() and detail() as the spec grows.",
+  "export const readerActions = [];",
+  'export const state = (v) => regions.map((r) => v[r]).join(" | ");',
+  "export const step = (action) => LABELS[action] ?? action;",
+  "",
+];
+
+fs.mkdirSync(dir, { recursive: true });
+fs.writeFileSync(path.join(dir, `${args.module}.tla`), out.join("\n"));
+fs.writeFileSync(path.join(dir, `${args.module}.cfg`), cfg.join("\n"));
+fs.writeFileSync(path.join(dir, `${args.module}.map.mjs`), map.join("\n"));
+console.error(
+  `${args.module}: ${vars.length} region variable(s), ${actions.length} action(s), rules ${rules.join(" ")} -> ${path.join(dir, args.module)}.{tla,cfg,map.mjs}`,
+);

package/bundled-skills/skills/peak/references/statechart/scripts/compare-charts.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import process from "node:process";
+import { FULL_LABELS, LEGEND_ID, compareCharts, parseMermaid } from "./lib.mjs";
+
+const USAGE = "Usage: node compare-charts.mjs EXPECTED.mmd ACTUAL.mmd";
+const HELP = `${USAGE}
+
+Compares two Mermaid stateDiagram-v2 charts: reachable states, start states, and labeled
+transitions. statechart.mjs from-chart runs it to check that the spec still draws the chart that
+the reader agreed to.
+
+EXPECTED is the agreed chart. ACTUAL is what tlc-to-chart.mjs drew from the spec in the customer
+view with --highlight 0 --full-labels --flat, without --cover, --fixed-dot, or --against-dot. Each
+chart compares as the
+machine that its steps reach from its start states. A chart with parallel regions compares as its
+combined machine, so a guard that blocks a step in only some combinations of regions shows as a
+difference. A "%% when ID, ID" or "%% when not ID, ID" line right after a transition is its guard:
+the step happens only while another region is in, or not in, one of those states. The label ends
+with the guard's words in [ ], which are not part of the label. A combined state is the region
+states joined by " | " in region order, which is what chart-to-tla.mjs's mapping writes. A step that does not change the state is not compared, because
+tlc-to-chart.mjs does not draw it. An edge label "a or b" counts as two labels. An unlabeled edge
+counts only when no labeled edge joins the same two states, because tlc-to-chart.mjs draws only
+the labels.
+
+  -h, --help  Print this help, and exit 0.
+
+Prints each difference and then "N difference(s)", or prints "same". Writes no file.
+
+Exit codes
+  0  The charts are the same.
+  1  The charts differ.
+  2  A bad argument, a chart that it cannot read, or an ACTUAL chart that is not drawn for
+     comparison.`;
+const more = "Run node compare-charts.mjs --help for the flags.";
+
+const files = [];
+for (const a of process.argv.slice(2)) {
+  if (a === "-h" || a === "--help") {
+    console.log(HELP);
+    process.exit(0);
+  } else if (a.startsWith("-") || files.length === 2) {
+    console.error(`unknown argument ${a}. ${more}`);
+    process.exit(2);
+  } else files.push(a);
+}
+if (files.length < 2) {
+  console.error(`${USAGE}\n${more}`);
+  process.exit(2);
+}
+const [expectedFile, actualFile] = files;
+
+const orExit = (file, f) => {
+  try {
+    return f();
+  } catch (e) {
+    console.error(`${file}: ${e.message}`);
+    process.exit(2);
+  }
+};
+const [expectedText, actualText] = files.map((f) => orExit(f, () => fs.readFileSync(f, "utf8")));
+const has = (re) => re.test(actualText);
+const textRefusals = [
+  [
+    has(/^\s*%% second model/m),
+    "it has a second model; draw ACTUAL without --fixed-dot or --against-dot",
+  ],
+  [
+    has(new RegExp(`^\\s*state\\s+"[^"]*"\\s+as\\s+(?!${LEGEND_ID}\\b)\\w+\\s*\\{`, "m")),
+    "it has boxes; draw ACTUAL with --flat",
+  ],
+  [
+    has(new RegExp(`^\\s*state\\s+"[^"]*"\\s+as\\s+${LEGEND_ID}\\s*\\{`, "m")) &&
+      !actualText.includes(FULL_LABELS),
+    "edge labels write shared words once; draw ACTUAL with --full-labels",
+  ],
+];
+for (const [bad, why] of textRefusals) {
+  if (bad) {
+    console.error(`${actualFile}: ${why}`);
+    process.exit(2);
+  }
+}
+const expectedRegions = orExit(expectedFile, () => parseMermaid(expectedText).regions);
+const actualRegions = orExit(actualFile, () => parseMermaid(actualText).regions);
+const numbered = Object.values(actualRegions)
+  .flatMap((r) => r.transitions)
+  .some((t) => /^\d+(, \d+)*\. /.test(t.label));
+if (numbered) {
+  console.error(
+    `${actualFile}: an edge label is a numbered path step; draw ACTUAL with --highlight 0`,
+  );
+  process.exit(2);
+}
+
+const rows = compareCharts(expectedRegions, actualRegions);
+let differences = 0;
+for (const [title, xs] of rows) {
+  console.log(`${title}:`);
+  for (const x of xs) console.log(`  ${x}`);
+  differences += xs.length;
+}
+console.log(differences === 0 ? "same" : `${differences} difference(s)`);
+process.exit(differences === 0 ? 0 : 1);