pi-t3-pstack 0.0.0-stage → 0.1.0

package/pstack/skills/statechart/scripts/passes/label.ts

@@ -0,0 +1,269 @@
+import {
+  type Answers,
+  type Bug,
+  type Graph,
+  type Hidden,
+  isRecord,
+  key,
+  type Labels,
+  list,
+  loopOf,
+  must,
+  type Rule,
+  type Shape,
+  sortBy,
+  stateText,
+  type Step,
+  type Story,
+  tupleKey,
+  type Vars,
+  type View,
+  type Walk,
+} from "../ir.ts";
+
+const isLabel = (l: unknown): l is string =>
+  typeof l === "string" && l !== "" && !/\bundefined\b|\bNaN\b|\[object Object\]/.test(l);
+
+const shapeOf = (shape: unknown, vars: Vars): Shape => {
+  function fail(): never {
+    throw new Error(
+      `The view's state() returned ${JSON.stringify(shape) ?? "undefined"} for the state ${stateText(vars)}. Return a string, an array of strings, or an object of those.`,
+    );
+  }
+  const path = (p: unknown) => {
+    const labels: string[] = [];
+    for (const l of [p].flat()) {
+      if (!isLabel(l)) fail();
+      labels.push(l);
+    }
+    if (!labels.length) fail();
+    return labels;
+  };
+  const regions: [string, unknown][] = isRecord(shape) ? Object.entries(shape) : [["", shape]];
+  const pairs: [string, string[]][] = [];
+  for (const [k, v] of regions) pairs.push([k, path(v)]);
+  return pairs.length ? Object.fromEntries(pairs) : fail();
+};
+
+const stepOf = (view: View) => (action: string, from: Vars, to: Vars) => {
+  const label = (view.step ?? ((a: string) => a))(action, from, to);
+  if (label === null || isLabel(label)) return label;
+  throw new Error(
+    `The view's step() returned ${JSON.stringify(label) ?? "undefined"} for the step ${action}.`,
+  );
+};
+
+function unlabeled(
+  action: string,
+  before: Vars,
+  after: Vars,
+  bug: { rule: Rule; loop?: number },
+): never {
+  const changed: string[] = [];
+  for (const k of Object.keys(after)) if (key(before[k]) !== key(after[k])) changed.push(k);
+  throw new Error(
+    `The view's step() returned null for the step ${action} that changes ${changed.join(", ") || "nothing"}. It is on the path to the ${bug.rule.name} bug${bug.loop === undefined ? "" : " or leaves its loop"}, so label it.`,
+  );
+}
+
+export function ask(graph: Graph, { states: tla, nameOf, from, to }: Walk, view: View): Answers {
+  const n = nameOf.length;
+  const m = from.length;
+  const state = view.state;
+  const shapes = new Array<Shape>(n);
+  for (let i = 0; i < n; i++)
+    shapes[i] = shapeOf(state ? state(tla[i].vars) : nameOf[i], tla[i].vars);
+  const names = Object.keys(shapes[0] ?? { "": [] });
+  const regionsKey = tupleKey(names);
+  for (let i = 0; i < n; i++)
+    if (tupleKey(Object.keys(shapes[i])) !== regionsKey)
+      throw new Error(
+        `The view's state() returned the regions ${names.join(", ")} for one state and ${Object.keys(shapes[i]).join(", ")} for the state ${stateText(tla[i].vars)}. Return the same regions for every state.`,
+      );
+  const step = stepOf(view);
+  const labels = new Array<string | Hidden>(m);
+  for (let j = 0; j < m; j++)
+    labels[j] = step(graph.steps[j].action, tla[from[j]].vars, tla[to[j]].vars);
+  const groups = new Array<unknown>(n);
+  const asked = new Uint8Array(n);
+  const group = (i: number) => {
+    if (view.group && !asked[i]) {
+      groups[i] = view.group(tla[i].vars);
+      asked[i] = 1;
+    }
+    return groups[i];
+  };
+  return { names, shapes, labels, group };
+}
+
+export function asParents(
+  { states: tla }: Walk,
+  { names, shapes, labels, group }: Answers,
+): Answers {
+  const parents = new Array<Shape>(shapes.length);
+  for (let i = 0; i < shapes.length; i++) {
+    const path: string[] = [];
+    for (const n of names) for (const p of shapes[i][n]) path.push(`${n} ${p}`);
+    parents[i] = shapeOf(path, tla[i].vars);
+  }
+  return { names: [""], shapes: parents, labels, group };
+}
+
+export function labelGraph(
+  graph: Graph,
+  { index, from, to, action }: Walk,
+  answers: Answers,
+  rank: Int32Array,
+  found: Bug[],
+): Labels {
+  const { names, shapes, labels: stepLabels } = answers;
+  const n = shapes.length;
+  const m = stepLabels.length;
+  const onPath = new Set<Step>();
+  for (const b of found) for (const p of b.path) onPath.add(p.step);
+  const pathStepIndex = new Map<Step, number>();
+  if (onPath.size)
+    for (let j = 0; j < m; j++)
+      if (onPath.has(graph.steps[j])) pathStepIndex.set(graph.steps[j], j);
+  const R = names.length;
+  const keys: string[][] = [];
+  const kinds: Int32Array[] = [];
+  const sizes: number[] = [];
+  for (const name of names) {
+    const key = new Array<string>(n);
+    const kind = new Int32Array(n);
+    const tops = new Map<string, number>();
+    const nested = new Map<string, number>();
+    const keyOf: string[] = [];
+    for (let i = 0; i < n; i++) {
+      const path = shapes[i][name];
+      const top = path.length === 1;
+      const seen = top ? tops : nested;
+      const k = top ? path[0] : tupleKey(path);
+      let c = seen.get(k);
+      if (c === undefined) {
+        seen.set(k, (c = keyOf.length));
+        keyOf.push(top ? tupleKey(path) : k);
+      }
+      key[i] = keyOf[c];
+      kind[i] = c;
+    }
+    keys.push(key);
+    kinds.push(kind);
+    sizes.push(keyOf.length);
+  }
+  for (const b of found) {
+    let t: Step | undefined;
+    for (const p of b.path)
+      if (stepLabels[must(pathStepIndex, p.step)] === null) {
+        t = p.step;
+        break;
+      }
+    if (!t) {
+      const inLoop = loopOf(b, index);
+      if (inLoop.size)
+        for (let j = 0; j < m; j++)
+          if (inLoop.has(from[j]) && !inLoop.has(to[j]) && stepLabels[j] === null) {
+            t = graph.steps[j];
+            break;
+          }
+    }
+    if (t) unlabeled(t.action, must(graph.states, t.from).vars, must(graph.states, t.to).vars, b);
+  }
+  const drawn: number[] = [];
+  const drawnLabels = new Array<string>(m);
+  for (let j = 0; j < m; j++) {
+    const label = stepLabels[j];
+    if (label === null) continue;
+    drawn.push(j);
+    drawnLabels[j] = label;
+  }
+  const fromRank = new Int32Array(m);
+  const toRank = new Int32Array(m);
+  for (let j = 0; j < m; j++) {
+    fromRank[j] = rank[from[j]];
+    toRank[j] = rank[to[j]];
+  }
+  const sorted = sortBy(Int32Array.from(drawn), [fromRank, toRank, action]);
+  const pathSteps = new Uint8Array(m);
+  for (const j of pathStepIndex.values()) pathSteps[j] = 1;
+  const byLabel = new Map<string, { changed: Uint8Array; sets: Set<string> }>();
+  if (R > 1)
+    for (const j of sorted) {
+      let entry = byLabel.get(drawnLabels[j]);
+      if (!entry)
+        byLabel.set(drawnLabels[j], (entry = { changed: new Uint8Array(R), sets: new Set() }));
+      const changed: string[] = [];
+      for (let r = 0; r < R; r++)
+        if (kinds[r][from[j]] !== kinds[r][to[j]]) {
+          changed.push(names[r]);
+          entry.changed[r] = 1;
+        }
+      if (changed.length > 1) entry.sets.add(list(changed));
+    }
+  const together = new Set<string>();
+  for (const [text, { sets }] of byLabel) if (sets.size) together.add(text);
+  const notes: string[] = [];
+  for (const [text, entry] of byLabel) {
+    const changed: string[] = [];
+    for (let r = 0; r < R; r++) if (entry.changed[r]) changed.push(names[r]);
+    if (changed.length < 2) continue;
+    if (!together.has(text)) {
+      notes.push(`The step ${text} changes only one of ${list(changed)} at a time.`);
+      continue;
+    }
+    const sets = [...entry.sets];
+    notes.push(
+      `The step ${text} changes ${sets.length > 1 ? `${sets.join(", or ")},` : sets[0]} at the same time.`,
+    );
+  }
+  return {
+    ...answers,
+    drawnLabels,
+    keys,
+    kinds,
+    sizes,
+    sorted,
+    pathStepIndex,
+    pathSteps,
+    together,
+    notes,
+  };
+}
+
+type Told<Id> = { rule: Rule; start: Id; path: { action: string; state: Id }[]; loop?: number };
+
+function tell<Id, B extends Told<Id>>(
+  states: ReadonlyMap<Id, { vars: Vars }>,
+  found: B[],
+  shapeAt: (id: Id) => Shape,
+  labelAt: (bug: B, k: number, from: Id) => string | Hidden,
+) {
+  const vars = (id: Id) => must(states, id).vars;
+  const stories = new Map<B, Story>();
+  for (const bug of found) {
+    const story: Story = [{ state: shapeAt(bug.start) }];
+    let from: Id = bug.start;
+    for (const [k, p] of bug.path.entries()) {
+      const step = labelAt(bug, k, from);
+      if (step === null) unlabeled(p.action, vars(from), vars(p.state), bug);
+      story.push({ step, state: shapeAt(p.state) });
+      from = p.state;
+    }
+    stories.set(bug, story);
+  }
+  return stories;
+}
+
+export const storiesOf = (
+  graph: Graph,
+  found: Bug[],
+  { index }: Walk,
+  { shapes, drawnLabels, pathStepIndex }: Labels,
+) =>
+  tell(
+    graph.states,
+    found,
+    (id) => shapes[must(index, id)],
+    (bug, k) => drawnLabels[must(pathStepIndex, bug.path[k].step)],
+  );

package/pstack/skills/statechart/scripts/passes/lift.ts

@@ -0,0 +1,85 @@
+import {
+  append,
+  type Chart,
+  type ChartState,
+  type ChartStep,
+  must,
+  type Region,
+  tupleKey,
+  unkey,
+} from "../ir.ts";
+
+export function liftToParents(states: ChartState[], steps: ChartStep[]) {
+  const depths = new Map<string, number>();
+  const leaves = new Map<string, number>();
+  for (const s of states.values())
+    for (let i = 1; i < s.path.length; i++) {
+      const prefix = tupleKey(s.path.slice(0, i));
+      depths.set(prefix, i);
+      leaves.set(prefix, (leaves.get(prefix) ?? 0) + 1);
+    }
+  if (!depths.size) return steps;
+  const leaving = new Map<string, ChartStep[]>();
+  for (const s of steps) {
+    let same = 0;
+    while (same < s.from.length && s.from[same] === s.to[same]) same++;
+    for (let i = 1; i < s.from.length; i++) {
+      if (i <= same && i < s.to.length) continue;
+      const prefix = tupleKey(s.from.slice(0, i));
+      if (depths.has(prefix)) append(leaving, prefix, s);
+    }
+  }
+  const removed = new Set<ChartStep>();
+  const lifted: ChartStep[] = [];
+  for (const [prefix] of [...depths].sort((a, b) => a[1] - b[1])) {
+    const groups = new Map<string, ChartStep[]>();
+    for (const s of leaving.get(prefix) ?? [])
+      if (!removed.has(s)) append(groups, tupleKey([s.label, s.when, s.to]), s);
+    const under = must(leaves, prefix);
+    for (const group of groups.values()) {
+      if (under < 2 || group.length < under) continue;
+      for (const s of group) removed.add(s);
+      lifted.push({ ...group[0], from: unkey(prefix) });
+    }
+  }
+  const kept: ChartStep[] = [];
+  for (const s of steps) if (!removed.has(s)) kept.push(s);
+  for (const s of lifted) kept.push(s);
+  return kept;
+}
+
+export function lift(chart: Chart): Chart {
+  const regions: Region[] = [];
+  for (const r of chart.regions) {
+    const known = new Map<string[], number>();
+    for (const s of r.states) known.set(s.path, known.size);
+    let numbers: Map<string, number> | undefined;
+    const pathIndex = (path: string[]) => {
+      let i = known.get(path);
+      if (i !== undefined) return i;
+      if (!numbers) {
+        numbers = new Map();
+        for (const s of r.states) numbers.set(tupleKey(s.path), numbers.size);
+      }
+      const k = tupleKey(path);
+      i = numbers.get(k);
+      if (i === undefined) numbers.set(k, (i = numbers.size));
+      known.set(path, i);
+      return i;
+    };
+    const merged = new Map<number | string, ChartStep>();
+    for (const s of liftToParents(r.states, r.steps)) {
+      const f = pathIndex(s.from);
+      const t = pathIndex(s.to);
+      const k =
+        s.when === undefined && f < 2 ** 26 && t < 2 ** 26
+          ? f * 2 ** 26 + t
+          : `${f},${t}:${s.when}`;
+      const prior = merged.get(k);
+      if (prior) prior.label += ` or ${s.label}`;
+      else merged.set(k, { ...s });
+    }
+    regions.push({ ...r, steps: [...merged.values()] });
+  }
+  return { ...chart, regions };
+}

package/pstack/skills/statechart/scripts/passes/loop-check.ts

@@ -0,0 +1,68 @@
+import {
+  append,
+  type Arrow,
+  type Bug,
+  type Chart,
+  holds,
+  type Labels,
+  loopOf,
+  must,
+  tupleKey,
+  unkey,
+  type Walk,
+} from "../ir.ts";
+
+export function loopCheck(
+  { regions, loops }: Chart,
+  { names, keys, drawnLabels, sorted }: Labels,
+  { index, from, to }: Walk,
+  found: Bug[],
+) {
+  const R = names.length;
+  const combo = (i: number) => {
+    const parts: string[] = [];
+    for (let r = 0; r < R; r++) parts.push(keys[r][i]);
+    return tupleKey(parts);
+  };
+  const stepsFrom = new Map<number, number[]>();
+  const arrowsFrom: Map<string, Arrow[]>[] = [];
+  if (loops.length) {
+    for (const j of sorted) append(stepsFrom, from[j], j);
+    for (const { arrows } of regions) {
+      const out = new Map<string, Arrow[]>();
+      for (const a of arrows) append(out, a.from, a);
+      arrowsFrom.push(out);
+    }
+  }
+  for (const b of found) {
+    if (b.loop === undefined) continue;
+    const inLoop = new Set<string>();
+    const twinsOf = new Map<string, number[]>();
+    for (const i of loopOf(b, index)) {
+      inLoop.add(combo(i));
+      append(twinsOf, combo(i), i);
+    }
+    for (const i of loopOf(b, index)) {
+      const twins = must(twinsOf, combo(i));
+      for (const [r, name] of names.entries()) {
+        const takes = (a: Arrow) => {
+          for (const s of twins)
+            for (const j of stepsFrom.get(s) ?? [])
+              if (drawnLabels[j] === a.label && keys[r][to[j]] === a.to) return true;
+          return false;
+        };
+        const rest: string[] = [];
+        for (let o = 0; o < R; o++) if (o !== r) rest.push(keys[o][i]);
+        for (const a of arrowsFrom[r].get(keys[r][i]) ?? []) {
+          if (!holds(a.condition, rest)) continue;
+          const next: string[] = [];
+          for (let o = 0; o < R; o++) next.push(o === r ? a.to : keys[o][i]);
+          if (!inLoop.has(tupleKey(next)) && !takes(a))
+            throw new Error(
+              `The chart draws the step ${a.label} out of ${name ? `${name} ` : ""}${unkey(a.from).join(" / ")}, but the ${b.rule.name} loop cannot take it there. Show in a label what stops it.`,
+            );
+        }
+      }
+    }
+  }
+}

package/pstack/skills/statechart/scripts/passes/paths.ts

@@ -0,0 +1,60 @@
+import {
+  type Bug,
+  type Graph,
+  hasRule,
+  type Lasso,
+  must,
+  type PathStep,
+  type Rule,
+  stateKey,
+  type Step,
+  type Trace,
+  type TraceState,
+  type Vars,
+} from "../ir.ts";
+
+export function pathGraph(names: string[]) {
+  const graph: Graph = { states: new Map(), steps: [] };
+  const ids = new Map<string, string>();
+  const taken = new Map<string, Step>();
+  const idOf = (vars: Vars | undefined, start: boolean) => {
+    if (!vars) throw new Error("TLC's trace has a state with no values.");
+    const k = stateKey(names.map((name) => vars[name]));
+    let id = ids.get(k);
+    if (id === undefined) {
+      ids.set(k, (id = String(ids.size)));
+      graph.states.set(id, { vars, start, breaks: [] });
+    } else if (start) must(graph.states, id).start = true;
+    return id;
+  };
+  const route = (seq: { action: string; vars: Vars | undefined }[]) => {
+    const start = idOf(seq[0].vars, true);
+    const path: PathStep[] = [];
+    let from = start;
+    for (let i = 1; i < seq.length; i++) {
+      const { action } = seq[i];
+      const to = idOf(seq[i].vars, false);
+      const k = `${from} ${to} ${action}`;
+      let step = taken.get(k);
+      if (!step) {
+        taken.set(k, (step = { from, to, action }));
+        graph.steps.push(step);
+      }
+      path.push({ action, state: to, step });
+      from = to;
+    }
+    return { start, path };
+  };
+  return {
+    graph,
+    bug: (rule: Rule, trace: TraceState[]): Bug => {
+      if (!trace.length) throw new Error(`TLC's trace for ${rule.name} has no states.`);
+      const bug = { rule, ...route(trace) };
+      const end = must(graph.states, bug.path.at(-1)?.state ?? bug.start);
+      if (!hasRule(end.breaks, rule)) end.breaks.push(rule);
+      return bug;
+    },
+    lasso: ({ seq, loop }: Trace): Lasso | undefined =>
+      seq.length ? { ...route(seq), loop, stutters: loop === seq.length - 1 } : undefined,
+  };
+}

package/pstack/skills/statechart/scripts/passes/reach.ts

@@ -0,0 +1,135 @@
+import {
+  type Bug,
+  byText,
+  count,
+  defaultState,
+  type Graph,
+  must,
+  type PathStep,
+  type Rule,
+  ruleKey,
+  sortBy,
+  type State,
+  type Walk,
+} from "../ir.ts";
+
+export function walk(graph: Graph): Walk {
+  const ids: string[] = [];
+  const states: State[] = [];
+  const nameOf: string[] = [];
+  const starts: number[] = [];
+  const unique = new Set<string>();
+  for (const [id, s] of graph.states) {
+    const name = defaultState(s.vars);
+    if (s.start) starts.push(ids.length);
+    ids.push(id);
+    states.push(s);
+    nameOf.push(name);
+    unique.add(name);
+  }
+  const names = Array.from(unique).sort(byText);
+  const rankOf = new Map<string, number>();
+  for (let i = 0; i < names.length; i++) rankOf.set(names[i], i);
+  const n = ids.length;
+  const index = new Map<string, number>();
+  const nameRank = new Int32Array(n);
+  for (let i = 0; i < n; i++) {
+    index.set(ids[i], i);
+    nameRank[i] = must(rankOf, nameOf[i]);
+  }
+  const m = graph.steps.length;
+  const from = new Int32Array(m);
+  const to = new Int32Array(m);
+  const action = new Int32Array(m);
+  const actions = new Map<string, number>();
+  for (let j = 0; j < m; j++) {
+    const t = graph.steps[j];
+    from[j] = must(index, t.from);
+    to[j] = must(index, t.to);
+    let a = actions.get(t.action);
+    if (a === undefined) actions.set(t.action, (a = actions.size));
+    action[j] = a;
+  }
+  const actionRank = new Int32Array(actions.size);
+  for (const [i, a] of [...actions.keys()].sort(byText).entries()) actionRank[must(actions, a)] = i;
+  const toName = new Int32Array(m);
+  for (let j = 0; j < m; j++) {
+    action[j] = actionRank[action[j]];
+    toName[j] = nameRank[to[j]];
+  }
+  const first = new Int32Array(n + 1);
+  for (let j = 0; j < m; j++) first[from[j] + 1]++;
+  for (let i = 0; i < n; i++) first[i + 1] += first[i];
+  const fill = first.slice(0, n);
+  const next = new Int32Array(m);
+  for (const j of sortBy(count(m), [action, toName])) next[fill[from[j]]++] = j;
+  starts.sort((a, b) => nameRank[a] - nameRank[b]);
+  const depth = new Int32Array(n).fill(-1);
+  const via = new Int32Array(n).fill(-1);
+  const reached = new Int32Array(n);
+  let size = 0;
+  for (const s of starts) {
+    depth[s] = 0;
+    reached[size++] = s;
+  }
+  for (let q = 0; q < size; q++) {
+    const s = reached[q];
+    for (let e = first[s]; e < first[s + 1]; e++) {
+      const t = to[next[e]];
+      if (depth[t] >= 0) continue;
+      depth[t] = depth[s] + 1;
+      via[t] = next[e];
+      reached[size++] = t;
+    }
+  }
+  return {
+    ids,
+    states,
+    index,
+    nameOf,
+    nameRank,
+    from,
+    to,
+    action,
+    depth,
+    via,
+    reached: reached.subarray(0, size),
+    starts,
+  };
+}
+
+export function drawOrder({ depth, nameRank }: Walk) {
+  const n = depth.length;
+  let deepest = 0;
+  for (let i = 0; i < n; i++) if (depth[i] > deepest) deepest = depth[i];
+  const level = new Int32Array(n);
+  for (let i = 0; i < n; i++) level[i] = depth[i] < 0 ? deepest + 1 : depth[i];
+  const order = sortBy(count(n), [level, nameRank]);
+  const rank = new Int32Array(n);
+  for (let p = 0; p < n; p++) rank[order[p]] = p;
+  return { order, rank };
+}
+
+export function bugs(graph: Graph, { ids, from, via, reached }: Walk = walk(graph)) {
+  const ends = new Map<string, string>();
+  for (const [id, s] of graph.states) for (const rule of s.ends ?? []) ends.set(ruleKey(rule), id);
+  const first = new Map<string, { rule: Rule; i: number }>();
+  for (const i of reached) {
+    const s = must(graph.states, ids[i]);
+    for (const rule of s.past ? s.ends : s.breaks) {
+      const k = ruleKey(rule);
+      if (!first.has(k) && (ends.get(k) ?? ids[i]) === ids[i]) first.set(k, { rule, i });
+    }
+  }
+  const found: Bug[] = [];
+  for (const { rule, i } of first.values()) {
+    const path: PathStep[] = [];
+    let start = i;
+    for (let j: number; (j = via[start]) >= 0; start = from[j]) {
+      const step = graph.steps[j];
+      path.unshift({ action: step.action, state: step.to, step });
+    }
+    found.push({ rule, start: ids[start], path });
+  }
+  return found;
+}