@olierjs/fugue-cli 0.1.0 → 0.1.3

package/skills/statechart/scripts/second-replay.mjs

@@ -0,0 +1,122 @@
+import { isRecord, stateKey } from "./lib.mjs";
+import { SEP, edgeId } from "./chart-parts.mjs";
+import { badOf } from "./bug-states.mjs";
+
+const holder = (o, p) => p.slice(0, -1).reduce((x, k) => (isRecord(x?.[k]) ? x[k] : null), o);
+function omit(vars, paths) {
+  if (!paths.length) return vars;
+  const out = structuredClone(vars);
+  for (const p of paths) {
+    const o = holder(out, p);
+    if (o) delete o[p.at(-1)];
+  }
+  return out;
+}
+
+export function replaySecond(
+  trace,
+  { main, lacks, extra, second, hiddenStep, readerPath, mainActions, secondRules, rawSecondTraces },
+) {
+  if (!second) return null;
+  const shared = (vars) => stateKey(omit(vars, lacks));
+  const sharedOf = (n) => stateKey(omit(n.vars, extra));
+  const out = new Map();
+  for (const e of [...second.graph.edges, ...second.graph.loops]) {
+    if (!out.has(e.from)) out.set(e.from, []);
+    out.get(e.from).push(e);
+  }
+  const actions = new Set([...second.graph.edges, ...second.graph.loops].map((e) => e.action));
+  const nodeOf = (id) => second.graph.nodes.get(id);
+  const screen = new Map(
+    [...second.graph.nodes.values()].map((n) => [n.id, second.customer(n.vars)]),
+  );
+  const words = (e) =>
+    second.step(e.action, nodeOf(e.from).vars, nodeOf(e.to).vars, "customer") || e.action;
+  const settle = (ids) => {
+    const all = new Set(ids);
+    for (const id of all)
+      for (const e of out.get(id) ?? []) {
+        const sameLabel = screen.get(e.to) === screen.get(id);
+        if (
+          !mainActions.has(e.action) &&
+          hiddenStep(trace.invariant, sameLabel, e.action, nodeOf(id).vars, nodeOf(e.to).vars)
+        )
+          all.add(e.to);
+      }
+    return all;
+  };
+  const seen = readerPath(trace, main, main.customer, "customer");
+  const shownAt = new Map(seen.map((p, j) => [p.modelStep, j]));
+  let here = settle(
+    [...second.graph.nodes.values()]
+      .filter((n) => n.init && screen.get(n.id) === seen[0].key)
+      .map((n) => n.id),
+  );
+  if (here.size === 0) return { reason: "starts in another state" };
+  const passed = new Set(here);
+  let j = 0;
+  for (let i = 1; i < trace.steps.length; i++) {
+    const { action } = trace.steps[i];
+    const hidden = !shownAt.has(i);
+    if (!hidden) j = shownAt.get(i);
+    const want = seen[j];
+    const [before, after] = [trace.steps[i - 1].vars, trace.steps[i].vars];
+    const known = actions.has(action);
+    if (!known && hidden) continue;
+    const moved = shared(before) !== shared(after);
+    const steps = (keep) => [...here].flatMap((id) => (out.get(id) ?? []).filter(keep));
+    const tries = steps((e) =>
+      known ? e.action === action : moved && sharedOf(nodeOf(e.to)) === shared(after),
+    );
+    if (hidden && tries.length === 0) continue;
+    const looksSame = (e) => screen.get(e.to) === want.key && (hidden || words(e) === want.label);
+    const matched = known ? tries.filter(looksSame) : tries;
+    const same = matched.length || hidden ? matched : steps(looksSame);
+    if (same.length) {
+      here = settle(same.map((e) => e.to));
+      for (const id of here) passed.add(id);
+      continue;
+    }
+    const outcomes = new Map();
+    for (const e of tries) {
+      const id = `${screen.get(e.to)}${SEP}${words(e)}`;
+      outcomes.set(id, [...(outcomes.get(id) ?? []), e]);
+    }
+    const taken = [...outcomes.values()].sort((a, b) => b.length - a.length)[0]?.[0];
+    const from = main.key(before);
+    const said = hidden ? main.step(action, before, after, "customer") || action : want.label;
+    const at = { modelStep: i, said, from, hidden };
+    if (!taken)
+      return {
+        ...at,
+        key: from,
+        label: main.step(action, before, after) || action,
+        disabled: true,
+      };
+    const [b, a] = [nodeOf(taken.from).vars, nodeOf(taken.to).vars];
+    return {
+      ...at,
+      key: second.key(a),
+      label: second.step(taken.action, b, a) || taken.action,
+      own: words(taken),
+    };
+  }
+  const bad = badOf(rawSecondTraces, trace.invariant);
+  const checked = secondRules.has(trace.invariant);
+  const ruleHolds = checked && ![...passed].some((id) => bad.has(stateKey(nodeOf(id).vars)));
+  return { sameEnd: true, checked, ruleHolds };
+}
+
+export function divergence(s, path, n, { inSecond, modelEdges }) {
+  if (s?.key === undefined) return s;
+  const step = path.findLastIndex((p) => p.modelStep < s.modelStep) + (s.hidden ? 0 : 1);
+  const plain = edgeId(s.from, s.key);
+  if (s.disabled) {
+    const text = inSecond(`${s.label} cannot happen at step ${step}`);
+    const edge = `${plain}${SEP}cannot${SEP}second`;
+    return { ...s, step, text, overview: `${text} of bug ${n}`, edge, apart: true };
+  }
+  const text = inSecond(s.label);
+  const drawn = [s.label, text].some((l) => modelEdges.get(plain)?.labels.has(l));
+  return { ...s, step, text, overview: text, edge: drawn ? plain : `${plain}${SEP}second` };
+}

package/skills/statechart/scripts/snapshot.mjs

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+const imports = (text, dir) =>
+  [...text.matchAll(/\b(?:from|import)\s*\(?\s*["'](\.{1,2}\/[^"']+)["']/g)].map((m) =>
+    path.resolve(dir, m[1]),
+  );
+
+const DEPENDENCIES = {
+  ".tla": (text, dir) =>
+    [
+      ...text
+        .replace(/\(\*[^]*?\*\)/g, " ")
+        .replace(/\\\*.*/g, " ")
+        .matchAll(/\b(?:EXTENDS|INSTANCE)\s+(\w+(?:\s*,\s*\w+)*)/g),
+    ].flatMap((m) => m[1].split(/\s*,\s*/).map((name) => path.join(dir, `${name}.tla`))),
+  ".mjs": imports,
+  ".js": imports,
+};
+
+export const copyPath = (root, file, paths = path) => {
+  const absolute = paths.resolve(file);
+  const pathRoot = paths.parse(absolute).root;
+  return paths.join(root, pathRoot.replace(/\W+/g, ""), paths.relative(pathRoot, absolute));
+};
+
+const contentOf = (file) => {
+  try {
+    return fs.readFileSync(file, "base64");
+  } catch {
+    return null;
+  }
+};
+
+export class Inputs {
+  #root = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-inputs-"));
+  #files = new Set();
+
+  constructor() {
+    process.on("exit", () => fs.rmSync(this.#root, { recursive: true, force: true }));
+  }
+
+  add(files) {
+    for (const file of files) if (file) this.#take(path.resolve(file), true);
+    return this;
+  }
+
+  copyOf(file) {
+    return copyPath(this.#root, file);
+  }
+
+  changed() {
+    return [...this.#files].find((file) => contentOf(file) !== contentOf(this.copyOf(file)));
+  }
+
+  #take(file, listed) {
+    if (this.#files.has(file)) return;
+    let content;
+    try {
+      content = fs.readFileSync(file);
+    } catch {
+      if (listed) this.#files.add(file);
+      return;
+    }
+    this.#files.add(file);
+    const copy = this.copyOf(file);
+    fs.mkdirSync(path.dirname(copy), { recursive: true });
+    fs.writeFileSync(copy, content);
+    const found = DEPENDENCIES[path.extname(file)]?.(content.toString("utf8"), path.dirname(file));
+    for (const dependency of found ?? []) this.#take(dependency, false);
+  }
+}

package/skills/statechart/scripts/spec-text.mjs

@@ -0,0 +1,126 @@
+import fs from "node:fs";
+import path from "node:path";
+import { BROKEN_MARK, PRIMES_OR_UNCHANGED, tlaVariables } from "./lib.mjs";
+
+export const withoutComments = (spec) =>
+  fs
+    .readFileSync(spec, "utf8")
+    .replace(/\(\*[^]*?\*\)/g, " ")
+    .replace(/\\\*.*/g, " ");
+
+function specVariables(spec, seen) {
+  const text = withoutComments(spec);
+  const extended = /\bEXTENDS\s+(\w+(?:\s*,\s*\w+)*)/.exec(text)?.[1].split(/\s*,\s*/) ?? [];
+  return [
+    ...extended.flatMap((m) => {
+      const file = path.join(path.dirname(spec), `${m}.tla`);
+      if (seen.has(m) || !fs.existsSync(file)) return [];
+      seen.add(m);
+      return specVariables(file, seen);
+    }),
+    ...tlaVariables(text),
+  ];
+}
+
+export const RULES_INVARIANT = "StatechartRules";
+
+export function writeRulesModule(spec, rules, dir) {
+  const name = path.basename(spec, ".tla");
+  const file = path.join(dir, `${name}_rules.tla`);
+  const fields = specVariables(spec, new Set([name])).map((v) => `${v} |-> ${v}`);
+  const broken = rules.map((r) => `(IF ${r} THEN {} ELSE {"${r}"})`).join(" \\cup ");
+  fs.writeFileSync(
+    file,
+    `---- MODULE ${name}_rules ----
+EXTENDS ${name}
+StatechartTLC == INSTANCE TLC
+StatechartBroken == ${broken}
+${RULES_INVARIANT} == StatechartBroken = {} \\/ StatechartTLC!PrintT(<<"${BROKEN_MARK}", [${fields.join(", ")}], StatechartBroken>>)
+====
+`,
+  );
+  return file;
+}
+
+export const SCAFFOLD = (name, spec) => {
+  const text = withoutComments(spec);
+  const vars = tlaVariables(text);
+  const primedDefinitions = [
+    ...new Set(
+      text
+        .split(/\n(?=\S)/)
+        .map((d) => /^(\w+)\s*(?:\([^)]*\))?\s*==([^]*)/.exec(d))
+        .filter((d) => d && PRIMES_OR_UNCHANGED.test(d[2]))
+        .map((d) => d[1]),
+    ),
+  ].sort();
+  return `// Chart labels for ${name}, for statechart.mjs. Write labels in the words of the person who reads
+// the chart, not in variable or action names.
+// v, before, and after map each variable to its value. Strings, numbers, and booleans keep their kind.
+// Sequences and tuples, including functions over 1..n, read from 1 as in TLA+, so v.seat[1] is the
+// first item. Reading index 0 stops the run. length, array methods, and spread still work. A
+// method's index, such as indexOf or the i in map((x, i) => ...), still counts from 0.
+// Sets become arrays. Records and other functions become objects.
+// Variables: ${vars.join(", ")}.
+
+// The actions that the reader takes, by action name, when the chart separates what the reader does
+// from what happens around the reader. facts.settled is true when only these are enabled. With
+// --cover, the overview keeps only the shortest path to each settled state, plus every bug path.
+// Leave it empty when every action counts the same.
+export const readerActions = [];
+
+// The label for one model state. facts.enabled is the set of actions the state enables,
+// including steps that change no variable. A label "context: progress", such as
+// "Primary down: write queued", puts the states of one context in one box, and can draw the
+// overview as two parallel regions. Use that form only when the context and the progress change
+// independently. A label without ": " draws each state on its own.
+// Do not claim a result that a pending step can still change, such as "write lost" while a
+// retry is still queued.
+export function state(v, facts) {
+	return JSON.stringify(v);
+}
+
+// The names of the two parallel regions, when the overview draws them: contexts, then progress.
+// export const regionNames = ["Primary", "Write"];
+
+// The group of one model state, in the reader's words, such as "Order shipped". The chart fills
+// the states of one group with one color, and the legend names the groups. TLC still decides
+// which states break a rule, and draws them with a thick red border on top of the group color.
+// groupColors gives a group a light color. Groups without one take a palette color.
+// export function group(v, facts) {}
+// export const groupColors = { "Order shipped": "#d1f2eb" };
+
+// The label for one step. A step that leaves the reader in the same state is not drawn,
+// unless the reader takes it on a bug path. "" draws no label, and a numbered bug step shows the action.
+// action is the action's name without its parameters, so compare before and after to tell which
+// process or item the step changed.
+// STEPS lists every definition that changes a variable. TLC names no step after one that another
+// action uses in its /\\ list, such as Log in Save == Log /\\ saved' = TRUE, so delete its entry.
+const STEPS = {
+${primedDefinitions.map((a) => `\t${a}: ${JSON.stringify(a)},`).join("\n")}
+};
+export function step(action, before, after) {
+	return STEPS[action] ?? action;
+}
+
+// When the step can happen, in plain words, such as "after the lease expires". The chart shows
+// "step [words]". "" adds nothing.
+// export function guard(action, before, after) {}
+
+// For a timer step, how many seconds the code waits, from the constant in the code. The chart
+// shows "after N s, step". Return nothing for other steps.
+// export function timer(action, before, after) {}
+
+// Why a bad state is bad, in the reader's words, such as "a worker crashed after it took the job,
+// and no other worker can take it". No variable, function, or event names.
+// Counterexamples that break one rule with one cause are one bug, so two bugs that end in the
+// same state stay apart only if their causes differ. Return null to group by the end state.
+// export function cause(v, facts, invariant) {}
+
+// The developer's words for one model state. With it, each bug is also drawn through these states.
+// export function detail(v, facts) {}
+
+// The legend's words for each status, in place of the defaults. Group entries keep their names.
+// export const legend = { works: "Works on main", wrong: "Wrong on main", fixed: "Fixed in the open PR" };
+`;
+};