Skip to content

mex-memory/mex / skills/mex-statechart

mex-statechart

Verified

Explain complicated existing behavior using checked state diagrams. Use when asked for a state diagram, to diagram the previous explanation, show a bug or recovery path, compare a proposed fix or existing TLA+ spec, or derive a model from an agreed chart. Generates native Mermaid and a readable terminal fallback; optionally view and explicitly save in MEX Hub.

upstream/scripts/statechart.mjs

View on GitHub
#!/usr/bin/env node
import { constants } from "node:buffer";
import { spawn, spawnSync } from "node:child_process";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import process from "node:process";
import { fileURLToPath, pathToFileURL } from "node:url";
import { HELP, more, USAGE, usage } from "./statechart-help.mjs";
import {
  BROKEN_PROPERTY,
  checkedOnlyInInitialStates,
  joinAnd,
  parseDot,
  tlcOutputWarning,
  uncitedConditions,
} from "./lib.mjs";
import { loopSentence, readerStateNamer, repeatsIn } from "./property-loop.mjs";
import { loadRenderer, renderPng, THEMES } from "./render.mjs";
import { ruleBook } from "./rule-book.mjs";
import { Inputs } from "./snapshot.mjs";
import { RULES_INVARIANT, SCAFFOLD, withoutComments, writeRulesModule } from "./spec-text.mjs";
import { cannotRunTlc, findTlc } from "./tlc-tools.mjs";

const here = path.dirname(fileURLToPath(import.meta.url));
const { MAX_STRING_LENGTH } = constants;

class CannotFinish extends Error {}
class TlcStopped extends CannotFinish {}
class NotPublished extends CannotFinish {}

const COMMANDS = {
  "from-spec": {
    values: [
      "--map",
      "--config",
      "--fixed",
      "--fixed-config",
      "--against",
      "--against-config",
      "--label",
      "--expect-broken",
      "--title",
      "--out",
      "--theme",
    ],
    switches: ["--cover", "--png"],
    renders: (flags) => flags.png,
    run: fromSpec,
  },
  "from-chart": {
    values: ["--module", "--expect-broken", "--title", "--out", "--theme"],
    switches: ["--png"],
    renders: (flags) => flags.png,
    run: fromChart,
  },
  render: { values: ["--theme", "--out"], switches: [], renders: () => true, run: renderFile },
};

function parseArgs([command, ...rest]) {
  if (command === "-h" || command === "--help") return { help: HELP[""] };
  if (!Object.hasOwn(COMMANDS, command))
    throw new CannotFinish(`${usage(Object.values(USAGE))}\n${more()}`);
  const { values, switches, renders } = COMMANDS[command];
  const flags = { "expect-broken": new Set() };
  let input;
  for (let i = 0; i < rest.length; i++) {
    const a = rest[i];
    if (a === "-h" || a === "--help") return { help: HELP[command] };
    if (switches.includes(a)) flags[a.slice(2)] = true;
    else if (values.includes(a)) {
      if (i + 1 === rest.length) throw new CannotFinish(`${a} needs a value. ${more(command)}`);
      const name = a.slice(2);
      if (flags[name] instanceof Set) for (const v of rest[++i].split(",")) flags[name].add(v);
      else flags[name] = rest[++i];
    } else if (!a.startsWith("-") && input === undefined) input = a;
    else throw new CannotFinish(`unknown argument ${a}. ${more(command)}`);
  }
  if (input === undefined) throw new CannotFinish(`${usage([USAGE[command]])}\n${more(command)}`);
  const themes = Object.keys(THEMES);
  if (flags.theme !== undefined && !themes.includes(flags.theme))
    throw new CannotFinish(
      `--theme takes ${themes.slice(0, -1).join(", ")}, or ${themes.at(-1)}. ${more(command)}`,
    );
  if (flags.theme !== undefined && !renders(flags))
    throw new CannotFinish(`--theme needs --png. ${more(command)}`);
  return { command, input, flags };
}

async function rendererFor(command, flags) {
  if (!COMMANDS[command].renders(flags)) return null;
  try {
    return { lib: await loadRenderer(), theme: THEMES[flags.theme ?? "light"] };
  } catch (e) {
    throw new CannotFinish(e.message);
  }
}

const rel = (file) => {
  const r = path.relative(process.cwd(), file) || ".";
  return r === ".." || r.startsWith(`..${path.sep}`) ? path.resolve(file) : r;
};
const cfgOf = (spec) => spec.replace(/\.tla$/, ".cfg");

function findTools() {
  try {
    return findTlc();
  } catch (e) {
    throw new CannotFinish(e.message);
  }
}

function script(name, scriptArgs, about, { okExits = [0] } = {}) {
  const r = spawnSync(process.execPath, [path.join(here, name), ...scriptArgs], {
    encoding: "utf8",
  });
  if (r.error) throw new CannotFinish(`cannot run ${name}: ${r.error.message}`);
  if (okExits.includes(r.status)) return r;
  const thrown = r.stderr.match(/^Error: (.*)$/m)?.[1];
  throw new CannotFinish(thrown ? `${rel(about)}: ${thrown}` : r.stderr.trim());
}

const KEYWORD =
  /^(SPECIFICATION|INIT|NEXT|CONSTANTS?|INVARIANTS?|PROPERTY|PROPERTIES|SYMMETRY|VIEW|CONSTRAINTS?|ACTION_CONSTRAINTS?|CHECK_DEADLOCK|POSTCONDITION|ALIAS)$/;

function splitRules(cfg) {
  const words = cfg
    .replace(/\(\*[^]*?\*\)/g, " ")
    .replace(/\\\*.*/g, " ")
    .split(/\s+/)
    .filter(Boolean);
  const kept = [];
  const rules = [];
  const properties = [];
  let section = "";
  for (const w of words) {
    if (KEYWORD.test(w)) section = w;
    const list = /^INVARIANTS?$/.test(section)
      ? rules
      : /^PROPERT(Y|IES)$/.test(section)
        ? properties
        : null;
    if (!list) kept.push(KEYWORD.test(w) && kept.length ? `\n${w}` : w);
    else if (w !== section && !list.includes(w)) list.push(w);
  }
  // TLC takes only a state predicate as an INVARIANT, and checks a state predicate given as a
  // PROPERTY only in the initial states, which the INVARIANT run checks too.
  return {
    cfgWithoutRules: `${kept.join(" ")}\n`,
    rules,
    properties: properties.filter((p) => !rules.includes(p)),
  };
}

function runJava(file, args, options, dot) {
  return new Promise((resolve) => {
    const r = { stdout: "", stderr: "", stopped: false, overflowed: false };
    const child = spawn(file, args, options);
    for (const stream of ["stdout", "stderr"])
      child[stream].setEncoding("utf8").on("data", (text) => {
        if (r.overflowed) return;
        if (r[stream].length + text.length <= MAX_STRING_LENGTH) r[stream] += text;
        else {
          r.overflowed = true;
          child.kill("SIGKILL");
        }
      });
    child.on("error", (e) => (r.error = e));
    const watch =
      dot &&
      setInterval(() => {
        if ((fs.statSync(dot, { throwIfNoEntry: false })?.size ?? 0) <= MAX_STRING_LENGTH) return;
        r.stopped = true;
        child.kill("SIGKILL");
      }, 500);
    child.on("close", (status, signal) => {
      clearInterval(watch);
      resolve({ ...r, status, signal });
    });
  });
}

async function tlc(tools, spec, cfg, base, { dump, module, workers = "1" } = {}) {
  fs.writeFileSync(`${base}.cfg`, cfg);
  const metadir = fs.mkdtempSync(path.join(os.tmpdir(), "tlc-"));
  // TLC writes the standard modules, such as Naturals.tla, to java.io.tmpdir under fixed names,
  // so runs that share that folder can read a module while another run rewrites it.
  const javaTmp = path.join(metadir, "tmp");
  fs.mkdirSync(javaTmp);
  // -deadlock: a system at rest has nothing left to do, which TLC would report as a deadlock.
  const r = await runJava(
    tools.java,
    [
      "-XX:+UseParallelGC",
      `-Djava.io.tmpdir=${javaTmp}`,
      ...(module ? [`-DTLA-Library=${path.dirname(path.resolve(spec))}`] : []),
      "-cp",
      tools.jar,
      "tlc2.TLC",
      "-workers",
      workers,
      "-metadir",
      metadir,
      "-deadlock",
      "-continue",
      ...(dump ? ["-dump", "dot,actionlabels", path.resolve(dump)] : []),
      "-config",
      path.resolve(`${base}.cfg`),
      module ? path.resolve(module) : path.basename(spec),
    ],
    { cwd: path.dirname(path.resolve(spec)) },
    dump,
  );
  fs.rmSync(metadir, { recursive: true, force: true });
  if (r.overflowed) {
    fs.writeFileSync(`${base}.out`, r.stdout);
    throw new TlcStopped(
      `${base}.out: TLC printed more than ${MAX_STRING_LENGTH.toLocaleString("en-US")} characters, the most that the command can read, so the command stopped TLC. Smaller constants make TLC print less.`,
    );
  }
  if (r.stopped) {
    fs.writeFileSync(`${base}.out`, r.stdout);
    return { stdout: r.stdout, stopped: true };
  }
  if (r.error || !/^TLC2 Version/m.test(r.stdout)) throw new CannotFinish(cannotRunTlc(tools, r));
  fs.writeFileSync(`${base}.out`, r.stdout);
  try {
    return { stdout: r.stdout, warning: tlcOutputWarning(r.stdout, `${base}.out`) };
  } catch (e) {
    throw new TlcStopped(e.message);
  }
}

function warnUnnamedSteps({ spec, copy }, cfg, dot) {
  const text = withoutComments(copy);
  const specName = /^SPECIFICATION\s+(\w+)/m.exec(cfg)?.[1];
  const specBody = specName && new RegExp(`^${specName}\\s*==(.*(\\n[ \\t]+.*)*)`, "m").exec(text);
  const next =
    /^NEXT\s+(\w+)/m.exec(cfg)?.[1] ?? /\[\]\s*\[\s*(\w+)\s*\]_/.exec(specBody?.[1] ?? text)?.[1];
  const graph = parseDot(fs.readFileSync(dot, "utf8"));
  const unnamed = [...graph.edges, ...graph.loops].filter((e) => e.action === next).length;
  if (unnamed > 0)
    console.error(
      `${rel(spec)}: ${unnamed} ${unnamed === 1 ? "step has" : "steps have"} the name ${next}, the whole next-state action. TLC goes down from ${next} through each \\/, \\E, LET, and definition, and names each step after the last definition on that path. It stops at any other expression, such as /\\, IF, or CASE. If the reader must tell these steps apart, join a definition for each kind of step with \\/ in ${next}, as in ${next} == Pay \\/ Charge, and move each conjunct of ${next} into those definitions.`,
    );
  return next;
}

function readModel(spec, cfgFile, flag, inputs) {
  const [copy, cfgCopy] = [spec, cfgFile].map((f) => inputs.copyOf(f));
  if (!fs.existsSync(copy)) throw new CannotFinish(`${rel(spec)} does not exist`);
  if (!fs.existsSync(cfgCopy)) {
    const beside = fs
      .readdirSync(path.dirname(spec))
      .filter((f) => f.endsWith(".cfg"))
      .sort();
    throw new CannotFinish(
      `${rel(cfgFile)} does not exist. Pass ${flag} with the config to check ${path.basename(spec)} with. ${
        beside.length
          ? `The configs beside it: ${beside.join(", ")}.`
          : "A config has SPECIFICATION and one INVARIANT line per rule."
      }`,
    );
  }
  return { spec, copy, cfgFile, ...splitRules(fs.readFileSync(cfgCopy, "utf8")) };
}

function readInput(spec, cfgFile, expected, inputs) {
  const model = readModel(spec, cfgFile, "--config", inputs);
  const names = [...model.rules, ...model.properties];
  const unknown = [...expected].filter((r) => !names.includes(r));
  if (unknown.length)
    throw new CannotFinish(
      `--expect-broken ${unknown.join(", ")}: not a rule in ${rel(model.cfgFile)}, whose rules are ${names.join(", ") || "none"}.`,
    );
  return model;
}

async function check(tools, model, { work, out, role }, expected) {
  const { spec, copy, cfgFile, cfgWithoutRules, rules, properties } = model;
  const started = Date.now();
  let runs = 0;
  const run = (cfg, file, options) => {
    runs++;
    return tlc(tools, copy, cfg, file, options);
  };
  const name = path.basename(spec, ".tla");
  const tlcDir = path.join(work, "tlc", ...(role ? [role] : []));
  fs.mkdirSync(tlcDir, { recursive: true });
  console.log(`TLC on ${rel(spec)} with ${rel(cfgFile)}:`);
  if (rules.length === 0)
    console.log(
      `  ${path.basename(cfgFile)} has no INVARIANT, so ${properties.length ? "the chart marks no state broken" : "no rule is checked"}.`,
    );
  const said = (rule, broken) =>
    `  ${rule} ${broken ? (expected.has(rule) ? "is broken (expected)" : "is broken") : "holds"}.`;
  const shown = published(work, out);
  const traces = [];
  for (const rule of rules) {
    const file = path.join(tlcDir, `${name}-${rule}`);
    const cfg = `${cfgWithoutRules}INVARIANT ${rule}\nCONSTRAINT ${rule}\n`;
    let result = await run(cfg, file, { workers: "auto" });
    // Several workers can reach a bad state by a longer path first. One worker searches breadth
    // first in a fixed order, so the chart's bug paths are the shortest, and the same every run.
    if (/^Error: Invariant /m.test(result.stdout)) result = await run(cfg, file);
    const broken = /^Error: Invariant /m.test(result.stdout);
    console.log(said(rule, broken));
    if (result.warning) console.error(`${shown(`${file}.out`)}: ${result.warning}`);
    traces.push({ file: `${file}.out`, rule, broken });
  }
  const temporal = [];
  for (const property of properties) {
    const file = path.join(tlcDir, `${name}-${property}`);
    const { stdout } = await run(`${cfgWithoutRules}PROPERTY ${property}\n`, file, {
      workers: "auto",
    });
    const broken = BROKEN_PROPERTY.test(stdout);
    const notes = [
      broken &&
        `The chart draws only INVARIANT rules, so read TLC's counterexample in ${shown(`${file}.out`)}.`,
      checkedOnlyInInitialStates(spec, property) &&
        `TLC checked ${property} only in the initial states, because it has no [], <>, or ~>. List it as an INVARIANT to check every state.`,
    ];
    console.log([said(property, broken), ...notes.filter(Boolean)].join(" "));
    temporal.push({ file: `${file}.out`, rule: property, broken });
  }
  const dot = path.join(tlcDir, `${name}.dot`);
  const module = rules.length ? writeRulesModule(copy, rules, tlcDir) : undefined;
  const dumpCfg = module ? `${cfgWithoutRules}INVARIANT ${RULES_INVARIANT}\n` : cfgWithoutRules;
  const { stopped } = await run(dumpCfg, path.join(tlcDir, name), {
    dump: dot,
    module,
    workers: "1",
  });
  const dotBytes = fs.statSync(dot).size;
  const next = dotBytes <= MAX_STRING_LENGTH && warnUnnamedSteps(model, cfgWithoutRules, dot);
  const seconds = ((Date.now() - started) / 1000).toFixed(1);
  console.log(`  TLC ran ${runs} ${runs === 1 ? "time" : "times"} in ${seconds} s.`);
  const broken = [...traces, ...temporal].some((t) => t.broken);
  return {
    spec,
    copy,
    dot,
    dotBytes,
    stopped,
    next,
    dumpOut: path.join(tlcDir, `${name}.out`),
    traces,
    properties: temporal,
    broken,
  };
}

function rulesAsExpected(now, other, expected) {
  const brokenIn = (m) =>
    [...(m?.traces ?? []), ...(m?.properties ?? [])].filter((t) => t.broken).map((t) => t.rule);
  if (expected.size === 0) return !now.broken && !other?.broken;
  const unexpected = [...new Set([...brokenIn(now), ...brokenIn(other)])].filter(
    (r) => !expected.has(r),
  );
  const holds = [...expected].filter((r) => !brokenIn(now).includes(r));
  if (unexpected.length) console.log(`\nBroken but not expected: ${unexpected.join(", ")}.`);
  if (holds.length) console.log(`\nExpected to break but holds: ${holds.join(", ")}.`);
  if (!unexpected.length && !holds.length)
    console.log(`\nBroken as expected: ${[...expected].join(", ")}.`);
  return !unexpected.length && !holds.length;
}

async function draw({ now, other, uncited, map, work, out, title, comparing, cover }) {
  const huge = [now, other].find((m) => m?.dotBytes > MAX_STRING_LENGTH);
  const limit = MAX_STRING_LENGTH.toLocaleString("en-US");
  if (huge)
    throw new NotPublished(
      `${rel(huge.spec)}: TLC's state graph ${huge.stopped ? `passed ${limit} bytes, the most that the command can read, so the command stopped TLC and draws no chart` : `has ${huge.dotBytes.toLocaleString("en-US")} bytes, more than the ${limit} that the command can read, so it draws no chart`}. The rule results above stand. Smaller constants make a smaller graph.`,
    );
  const shown = published(work, out);
  const mapping = await import(pathToFileURL(path.resolve(map)).href);
  const from = ["--dot", now.dot, "--broken", now.dumpOut, "--map", map, "--spec", now.copy];
  for (const m of [now, other]) if (m?.next) from.push("--next", m.next);
  from.push(...now.traces.flatMap((t) => ["--traces", t.file]));
  if (other) {
    from.push(`--${other.role}-dot`, other.dot, `--${other.role}-broken`, other.dumpOut);
    from.push("--spec", other.copy);
    from.push(...other.traces.flatMap((t) => [`--${other.role}-traces`, t.file]));
    if (other.traces.length)
      from.push(`--${other.role}-rules`, other.traces.map((t) => t.rule).join(","));
    if (other.label !== undefined) from.push("--label", other.label);
    if (other.listed) from.push("--listed", JSON.stringify(other.listed));
  }
  if (comparing) from.push("--full-labels", "--flat", "--loops");
  const titled = (suffix) => (title ? ["--title", `${title}${suffix}`] : []);

  const files = {
    overview: path.join(work, "chart.mmd"),
    stories: path.join(work, "stories.md"),
    summary: path.join(work, "summary.json"),
  };
  const proof = path.join(work, "tlc", "regions-proof.mmd");
  const everyArrow = path.join(work, "tlc", "regions-all.mmd");
  script(
    "tlc-to-chart.mjs",
    [
      ...from,
      ...(comparing ? [] : ["--regions", "--proof", proof, "--regions-all", everyArrow]),
      ...(cover ? ["--cover"] : []),
      ...titled(""),
      "--highlight",
      "0",
      "--out",
      files.overview,
      "--story",
      files.stories,
      "--summary",
      files.summary,
    ],
    map,
  );
  const summary = JSON.parse(fs.readFileSync(files.summary, "utf8"));
  const L = summary.second?.label;
  const broken = [now, other].filter(Boolean).flatMap((m) => {
    const book = ruleBook(m.copy);
    const where = m === now ? "" : ` ${other.role === "fixed" ? "with" : "in"} ${L}`;
    const nameOf = readerStateNamer(mapping, m.dot);
    return m.properties
      .filter((p) => p.broken)
      .map((p) => ({
        where,
        property: {
          spec: rel(m.spec),
          property: p.rule,
          rule: book.get(p.rule)?.sentence ?? null,
          repeats: repeatsIn(fs.readFileSync(p.file, "utf8"), nameOf),
          counterexample: path.relative(work, p.file),
        },
      }));
  });
  const brokenProperties = broken.map((b) => b.property);
  fs.writeFileSync(
    files.summary,
    `${JSON.stringify({ ...summary, ...(uncited && { uncited }), brokenProperties }, null, 2)}\n`,
  );
  if (brokenProperties.length) {
    const lines = broken.map(
      ({ where, property: b }) =>
        `Rule broken${where}: ${[
          (b.rule ?? `\`${b.property}\``).replace(/\.?$/, "."),
          loopSentence(b.repeats),
          `TLC's counterexample is in ${b.counterexample}.`,
        ]
          .filter(Boolean)
          .join(" ")}`,
    );
    const bugs = fs.readFileSync(files.stories, "utf8");
    fs.writeFileSync(
      files.stories,
      `${bugs}${bugs && "\n"}## Broken rules that the chart does not draw\n\n${lines.join("\n")}\n`,
    );
  }
  const charts = [files.overview];
  for (const c of summary.classes) {
    const views = typeof mapping.detail === "function" ? ["", "-developer", "-layered"] : [""];
    for (const view of views) {
      const file = path.join(work, `bug-${c.n}${view}.mmd`);
      const shape = [...(view ? ["--view", view.slice(1)] : []), "--path-only"];
      script(
        "tlc-to-chart.mjs",
        [...from, ...shape, ...titled(`, bug ${c.n}`), "--highlight", String(c.n), "--out", file],
        map,
      );
      charts.push(file);
    }
  }

  const { works, wrong, fixed: fixedCount, mixed, after, worse } = summary.chartStatus;
  console.log(
    `\nChart: ${summary.chartStates} states and ${summary.chartTransitions} transitions from ${summary.modelStates} model states.`,
  );
  const r = summary.regions;
  if (r?.drawn)
    console.log(
      `It has 2 parallel regions, of ${r.states[0]} and ${r.states[1]} states. Proof: their ${r.all} arrows together make exactly the ${r.flat.states} states and ${r.flat.transitions} labeled steps of ${shown(proof)}, and the ${r.transitions} drawn arrows make only steps among them. ${shown(everyArrow)} has all ${r.all} arrows.`,
    );
  else if (r) console.log(`It has no parallel regions, because ${r.why}.`);
  const c = summary.cover;
  if (c?.drawn === false) console.log(`--cover draws every state, because ${c.why}.`);
  else if (c) {
    const list = (head, xs) => [
      ...(xs.length ? [head] : []),
      ...xs.slice(0, 10).map((x) => `  ${x}`),
      ...(xs.length > 10 ? [`  and ${xs.length - 10} more in summary.json`] : []),
    ];
    const left = [
      ...list("States left out:", c.leftOutStates),
      ...list("Transitions left out:", c.leftOutTransitions),
    ];
    console.log(
      left.length
        ? `--cover leaves out ${c.leftOutStates.length} of ${c.states} states and ${c.leftOutTransitions.length} of ${c.transitions} transitions. The counts of states that work or break a rule include the states it leaves out.\n${left.join("\n")}`
        : "--cover leaves out no state and no transition.",
    );
  }
  const verb = (n) => (n === 1 ? "breaks" : "break");
  const breaks = `${wrong} ${verb(wrong)} a rule`;
  const withFix = other?.role === "fixed" ? ` with ${L}` : "";
  const partly =
    (mixed ? `, ${mixed} ${verb(mixed)} a rule in some cases${withFix}` : "") +
    (after ? `, ${after} reached only after a bug${withFix}` : "") +
    (worse ? `, ${worse} ${verb(worse)} a rule only${withFix}` : "");
  console.log(
    other?.role === "fixed"
      ? `${works} work today, ${wrong} still wrong with ${L}, ${fixedCount} fixed or new with ${L}${partly}.\n`
      : other?.role === "against"
        ? `${works} work, ${breaks}, ${fixedCount} only in ${L}${partly}.\n`
        : `${works} work, ${breaks}${partly}.\n`,
  );
  if (summary.mixedStatus.length)
    console.log(
      `${summary.mixedStatus.length === 1 ? "This state breaks" : "These states break"} a rule in some cases and not in others:\n${summary.mixedStatus.map((t) => `  ${t}`).join("\n")}\n`,
    );
  if (summary.codeLike.length)
    console.log(
      `These labels or causes read like code. Write them in the reader's words in ${rel(map)}:\n${summary.codeLike.map((t) => `  ${t}`).join("\n")}\n`,
    );
  const stories = fs.readFileSync(files.stories, "utf8").trimEnd();
  console.log(
    summary.classes.length
      ? stories
      : ["No state breaks an INVARIANT rule.", stories].filter(Boolean).join("\n\n"),
  );
  return { files, charts };
}

const pngOf = (chart) => chart.replace(/(\.mmd)?$/, ".png");

function render(charts, { lib, theme }, shown) {
  const pngs = [];
  for (const chart of charts) {
    try {
      fs.writeFileSync(pngOf(chart), renderPng(lib, fs.readFileSync(chart, "utf8"), { theme }));
      pngs.push(pngOf(chart));
    } catch (e) {
      console.error(`could not render ${shown(chart)}: ${e.message}`);
    }
  }
  return pngs;
}

function finish({ work, out, inputs }, { files, charts }, ok, renderer) {
  unchanged(inputs, out);
  const pngs = renderer ? render(charts, renderer, published(work, out)) : [];
  publish(work, out, inputs);
  const written = [...charts, ...pngs, files.stories, files.summary]
    .map((f) => path.basename(f))
    .join(", ");
  console.log(`\nWrote ${written} in ${rel(out)}.`);
  if (renderer && pngs.length < charts.length) return 2;
  return ok ? 0 : 1;
}

function renderFile(input, flags, { lib, theme }) {
  const out = flags.out ?? pngOf(input);
  const step = (failed, f) => {
    try {
      return f();
    } catch (e) {
      throw new CannotFinish(`${failed}: ${e.message}`);
    }
  };
  const src = step(`cannot read ${rel(input)}`, () => fs.readFileSync(input, "utf8"));
  const png = step(`could not render ${rel(input)}`, () => renderPng(lib, src, { theme }));
  step(`cannot write ${rel(out)}`, () => {
    fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
    fs.writeFileSync(out, png);
  });
  console.log(`Wrote ${rel(out)}.`);
  return 0;
}

const published = (work, out) => (file) => rel(path.join(out, path.relative(work, file)));

const OWN =
  /^((chart|bug-\d+(-developer|-layered)?)\.(mmd|png)|stories\.md|summary\.json|tlc|\.DS_Store)$/;

function foreign(dir) {
  try {
    return fs
      .readdirSync(dir)
      .filter((f) => !OWN.test(f))
      .sort();
  } catch (e) {
    if (e.code === "ENOENT") return [];
    throw new CannotFinish(`cannot use ${rel(dir)} as the output folder: ${e.message}`);
  }
}

function refuseForeign(out, files = foreign(out)) {
  const [first, ...others] = files;
  if (first)
    throw new CannotFinish(
      `${rel(out)} has ${others.length ? `${others.length + 1} files that this command did not write, such as ${first}` : `a file that this command did not write: ${first}`}. A run puts its files in place of the whole output folder, so pass --out with a new folder.`,
    );
}

function outDir(flagged, input, name) {
  const out = flagged ?? path.join(path.dirname(input), `${name}-statechart`);
  refuseForeign(out);
  return out;
}

async function inWorkFolder(body) {
  const work = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-"));
  fs.mkdirSync(path.join(work, "tlc"));
  let keep = false;
  try {
    return await body(work);
  } catch (e) {
    keep = fs.readdirSync(path.join(work, "tlc")).some((f) => f.endsWith(".out"));
    if (keep && !(e instanceof TlcStopped))
      e.message += ` The files that this run wrote are in ${rel(work)}.`;
    throw e;
  } finally {
    if (!keep) fs.rmSync(work, { recursive: true, force: true });
  }
}

const moved = (from, to, ...missed) => {
  try {
    fs.renameSync(from, to);
    return true;
  } catch (e) {
    if (missed.includes(e.code)) return false;
    if (!["ENOSYS", "EXDEV", "EISDIR"].includes(e.code)) throw e;
  }
  // Some filesystems, such as FUSE mounts, cannot rename a folder that has files. They fail with
  // ENOSYS, or with EISDIR when the target exists. They can rename an empty folder.
  if (!fs.existsSync(from) && missed.includes("ENOENT")) return false;
  const claimed = claimedFolder(to, missed);
  if (claimed === null) return false;
  try {
    copyExclusive(from, to);
    if (!sameFolder(to, claimed))
      throw new Error("another run replaced the folder during the copy");
  } catch (e) {
    if (sameFolder(to, claimed)) fs.rmSync(to, { recursive: true, force: true });
    throw e;
  } finally {
    fs.closeSync(claimed);
  }
  fs.rmSync(from, { recursive: true, force: true });
  return true;
};

function claimedFolder(to, missed) {
  // Making a folder and opening it take two calls. Another run can replace the folder at `to`
  // between them. So the run opens its folder before it moves the folder to `to`.
  // A filesystem can reuse a removed folder's inode number. Holding this folder open keeps its
  // number, so a folder that another run makes in its place cannot match it.
  const mine = fs.mkdtempSync(path.join(path.dirname(to), `.${path.basename(to)}-`));
  const claimed = fs.openSync(mine, "r");
  try {
    fs.renameSync(mine, to);
    return claimed;
  } catch (e) {
    fs.closeSync(claimed);
    fs.rmdirSync(mine);
    if (missed.includes(e.code)) return null;
    throw e;
  }
}

function sameFolder(at, claimed) {
  const now = fs.statSync(at, { throwIfNoEntry: false });
  const made = fs.fstatSync(claimed);
  return now?.dev === made.dev && now?.ino === made.ino;
}

function copyExclusive(from, to) {
  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
    const source = path.join(from, entry.name);
    const target = path.join(to, entry.name);
    if (entry.isDirectory()) {
      fs.mkdirSync(target);
      copyExclusive(source, target);
    } else fs.copyFileSync(source, target, fs.constants.COPYFILE_EXCL);
  }
}

function unchanged(inputs, out) {
  const changed = inputs.changed();
  if (changed)
    throw new NotPublished(
      `${rel(changed)} changed while this run read it, so the run left ${rel(out)} as it was. Run the command again.`,
    );
}

function publish(work, out, inputs) {
  const parent = path.dirname(path.resolve(out));
  fs.mkdirSync(parent, { recursive: true });
  const next = fs.mkdtempSync(path.join(parent, `.${path.basename(out)}-`));
  const old = `${next}-old`;
  let aside = false;
  try {
    fs.cpSync(work, next, { recursive: true });
    unchanged(inputs, out);
    refuseForeign(out);
    while (!moved(next, out, "ENOTEMPTY", "EEXIST")) {
      if (aside) {
        refuseForeign(out);
        fs.rmSync(old, { recursive: true, force: true });
        aside = false;
      }
      aside = moved(out, old, "ENOENT");
      if (aside) refuseForeign(out, foreign(old));
    }
  } catch (e) {
    const back = !aside || putBack(old, out);
    fs.rmSync(next, { recursive: true, force: true });
    const why = e instanceof CannotFinish ? e.message : `cannot replace ${rel(out)}: ${e.message}.`;
    if (!back)
      throw new NotPublished(
        `${why} This run moved the previous ${rel(out)} to ${rel(old)} and could not put it back.`,
      );
    throw new NotPublished(
      e instanceof CannotFinish ? why : `${why} The run left ${rel(out)} as it was.`,
    );
  }
  if (aside) fs.rmSync(old, { recursive: true, force: true });
}

function putBack(old, out) {
  try {
    return moved(old, out, "ENOTEMPTY", "EEXIST");
  } catch {
    return false;
  }
}

function secondCfg(cfg, flags) {
  if (flags["fixed-config"] && !flags.fixed)
    throw new CannotFinish(`--fixed-config needs --fixed. ${more("from-spec")}`);
  if (flags["against-config"] && !flags.against)
    throw new CannotFinish(`--against-config needs --against. ${more("from-spec")}`);
  if (flags.fixed)
    return flags["fixed-config"] ?? (fs.existsSync(cfgOf(flags.fixed)) ? cfgOf(flags.fixed) : cfg);
  return flags.against && (flags["against-config"] ?? cfgOf(flags.against));
}

function secondModel(input, cfg, { fixed, against, label }, inputs) {
  if (fixed && against)
    throw new CannotFinish(`use --fixed or --against, not both. ${more("from-spec")}`);
  if (!fixed && !against) {
    if (label === undefined) return null;
    throw new CannotFinish(
      `--label names the --fixed or --against model; it needs one of them. ${more("from-spec")}`,
    );
  }
  const [role, spec] = fixed ? ["fixed", fixed] : ["against", against];
  if (path.resolve(spec) === path.resolve(input))
    throw new CannotFinish(`--${role} needs a file other than the spec, ${rel(input)}.`);
  return { role, label, model: readModel(spec, cfg, `--${role}-config`, inputs) };
}

function warnUnchecked(now, other) {
  const unchecked = now.rules.filter((r) => !other.rules.includes(r));
  if (unchecked.length)
    console.error(
      `${rel(other.cfgFile)} does not check ${unchecked.join(", ")}, so the stories cannot say whether ${rel(other.spec)} keeps ${unchecked.length === 1 ? "it" : "them"}.`,
    );
}

function listedBreaks(spec) {
  const dir = path.dirname(spec);
  const files = fs.readdirSync(dir).sort();
  const modules = files.filter((f) => f.endsWith(".tla") && !f.includes("_TTrace_"));
  const only = modules.length === 1 ? path.basename(modules[0], ".tla") : undefined;
  const breaks = {};
  let headed = false;
  for (const f of files.filter((f) => f.endsWith(".cfg"))) {
    const cfg = fs.readFileSync(path.join(dir, f), "utf8");
    const module = /^\\\* module:[ \t]*(\w+)[ \t]*$/m.exec(cfg)?.[1] ?? only;
    const expect = /^\\\* expect:[ \t]*(\w+)[ \t]*$/m.exec(cfg)?.[1];
    if (module !== path.basename(spec, ".tla") || !expect) continue;
    headed = true;
    if (!/^(pass|deadlock)$|^error/.test(expect)) breaks[f] = expect;
  }
  return headed ? { spec: path.basename(spec), breaks } : null;
}

function warnUnlisted(now, other) {
  if (other.listed || !now.traces.some((t) => t.broken)) return;
  const module = path.basename(other.spec, ".tla");
  console.error(
    `No config beside ${rel(other.spec)} has an "\\* expect:" line for ${module}, so the stories cannot say whether ${module} already lists each bug. When ${path.basename(other.spec)} is a copy, pass the spec in its own folder.`,
  );
}

function warnUncited(models) {
  return Object.fromEntries(
    models.map(({ spec, copy, traces, properties }) => {
      const found = uncitedConditions(fs.readFileSync(copy, "utf8"));
      const held = [...traces, ...properties].filter((t) => !t.broken).map((t) => t.rule);
      const short = (s) => (s.length > 90 ? `${s.slice(0, 87)}...` : s);
      if (found.length && held.length)
        console.error(
          `${rel(spec)}: ${joinAnd(held)} ${held.length === 1 ? "holds" : "hold"}, but a rule can also hold because the model waits for a condition that the code does not check. No comment gives the file and line of the code that checks ${found.length === 1 ? "this condition" : "these conditions"}:\n${found.map((c) => `  ${rel(spec)}:${c.line} ${c.action}: ${short(c.condition)}`).join("\n")}\nPut that file and line in a comment on each condition, as in \\* pay.ts:120, or remove the condition when no code checks it.`,
        );
      return [rel(spec), found];
    }),
  );
}

async function fromSpec(input, { "expect-broken": expected, title, cover, ...flags }, renderer) {
  const name = path.basename(input, ".tla");
  const map = flags.map ?? path.join(path.dirname(input), `${name}.map.mjs`);
  const cfg = flags.config ?? cfgOf(input);
  const otherCfg = secondCfg(cfg, flags);
  const inputs = new Inputs().add([input, cfg, map, flags.fixed ?? flags.against, otherCfg]);
  const second = secondModel(input, otherCfg, flags, inputs);
  const listed = second?.role === "against" ? listedBreaks(second.model.spec) : undefined;
  const model = readInput(input, cfg, expected, inputs);
  const out = outDir(flags.out, input, name);
  if (!fs.existsSync(map)) {
    fs.writeFileSync(map, SCAFFOLD(name, input));
    throw new CannotFinish(`Wrote ${rel(map)}. Fill in its labels, then run this command again.`);
  }
  const tools = findTools();
  return inWorkFolder(async (work) => {
    const now = await check(tools, model, { work, out }, expected);
    const other = second && {
      role: second.role,
      label: second.label,
      listed,
      ...(await check(tools, second.model, { work, out, role: second.role }, expected)),
    };
    let uncited;
    if (second) {
      warnUnchecked(model, second.model);
      if (second.role === "against") warnUnlisted(now, other);
      uncited = warnUncited(second.role === "fixed" ? [now, other] : [now]);
    }
    const drawn = await draw({ now, other, uncited, map, work, out, title, cover });
    return finish({ work, out, inputs }, drawn, rulesAsExpected(now, other, expected), renderer);
  });
}

async function fromChart(input, { "expect-broken": expected, ...flags }, renderer) {
  const name =
    flags.module ??
    path
      .basename(input, path.extname(input))
      .replace(/(^|[^A-Za-z0-9]+)([A-Za-z0-9])/g, (_, __, c) => c.toUpperCase());
  if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(name))
    throw new CannotFinish(`cannot make a TLA+ module name from ${input}; add --module NAME`);
  const spec = path.join(path.dirname(input), `${name}.tla`);
  const map = spec.replace(/\.tla$/, ".map.mjs");
  const inputs = new Inputs().add([input]);
  if (fs.existsSync(spec)) {
    console.log(`Kept ${rel(spec)}. Delete it to write the spec again from ${rel(input)}.`);
  } else {
    script("chart-to-tla.mjs", [input, "--module", name], input);
    console.log(`Wrote ${name}.tla, ${name}.cfg, and ${name}.map.mjs from ${rel(input)}.`);
  }
  inputs.add([spec, cfgOf(spec), map]);
  const tools = findTools();
  const model = readInput(spec, cfgOf(spec), expected, inputs);
  const out = outDir(flags.out, input, name);
  return inWorkFolder(async (work) => {
    const now = await check(tools, model, { work, out }, expected);
    const drawn = await draw({ now, map, work, out, title: flags.title, comparing: true });
    const compared = script(
      "compare-charts.mjs",
      [inputs.copyOf(input), drawn.files.overview],
      input,
      {
        okExits: [0, 1],
      },
    );
    if (compared.status === 0) console.log(`\nThe spec draws ${rel(input)} back unchanged.`);
    else
      console.log(
        `\nThe spec does not draw ${rel(input)}:\n${compared.stdout.trimEnd().replace(/^/gm, "  ")}`,
      );
    return finish(
      { work, out, inputs },
      drawn,
      rulesAsExpected(now, null, expected) && compared.status === 0,
      renderer,
    );
  });
}

try {
  const { help, command, input, flags } = parseArgs(process.argv.slice(2));
  if (help) {
    console.log(help);
    process.exit(0);
  }
  process.exit(await COMMANDS[command].run(input, flags, await rendererFor(command, flags)));
} catch (e) {
  if (!(e instanceof CannotFinish)) throw e;
  console.error(e.message);
  process.exit(2);
}

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall