@delurio/cli 0.0.0 → 0.1.0

package/dist/changes.js

@@ -0,0 +1,69 @@
+// `changes:` in ui.yaml (SPEC.md §4): a flow whose steps write something tells its users, in its own note, what it
+// changes and what follows. An action writes when its route is not a GET, when a policy lets someone `write` with it, or
+// when it is a step inside the service (no route) that returns an entity; all three are read from the flow's domain,
+// looked up by id among the graphs beside this one. A flow with no screens, or whose domain is not found, is not checked.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { parse } from 'yaml';
+const SKIP = new Set(['viz', 'video', 'node_modules', '.git']);
+// the root to search: the nearest folder called `graphs` above the graph, else the graph's parent
+function rootOf(dir) {
+    for (let d = dir, i = 0; i < 5; i++, d = dirname(d))
+        if (basename(d) === 'graphs')
+            return d;
+    return dirname(dir);
+}
+function domainUnder(root, id, depth = 4) {
+    const file = join(root, 'domain.yaml');
+    if (existsSync(file)) {
+        const d = parse(readFileSync(file, 'utf8'));
+        if (d?.id === id)
+            return d;
+    }
+    if (depth === 0)
+        return null;
+    for (const name of readdirSync(root)) {
+        if (SKIP.has(name))
+            continue;
+        const sub = join(root, name);
+        if (!statSync(sub).isDirectory())
+            continue;
+        const found = domainUnder(sub, id, depth - 1);
+        if (found !== null)
+            return found;
+    }
+    return null;
+}
+export function checkChanges(g) {
+    if (g.ui.absent === true || g.flow.domain === undefined)
+        return null;
+    const domain = domainUnder(rootOf(g.dir), g.flow.domain);
+    if (domain === null)
+        return null;
+    const writing = new Set();
+    for (const [name, a] of Object.entries(domain.actions ?? {})) {
+        const method = a?.route?.trim().split(/\s+/)[0]?.toUpperCase();
+        if ((method !== undefined && method !== 'GET') || (method === undefined && a?.result?.returns !== undefined))
+            writing.add(name);
+    }
+    for (const p of domain.policies ?? [])
+        if ((p.write ?? []).length > 0)
+            for (const name of p.do ?? [])
+                writing.add(name);
+    const invoked = Object.values(g.flow.states).map((s) => s.invoke?.action);
+    const writes = [...new Set(invoked.filter((a) => a !== undefined && writing.has(a)))].sort();
+    const key = g.ui.changes?.key ?? null;
+    const problems = [];
+    if (writes.length > 0 && key === null)
+        problems.push(`its steps write (${writes.join(', ')}), but ui.yaml has no changes note (SPEC.md §4)`);
+    if (key !== null) {
+        for (const locale of g.ui.locales ?? [basename(g.ui.catalog, '.json')]) {
+            const file = join(g.dir, dirname(g.ui.catalog), `${locale}.json`);
+            const catalog = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null;
+            const note = catalog?.[key];
+            if (typeof note !== 'string' || note.trim() === '')
+                problems.push(`the changes note ${key} is not in the ${locale} catalog`);
+        }
+    }
+    return { writes, key, problems };
+}

package/dist/check.js

@@ -0,0 +1,266 @@
+// `check`: every graph under a folder, as a project's CI runs it (graphs/agents/cli.check, SPEC.md §10). It reads the
+// files and nothing else, writes no page, and gives each finding as a GNU error line, or as SARIF 2.1.0 with
+// --format sarif. Exit 0 when clean, 1 when a graph cannot be loaded or is written for a newer format, 2 when an error
+// is found under --strict (and, with --baseline, new since that run).
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { parse } from 'yaml';
+import { GraphError, load } from './graph.js';
+import { checkAssertions, explore, Model, ModelError } from './model.js';
+import { stepsByEvents } from './story.js';
+import { renderScreens } from './wireframe.js';
+import { checkStarts } from './starts.js';
+import { checkChanges } from './changes.js';
+import { KitError, resolveKit } from './kit.js';
+import { checkGoals, findings, loadNav, viewOf } from './nav.js';
+export const CHECK_USAGE = [
+    '  node src/cli.ts check <graphs folder> [--strict] [--baseline <sarif>] [--format sarif --output <file>]',
+    '    checks every graph under the folder and writes nothing else: GNU error lines on stdout, or SARIF 2.1.0;',
+    '    exit 0 clean, 1 a graph cannot be loaded or needs a newer format, 2 an error under --strict (new since --baseline)',
+].join('\n');
+const FORMAT = 'delurio-graph/0';
+const SKIP = new Set(['viz', 'video', 'recording', 'node_modules', '.git']);
+const RULES = [
+    { id: 'load', text: 'The graph cannot be loaded', level: 'error' },
+    { id: 'format-newer', text: 'The graph is written for a newer format than this checker reads', level: 'error' },
+    { id: 'assertion-violated', text: 'A guarantee of the flow is broken by a reachable situation', level: 'error' },
+    { id: 'main-story-unwalkable', text: 'The declared main story cannot be walked', level: 'error' },
+    { id: 'catalog-key-missing', text: 'A catalog key the screens use is missing', level: 'error' },
+    { id: 'sample-missing', text: 'A catalog message has a placeholder with no sample value', level: 'error' },
+    { id: 'no-renderer', text: 'A component has no renderer', level: 'error' },
+    { id: 'kit-uncovered', text: "The kit does not cover a component or an intent", level: 'error' },
+    { id: 'list-item-outside-list', text: 'A list item is drawn outside a list', level: 'error' },
+    { id: 'hand-over', text: 'A started flow cannot begin with what it is given', level: 'error' },
+    { id: 'changes-note-missing', text: 'A flow whose steps write has no changes note (SPEC.md §4)', level: 'error' },
+    { id: 'changes-note-locale', text: "The changes note is missing from a locale's catalog", level: 'error' },
+    { id: 'graph-warning', text: 'Another warning of the graph', level: 'error' },
+    { id: 'nav-problem', text: 'A problem of the navigation graph', level: 'error' },
+    { id: 'nav-note', text: 'A note on the navigation graph', level: 'warning' },
+];
+const LEVEL = new Map(RULES.map((r) => [r.id, r.level]));
+// the 1-based line and column of the first occurrence of `needle`, else the file's start
+function placeOf(abs, needle) {
+    if (needle === null || !existsSync(abs))
+        return { line: 1, column: 1 };
+    const lines = readFileSync(abs, 'utf8').split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const c = lines[i].indexOf(needle);
+        if (c >= 0)
+            return { line: i + 1, column: c + 1 };
+    }
+    return { line: 1, column: 1 };
+}
+function graphDirs(root, out = []) {
+    if (existsSync(join(root, 'flow.yaml')) || existsSync(join(root, 'nav.yaml')))
+        out.push(root);
+    for (const name of readdirSync(root).sort()) {
+        if (SKIP.has(name) || name.startsWith('.'))
+            continue;
+        const sub = join(root, name);
+        if (statSync(sub).isDirectory())
+            graphDirs(sub, out);
+    }
+    return out;
+}
+// the format the file says it is written in: null when it is this one
+function newerFormat(abs) {
+    const doc = parse(readFileSync(abs, 'utf8'));
+    const s = typeof doc?.schema === 'string' ? doc.schema : FORMAT;
+    return s === FORMAT ? null : s;
+}
+function rel(abs) {
+    return relative(process.cwd(), abs) || '.';
+}
+function result(rule, file, at, message, graph, element, notes = []) {
+    return { rule, level: LEVEL.get(rule) ?? 'error', file: rel(file), line: at.line, column: at.column, message, graph, element, notes };
+}
+// a warning raised while checking a flow, sorted into its rule and placed in its file
+function fromWarning(dir, graph, w) {
+    const flow = join(dir, 'flow.yaml');
+    const ui = join(dir, 'ui.yaml');
+    let m;
+    if ((m = /^catalog key (\S+) is missing/.exec(w)))
+        return result('catalog-key-missing', ui, placeOf(ui, m[1]), w, graph, m[1]);
+    if ((m = /^no sample value for \{(\w+)\} in (\S+)/.exec(w)))
+        return result('sample-missing', ui, placeOf(ui, m[2]), w, graph, `${m[2]}/${m[1]}`);
+    if ((m = /^(\S+): ListItem outside a List/.exec(w)))
+        return result('list-item-outside-list', ui, placeOf(ui, `${m[1]}:`), w, graph, m[1]);
+    if ((m = /\(node (\S+?)\)/.exec(w)) && /^kit /.test(w))
+        return result('kit-uncovered', ui, placeOf(ui, `${m[1]}:`), w, graph, m[1]);
+    if ((m = /^(\S+): component .* has no wireframe renderer/.exec(w)))
+        return result('no-renderer', ui, placeOf(ui, `${m[1]}:`), w, graph, m[1]);
+    if (/declared main story cannot be walked/.test(w))
+        return result('main-story-unwalkable', flow, placeOf(flow, 'main:'), w, graph, 'main');
+    if ((m = /^(\S+) starts (\S+): (.*)$/.exec(w)))
+        return result('hand-over', flow, placeOf(flow, `flow: ${m[2]}`), w, graph, `${m[1]}->${m[2]}`);
+    if (/has no changes note/.test(w))
+        return result('changes-note-missing', ui, placeOf(ui, 'samples:'), w, graph, 'changes');
+    if ((m = /^the changes note (\S+) is not in the (\w+) catalog/.exec(w)))
+        return result('changes-note-locale', ui, placeOf(ui, 'changes:'), w, graph, `changes/${m[2]}`);
+    return result('graph-warning', existsSync(ui) ? ui : flow, { line: 1, column: 1 }, w, graph, w);
+}
+function checkFlow(dir) {
+    const file = join(dir, 'flow.yaml');
+    const g = load(dir);
+    const kit = resolveKit(dir, g.ui.kit, undefined);
+    const model = new Model(g.flow);
+    const ex = explore(model);
+    const out = [];
+    const warnings = [];
+    const warn = (m) => {
+        if (!warnings.includes(m))
+            warnings.push(m);
+    };
+    for (const a of checkAssertions(model, ex)) {
+        if (a.violation === undefined)
+            continue;
+        const at = placeOf(file, `id: ${a.id}`);
+        const start = Object.entries(a.violation.start).map(([k, v]) => `${k} = ${String(v)}`).join(', ');
+        const notes = [{ file: rel(file), ...at, message: `start: ${start || 'the initial context'}` }];
+        a.violation.events.forEach((e, i) => notes.push({ file: rel(file), ...at, message: `step ${i + 1}: ${e}` }));
+        notes.push({ file: rel(file), ...at, message: `reached: ${a.violation.state}` });
+        out.push(result('assertion-violated', file, at, `${a.id} is broken: ${a.say ?? a.never}`, g.flow.id, a.id, notes));
+    }
+    if (g.flow.main !== undefined && stepsByEvents(model, g.flow.main) === null)
+        warn('the declared main story cannot be walked: an event is not possible where it is sent');
+    renderScreens(g, warn, kit);
+    for (const h of checkStarts(g, model, ex))
+        for (const p of h.problems)
+            warn(`${h.from} starts ${h.flow}: ${p}`);
+    for (const p of checkChanges(g)?.problems ?? [])
+        warn(p);
+    for (const w of warnings)
+        out.push(fromWarning(dir, g.flow.id, w));
+    return out;
+}
+function checkNav(dir) {
+    const file = join(dir, 'nav.yaml');
+    const { g, warnings } = loadNav(dir, undefined);
+    const views = g.personas.map((p) => viewOf(g, p));
+    const found = findings(g, views, checkGoals(g, views));
+    const out = found.map((f) => result(f.level === 'problem' ? 'nav-problem' : 'nav-note', file, { line: 1, column: 1 }, `${f.say} (${f.code})`, g.id, f.code, f.detail.map((d) => ({ file: rel(file), line: 1, column: 1, message: d }))));
+    for (const w of warnings)
+        out.push(result('graph-warning', file, { line: 1, column: 1 }, w, g.id, w));
+    return out;
+}
+const fingerprint = (r) => createHash('sha256').update(`${r.rule}|${r.graph}|${r.element}`).digest('hex').slice(0, 32);
+function baselinePrints(file) {
+    const doc = JSON.parse(readFileSync(file, 'utf8'));
+    const out = new Set();
+    for (const run of doc.runs ?? [])
+        for (const r of run.results ?? [])
+            if (r.fingerprints?.['delurio/v1'] !== undefined)
+                out.add(r.fingerprints['delurio/v1']);
+    return out;
+}
+function toolVersion() {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return pkg.version ?? '0.0.0';
+}
+function sarif(results, exitCode) {
+    const used = RULES.filter((r) => results.some((x) => x.rule === r.id));
+    return {
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'delurio',
+                        version: toolVersion(),
+                        informationUri: 'https://delur.io',
+                        rules: used.map((r) => ({ id: r.id, shortDescription: { text: r.text }, defaultConfiguration: { level: r.level } })),
+                    },
+                },
+                automationDetails: { id: 'delurio/check/' },
+                invocations: [{ executionSuccessful: exitCode !== 1, exitCode }],
+                results: results.map((r) => ({
+                    ruleId: r.rule,
+                    ruleIndex: used.findIndex((u) => u.id === r.rule),
+                    level: r.level,
+                    message: { text: r.message },
+                    locations: [
+                        {
+                            physicalLocation: { artifactLocation: { uri: r.file.split('\\').join('/') }, region: { startLine: r.line, startColumn: r.column } },
+                            logicalLocations: [{ fullyQualifiedName: `${r.graph}/${r.element}` }],
+                        },
+                    ],
+                    fingerprints: { 'delurio/v1': fingerprint(r) },
+                    ...(r.notes.length > 0 && r.rule === 'assertion-violated'
+                        ? { codeFlows: [{ threadFlows: [{ locations: r.notes.map((n) => ({ location: { message: { text: n.message } } })) }] }] }
+                        : {}),
+                    ...(r.baselineState === undefined ? {} : { baselineState: r.baselineState }),
+                })),
+            },
+        ],
+    };
+}
+export function checkMain(args) {
+    const flag = (name) => {
+        const i = args.indexOf(name);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const withValue = ['--baseline', '--format', '--output'];
+    const dir = args.find((a, i) => !a.startsWith('--') && !withValue.includes(args[i - 1] ?? ''));
+    if (dir === undefined) {
+        console.error(`usage:\n${CHECK_USAGE}`);
+        return 1;
+    }
+    const root = resolve(dir);
+    const strict = args.includes('--strict');
+    const format = flag('--format') ?? 'text';
+    const output = flag('--output');
+    const baseline = flag('--baseline');
+    if (format !== 'text' && format !== 'sarif') {
+        console.error(`--format is text or sarif, not ${format}`);
+        return 1;
+    }
+    const results = [];
+    let broken = false;
+    for (const d of graphDirs(root)) {
+        const file = existsSync(join(d, 'flow.yaml')) ? join(d, 'flow.yaml') : join(d, 'nav.yaml');
+        try {
+            const newer = newerFormat(file);
+            if (newer !== null) {
+                broken = true;
+                results.push(result('format-newer', file, placeOf(file, 'schema:'), `written in ${newer}; this checker reads ${FORMAT}: pin a version that reads it`, rel(d), 'schema'));
+                continue;
+            }
+            results.push(...(file.endsWith('flow.yaml') ? checkFlow(d) : checkNav(d)));
+        }
+        catch (err) {
+            if (!(err instanceof GraphError || err instanceof ModelError || err instanceof KitError || (err instanceof Error && err.name === 'YAMLParseError')))
+                throw err;
+            broken = true;
+            const linePos = err.linePos?.[0];
+            results.push(result('load', file, linePos === undefined ? { line: 1, column: 1 } : { line: linePos.line, column: linePos.col }, err.message.split('\n')[0], rel(d), 'load'));
+        }
+    }
+    results.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column || a.rule.localeCompare(b.rule) || a.message.localeCompare(b.message));
+    if (baseline !== undefined) {
+        const prints = baselinePrints(baseline);
+        for (const r of results)
+            r.baselineState = prints.has(fingerprint(r)) ? 'unchanged' : 'new';
+    }
+    const failing = results.filter((r) => r.level === 'error' && r.rule !== 'load' && r.rule !== 'format-newer' && (r.baselineState === undefined || r.baselineState === 'new'));
+    const exitCode = broken ? 1 : strict && failing.length > 0 ? 2 : 0;
+    if (format === 'sarif') {
+        const text = `${JSON.stringify(sarif(results, exitCode), null, 2)}\n`;
+        if (output === undefined)
+            process.stdout.write(text);
+        else
+            writeFileSync(output, text);
+    }
+    if (format === 'text' || output !== undefined) {
+        for (const r of results) {
+            const level = r.level === 'error' && r.baselineState === 'unchanged' ? 'warning' : r.level;
+            console.log(`${r.file}:${r.line}:${r.column}: ${level}: ${r.message} [${r.rule}]`);
+            for (const n of r.notes)
+                console.log(`${n.file}:${n.line}:${n.column}: note: ${n.message}`);
+        }
+        const graphs = graphDirs(root).length;
+        console.error(`delurio check: ${graphs} graphs, ${results.filter((r) => r.level === 'error').length} errors, ${results.filter((r) => r.level === 'warning').length} warnings; exit ${exitCode}`);
+    }
+    return exitCode;
+}

package/dist/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// delurio: the open checker and page of delurio-graph/0 (SPEC.md). Reads graph files and nothing else: no network, no
+// account, no model.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { GraphError, load } from './graph.js';
+import { checkAssertions, explore, finalPaths, Model, ModelError } from './model.js';
+import { renderMermaid } from './mermaid.js';
+import { renderSpine } from './spine.js';
+import { renderScreens } from './wireframe.js';
+import { renderPage } from './html.js';
+import { checkChanges } from './changes.js';
+import { checkStarts } from './starts.js';
+import { mainStoryIndex, narrate, stepsByEvents, stepsTo } from './story.js';
+import { checkGoals, findings, loadNav, menuRows, viewOf } from './nav.js';
+import { renderNavMermaid, renderNavPage } from './nav-page.js';
+import { DIFF_USAGE, diffMain } from './diff.js';
+import { KitError, resolveKit } from './kit.js';
+import { CHECK_USAGE, checkMain } from './check.js';
+const USAGE = [
+    'usage:',
+    CHECK_USAGE,
+    '  delurio page <graph dir> [--out <dir>] [--kit <kit>] [--locale <code>] [--strict]',
+    '    writes the graph\'s page: <out>/index.html and its diagram (default out: <graph dir>/viz)',
+    DIFF_USAGE.replaceAll('node src/cli.ts', 'delurio'),
+].join('\n').replaceAll('node src/cli.ts', 'delurio');
+const flag = (args, name) => {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+};
+function navPage(dir, args) {
+    const out = resolve(flag(args, '--out') ?? join(dir, 'viz'));
+    const { g, warnings } = loadNav(dir, flag(args, '--locale'));
+    const views = g.personas.map((p) => viewOf(g, p));
+    const rows = menuRows(g, views);
+    const goals = checkGoals(g, views);
+    const found = findings(g, views, goals);
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, 'index.html'), renderNavPage({ g, views, rows, goals, found, repo: null, warnings }));
+    writeFileSync(join(out, 'nav.mmd'), renderNavMermaid(g));
+    const problems = found.filter((f) => f.level === 'problem');
+    console.log(`${g.id}: ${Object.keys(g.pages).length} pages, ${g.specs.length} ways to move, ${g.personas.length} kinds of user; ${problems.length} problems, ${found.length - problems.length} notes`);
+    for (const w of warnings)
+        console.error(`warning: ${w}`);
+    console.log(`wrote ${join(out, 'index.html')} and ${join(out, 'nav.mmd')}`);
+    return args.includes('--strict') && (warnings.length > 0 || problems.length > 0) ? 2 : 0;
+}
+async function flowPage(dir, args) {
+    const out = resolve(flag(args, '--out') ?? join(dir, 'viz'));
+    const warnings = [];
+    const warn = (m) => {
+        if (!warnings.includes(m))
+            warnings.push(m);
+    };
+    const g = load(dir);
+    const kit = resolveKit(dir, g.ui.kit, flag(args, '--kit'));
+    const model = new Model(g.flow);
+    const ex = explore(model);
+    const assertions = checkAssertions(model, ex);
+    const finals = finalPaths(model, ex);
+    const mainIndex = mainStoryIndex(g, ex);
+    const declared = g.flow.main === undefined ? null : stepsByEvents(model, g.flow.main);
+    if (g.flow.main !== undefined && declared === null)
+        warn('the declared main story cannot be walked: an event is not possible where it is sent');
+    const mainSteps = declared ?? (mainIndex === null ? null : stepsTo(model, ex, mainIndex));
+    const main = mainSteps === null ? null : narrate(g, model, mainSteps);
+    const spineMain = await renderSpine(g, ex, 'main', mainSteps);
+    const spineFull = await renderSpine(g, ex, 'full', mainSteps);
+    const screens = renderScreens(g, warn, kit);
+    const handOvers = checkStarts(g, model, ex);
+    for (const h of handOvers)
+        for (const p of h.problems)
+            warn(`${h.from} starts ${h.flow}: ${p}`);
+    for (const p of checkChanges(g)?.problems ?? [])
+        warn(p);
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, 'index.html'), renderPage({ g, m: model, ex, assertions, finals, main, spineMain, spineFull, screens, kit, handOvers }));
+    writeFileSync(join(out, 'flow.mmd'), renderMermaid(g, ex));
+    const violated = assertions.filter((a) => a.violation !== undefined);
+    console.log(`${g.flow.id}: ${Object.keys(g.flow.states).length} states, ${ex.configs.length} configurations from ${ex.starts} starts, ${assertions.length - violated.length}/${assertions.length} assertions hold`);
+    for (const a of violated)
+        console.log(`  violated: ${a.id}`);
+    for (const w of warnings)
+        console.error(`warning: ${w}`);
+    console.log(`wrote ${join(out, 'index.html')} and ${join(out, 'flow.mmd')}`);
+    return args.includes('--strict') && (violated.length > 0 || warnings.length > 0) ? 2 : 0;
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args[0] === 'check')
+        return checkMain(args.slice(1));
+    if (args[0] === 'diff')
+        return diffMain(args.slice(1));
+    if (args[0] === 'page') {
+        const rest = args.slice(1);
+        const withValue = ['--out', '--kit', '--locale'];
+        const dir = rest.find((a, i) => !a.startsWith('--') && !withValue.includes(rest[i - 1] ?? ''));
+        if (dir === undefined) {
+            console.error(USAGE);
+            return 1;
+        }
+        return existsSync(join(dir, 'flow.yaml')) ? flowPage(dir, rest) : navPage(dir, rest);
+    }
+    console.error(USAGE);
+    return args.length === 0 || args.includes('--help') ? 0 : 1;
+}
+main().then((code) => process.exit(code), (err) => {
+    if (err instanceof GraphError || err instanceof ModelError || err instanceof KitError) {
+        console.error(`error: ${err.message}`);
+        process.exit(1);
+    }
+    throw err;
+});

package/dist/compare.js

@@ -0,0 +1,143 @@
+// What the revision diff is made of, for both kinds of graph: structural changes keyed by id, and changes in behaviour.
+// Nothing here knows what a flow or a page is; diff-flow.ts and diff-nav.ts do.
+const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+const isMap = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+// a value as text with sorted keys, so two values written in a different key order compare equal
+export function canon(v) {
+    if (v === undefined)
+        return '~';
+    if (Array.isArray(v))
+        return `[${v.map(canon).join(',')}]`;
+    if (isMap(v)) {
+        const keys = Object.keys(v).filter((k) => v[k] !== undefined).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canon(v[k])}`).join(',')}}`;
+    }
+    return JSON.stringify(v);
+}
+export const same = (a, b) => canon(a) === canon(b);
+// the keys of both maps: the new order first, then the keys only the old one has, in its order
+export function union(before, after) {
+    const out = Object.keys(after ?? {});
+    for (const k of Object.keys(before ?? {}))
+        if (!own(after ?? {}, k))
+            out.push(k);
+    return out;
+}
+export const quote = (s) => `“${s}”`;
+export const joinWords = (xs) => (xs.length <= 1 ? xs.join('') : `${xs.slice(0, -1).join(', ')} and ${xs[xs.length - 1]}`);
+// Pairs the items of two ordered lists (the rules of an `always`, the alternatives of one event, the entries of a nav graph).
+// The first key pairs items in the order they occur (the n-th with the n-th); a later key pairs what is left only when it is
+// unique on both sides, so nothing is paired by guesswork. Returns [before index, after index] pairs, sorted by before index.
+export function matchOrdered(before, after, keys) {
+    const pairs = [];
+    const usedB = new Set();
+    const usedA = new Set();
+    keys.forEach((key, round) => {
+        const group = (xs, used) => {
+            const m = new Map();
+            xs.forEach((x, i) => {
+                if (used.has(i))
+                    return;
+                const k = key(x);
+                if (k !== null)
+                    m.set(k, [...(m.get(k) ?? []), i]);
+            });
+            return m;
+        };
+        const gb = group(before, usedB);
+        const ga = group(after, usedA);
+        for (const [k, bs] of gb) {
+            const as = ga.get(k);
+            if (as === undefined)
+                continue;
+            if (round > 0 && (bs.length > 1 || as.length > 1))
+                continue;
+            for (let j = 0; j < Math.min(bs.length, as.length); j++) {
+                pairs.push([bs[j], as[j]]);
+                usedB.add(bs[j]);
+                usedA.add(as[j]);
+            }
+        }
+    });
+    return pairs.sort((x, y) => x[0] - y[0]);
+}
+// The pairs that changed place relative to the others: the pairs outside the longest run that keeps its order.
+// An item that only shifted because something was added or removed before it is not moved.
+export function moved(pairs) {
+    const sorted = [...pairs].sort((x, y) => x[0] - y[0]);
+    const n = sorted.length;
+    const len = new Array(n).fill(1);
+    const prev = new Array(n).fill(-1);
+    for (let i = 0; i < n; i++) {
+        for (let j = 0; j < i; j++) {
+            if (sorted[j][1] < sorted[i][1] && len[j] + 1 > len[i]) {
+                len[i] = len[j] + 1;
+                prev[i] = j;
+            }
+        }
+    }
+    let best = -1;
+    for (let i = 0; i < n; i++)
+        if (best < 0 || len[i] > len[best])
+            best = i;
+    const keep = new Set();
+    for (let i = best; i >= 0; i = prev[i])
+        keep.add(i);
+    return sorted.filter((_, i) => !keep.has(i));
+}
+// A field-by-field comparison for data graph-viz does not interpret (domain.yaml, unknown keys): maps by key, lists whose
+// items all carry an `id` by id, anything else as one value. A field called `source` or `evidence` is a citation.
+export function deepDiff(area, key, before, after, out, path = []) {
+    if (same(before, after))
+        return;
+    if (isMap(before) && isMap(after)) {
+        for (const k of union(before, after))
+            deepDiff(area, key, before[k], after[k], out, [...path, k]);
+        return;
+    }
+    const byId = (v) => Array.isArray(v) && v.every((x) => isMap(x) && typeof x.id === 'string');
+    if (byId(before) && byId(after) && before.length + after.length > 0) {
+        const mb = Object.fromEntries(before.map((x) => [x.id, x]));
+        const ma = Object.fromEntries(after.map((x) => [x.id, x]));
+        if (Object.keys(mb).length === before.length && Object.keys(ma).length === after.length) {
+            for (const id of union(mb, ma))
+                deepDiff(area, key, mb[id], ma[id], out, [...path, id]);
+            return;
+        }
+    }
+    const last = path[path.length - 1];
+    out.push({
+        area: last === 'source' || last === 'evidence' ? 'citations' : area,
+        key,
+        op: before === undefined ? 'added' : after === undefined ? 'removed' : 'changed',
+        field: path.length === 0 ? undefined : path.join('.'),
+        before,
+        after,
+        say: null,
+    });
+}
+// the plain old → new comparison of named fields of one item; `say` words the change for people, or gives null
+export function fieldChanges(area, key, before, after, fields, say) {
+    const out = [];
+    for (const f of fields) {
+        if (same(before[f], after[f]))
+            continue;
+        const citation = f === 'source' || f === 'evidence';
+        out.push({ area: citation ? 'citations' : area, key, op: 'changed', field: f, before: before[f], after: after[f], say: citation ? null : say(f, before[f], after[f]) });
+    }
+    return out;
+}
+// the keys of an item that are not in `known`, compared as data
+export function otherKeys(key, before, after, known, out) {
+    for (const k of union(before, after)) {
+        if (known.includes(k))
+            continue;
+        deepDiff('other', key, before[k], after[k], out, [k]);
+    }
+}
+// added and removed items of two lists of plain words
+export function listChanges(before, after) {
+    const b = before ?? [];
+    const a = after ?? [];
+    return { added: a.filter((x) => !b.includes(x)), removed: b.filter((x) => !a.includes(x)) };
+}