raga-cli 0.0.0-stage → 0.8.0

package/bundled-skills/skills/peak/references/statechart/scripts/model/OutputFolder.cfg

@@ -0,0 +1,6 @@
+SPECIFICATION Spec
+INVARIANT ChartsOneSpec
+INVARIANT KeepsYourFiles
+INVARIANT NeverLosesChart
+INVARIANT ExitTwoLeavesFolder
+INVARIANT OverlapNeverRefuses

package/bundled-skills/skills/peak/references/statechart/scripts/model/OutputFolder.map.mjs

@@ -0,0 +1,106 @@
+const QUIET = ["idle", "exited", "stopped", "orphanTlc"];
+const going = (v) => v.pc.filter((p) => !QUIET.includes(p)).length;
+const changed = (before, after) =>
+  after.pc.findIndex(
+    (p, i) => p !== before.pc[i] || after.aside[i].exists !== before.aside[i].exists,
+  ) + 1;
+
+export const readerActions = ["Start", "Edit", "Note", "Stop", "KillNode"];
+
+function context(v) {
+  if (v.pc.every((p) => p === "idle")) return "Before any run";
+  if (going(v) === 2) return "Two runs going";
+  return going(v) === 1 ? "One run going" : "Done";
+}
+
+const SPECS = { 1: "the spec", 2: "the edited spec", "1,2": "both specs" };
+
+function contents(v) {
+  const kept = v.aside.filter((a) => a.exists);
+  const aside = kept.some((a) => a.notes)
+    ? ", your notes moved aside"
+    : kept.some((a) => a.by)
+      ? ", the old chart moved aside"
+      : "";
+  const parts = [
+    v.out.by && `chart of ${SPECS[v.out.read.join()]}`,
+    v.out.notes && "your notes",
+  ].filter(Boolean);
+  if (!v.out.exists) return `no folder${aside}`;
+  return `${parts.join(" and ") || "empty folder"}${aside}`;
+}
+
+export function state(v) {
+  return `${context(v)}: ${contents(v)}`;
+}
+
+export function group(v) {
+  if (v.pc.every((p) => p === "idle")) return "Not started";
+  return going(v) ? "Running" : "Finished";
+}
+
+export function step(action, before, after) {
+  const r = changed(before, after);
+  switch (action) {
+    case "Start": {
+      const where = going(before) ? " in a second shell" : "";
+      const how = after.inputOk[r - 1] ? "" : " with a typo";
+      return `you start run ${r}${where}${how}`;
+    }
+    case "Refuse":
+      return before.inputOk[r - 1]
+        ? `run ${r} says the folder has a file that it did not write`
+        : `run ${r} says the input is wrong`;
+    case "Tlc":
+      return `run ${r}'s TLC reads the spec`;
+    case "Draw":
+      return `run ${r} draws the chart in its own folder`;
+    case "Stale":
+      return `run ${r} says the spec changed while it read it`;
+    case "Foreign":
+      return `run ${r} says the folder has a file that it did not write`;
+    case "Swap":
+    case "Checked":
+      return "";
+    case "MoveIn":
+      return `run ${r} moves its folder into place`;
+    case "MoveAside":
+      return `run ${r} moves the old folder aside`;
+    case "Restore":
+      return `run ${r} puts the folder with your notes back and stops`;
+    case "Supersede":
+      return `run ${r} finds another run's folder in place and deletes the old folder`;
+    case "KeepAside":
+      return `run ${r} keeps the folder with your notes aside and says where`;
+    case "RenameFails":
+      if (after.aside[r - 1].exists)
+        return `run ${r} cannot rename a folder and says where the old folder is`;
+      return after.out.exists && !before.out.exists
+        ? `run ${r} cannot rename a folder, puts the old folder back, and stops`
+        : `run ${r} cannot rename a folder and stops`;
+    case "Clean":
+      return `run ${r} deletes the old folder and finishes`;
+    case "Edit":
+      return "you edit the spec";
+    case "Note":
+      return "you save notes in the folder";
+    case "Stop":
+      return `you stop run ${r} with Ctrl-C`;
+    case "KillNode":
+      return `you kill run ${r}'s Node, and its TLC keeps running`;
+    case "OrphanEnd":
+      return `run ${r}'s orphaned TLC finishes`;
+    default:
+      return action;
+  }
+}
+
+export function cause(v, facts, invariant) {
+  return {
+    ChartsOneSpec: "the run read the spec before and after an edit, and still wrote its chart",
+    KeepsYourFiles: "a run deleted a folder that had your notes in it",
+    NeverLosesChart: "a run deleted the last chart before another chart was in place",
+    ExitTwoLeavesFolder: "a run wrote the folder and then said it could not finish",
+    OverlapNeverRefuses: "a run stopped only because another run overlapped it",
+  }[invariant];
+}

package/bundled-skills/skills/peak/references/statechart/scripts/model/OutputFolder.tla

@@ -0,0 +1,176 @@
+---- MODULE OutputFolder ----
+EXTENDS Naturals
+
+Runs == {1, 2}
+NoRun == 0
+NoFolder == [exists |-> FALSE, by |-> NoRun, read |-> {}, notes |-> FALSE]
+
+VARIABLES pc, inputOk, snap, read, out, aside, spec, noted, wrote, broke, exitCode
+
+vars == <<pc, inputOk, snap, read, out, aside, spec, noted, wrote, broke, exitCode>>
+
+Init ==
+  /\ pc = [r \in Runs |-> "idle"]
+  /\ inputOk = [r \in Runs |-> TRUE]
+  /\ snap = [r \in Runs |-> 0]
+  /\ read = [r \in Runs |-> {}]
+  /\ out = NoFolder
+  /\ aside = [r \in Runs |-> NoFolder]
+  /\ spec = 1
+  /\ noted = FALSE
+  /\ wrote = [r \in Runs |-> FALSE]
+  /\ broke = [r \in Runs |-> FALSE]
+  /\ exitCode = [r \in Runs |-> "none"]
+
+Set(f, r, v) == [f EXCEPT ![r] = v]
+Going(r) == pc[r] \notin {"idle", "exited", "stopped", "orphanTlc"}
+Go(r, to) == pc' = Set(pc, r, to)
+Exit(r, code) == pc' = Set(pc, r, "exited") /\ exitCode' = Set(exitCode, r, code)
+
+Start(r) ==
+  /\ pc[r] = "idle"
+  /\ r = 2 => pc[1] # "idle"
+  /\ \E ok \in BOOLEAN : inputOk' = Set(inputOk, r, ok)
+  /\ snap' = Set(snap, r, spec)
+  /\ Go(r, "check")
+  /\ UNCHANGED <<read, out, aside, spec, noted, wrote, broke, exitCode>>
+
+Refuse(r) ==
+  /\ pc[r] = "check"
+  /\ ~inputOk[r] \/ out.notes
+  /\ Exit(r, "2")
+  /\ UNCHANGED <<inputOk, snap, read, out, aside, spec, noted, wrote, broke>>
+
+Tlc(r) ==
+  /\ \/ pc[r] = "check" /\ inputOk[r] /\ ~out.notes
+     \/ pc[r] = "tlc"
+  /\ read' = Set(read, r, read[r] \cup {spec})
+  /\ Go(r, IF pc[r] = "check" THEN "tlc" ELSE "draw")
+  /\ UNCHANGED <<inputOk, snap, out, aside, spec, noted, wrote, broke, exitCode>>
+
+Draw(r) ==
+  /\ pc[r] = "draw"
+  /\ Go(r, "publish")
+  /\ UNCHANGED <<inputOk, snap, read, out, aside, spec, noted, wrote, broke, exitCode>>
+
+Stale(r) ==
+  /\ pc[r] = "publish" /\ spec # snap[r]
+  /\ Exit(r, "2")
+  /\ UNCHANGED <<inputOk, snap, read, out, aside, spec, noted, wrote, broke>>
+
+Foreign(r) ==
+  /\ pc[r] = "publish" /\ spec = snap[r] /\ out.notes
+  /\ Exit(r, "2")
+  /\ UNCHANGED <<inputOk, snap, read, out, aside, spec, noted, wrote, broke>>
+
+Swap(r) ==
+  /\ pc[r] = "publish" /\ spec = snap[r] /\ ~out.notes
+  /\ Go(r, "swap")
+  /\ UNCHANGED <<inputOk, snap, read, out, aside, spec, noted, wrote, broke, exitCode>>
+
+MoveIn(r) ==
+  /\ pc[r] = "swap" /\ ~out.exists
+  /\ out' = [exists |-> TRUE, by |-> r, read |-> read[r], notes |-> FALSE]
+  /\ wrote' = Set(wrote, r, TRUE)
+  /\ Go(r, "clean")
+  /\ UNCHANGED <<inputOk, snap, read, aside, spec, noted, broke, exitCode>>
+
+MoveAside(r) ==
+  /\ pc[r] = "swap" /\ out.exists /\ ~aside[r].exists
+  /\ aside' = Set(aside, r, out)
+  /\ out' = NoFolder
+  /\ Go(r, "aside")
+  /\ UNCHANGED <<inputOk, snap, read, spec, noted, wrote, broke, exitCode>>
+
+Checked(r) ==
+  /\ pc[r] = "aside" /\ ~aside[r].notes
+  /\ Go(r, "swap")
+  /\ UNCHANGED <<inputOk, snap, read, out, aside, spec, noted, wrote, broke, exitCode>>
+
+Supersede(r) ==
+  /\ pc[r] = "swap" /\ out.exists /\ aside[r].exists /\ ~out.notes
+  /\ aside' = Set(aside, r, NoFolder)
+  /\ UNCHANGED <<pc, inputOk, snap, read, out, spec, noted, wrote, broke, exitCode>>
+
+Restore(r) ==
+  /\ pc[r] = "aside" /\ aside[r].notes /\ ~out.exists
+  /\ out' = aside[r]
+  /\ aside' = Set(aside, r, NoFolder)
+  /\ Exit(r, "2")
+  /\ UNCHANGED <<inputOk, snap, read, spec, noted, wrote, broke>>
+
+KeepAside(r) ==
+  /\ \/ pc[r] = "aside" /\ aside[r].notes /\ out.exists
+     \/ pc[r] = "swap" /\ aside[r].exists /\ out.notes
+  /\ Exit(r, "2")
+  /\ UNCHANGED <<inputOk, snap, read, out, aside, spec, noted, wrote, broke>>
+
+RenameFails(r) ==
+  /\ pc[r] \in {"swap", "aside"}
+  /\ \/ /\ aside[r].exists /\ ~out.exists
+        /\ out' = aside[r]
+        /\ aside' = Set(aside, r, NoFolder)
+     \/ UNCHANGED <<out, aside>>
+  /\ broke' = Set(broke, r, TRUE)
+  /\ Exit(r, "2")
+  /\ UNCHANGED <<inputOk, snap, read, spec, noted, wrote>>
+
+Clean(r) ==
+  /\ pc[r] = "clean"
+  /\ aside' = Set(aside, r, NoFolder)
+  /\ Exit(r, "0")
+  /\ UNCHANGED <<inputOk, snap, read, out, spec, noted, wrote, broke>>
+
+Stop(r) ==
+  /\ Going(r)
+  /\ Go(r, "stopped")
+  /\ UNCHANGED <<inputOk, snap, read, out, aside, spec, noted, wrote, broke, exitCode>>
+
+KillNode(r) ==
+  /\ pc[r] = "tlc"
+  /\ Go(r, "orphanTlc")
+  /\ UNCHANGED <<inputOk, snap, read, out, aside, spec, noted, wrote, broke, exitCode>>
+
+OrphanEnd(r) ==
+  /\ pc[r] = "orphanTlc"
+  /\ Go(r, "stopped")
+  /\ UNCHANGED <<inputOk, snap, read, out, aside, spec, noted, wrote, broke, exitCode>>
+
+Edit ==
+  /\ spec = 1
+  /\ spec' = 2
+  /\ UNCHANGED <<pc, inputOk, snap, read, out, aside, noted, wrote, broke, exitCode>>
+
+Note ==
+  /\ ~noted
+  /\ noted' = TRUE
+  /\ out' = [out EXCEPT !.exists = TRUE, !.notes = TRUE]
+  /\ UNCHANGED <<pc, inputOk, snap, read, aside, spec, wrote, broke, exitCode>>
+
+Next ==
+  \/ Edit \/ Note
+  \/ \E r \in Runs :
+       Start(r) \/ Refuse(r) \/ Tlc(r) \/ Draw(r) \/ Stale(r) \/ Foreign(r) \/ Swap(r)
+         \/ MoveIn(r) \/ MoveAside(r) \/ Checked(r) \/ Supersede(r) \/ Restore(r)
+         \/ KeepAside(r) \/ RenameFails(r) \/ Clean(r) \/ Stop(r) \/ KillNode(r) \/ OrphanEnd(r)
+
+Spec == Init /\ [][Next]_vars
+
+\* The folder never holds a chart drawn from two versions of the spec.
+ChartsOneSpec == out.read \in {{}, {1}, {2}}
+
+\* A file that you put in the folder is never deleted.
+KeepsYourFiles == noted => out.notes \/ \E r \in Runs : aside[r].notes
+
+\* Once a run writes a chart, the folder or a folder that a run moved aside always holds one.
+NeverLosesChart ==
+  (\E r \in Runs : wrote[r]) => out.by # NoRun \/ \E r \in Runs : aside[r].by # NoRun
+
+\* A run that exits 2 did not write the folder.
+ExitTwoLeavesFolder == \A r \in Runs : exitCode[r] = "2" => ~wrote[r]
+
+\* A run exits 2 only for a wrong input, an edited spec, a file that it did not write, or a failed
+\* rename, never because another run overlaps it.
+OverlapNeverRefuses ==
+  \A r \in Runs : exitCode[r] = "2" => ~inputOk[r] \/ spec # snap[r] \/ noted \/ broke[r]
+====