pi-pstack-native 0.0.0-stage → 1.0.0

package/dist/statechart/ir.js

@@ -0,0 +1,317 @@
+export const EC = {
+    TLC_INVARIANT_VIOLATED_INITIAL: 2107,
+    TLC_PROPERTY_VIOLATED_INITIAL: 2108,
+    TLC_INVARIANT_VIOLATED_BEHAVIOR: 2110,
+    TLC_ACTION_PROPERTY_VIOLATED_BEHAVIOR: 2112,
+    TLC_DEADLOCK_REACHED: 2114,
+    TLC_TEMPORAL_PROPERTY_VIOLATED: 2116,
+    TLC_BACK_TO_STATE: 2122,
+    TLC_FINISHED: 2186,
+    TLC_INIT_GENERATED1: 2190,
+    TLC_INIT_GENERATED2: 2191,
+    TLC_STATS: 2199,
+    TLC_PROGRESS_STATS: 2200,
+    TLC_STATE_PRINT2: 2217,
+    TLC_STATE_PRINT3: 2218,
+    TLC_SANY_END: 2219,
+    TLC_SANY_START: 2220,
+};
+export const LEVEL = { NONE: 0, ERROR: 1, TLCBUG: 2, WARNING: 3, STATE: 4 };
+export const RERUN_STATES = 100_000;
+export const CHART_STATES = 500;
+export const checked = Symbol("checked");
+export const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export const isStrings = (v) => Array.isArray(v) && v.every((s) => typeof s === "string");
+export const PART = 1 << 24;
+export const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export const list = (items, and = "and") => items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} ${and} ${items.at(-1)}`;
+const ESCAPES = {
+    '"': '\\"',
+    "\\": "\\\\",
+    "\n": "\\n",
+    "\t": "\\t",
+    "\r": "\\r",
+    "\f": "\\f",
+};
+const quote = (s) => `"${s.replace(/["\\\n\t\r\f]/g, (c) => ESCAPES[c])}"`;
+const joined = (items, sep) => {
+    let s = "";
+    for (let i = 0; i < items.length; i++)
+        s += (i ? sep : "") + show(items[i]);
+    return s;
+};
+export const show = (v) => {
+    switch (typeof v) {
+        case "boolean":
+            return v ? "TRUE" : "FALSE";
+        case "number":
+            return String(v);
+        case "string":
+            return quote(v);
+    }
+    switch (v.kind) {
+        case "model":
+            return v.name;
+        case "interval":
+            return `${v.lo}..${v.hi}`;
+        case "set":
+            return `{${joined(v.members, ", ")}}`;
+        case "function": {
+            if (v.printedAs === "tuple")
+                return `<<${joined(v.values, ", ")}>>`;
+            const record = v.printedAs === "record";
+            let s = record ? "[" : "(";
+            for (let i = 0; i < v.keys.length; i++)
+                s += record
+                    ? `${i ? ", " : ""}${String(v.keys[i])} |-> ${show(v.values[i])}`
+                    : `${i ? " @@ " : ""}${show(v.keys[i])} :> ${show(v.values[i])}`;
+            return s + (record ? "]" : ")");
+        }
+    }
+};
+export const must = (map, key) => {
+    const value = map.get(key);
+    if (value === undefined)
+        throw new Error(`The chart lost track of ${JSON.stringify(key)}.`);
+    return value;
+};
+export const append = (groups, key, item) => {
+    const group = groups.get(key);
+    if (group)
+        group.push(item);
+    else
+        groups.set(key, [item]);
+};
+export const seqOf = (bug, index) => {
+    const seq = [must(index, bug.start)];
+    for (const p of bug.path)
+        seq.push(must(index, p.state));
+    return seq;
+};
+export const loopOf = (bug, index) => new Set(bug.loop === undefined ? [] : seqOf(bug, index).slice(bug.loop));
+export const defaultState = (vars) => {
+    const entries = Object.entries(vars);
+    if (entries.length === 1)
+        return show(entries[0][1]);
+    const parts = [];
+    for (const [k, v] of entries)
+        parts.push(`${k}=${show(v)}`);
+    return parts.join(" ");
+};
+export const stateText = (vars) => {
+    const parts = [];
+    for (const [k, v] of Object.entries(vars))
+        parts.push(`${k} = ${show(v)}`);
+    return parts.join(" /\\ ");
+};
+export const count = (n) => {
+    const items = new Int32Array(n);
+    for (let i = 0; i < n; i++)
+        items[i] = i;
+    return items;
+};
+export const sortBy = (items, keys) => {
+    for (let k = keys.length - 1; k >= 0; k--) {
+        const key = keys[k];
+        let size = 0;
+        for (let p = 0; p < items.length; p++)
+            if (key[items[p]] >= size)
+                size = key[items[p]] + 1;
+        const start = new Int32Array(size + 1);
+        for (let p = 0; p < items.length; p++)
+            start[key[items[p]] + 1]++;
+        for (let v = 0; v < size; v++)
+            start[v + 1] += start[v];
+        const sorted = new Int32Array(items.length);
+        for (let p = 0; p < items.length; p++)
+            sorted[start[key[items[p]]]++] = items[p];
+        items = sorted;
+    }
+    return items;
+};
+export const tupleKey = (parts) => JSON.stringify(parts);
+export const unkey = (k) => {
+    const parts = JSON.parse(k);
+    if (!isStrings(parts))
+        throw new Error(`The chart cannot read the key ${k}.`);
+    return parts;
+};
+export function holds(condition, others) {
+    switch (condition.kind) {
+        case "and":
+            for (let j = 0; j < others.length; j++)
+                if (!condition.otherKeys[j].has(others[j]))
+                    return false;
+            return true;
+        case "or":
+            for (let j = 0; j < others.length; j++)
+                if (condition.otherKeys[j].has(others[j]))
+                    return true;
+            return false;
+        case "tuples":
+            return condition.otherTuples.has(tupleKey(others));
+    }
+}
+export const ruleKey = (rule) => tupleKey([rule.kind, rule.name]);
+export const hasRule = (rules, rule) => {
+    for (const r of rules)
+        if (r.kind === rule.kind && r.name === rule.name)
+            return true;
+    return false;
+};
+const ascending = (keys) => {
+    for (let i = 1; i < keys.length; i++)
+        if (keys[i - 1] > keys[i])
+            return false;
+    return true;
+};
+const span = (lo, hi) => (hi > lo ? `${lo}..${hi}` : String(lo));
+const setKey = (members) => {
+    const ints = [];
+    let others = [];
+    for (const m of members)
+        if (typeof m === "number")
+            ints.push(m);
+        else
+            others.push(key(m));
+    for (let i = 1; i < ints.length; i++)
+        if (ints[i - 1] >= ints[i]) {
+            ints.sort((a, b) => a - b);
+            break;
+        }
+    if (!ascending(others))
+        others = others.sort(byText);
+    let s = "{";
+    for (let i = 0; i < ints.length;) {
+        let j = i;
+        while (j + 1 < ints.length && ints[j + 1] - ints[j] <= 1)
+            j++;
+        s += `${s.length > 1 ? "," : ""}${span(ints[i], ints[j])}`;
+        i = j + 1;
+    }
+    for (let i = 0; i < others.length; i++)
+        if (!i || others[i] !== others[i - 1])
+            s += (s.length > 1 ? "," : "") + others[i];
+    return s + "}";
+};
+const functionKey = ({ keys, values }) => {
+    const order = [];
+    const keyTexts = [];
+    let ints = 0;
+    for (let i = 0; i < keys.length; i++) {
+        order.push(i);
+        keyTexts.push(key(keys[i]));
+        if (typeof keys[i] === "number")
+            ints++;
+    }
+    const rank = (i) => (typeof keys[i] === "number" ? keys[i] : Infinity);
+    order.sort((a, b) => rank(a) - rank(b) || byText(keyTexts[a], keyTexts[b]) || a - b);
+    let tuple = ints === keys.length;
+    for (let i = 0; tuple && i < order.length; i++)
+        tuple = keys[order[i]] === i + 1;
+    let s = tuple ? "<<" : "(";
+    for (let i = 0, kept = 0; i < order.length; i++) {
+        const k = order[i];
+        if (i && keyTexts[k] === keyTexts[order[i - 1]])
+            continue;
+        const v = key(values[k]);
+        s += tuple ? `${kept++ ? "," : ""}${v}` : `${kept++ ? "@@" : ""}${keyTexts[k]}:>${v}`;
+    }
+    return s + (tuple ? ">>" : ")");
+};
+const keys = new WeakMap();
+export const key = (v) => {
+    switch (typeof v) {
+        case "boolean":
+            return v ? "TRUE" : "FALSE";
+        case "number":
+            return String(v);
+        case "string":
+            return JSON.stringify(v);
+    }
+    if (v.kind === "model")
+        return v.name;
+    let k = keys.get(v);
+    if (k === undefined) {
+        k =
+            v.kind === "interval"
+                ? `{${v.lo > v.hi ? "" : span(v.lo, v.hi)}}`
+                : v.kind === "set"
+                    ? setKey(v.members)
+                    : functionKey(v);
+        keys.set(v, k);
+    }
+    return k;
+};
+export const stateKey = (values) => {
+    let k = "";
+    for (let i = 0; i < values.length; i++)
+        k += (i ? "," : "") + key(values[i]);
+    return k;
+};
+export const memo = (make, limit = 1 << 16) => {
+    const cache = new Map();
+    return (k) => {
+        let v = cache.get(k);
+        if (v === undefined) {
+            if (cache.size >= limit)
+                cache.clear();
+            cache.set(k, (v = make(k)));
+        }
+        return v;
+    };
+};
+export const valuesOf = (vars, names) => {
+    const values = [];
+    for (const n of names)
+        values.push(vars[n]);
+    return values;
+};
+export const findTrace = (counterexample, names, rule, find) => {
+    const trace = [];
+    for (const { action, vars } of counterexample) {
+        const values = valuesOf(vars, names);
+        trace.push({ action, vars, values, id: find(values) });
+    }
+    const end = trace.length - 1;
+    if (end < 0)
+        throw new Error(`TLC's trace for ${rule.name} has no states.`);
+    for (let i = 0; i < end; i++)
+        if (trace[i].id === undefined)
+            throw new Error(`TLC's trace for ${rule.name} has a state before its last that the dump does not list.`);
+    return trace;
+};
+export const findLoop = ({ seq, loop }, names, find) => {
+    const found = [];
+    for (const { action, vars } of seq)
+        found.push({ action, id: vars && find(valuesOf(vars, names)) });
+    return { seq: found, loop };
+};
+export const pastState = (vars, start, marked, excluded) => {
+    const breaks = [];
+    for (const r of marked)
+        if (!hasRule(breaks, r))
+            breaks.push(r);
+    return { vars, start, breaks, ends: [], past: true, excluded };
+};
+export const CHECK_DEADLOCK = "CHECK_DEADLOCK";
+const deadlockRule = ({ invariants, properties }) => ({
+    kind: "deadlock",
+    name: invariants.includes("NoDeadlock") || properties.includes("NoDeadlock")
+        ? CHECK_DEADLOCK
+        : "NoDeadlock",
+});
+export const hasSection = ({ written }, ...keys) => {
+    for (const s of written)
+        if (keys.includes(s.key))
+            return true;
+    return false;
+};
+export const stateRules = (spec) => {
+    const rules = [];
+    for (const name of spec.invariants)
+        rules.push({ kind: "invariant", name });
+    if (spec.deadlock)
+        rules.push(deadlockRule(spec));
+    return rules;
+};

package/dist/statechart/passes/annotate.js

@@ -0,0 +1,102 @@
+import { findLoop, findTrace, hasRule, must, pastState, stateKey, valuesOf, } from "../ir.js";
+export const finder = (graph, names) => {
+    let ids;
+    const find = (values) => {
+        if (!ids) {
+            ids = new Map();
+            for (const [id, s] of graph.states)
+                if (!s.excluded)
+                    ids.set(stateKey(valuesOf(s.vars, names)), id);
+        }
+        return ids.get(stateKey(values));
+    };
+    find.add = (id, values) => ids?.set(stateKey(values), id);
+    return find;
+};
+export function mark(graph, marks, names, rules, find = finder(graph, names)) {
+    const byName = new Map();
+    for (const rule of rules)
+        byName.set(rule.name, rule);
+    const past = new Map();
+    for (const { values, broken } of marks) {
+        const id = find(values);
+        const state = id === undefined ? undefined : graph.states.get(id);
+        for (const name of broken) {
+            const rule = must(byName, name);
+            if (state)
+                state.breaks.push(rule);
+            else
+                past.set(stateKey(values), (past.get(stateKey(values)) ?? new Set()).add(rule));
+        }
+    }
+    return past;
+}
+export function deadEnds(graph, rule) {
+    const from = new Set();
+    for (const t of graph.steps)
+        from.add(t.from);
+    for (const [id, s] of graph.states)
+        if (!s.past && !from.has(id))
+            s.breaks.push(rule);
+}
+export function addPast(graph, counterexample, names, rule, past, excludes, find = finder(graph, names)) {
+    const trace = findTrace(counterexample, names, rule, find);
+    const end = trace.length - 1;
+    const from = trace[end - 1]?.id;
+    const action = trace[end].action;
+    const taken = (to) => {
+        for (const t of graph.steps)
+            if (t.from === from && t.to === to && t.action === action)
+                return true;
+        return false;
+    };
+    let to = trace[end].id;
+    const reached = to === undefined ? undefined : graph.states.get(to);
+    const excluded = excludes && reached !== undefined && end > 0 && !reached.past && !taken(to);
+    if (excluded)
+        to = `past ${to} ${action} ${from}`;
+    to ??= `past ${graph.states.size}`;
+    let last = graph.states.get(to);
+    if (!last) {
+        const marked = excluded ? reached.breaks : (past.get(stateKey(trace[end].values)) ?? []);
+        last = pastState(trace[end].vars, end === 0, marked, excluded);
+        graph.states.set(to, last);
+        if (!excluded)
+            find.add(to, trace[end].values);
+    }
+    if (!hasRule(last.breaks, rule))
+        last.breaks.push(rule);
+    (last.ends ??= []).push(rule);
+    if (from !== undefined && last.past && !taken(to))
+        graph.steps.push({ from, to, action });
+}
+export function lasso(graph, trace, names, find = finder(graph, names)) {
+    const { seq, loop } = findLoop(trace, names, find);
+    const start = seq[0]?.id;
+    if (start === undefined)
+        return undefined;
+    const out = new Map();
+    for (const s of seq)
+        out.set(s.id, []);
+    for (const t of graph.steps)
+        out.get(t.from)?.push(t);
+    const route = [];
+    for (let i = 1; i < seq.length; i++) {
+        let step;
+        for (const t of out.get(seq[i - 1].id) ?? [])
+            if (t.to === seq[i].id && t.action === seq[i].action) {
+                step = t;
+                break;
+            }
+        if (!step)
+            return undefined;
+        route.push({ action: step.action, state: step.to, step });
+    }
+    const stutters = loop === seq.length - 1;
+    return {
+        start,
+        path: route,
+        loop,
+        stutters,
+    };
+}

package/dist/statechart/passes/label.js

@@ -0,0 +1,217 @@
+import { isRecord, key, list, loopOf, must, sortBy, stateText, tupleKey, } from "../ir.js";
+const isLabel = (l) => typeof l === "string" && l !== "" && !/\bundefined\b|\bNaN\b|\[object Object\]/.test(l);
+const shapeOf = (shape, vars) => {
+    function fail() {
+        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) => {
+        const labels = [];
+        for (const l of [p].flat()) {
+            if (!isLabel(l))
+                fail();
+            labels.push(l);
+        }
+        if (!labels.length)
+            fail();
+        return labels;
+    };
+    const regions = isRecord(shape) ? Object.entries(shape) : [["", shape]];
+    const pairs = [];
+    for (const [k, v] of regions)
+        pairs.push([k, path(v)]);
+    return pairs.length ? Object.fromEntries(pairs) : fail();
+};
+const stepOf = (view) => (action, from, to) => {
+    const label = (view.step ?? ((a) => 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, before, after, bug) {
+    const changed = [];
+    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, { states: tla, nameOf, from, to }, view) {
+    const n = nameOf.length;
+    const m = from.length;
+    const state = view.state;
+    const shapes = new Array(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(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(n);
+    const asked = new Uint8Array(n);
+    const group = (i) => {
+        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 }, { names, shapes, labels, group }) {
+    const parents = new Array(shapes.length);
+    for (let i = 0; i < shapes.length; i++) {
+        const path = [];
+        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, { index, from, to, action }, answers, rank, found) {
+    const { names, shapes, labels: stepLabels } = answers;
+    const n = shapes.length;
+    const m = stepLabels.length;
+    const onPath = new Set();
+    for (const b of found)
+        for (const p of b.path)
+            onPath.add(p.step);
+    const pathStepIndex = new Map();
+    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 = [];
+    const kinds = [];
+    const sizes = [];
+    for (const name of names) {
+        const key = new Array(n);
+        const kind = new Int32Array(n);
+        const tops = new Map();
+        const nested = new Map();
+        const keyOf = [];
+        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;
+        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 = [];
+    const drawnLabels = new Array(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();
+    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 = [];
+            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();
+    for (const [text, { sets }] of byLabel)
+        if (sets.size)
+            together.add(text);
+    const notes = [];
+    for (const [text, entry] of byLabel) {
+        const changed = [];
+        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,
+    };
+}
+function tell(states, found, shapeAt, labelAt) {
+    const vars = (id) => must(states, id).vars;
+    const stories = new Map();
+    for (const bug of found) {
+        const story = [{ state: shapeAt(bug.start) }];
+        let from = 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, found, { index }, { shapes, drawnLabels, pathStepIndex }) => tell(graph.states, found, (id) => shapes[must(index, id)], (bug, k) => drawnLabels[must(pathStepIndex, bug.path[k].step)]);