@olierjs/fugue-cli 0.0.0-stage → 0.1.2

package/skills/statechart/scripts/chart-edges.mjs

@@ -0,0 +1,68 @@
+import { edgeId } from "./chart-parts.mjs";
+import { diverges } from "./bug-states.mjs";
+
+export const edgesAlong = (c) =>
+  c.path.slice(1).map((p, i) => ({
+    id: edgeId(c.path[i].key, p.key),
+    from: c.path[i].key,
+    to: p.key,
+    label: p.label,
+    guard: p.guard,
+  }));
+
+export function chartEdges({ args, now, secondQ, modelEdges, classes, chosen, coverOff }) {
+  const edges = new Map(modelEdges);
+  for (const { second: s } of classes.filter(diverges)) {
+    if (modelEdges.has(s.edge)) continue;
+    if (!edges.has(s.edge))
+      edges.set(s.edge, {
+        from: s.from,
+        to: s.key,
+        labels: new Set(),
+        secondOnly: true,
+        apart: s.apart,
+      });
+    edges.get(s.edge).labels.add(s.overview);
+  }
+  const pathNumbers = new Map();
+  (chosen ? edgesAlong(chosen) : []).forEach((step, i) => {
+    if (!pathNumbers.has(step.id)) pathNumbers.set(step.id, []);
+    const shown = step.guard ? `${step.label} [${step.guard}]` : step.label;
+    pathNumbers.get(step.id).push({ n: i + 1, label: step.label, shown });
+    if (!edges.has(step.id))
+      edges.set(step.id, { from: step.from, to: step.to, labels: new Set([step.label]) });
+  });
+  const bugSteps = classes.flatMap(edgesAlong);
+  const pathEdges = new Map();
+  for (const step of bugSteps) {
+    if (edges.has(step.id)) continue;
+    if (!pathEdges.has(step.id))
+      pathEdges.set(step.id, { from: step.from, to: step.to, labels: new Set() });
+    pathEdges.get(step.id).labels.add(step.label);
+  }
+  for (const [id, e] of pathEdges) edges.set(id, e);
+  if (!args.cover || coverOff) return { edges, pathNumbers, coverEdges: null };
+
+  const coverEdges = new Set(bugSteps.map((step) => step.id));
+  const bfs = (q, targets) => {
+    const parent = new Map([...q.initial].map((k) => [k, null]));
+    const outEdges = new Map();
+    for (const [id, e] of q.edges) {
+      if (!outEdges.has(e.from)) outEdges.set(e.from, []);
+      outEdges.get(e.from).push([id, e]);
+    }
+    for (const k of parent.keys())
+      for (const [id, e] of outEdges.get(k) ?? []) if (!parent.has(e.to)) parent.set(e.to, id);
+    for (const t of targets) {
+      for (let id = parent.get(t); id; id = parent.get(q.edges.get(id).from)) coverEdges.add(id);
+    }
+  };
+  bfs(now, now.settled);
+  if (secondQ)
+    bfs(
+      secondQ,
+      [...secondQ.settled].filter((k) => !now.nodes.has(k)),
+    );
+  for (const c of classes.filter(diverges)) coverEdges.add(c.second.edge);
+  return { edges, pathNumbers, coverEdges };
+}

package/skills/statechart/scripts/chart-parts.mjs

@@ -0,0 +1,21 @@
+export const SEP = "\u0000";
+export const edgeId = (from, to) => `${from}${SEP}${SEP}${to}`;
+
+export function guarded(guards, label) {
+  const words = guards?.get(label);
+  return words && !words.has("") ? `${label} [${[...words].sort().join(" or ")}]` : label;
+}
+export const addGuard = (guards, label, words) => {
+  if (!guards.has(label)) guards.set(label, new Set());
+  guards.get(label).add(words);
+};
+
+export const frontMatter = (title) => [
+  "---",
+  ...(title ? [`title: ${JSON.stringify(title)}`] : []),
+  "config:",
+  "  markdownAutoWrap: false",
+  "  state:",
+  "    useMaxWidth: false",
+  "---",
+];

package/skills/statechart/scripts/chart-to-tla.mjs

@@ -0,0 +1,205 @@
+#!/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 args = {};
+for (let i = 2; i < process.argv.length; i++) {
+  const a = process.argv[i];
+  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}.`);
+    process.exit(2);
+  }
+}
+if (!args.chart || !/^[A-Za-z][A-Za-z0-9_]*$/.test(args.module ?? "")) {
+  console.error(USAGE);
+  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 == FALSE");
+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/skills/statechart/scripts/compare-charts.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import process from "node:process";
+import { FULL_LABELS, LEGEND_ID, NO_LOOPS, compareCharts, parseMermaid } from "./lib.mjs";
+
+const USAGE = "Usage: node compare-charts.mjs EXPECTED.mmd ACTUAL.mmd";
+
+const files = [];
+for (const a of process.argv.slice(2)) {
+  if (a.startsWith("-") || files.length === 2) {
+    console.error(`unknown argument ${a}.`);
+    process.exit(2);
+  } else files.push(a);
+}
+if (files.length < 2) {
+  console.error(USAGE);
+  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, {
+  loops: !actualText.includes(NO_LOOPS),
+});
+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);