@delurio/cli 0.0.0 → 0.1.0

package/dist/diff.js

@@ -0,0 +1,316 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import { parse } from 'yaml';
+import { GraphError, humanize, load } from './graph.js';
+import { loadNav } from './nav.js';
+import { joinWords } from './compare.js';
+import { flowBehaviour, flowSameBehaviour, flowStructure, runSide } from './diff-flow.js';
+import { navBehaviour, navSameBehaviour, navStructure, runNav } from './diff-nav.js';
+// `node src/cli.ts diff`: what a revision of a graph changes, for a PR description. Each side is a graph directory on disk
+// or the same directory at a git revision (read with `git show <commit>:<path>`, nothing is checked out). No model, no
+// network: the same two revisions give the same bytes.
+export const DIFF_USAGE = [
+    '  node src/cli.ts diff <old dir> <new dir> [--base <rev>] [--head <rev>] [--json] [--fail-on-behaviour] [--fail-on-regression]',
+    '  node src/cli.ts diff <graph dir> --base <rev> [--head <rev>] ...',
+    '    what the new revision changes, as markdown for a PR description (--json: for machines); --base reads the old side',
+    '    from a git revision, --head the new one (default: the directory on disk). Works for flow and navigation graphs.',
+    '    --fail-on-behaviour: exit 2 when what the graph does changed;  --fail-on-regression: exit 2 when a guarantee newly',
+    '    fails, a goal newly fails or a problem is new',
+].join('\n');
+// a directory inside the repository is named from its root, as a PR reader knows it; one outside as given
+function shown(dir) {
+    const top = git(['rev-parse', '--show-toplevel'], process.cwd())?.trim();
+    if (top === undefined || top === '')
+        return dir;
+    const rel = relative(top, resolve(dir)).split(sep).join('/');
+    return rel.startsWith('..') || isAbsolute(rel) ? dir : rel === '' ? '.' : rel;
+}
+function dirSource(dir) {
+    const texts = new Map();
+    if (!existsSync(dir))
+        throw new GraphError(`${dir} does not exist`);
+    return {
+        where: shown(dir),
+        rev: null,
+        texts,
+        exists: (file) => existsSync(join(dir, file)),
+        read: (file) => {
+            const path = join(dir, file);
+            if (!existsSync(path))
+                throw new GraphError(`${path} does not exist`);
+            const text = readFileSync(path, 'utf8');
+            texts.set(posix.normalize(file), text);
+            return text;
+        },
+    };
+}
+function git(args, cwd) {
+    try {
+        return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 1 << 28 });
+    }
+    catch {
+        return null;
+    }
+}
+function gitSource(rev, dir) {
+    const top = git(['rev-parse', '--show-toplevel'], process.cwd())?.trim();
+    if (top === undefined || top === '')
+        throw new GraphError(`--base and --head read a git revision, and ${process.cwd()} is not in a git repository`);
+    const commit = git(['rev-parse', '--verify', '--quiet', `${rev}^{commit}`], top)?.trim();
+    if (commit === undefined || commit === '')
+        throw new GraphError(`${rev} is not a revision of ${top}`);
+    const rel = relative(top, resolve(dir)).split(sep).join('/');
+    if (rel.startsWith('..') || isAbsolute(rel))
+        throw new GraphError(`${dir} is outside the repository ${top}`);
+    const short = commit.slice(0, 7); // fixed length, so the output does not change as the repository grows
+    const path = (file) => {
+        const p = posix.normalize(posix.join(rel, file));
+        if (p.startsWith('../'))
+            throw new GraphError(`${file} is outside the repository`);
+        return p;
+    };
+    const texts = new Map();
+    const shownRev = commit.startsWith(rev) ? short : `${rev} (${short})`;
+    if (git(['cat-file', '-e', `${commit}:${rel === '' ? '.' : rel}`], top) === null)
+        throw new GraphError(`${rel} does not exist at ${shownRev}; a new graph has no diff, render it instead`);
+    return {
+        where: rel === '' ? '.' : rel,
+        rev: shownRev,
+        texts,
+        exists: (file) => git(['cat-file', '-e', `${commit}:${path(file)}`], top) !== null,
+        read: (file) => {
+            const text = git(['show', `${commit}:${path(file)}`], top);
+            if (text === null)
+                throw new GraphError(`${path(file)} does not exist at ${short}`);
+            texts.set(posix.normalize(file), text);
+            return text;
+        },
+    };
+}
+// The API description of a flow: domain.yaml beside it, else the shared ../domain/domain.yaml of a capture layout,
+// else ../../domain/domain.yaml of graphs/ (graphs/<part>/<flow>). When the flow names its domain, the file must be that domain.
+function findDomain(src, g) {
+    for (const file of ['domain.yaml', '../domain/domain.yaml', '../../domain/domain.yaml']) {
+        if (!src.exists(file))
+            continue;
+        const doc = parse(src.read(file));
+        const named = g.flow.domain;
+        if (typeof named === 'string' && doc?.id !== named)
+            throw new GraphError(`flow.yaml names the domain ${named}, but ${file} is ${String(doc?.id)}`);
+        return { file, doc };
+    }
+    return null;
+}
+function loadSide(src, name, locale) {
+    try {
+        if (src.exists('flow.yaml')) {
+            const g = load(src.where, src.read, src.exists);
+            return { kind: 'flow', side: { g, domain: findDomain(src, g) } };
+        }
+        if (src.exists('nav.yaml'))
+            return { kind: 'nav', side: loadNav(src.where, locale, src.read) };
+    }
+    catch (err) {
+        throw new GraphError(`${name} (${label(src)}): ${err.message}`);
+    }
+    throw new GraphError(`${name} (${label(src)}) has neither flow.yaml nor nav.yaml`);
+}
+const label = (s) => (s.rev === null ? s.where : `${s.where} at ${s.rev}`);
+const HEADINGS = {
+    flow: 'The flow',
+    graph: 'The graph',
+    scope: 'What this view shows',
+    main: 'The main story',
+    steps: 'Steps',
+    ways: 'How it moves on',
+    guarantees: 'Guarantees',
+    situations: 'What it keeps track of',
+    conditions: 'Conditions and effects',
+    screens: 'What the user sees',
+    people: 'Kinds of user',
+    pages: 'Pages',
+    entries: 'Menus, links and buttons',
+    goals: 'Goals',
+    frames: 'Frames',
+    facts: 'Facts and conditions',
+    notModeled: 'Not modeled',
+    wording: 'Wording',
+    domain: 'The API it calls (domain.yaml)',
+    other: 'Other keys',
+    citations: 'Source citations',
+};
+// markdown: escape what would turn plain words into markup
+const md = (s) => s.replace(/([\\`*_[\]<])/g, '\\$1');
+function tick(s) {
+    const longest = Math.max(0, ...(s.match(/`+/g) ?? []).map((r) => r.length));
+    const fence = '`'.repeat(longest + 1);
+    const pad = s.startsWith('`') || s.endsWith('`') ? ' ' : '';
+    return `${fence}${pad}${s}${pad}${fence}`;
+}
+const value = (v) => (v === undefined ? '(none)' : tick(JSON.stringify(v)));
+function exactLine(c) {
+    const what = c.field === undefined ? c.key : `${c.key} › ${c.field}`;
+    const short = (v) => {
+        if (v === undefined)
+            return '';
+        const text = JSON.stringify(v);
+        return text.length <= 160 ? `: ${tick(text)}` : '';
+    };
+    if (c.op === 'added')
+        return `- ${tick(what)} added${short(c.after)}`;
+    if (c.op === 'removed')
+        return `- ${tick(what)} removed${short(c.before)}`;
+    if (c.op === 'moved')
+        return `- ${tick(what)} moved from ${String(c.before)} to ${String(c.after)}`;
+    return `- ${tick(what)}: ${value(c.before)} → ${value(c.after)}`;
+}
+// the line that stands for the changes of an area that have no sentence of their own
+function summaryLine(area, items) {
+    const n = items.length;
+    const plural = (k, w) => `${k} ${w}${k === 1 ? '' : 's'}`;
+    const distinct = (xs) => [...new Set(xs)];
+    if (area === 'conditions' || area === 'facts') {
+        const guards = items.filter((c) => c.key.startsWith('guard ')).length;
+        const other = n - guards;
+        const parts = [guards > 0 ? plural(guards, 'named condition') : '', other > 0 ? plural(other, area === 'facts' ? 'fact' : 'effect') : ''].filter((x) => x !== '');
+        return `${joinWords(parts)} changed; the exact text is under the exact changes.`;
+    }
+    if (area === 'domain') {
+        const one = { entities: 'entity', actions: 'action', policies: 'policy', invariants: 'invariant', relations: 'relation', helpers: 'helper', permissions: 'permission', jobs: 'job' };
+        const where = (c) => {
+            const [section, name] = (c.field ?? '').split('.');
+            return name === undefined ? section : `${one[section] ?? section} ${name}`;
+        };
+        return `${plural(n, 'change')} in the API description: ${joinWords(distinct(items.map(where)))}.`;
+    }
+    if (area === 'ways')
+        return `${plural(n, 'way')} on from removed steps, under the exact changes.`;
+    if (area === 'citations')
+        return `${plural(n, 'source citation')} changed.`;
+    if (area === 'other')
+        return `${plural(n, 'change')} in keys this tool does not read: ${distinct(items.map((c) => (c.field ?? c.key).split('.')[0])).join(', ')}.`;
+    return `${plural(n, 'more change')}, under the exact changes.`;
+}
+export function renderMarkdown(r) {
+    const out = [];
+    out.push(`## ${md(r.title)}: what this revision changes`, '');
+    const kind = r.kind === 'flow' ? 'Flow graph' : 'Navigation graph';
+    const at = (s) => (s.rev === null ? 'the directory on disk' : tick(s.rev));
+    out.push(r.before.where === r.after.where ? `${kind} ${tick(r.after.where)}: ${at(r.before)} → ${at(r.after)}.` : `${kind}: ${tick(label(r.before))} → ${tick(label(r.after))}.`);
+    const files = [...new Set([...r.after.texts.keys(), ...r.before.texts.keys()])];
+    const changed = files.filter((f) => r.before.texts.get(f) !== r.after.texts.get(f));
+    out.push(`Compared ${files.join(', ')}; ${changed.length === 0 ? 'no file differs' : `changed: ${changed.join(', ')}`}.`, '');
+    out.push('### What it does differently', '');
+    if (r.behaviour.length === 0)
+        out.push(md(r.same));
+    else if (r.kind === 'flow')
+        for (const s of r.behaviour)
+            out.push(...item(s));
+    else {
+        const people = [...new Set(r.behaviour.filter((s) => s.persona !== undefined).map((s) => s.persona))];
+        for (const who of people) {
+            const items = r.behaviour.filter((s) => s.persona === who);
+            if (items.length > 8)
+                out.push(`<details><summary><b>${md(who)}</b>: ${items.length} changes</summary>`, '', ...items.flatMap(item), '', '</details>', '');
+            else
+                out.push(`**${md(who)}**`, '', ...items.flatMap(item), '');
+        }
+        const rest = r.behaviour.filter((s) => s.persona === undefined);
+        if (rest.length > 0)
+            out.push('**Findings**', '', ...rest.flatMap(item));
+    }
+    out.push('');
+    out.push('### What changed in the graph', '');
+    if (r.structure.length === 0)
+        out.push(changed.length === 0 ? 'Nothing.' : 'Nothing: the files differ only in comments, layout or key order.');
+    for (const area of Object.keys(HEADINGS)) {
+        const items = r.structure.filter((c) => c.area === area);
+        if (items.length === 0)
+            continue;
+        const said = items.filter((c) => c.say !== null);
+        const silent = items.filter((c) => c.say === null);
+        out.push(`**${HEADINGS[area]}**`, '');
+        for (const c of said)
+            out.push(`- ${md(c.say)}`);
+        if (silent.length > 0)
+            out.push(`- ${md(summaryLine(area, silent))}`);
+        out.push('');
+    }
+    if (r.structure.length > 0) {
+        out.push(`<details><summary>Exact changes, by id (${r.structure.length})</summary>`, '');
+        for (const c of r.structure)
+            out.push(exactLine(c));
+        out.push('', '</details>');
+    }
+    return `${out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`;
+}
+function item(s) {
+    return [`- ${s.worse ? `**${md(s.say)}**` : md(s.say)}`, ...s.detail.map((d) => `  ${md(d)}`)];
+}
+export function renderJson(r) {
+    const side = (s) => ({ path: s.where, revision: s.rev, files: [...s.texts.keys()] });
+    const files = [...new Set([...r.after.texts.keys(), ...r.before.texts.keys()])];
+    return `${JSON.stringify({
+        schema: 'delurio-graph-diff/0',
+        kind: r.kind,
+        title: r.title,
+        before: side(r.before),
+        after: side(r.after),
+        changedFiles: files.filter((f) => r.before.texts.get(f) !== r.after.texts.get(f)),
+        behaviourChanged: r.behaviour.length > 0,
+        regressions: r.behaviour.filter((s) => s.worse).length,
+        behaviour: r.behaviour,
+        structure: r.structure,
+    }, null, 2)}\n`;
+}
+export function compare(before, after, locale) {
+    const b = loadSide(before, 'before', locale);
+    const a = loadSide(after, 'after', locale);
+    if (b.kind === 'flow' && a.kind === 'flow') {
+        const s = flowStructure(b.side, a.side);
+        const rb = runSide(b.side.g, `before (${label(before)})`);
+        const ra = runSide(a.side.g, `after (${label(after)})`);
+        return { kind: 'flow', title: a.side.g.flow.title ?? humanize(a.side.g.flow.id), before, after, structure: s.changes, behaviour: flowBehaviour(rb, ra, s), same: flowSameBehaviour(ra) };
+    }
+    if (b.kind === 'nav' && a.kind === 'nav') {
+        for (const w of b.side.warnings)
+            console.error(`warning: before: ${w}`);
+        for (const w of a.side.warnings)
+            console.error(`warning: after: ${w}`);
+        const s = navStructure(b.side, a.side);
+        const rb = runNav(b.side.g, `before (${label(before)})`);
+        const ra = runNav(a.side.g, `after (${label(after)})`);
+        return { kind: 'nav', title: a.side.g.title, before, after, structure: s.changes, behaviour: navBehaviour(rb, ra, s), same: navSameBehaviour(ra) };
+    }
+    throw new GraphError(`before (${label(before)}) is a ${b.kind} graph and after (${label(after)}) a ${a.kind} graph`);
+}
+export async function diffMain(args) {
+    const withValue = ['--base', '--head', '--locale'];
+    const dirs = args.filter((x, i) => !x.startsWith('--') && !withValue.includes(args[i - 1] ?? ''));
+    const flag = (name) => {
+        const i = args.indexOf(name);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const base = flag('--base');
+    const head = flag('--head');
+    for (const name of withValue)
+        if (args.includes(name) && (flag(name) === undefined || flag(name)?.startsWith('--') === true))
+            throw new GraphError(`${name} needs a value`);
+    if (dirs.length === 0 || dirs.length > 2 || (dirs.length === 1 && base === undefined && head === undefined)) {
+        console.error(`usage:\n${DIFF_USAGE}`);
+        return 1;
+    }
+    const [oldDir, newDir] = dirs.length === 2 ? dirs : [dirs[0], dirs[0]];
+    const before = base === undefined ? dirSource(oldDir) : gitSource(base, oldDir);
+    const after = head === undefined ? dirSource(newDir) : gitSource(head, newDir);
+    const report = compare(before, after, flag('--locale'));
+    const text = args.includes('--json') ? renderJson(report) : renderMarkdown(report);
+    await new Promise((done) => process.stdout.write(text, () => done())); // all of it, before the process exits
+    const regressions = report.behaviour.filter((s) => s.worse).length;
+    if (args.includes('--fail-on-regression') && regressions > 0)
+        return 2;
+    if (args.includes('--fail-on-behaviour') && report.behaviour.length > 0)
+        return 2;
+    return 0;
+}

package/dist/edges.js

@@ -0,0 +1,120 @@
+import { alternatives, humanize } from './graph.js';
+export const BY = { human: 'person', ai: 'AI', agent: 'agent', ci: 'CI' };
+export function kindOf(g, name) {
+    const st = g.flow.states[name];
+    if (st.type === 'final')
+        return 'exit';
+    if (st.invoke?.flow !== undefined)
+        return 'subflow';
+    const shown = Object.values(g.ui.nodes).some((n) => (n.in ?? []).includes(name) && !(n.unless ?? []).includes(name));
+    return shown ? 'screen' : 'server';
+}
+export function exitLine(st) {
+    if (st.leavesPage === true)
+        return 'user leaves the page';
+    if (st.redirect === 'never')
+        return 'no redirect, page shown';
+    if (st.redirect === 'success')
+        return `redirect with ${(st.carries ?? []).join(' + ')}`;
+    if (st.redirect === undefined && st.code === undefined)
+        return 'ends here';
+    const codes = (st.code ?? '').split('|').map((c) => c.trim()).filter((c) => c !== '');
+    return codes.length === 1 ? `redirect, error=${codes[0]}` : `redirect, error (${codes.length} codes)`;
+}
+// a step's `response` in one line: the status, the code and the redirect first, then the other fields
+export function responseLine(r) {
+    const first = ['status', 'code', 'redirect'].filter((k) => r[k] !== undefined).map((k) => (k === 'redirect' ? `redirect ${String(r[k])}` : String(r[k])));
+    const rest = Object.entries(r)
+        .filter(([k]) => !['status', 'code', 'redirect'].includes(k))
+        .map(([k, v]) => `${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`);
+    return [...first, ...rest].join(' · ');
+}
+export function nodeLine(g, name) {
+    const st = g.flow.states[name];
+    const kind = kindOf(g, name);
+    if (kind === 'exit')
+        return exitLine(st);
+    if (kind === 'subflow')
+        return `sign-in flow · ${st.invoke?.flow}`;
+    const by = st.by === undefined ? null : BY[st.by];
+    if (st.goal === true)
+        return `${name} · goal`;
+    return `${name} · ${by ?? (kind === 'screen' ? 'screen' : 'server step')}`;
+}
+// visible text for a catalog key, with {placeholders} filled from the samples
+export function plain(g, key) {
+    const raw = g.catalog[key] ?? key;
+    return raw.replace(/\{(\w+)\}/g, (_m, p) => g.ui.samples[p] ?? p);
+}
+// the button or link text a person presses to send `event` while in `state`, if there is one
+export function pressLabel(g, state, event) {
+    for (const n of Object.values(g.ui.nodes)) {
+        if (n.emits !== event || !(n.in ?? []).includes(state))
+            continue;
+        if (n.text?.key !== undefined)
+            return plain(g, n.text.key);
+    }
+    return null;
+}
+export function wrap(text, max) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(' ')) {
+        if (line !== '' && line.length + 1 + word.length > max) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = line === '' ? word : `${line} ${word}`;
+        }
+    }
+    if (line !== '')
+        lines.push(line);
+    return lines;
+}
+export function collectEdges(g, ex) {
+    const groups = new Map();
+    const add = (from, to, label, kind, used) => {
+        const key = `${from}>${to}`;
+        const grp = groups.get(key) ?? { from, to, labels: [], kinds: new Set(), used: false };
+        if (label !== null && !grp.labels.includes(label))
+            grp.labels.push(label);
+        grp.kinds.add(kind);
+        grp.used = grp.used || used;
+        groups.set(key, grp);
+    };
+    for (const [name, st] of Object.entries(g.flow.states)) {
+        (st.always ?? []).forEach((a, i) => add(name, a.target, a.say ?? a.guard ?? 'otherwise', 'route', ex.taken.has(`${name}|always|${i}`)));
+        for (const [event, spec] of Object.entries(st.on ?? {})) {
+            alternatives(spec).forEach((a, i) => {
+                const press = pressLabel(g, name, event);
+                let label;
+                let kind;
+                if (press !== null) {
+                    label = `“${press}”`;
+                    kind = 'user';
+                }
+                else if (event.startsWith('FAIL')) {
+                    label = a.say !== undefined ? `fails: ${a.say}` : humanize(event);
+                    kind = 'fail';
+                }
+                else {
+                    label = a.say ?? null;
+                    kind = 'system';
+                }
+                add(name, a.target, label, kind, ex.taken.has(`${name}|${event}|${i}`));
+                if (a.starts !== undefined)
+                    add(name, a.target, `starts ${a.starts.flow}`, kind, ex.taken.has(`${name}|${event}|${i}`));
+            });
+        }
+    }
+    const order = ['user', 'system', 'route', 'fail'];
+    return [...groups.values()].map((grp) => ({
+        from: grp.from,
+        to: grp.to,
+        labels: grp.labels,
+        kind: order.find((k) => grp.kinds.has(k)) ?? 'system',
+        leave: g.flow.states[grp.to].leavesPage === true,
+        unused: !grp.used,
+    }));
+}

package/dist/expr.js

@@ -0,0 +1,157 @@
+const cache = new Map();
+function tokenize(src) {
+    const out = [];
+    const re = /\s*(?:==|!=|[()[\],]|'[^']*'|"[^"]*"|-?\d+(?:\.\d+)?|[A-Za-z_][A-Za-z0-9_.]*)/y;
+    let i = 0;
+    while (i < src.length) {
+        re.lastIndex = i;
+        const m = re.exec(src);
+        if (m === null) {
+            if (src.slice(i).trim() === '')
+                break;
+            throw new Error(`cannot read "${src.slice(i)}" in: ${src}`);
+        }
+        out.push(m[0].trim());
+        i = re.lastIndex;
+    }
+    return out;
+}
+export function parseExpr(src) {
+    const hit = cache.get(src);
+    if (hit !== undefined)
+        return hit;
+    const toks = tokenize(src);
+    let i = 0;
+    const peek = () => toks[i];
+    const next = () => toks[i++];
+    const expect = (t) => {
+        if (next() !== t)
+            throw new Error(`expected "${t}" in: ${src}`);
+    };
+    const atom = () => {
+        const t = next();
+        if (t === undefined)
+            throw new Error(`unexpected end in: ${src}`);
+        if (t === '(') {
+            const e = orExpr();
+            expect(')');
+            return e;
+        }
+        if (t === '[') {
+            const items = [];
+            while (peek() !== ']') {
+                items.push(atom());
+                if (peek() === ',')
+                    next();
+            }
+            expect(']');
+            return { k: 'list', items };
+        }
+        if (t.startsWith("'") || t.startsWith('"'))
+            return { k: 'lit', v: t.slice(1, -1) };
+        if (/^-?\d/.test(t))
+            return { k: 'lit', v: Number(t) };
+        if (t === 'true')
+            return { k: 'lit', v: true };
+        if (t === 'false')
+            return { k: 'lit', v: false };
+        if (t === 'null')
+            return { k: 'lit', v: null };
+        if (/^[A-Za-z_]/.test(t) && !['and', 'or', 'not', 'in'].includes(t))
+            return { k: 'id', name: t };
+        throw new Error(`unexpected "${t}" in: ${src}`);
+    };
+    const cmpExpr = () => {
+        const l = atom();
+        const p = peek();
+        if (p === '==' || p === '!=') {
+            next();
+            return { k: 'cmp', op: p, l, r: atom() };
+        }
+        if (p === 'in') {
+            next();
+            return { k: 'cmp', op: 'in', l, r: atom() };
+        }
+        if (p === 'not' && toks[i + 1] === 'in') {
+            i += 2;
+            return { k: 'cmp', op: 'not in', l, r: atom() };
+        }
+        return l;
+    };
+    const notExpr = () => {
+        if (peek() === 'not') {
+            next();
+            return { k: 'not', e: notExpr() };
+        }
+        return cmpExpr();
+    };
+    const andExpr = () => {
+        let l = notExpr();
+        while (peek() === 'and') {
+            next();
+            l = { k: 'and', l, r: notExpr() };
+        }
+        return l;
+    };
+    const orExpr = () => {
+        let l = andExpr();
+        while (peek() === 'or') {
+            next();
+            l = { k: 'or', l, r: andExpr() };
+        }
+        return l;
+    };
+    const e = orExpr();
+    if (i !== toks.length)
+        throw new Error(`unexpected "${toks[i]}" in: ${src}`);
+    cache.set(src, e);
+    return e;
+}
+export function evaluate(e, lookup) {
+    switch (e.k) {
+        case 'lit':
+            return e.v;
+        case 'id':
+            return lookup(e.name);
+        case 'list':
+            return e.items.map((x) => evaluate(x, lookup));
+        case 'not':
+            return !evaluate(e.e, lookup);
+        case 'and':
+            return Boolean(evaluate(e.l, lookup)) && Boolean(evaluate(e.r, lookup));
+        case 'or':
+            return Boolean(evaluate(e.l, lookup)) || Boolean(evaluate(e.r, lookup));
+        case 'cmp': {
+            const l = evaluate(e.l, lookup);
+            const r = evaluate(e.r, lookup);
+            if (e.op === '==')
+                return l === r;
+            if (e.op === '!=')
+                return l !== r;
+            const inList = Array.isArray(r) && r.some((x) => x === l);
+            return e.op === 'in' ? inList : !inList;
+        }
+    }
+}
+export function identifiers(e, out = new Set()) {
+    switch (e.k) {
+        case 'id':
+            out.add(e.name);
+            break;
+        case 'list':
+            e.items.forEach((x) => identifiers(x, out));
+            break;
+        case 'not':
+            identifiers(e.e, out);
+            break;
+        case 'and':
+        case 'or':
+        case 'cmp':
+            identifiers(e.l, out);
+            identifiers(e.r, out);
+            break;
+        case 'lit':
+            break;
+    }
+    return out;
+}

package/dist/graph.js

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { identifiers, parseExpr } from './expr.js';
+export class GraphError extends Error {
+}
+// 'silentRedirect' -> 'silent redirect'; used only when the graph gives no title
+export function humanize(id) {
+    const words = id.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_.-]+/g, ' ').toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+export function titleOf(flow, state) {
+    return flow.states[state].title ?? humanize(state);
+}
+export function alternatives(spec) {
+    const list = Array.isArray(spec) ? spec : [spec];
+    return list.map((a) => (typeof a === 'string' ? { target: a } : a));
+}
+// `read` and `exists` take a path relative to `dir`; the revision diff passes ones that read a git revision instead of the disk
+export function load(dir, read = (file) => readFileSync(join(dir, file), 'utf8'), exists = (file) => existsSync(join(dir, file))) {
+    const flow = parse(read('flow.yaml'));
+    // a flow with no context, guards or effects leaves the key out; every reader expects an object
+    flow.context ??= {};
+    flow.guards ??= {};
+    flow.effects ??= {};
+    // a flow with no screens (an endpoint, a webhook, a CI job) has no ui.yaml and no catalog
+    const ui = exists('ui.yaml') ? parse(read('ui.yaml')) : { absent: true, id: flow.id, catalog: '', samples: {}, nodes: {} };
+    const catalog = ui.absent === true ? {} : JSON.parse(read(ui.catalog));
+    if (flow.states[flow.initial] === undefined)
+        throw new GraphError(`initial state ${flow.initial} does not exist`);
+    for (const [name, st] of Object.entries(flow.states)) {
+        if (st.states !== undefined || st.type === 'parallel' || st.type === 'history') {
+            throw new GraphError(`state ${name}: nested, parallel and history states are not supported by graph-viz yet`);
+        }
+        const targets = [
+            ...(st.always ?? []).map((a) => a.target),
+            ...Object.values(st.on ?? {}).flatMap((spec) => alternatives(spec).map((a) => a.target)),
+        ];
+        for (const t of targets) {
+            if (flow.states[t] === undefined)
+                throw new GraphError(`state ${name} goes to ${t}, which does not exist`);
+        }
+        const ways = [...(st.always ?? []), ...Object.values(st.on ?? {}).flatMap((spec) => alternatives(spec))];
+        for (const w of ways) {
+            if (w.starts === undefined)
+                continue;
+            if (typeof w.starts.flow !== 'string')
+                throw new GraphError(`state ${name}: \`starts\` names no flow`);
+            for (const [k, v] of Object.entries(w.starts.given ?? {})) {
+                if (typeof v !== 'string')
+                    continue;
+                for (const id of identifiers(parseExpr(v))) {
+                    if (id !== 'state' && flow.context[id] === undefined && flow.guards[id] === undefined) {
+                        throw new GraphError(`state ${name} starts ${w.starts.flow} with ${k} = ${v}: ${id} is not a variable or a guard of this flow (a value is quoted: '${id}')`);
+                    }
+                }
+            }
+        }
+    }
+    for (const [id, node] of Object.entries(ui.nodes)) {
+        for (const s of [...(node.in ?? []), ...(node.unless ?? []), ...(node.disabledIn ?? [])]) {
+            if (flow.states[s] === undefined)
+                throw new GraphError(`ui node ${id} names the unknown state ${s}`);
+        }
+    }
+    return { dir, flow, ui, catalog };
+}