@delurio/cli 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+While the version is 0.x, a release that can judge the same graphs differently (a new check, a stricter schema) bumps the minor; a fix that judges nothing differently bumps the patch.
+
+## 0.2.0 (2026-10-25)
+
+- JSON Schemas (2020-12) for `flow`, `ui`, `nav` (and `nav.extracted.yaml`), `domain` and `catalog` files, shipped in `schemas/`, for editors: completion, hover help from SPEC.md, and errors such as a typo in a key or a title cut short by a comma inside `{ }`.
+- `page --watch` writes the pages again on every change under the folder; `page --serve [--port <n>]` also serves them on 127.0.0.1 and reloads the open page after each write, or says why a graph could not be loaded.
+- `check` validates every graph file against its kind's schema: each place a file does not follow it is an error of the new rule `schema`, at its line and column, which fails `--strict` (exit 2) and works with `--baseline`.
+
+## 0.1.1 (2026-10-25)
+
+- `page` on a folder writes the page of every graph under it and `index.html` listing them, in one process.
+- A folder that holds no graph gets one line instead of a stack trace; counts read in the singular when there is one.
+- The README runs every command as `npx @delurio/cli`.
+
+## 0.1.0 (2026-10-25)
+
+- `check`: every graph under a folder, as GNU error lines or SARIF 2.1.0, with `--baseline`; exit 0, 1 or 2.
+- `page`: a graph's page in words, with its guarantees, screens and diagram.
+- `diff`: what a revision changes in a graph, in words, for a pull request.

package/README.md

@@ -64,6 +64,34 @@ Given a folder of graphs instead, it writes the page of every graph under it, ea
 npx @delurio/cli page graphs --out viz
 ```
 
+## Write a graph in an editor
+
+The package ships a JSON Schema (2020-12) for each kind of graph file in `schemas/`: `flow`, `ui`, `nav` (also `nav.extracted.yaml`), `domain` and `catalog`. With them an editor completes keys, explains each one from SPEC.md on hover, and marks a typo, a value of the wrong kind, or a title cut short by a comma inside `{ }`. In VS Code, with the YAML extension, put this in `.vscode/settings.json`:
+
+```json
+{
+  "yaml.schemas": {
+    "https://unpkg.com/@delurio/cli@0.2.0/schemas/flow.schema.json": "**/flow.yaml",
+    "https://unpkg.com/@delurio/cli@0.2.0/schemas/ui.schema.json": "**/ui.yaml",
+    "https://unpkg.com/@delurio/cli@0.2.0/schemas/nav.schema.json": ["**/nav.yaml", "**/nav.extracted.yaml"],
+    "https://unpkg.com/@delurio/cli@0.2.0/schemas/domain.schema.json": "**/domain.yaml"
+  },
+  "json.schemas": [
+    { "fileMatch": ["**/catalog/*.json"], "url": "https://unpkg.com/@delurio/cli@0.2.0/schemas/catalog.schema.json" }
+  ]
+}
+```
+
+With the package installed, `./node_modules/@delurio/cli/schemas/<kind>.schema.json` works the same, offline. `check` reports the same as the editor, as errors of the rule `schema` that fail `--strict`, and finds what a schema cannot see, such as a state that does not exist or a catalog key that is missing.
+
+Next to the editor, keep the pages open and current:
+
+```sh
+npx @delurio/cli page graphs --serve      # http://127.0.0.1:4600/, written again and reloaded on every save
+```
+
+`--watch` writes the pages again on every change without serving them. `--serve` listens on 127.0.0.1 only and serves the written pages and nothing else; when a save leaves a graph that cannot be loaded, the open page says why until the next good save.
+
 ## What a revision changes, in words
 
 ```sh

package/SPEC.md

@@ -68,7 +68,7 @@ states: { <state>: { .. } }
 assertions: [ { id, never: "<expression>", say, source } ]
 ```
 
-A flow is a statechart, and its meaning is a subset of SCXML's (W3C Recommendation, 2015). A transition in `on` is an SCXML transition with an event, `always` is a list of eventless transitions, a list of transitions is tried in document order, `invoke` and `type: final` mean what they mean in SCXML, a guard is a `cond` and an effect an `<assign>`; `DONE` and `FAIL.<class>` stand for SCXML's `done.invoke` and `error` events. A flow can therefore be written out as SCXML; that export is an open issue.
+A flow is a statechart, and its meaning is a subset of SCXML's (W3C Recommendation, 2015). A transition in `on` is an SCXML transition with an event, `always` is a list of eventless transitions, a list of transitions is tried in document order, `invoke` and `type: final` mean what they mean in SCXML, a guard is a `cond` and an effect an `<assign>`; `DONE` and `FAIL.<class>` stand for SCXML's `done.invoke` and `error` events. A flow can therefore be written out as SCXML; that export is [#9](https://github.com/delurio-labs/delurio/issues/9).
 
 ### Context
 
@@ -117,7 +117,7 @@ A configuration is a state together with a value for every context variable. The
 
 Each assertion is `never: <expression>`: it holds when no reachable configuration satisfies the expression. A violation is reported with the shortest event path from a starting situation. Under `--strict` a violated assertion exits 2.
 
-The checker does not yet fail on unreachable states, transitions no situation takes, or states with no way out; the page already shows them. That is an open issue. Paths that cover every transition are an open issue.
+The checker does not yet fail on unreachable states, transitions no situation takes, or states with no way out; the page already shows them. That is [#2](https://github.com/delurio-labs/delurio/issues/2). Paths that cover every transition are [#4](https://github.com/delurio-labs/delurio/issues/4).
 
 ### Several flows
 
@@ -177,7 +177,7 @@ rules: [ { id, rule } ]
 
 A `role` is a WAI-ARIA 1.2 role, and `name` is the accessible name that Accessible Name and Description Computation 1.2 gives the node; `kit check` reads both from the browser's accessibility tree.
 
-A node is shown in a state when the state is in `in`, not in `unless`, and `when` holds. `edges` records relations the page and the checks use: a node labelled by another, an action that leads to a state. `rules` are written but no tool reads them yet; checking them, together with dialogs, focus return, confirmation before a destructive action and events handled where shown, is an open issue.
+A node is shown in a state when the state is in `in`, not in `unless`, and `when` holds. `edges` records relations the page and the checks use: a node labelled by another, an action that leads to a state. `rules` are written but no tool reads them yet; checking them, together with dialogs, focus return, confirmation before a destructive action and events handled where shown, is [#3](https://github.com/delurio-labs/delurio/issues/3).
 
 ### Catalog
 
@@ -231,11 +231,13 @@ invariants:
 
 A capture may carry more words of its own on a field (`owner`, `note`, `editableBy`, `matching`, `opaque`). They are kept and compared, and no tool reads them.
 
+An action, a refusal and an invariant may carry `note`: the author's own words, which no tool reads. An invariant the code does not keep is still written, with `holds: false` and the `finding` that reports it: the finding's id in the graph's report, such as `MS-7`. A capture describes the code, so the invariant says what should hold and the finding says where it does not. Decided on 25 Oct 2026.
+
 **The API.** An action with a `route` (`METHOD /path`) is one OpenAPI 3.1 operation: its name is the `operationId`, `needs` its security requirement, `query` (a JSON Schema object) its query parameters, `body` its request body, `result` its response (`returns` an entity, a `redirect`, a `status`, or a JSON Schema), and each refusal one more response. When a refusal has a body, it is RFC 9457 problem details with the refusal code as its `type`. So a domain can be written out as an OpenAPI document, and an app that already publishes one names it at the top (`openapi: <file>`) and each action's operation by `operationId`, instead of copying them. An action with no route is a step inside the service. `needs`, `policies`, `sideEffects`, `refusals.<code>.redirect` and `invariants` are delurio's own: no standard says who may do what to which data, or what must always hold.
 
-This form was decided on 22 Oct 2026. Graphs captured before it may still give fields as `{ kind: text }`; they are converted when a tool first reads fields. The OpenAPI export and import are an open issue.
+This form was decided on 22 Oct 2026. Graphs captured before it may still give fields as `{ kind: text }`; they are converted when a tool first reads fields. The OpenAPI export and import are [#8](https://github.com/delurio-labs/delurio/issues/8).
 
-No tool checks a domain yet: the revision diff compares it and anchors lock its `source:` keys. Loading it with the flow and checking policies, secrets and `invoke` names is an open issue; generating it from Drizzle and Zod is an open issue; a registry that every API operation and route is covered by a graph is an open issue.
+No tool checks a domain yet: the revision diff compares it and anchors lock its `source:` keys. Loading it with the flow and checking policies, secrets and `invoke` names is [#5](https://github.com/delurio-labs/delurio/issues/5); generating it from Drizzle and Zod is [#6](https://github.com/delurio-labs/delurio/issues/6); a registry that every API operation and route is covered by a graph is [#7](https://github.com/delurio-labs/delurio/issues/7).
 
 ## 6. Navigation (`kind: nav`)
 
@@ -324,12 +326,12 @@ graphs/product/flow.yaml:88:7: note: step 2: CODE_CHANGED from developing, with
 
 The same input gives the same bytes: no times, no random ids, results in a fixed order. Every file written is valid against the OASIS schema.
 
-There is no other machine format: no JSON of delurio's own, and nothing that only one CI reads. A converter for a CI that reads neither (GitLab's Code Quality report, Bitbucket's Code Insights) is written when a customer needs it, outside the checker. The public, pinned, offline CLI that gives both outputs is an open issue.
+There is no other machine format: no JSON of delurio's own, and nothing that only one CI reads. A converter for a CI that reads neither (GitLab's Code Quality report, Bitbucket's Code Insights) is written when a customer needs it, outside the checker. The public, pinned, offline CLI that gives both outputs is `@delurio/cli`, built from this repository; what its first release left out is [#1](https://github.com/delurio-labs/delurio/issues/1).
 
 ## 11. Writing a graph
 
 - Model the few cases that change behaviour; a guard over hundreds of permission codes is wrong.
-- Quote a YAML list item that contains `: `, or YAML reads it as a map.
+- Quote a YAML list item that contains `: `, or YAML reads it as a map. Quote a value inside `{ }` that contains `, ` too, or YAML cuts it there and reads the rest as a key: `{ type: final, title: "Paid, and sent" }`.
 - Say every rule that must hold as an assertion; do not leave it implied by the drawing.
 - In capture mode, describe what the code does today: no new feature, no fix. An invariant the code breaks is modelled as the code has it and reported, not written as an assertion that fails.
 - One process, one flow. A process that runs beside another starts it (`starts:`) or waits for it (`invoke: { flow }`).

package/dist/check.js

@@ -14,6 +14,7 @@ import { checkStarts } from './starts.js';
 import { checkChanges } from './changes.js';
 import { KitError, resolveKit } from './kit.js';
 import { checkGoals, findings, loadNav, viewOf } from './nav.js';
+import { schemaKindOf, validateFile } from './schemas.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;',
@@ -24,6 +25,7 @@ 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: 'schema', text: "A graph file does not follow its kind's schema (SPEC.md)", 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' },
@@ -65,6 +67,19 @@ export function graphDirs(root, out = []) {
     }
     return out;
 }
+// every file under root that a schema covers (flow, ui, nav, nav.extracted, domain, catalog), in path order
+function graphFiles(root, out = []) {
+    for (const name of readdirSync(root).sort()) {
+        if (SKIP.has(name) || name.startsWith('.'))
+            continue;
+        const path = join(root, name);
+        if (statSync(path).isDirectory())
+            graphFiles(path, out);
+        else if (schemaKindOf(path) !== null)
+            out.push(path);
+    }
+    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'));
@@ -239,6 +254,11 @@ export function checkMain(args) {
             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'));
         }
     }
+    // every graph file against its kind's schema: what an editor with the schemas marks, check reports
+    for (const file of graphFiles(root)) {
+        for (const f of validateFile(file))
+            results.push(result('schema', file, f, f.message, f.graph ?? rel(file), f.element));
+    }
     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);

package/dist/cli.js

@@ -19,12 +19,15 @@ import { DIFF_USAGE, diffMain } from './diff.js';
 import { KitError, resolveKit } from './kit.js';
 import { CHECK_USAGE, checkMain, count, graphDirs } from './check.js';
 import { renderIndexPage } from './index-page.js';
+import { watchPages } from './watch.js';
 const USAGE = [
     'usage:',
     CHECK_USAGE,
-    '  delurio page <graph dir | graphs folder> [--out <dir>] [--kit <kit>] [--locale <code>] [--strict]',
+    '  delurio page <graph dir | graphs folder> [--out <dir>] [--kit <kit>] [--locale <code>] [--strict] [--watch] [--serve [--port <n>]]',
     '    writes the graph\'s page: <out>/index.html and its diagram (default out: <graph dir>/viz); on a folder of graphs,',
-    '    the page of each at <out>/<its path> and an index of them all at <out>/index.html (default out: <folder>/viz)',
+    '    the page of each at <out>/<its path> and an index of them all at <out>/index.html (default out: <folder>/viz);',
+    '    --watch writes them again on every change under the folder; --serve also shows them at http://127.0.0.1:<port>/',
+    '    (default 4600) and reloads the open page after each write',
     DIFF_USAGE.replaceAll('node src/cli.ts', 'delurio'),
 ].join('\n').replaceAll('node src/cli.ts', 'delurio');
 const flag = (args, name) => {
@@ -94,13 +97,13 @@ const isGraph = (dir) => existsSync(join(dir, 'flow.yaml')) || existsSync(join(d
 // every graph under the folder, each into <out>/<its path>, and the index of them all. A graph that cannot be loaded
 // is listed as such and the rest are still written: exit 1 when one cannot be loaded, else 2 under --strict when one
 // would fail on its own, else 0.
-async function treePages(root, args) {
+async function treePages(root, out, args) {
     const dirs = graphDirs(root);
     if (dirs.length === 0) {
-        console.error(`error: ${root} is not a graph and holds none: there is no flow.yaml or nav.yaml in it or under it`);
-        return 1;
+        const message = `${root} is not a graph and holds none: there is no flow.yaml or nav.yaml in it or under it`;
+        console.error(`error: ${message}`);
+        return { code: 1, message };
     }
-    const out = resolve(flag(args, '--out') ?? join(root, 'viz'));
     const entries = [];
     let broken = false;
     let failing = false;
@@ -113,7 +116,7 @@ async function treePages(root, args) {
             failing ||= code !== 0;
         }
         catch (err) {
-            if (!(err instanceof GraphError || err instanceof ModelError || err instanceof KitError || (err instanceof Error && err.name === 'YAMLParseError')))
+            if (!loadError(err))
                 throw err;
             broken = true;
             const message = err.message.split('\n')[0].replace(/:$/, '');
@@ -124,7 +127,27 @@ async function treePages(root, args) {
     mkdirSync(out, { recursive: true });
     writeFileSync(join(out, 'index.html'), renderIndexPage(basename(resolve(root)), entries));
     console.log(`wrote ${join(out, 'index.html')} and the pages of ${count(entries.length - entries.filter((e) => e.error !== null).length, 'graph')} under ${out}`);
-    return broken ? 1 : failing ? 2 : 0;
+    const firstError = entries.find((e) => e.error !== null);
+    return { code: broken ? 1 : failing ? 2 : 0, message: firstError === undefined ? '' : `${firstError.path}: ${firstError.error}` };
+}
+const loadError = (err) => err instanceof GraphError || err instanceof ModelError || err instanceof KitError || (err instanceof Error && err.name === 'YAMLParseError');
+// one graph's page, or the pages of every graph under the folder
+async function writePages(dir, out, args) {
+    if (!isGraph(dir))
+        return treePages(dir, out, args);
+    try {
+        const flow = existsSync(join(dir, 'flow.yaml'));
+        const { code } = flow ? await flowPage(dir, out, args) : navPage(dir, out, args);
+        console.log(`wrote ${join(out, 'index.html')} and ${join(out, flow ? 'flow.mmd' : 'nav.mmd')}`);
+        return { code, message: '' };
+    }
+    catch (err) {
+        if (!loadError(err))
+            throw err;
+        const message = err.message.split('\n')[0].replace(/:$/, '');
+        console.error(`error: ${message}`);
+        return { code: 1, message };
+    }
 }
 async function main() {
     const args = process.argv.slice(2);
@@ -134,7 +157,7 @@ async function main() {
         return diffMain(args.slice(1));
     if (args[0] === 'page') {
         const rest = args.slice(1);
-        const withValue = ['--out', '--kit', '--locale'];
+        const withValue = ['--out', '--kit', '--locale', '--port'];
         const dir = rest.find((a, i) => !a.startsWith('--') && !withValue.includes(rest[i - 1] ?? ''));
         if (dir === undefined) {
             console.error(USAGE);
@@ -144,12 +167,20 @@ async function main() {
             console.error(`error: ${dir} is not a folder`);
             return 1;
         }
-        if (!isGraph(dir))
-            return treePages(dir, rest);
         const out = resolve(flag(rest, '--out') ?? join(dir, 'viz'));
-        const { code } = existsSync(join(dir, 'flow.yaml')) ? await flowPage(dir, out, rest) : navPage(dir, out, rest);
-        console.log(`wrote ${join(out, 'index.html')} and ${join(out, existsSync(join(dir, 'flow.yaml')) ? 'flow.mmd' : 'nav.mmd')}`);
-        return code;
+        const first = await writePages(dir, out, rest);
+        const serve = rest.includes('--serve');
+        if (!serve && !rest.includes('--watch'))
+            return first.code;
+        const port = Number(flag(rest, '--port') ?? 4600);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            console.error(`error: --port is a port number, not ${flag(rest, '--port')}`);
+            return 1;
+        }
+        return watchPages(dir, out, async () => {
+            const again = await writePages(dir, out, rest);
+            return { ok: again.code !== 1, message: again.message };
+        }, serve ? port : null);
     }
     console.error(USAGE);
     return args.length === 0 || args.includes('--help') ? 0 : 1;

package/dist/schemas.js

@@ -0,0 +1,256 @@
+// The JSON Schemas of schemas/ (one per kind of graph file, SPEC.md §12) as `check` applies them: a file is validated
+// against its kind's schema, and each failure is placed at its line and column through the YAML document and said in
+// words a writer can act on: the key that is not one, the key it was probably meant to be, why an if/then rule exists
+// (its `$comment`), and the comma that cut a value inside `{ }`. The schemas are read from the package's own folder,
+// beside src/ and dist/ alike.
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import addFormatsModule from 'ajv-formats';
+import { isMap, isSeq, LineCounter, parse, parseDocument } from 'yaml';
+const FORMAT = 'delurio-graph/0';
+const KINDS = ['flow', 'ui', 'domain', 'nav', 'catalog'];
+// the kind of graph file, by its name: null for a file no schema covers (binding, tutorial, kit, anchors.lock)
+export function schemaKindOf(file) {
+    const name = basename(file);
+    if (name === 'flow.yaml' || name === 'ui.yaml' || name === 'domain.yaml')
+        return name.slice(0, -'.yaml'.length);
+    if (name === 'nav.yaml' || name === 'nav.extracted.yaml')
+        return 'nav';
+    if (name.endsWith('.json') && basename(dirname(file)) === 'catalog')
+        return 'catalog';
+    return null;
+}
+let compiled = null;
+// compiled once, on first use; strictRequired is off because an if/then names keys its branch does not declare
+function schemas() {
+    if (compiled !== null)
+        return compiled;
+    const ajv = new Ajv2020({ allErrors: true, verbose: true, strict: true, strictRequired: false, allowUnionTypes: true });
+    addFormatsModule.default(ajv);
+    const roots = {};
+    const validators = {};
+    for (const kind of KINDS)
+        roots[kind] = JSON.parse(readFileSync(new URL(`../schemas/${kind}.schema.json`, import.meta.url), 'utf8'));
+    for (const kind of KINDS)
+        validators[kind] = ajv.compile(roots[kind]);
+    compiled = { roots, validators };
+    return compiled;
+}
+const steps = (pointer) => (pointer === '' ? [] : pointer.slice(1).split('/').map((t) => t.replace(/~1/g, '/').replace(/~0/g, '~')));
+const escape = (step) => step.replace(/~/g, '~0').replace(/\//g, '~1');
+const within = (path, base) => path === base || path.startsWith(`${base}/`);
+const keyOf = (pair) => String(pair.key?.value ?? pair.key);
+// the YAML node at a JSON pointer; with `name`, the key `name` of the map there, that map and the key's value
+function place(doc, pointer, name) {
+    let node = doc.contents;
+    for (const t of steps(pointer)) {
+        const next = isMap(node) ? node.items.find((p) => keyOf(p) === t)?.value : isSeq(node) ? node.items[Number(t)] : undefined;
+        if (next === undefined || next === null)
+            break;
+        node = next;
+    }
+    if (name === undefined || !isMap(node))
+        return { at: node };
+    const pair = node.items.find((p) => keyOf(p) === name);
+    return { at: pair?.key ?? node, map: node, value: pair?.value };
+}
+// a schema and the ones its `$ref`s name, inside the same file
+function chain(root, schema) {
+    const out = [];
+    for (let s = schema; s !== null && typeof s === 'object' && out.length < 8;) {
+        const here = s;
+        out.push(here);
+        const ref = here.$ref;
+        s = typeof ref === 'string' && ref.startsWith('#/') ? ref.slice(2).split('/').reduce((x, k) => x?.[k], root) : undefined;
+    }
+    return out;
+}
+// edits between two names, a swap of two neighbours counting as one (titel, title)
+function distance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++)
+        d[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+        }
+    }
+    return d[a.length][b.length];
+}
+const KIND_WORDS = { object: 'an object', array: 'a list', string: 'a string', integer: 'an integer', number: 'a number', boolean: 'true or false', null: 'null' };
+const either = (xs) => (xs.length <= 1 ? xs.join('') : `${xs.slice(0, -1).join(', ')} or ${xs[xs.length - 1]}`);
+const quoted = (xs) => either(xs.map((x) => JSON.stringify(x)));
+function message(e, root) {
+    const p = e.params;
+    switch (e.keyword) {
+        case 'additionalProperties':
+        case 'unevaluatedProperties': {
+            const name = String(p.additionalProperty ?? p.unevaluatedProperty);
+            const known = chain(root, e.parentSchema).flatMap((x) => Object.keys(x.properties ?? {}));
+            const near = known.filter((k) => distance(k.toLowerCase(), name.toLowerCase()) <= Math.min(2, Math.max(1, Math.floor(k.length / 3))));
+            return `"${name}" is not a key here${near.length > 0 ? `; did you mean ${quoted(near)}?` : ''}`;
+        }
+        case 'required':
+            return `${p.missingProperty.map((k) => JSON.stringify(k)).join(' or ')} is missing`;
+        case 'enum': {
+            const allowed = p.allowedValues;
+            return allowed.length <= 12 ? `must be ${quoted(allowed)}` : `${JSON.stringify(e.data)} is not one of its ${allowed.length} values`;
+        }
+        case 'const':
+            return `must be ${JSON.stringify(p.allowedValue)}`;
+        case 'type':
+            return `must be ${either(p.type.map((t) => KIND_WORDS[t] ?? t))}`;
+        case 'pattern':
+            return `${JSON.stringify(e.data)} does not match ${String(p.pattern)}`;
+        case 'propertyNames': {
+            const said = chain(root, e.parentSchema?.propertyNames).find((x) => typeof x.description === 'string')?.description;
+            return `the name "${String(p.propertyName)}" is not allowed${said === undefined ? '' : `: ${said.split('. ')[0].replace(/\.$/, '')}`}`;
+        }
+        case 'false schema':
+            return 'is not allowed here';
+        case 'oneOf':
+            return 'matches more than one of its forms';
+        case 'minItems':
+        case 'maxItems':
+        case 'minProperties':
+        case 'maxProperties': {
+            const n = Number(p.limit);
+            const what = e.keyword.endsWith('Items') ? (n === 1 ? 'item' : 'items') : n === 1 ? 'key' : 'keys';
+            return e.keyword.startsWith('min') ? `needs at least ${n} ${what}` : `has more than ${n} ${what}`;
+        }
+        default:
+            return e.message ?? e.keyword;
+    }
+}
+// Ajv reports every alternative of an anyOf and every rule around a then; keep what the writer can act on
+function simplify(errors) {
+    // the reason for an if/then rule, from its $comment, goes onto the errors its then or else gave (just before it)
+    errors.forEach((e, i) => {
+        const comment = e.parentSchema?.$comment;
+        if (e.keyword !== 'if' || typeof comment !== 'string')
+            return;
+        const base = e.schemaPath.slice(0, -'/if'.length);
+        for (let j = i - 1; j >= 0; j--) {
+            const x = errors[j];
+            if (!within(x.instancePath, e.instancePath) || !(x.schemaPath.startsWith(`${base}/then/`) || x.schemaPath.startsWith(`${base}/else/`)))
+                break;
+            x.because = comment;
+        }
+    });
+    const wrapper = (x) => ['if', 'anyOf', 'oneOf'].includes(x.keyword);
+    const explained = (e) => errors.some((x) => x !== e && !wrapper(x) && ((x.instancePath !== e.instancePath && within(x.instancePath, e.instancePath)) || (x.instancePath === e.instancePath && x.keyword !== 'type')));
+    const kept = errors.filter((e) => {
+        if (e.keyword === 'if')
+            return false; // its then or else said it
+        if (e.keyword === 'anyOf' || (e.keyword === 'oneOf' && e.params.passingSchemas === null)) {
+            return !explained(e) && !errors.some((x) => x !== e && x.keyword === 'type' && x.instancePath === e.instancePath);
+        }
+        if (e.keyword === 'type')
+            return !explained(e); // an alternative of the right type is there, and failed further in
+        if (e.propertyName !== undefined)
+            return false; // the name's own failure; its propertyNames error says it
+        return true;
+    });
+    // what is left at one place in one form is one line: the types the alternatives want, the keys of which one is needed
+    const out = [];
+    for (const e of kept) {
+        const alternative = e.keyword === 'required' && /\/(anyOf|oneOf)\/\d+\/required$/.test(e.schemaPath);
+        const twin = out.find((x) => x.instancePath === e.instancePath && x.keyword === e.keyword && (e.keyword === 'type' || (alternative && x.alternative === true)));
+        const p = e.params;
+        if (twin !== undefined && e.keyword === 'type')
+            twin.params.type = [...new Set([...twin.params.type, ...[p.type].flat()])];
+        else if (twin !== undefined)
+            twin.params.missingProperty.push(p.missingProperty);
+        else {
+            const params = e.keyword === 'type' ? { type: [p.type].flat() } : e.keyword === 'required' ? { missingProperty: [p.missingProperty] } : e.params;
+            out.push({ ...e, alternative, params });
+        }
+    }
+    return out;
+}
+// the id of the graph a file belongs to, when the file does not say it: the flow, nav or ui graph beside it
+function graphIdBeside(dir) {
+    for (const name of ['flow.yaml', 'nav.yaml', 'ui.yaml']) {
+        const file = join(dir, name);
+        if (!existsSync(file))
+            continue;
+        try {
+            const id = parse(readFileSync(file, 'utf8'))?.id;
+            if (typeof id === 'string')
+                return id;
+        }
+        catch {
+            // a graph file that does not parse names no graph; its own check says why
+        }
+    }
+    return null;
+}
+// every place where the file does not follow its kind's schema; a file written for another format is left to the
+// format check
+export function validateFile(file) {
+    const kind = schemaKindOf(file);
+    if (kind === null)
+        return [];
+    const text = readFileSync(file, 'utf8');
+    const lineCounter = new LineCounter();
+    const doc = parseDocument(text, { lineCounter, prettyErrors: false });
+    const at = (offset) => {
+        const { line, col } = lineCounter.linePos(offset ?? 0);
+        return { line, column: col };
+    };
+    const ownFile = kind === 'catalog' ? `catalog/${basename(file)}` : basename(file);
+    let graph = null;
+    const failure = (where, said, pointer) => {
+        graph ??= graphIdBeside(kind === 'catalog' ? dirname(dirname(file)) : dirname(file));
+        return { ...where, message: said, graph, element: `${ownFile}#${pointer}` };
+    };
+    // the first YAML error only: the ones after it mostly follow from it
+    if (doc.errors.length > 0)
+        return [failure(at(doc.errors[0].pos[0]), `not YAML: ${doc.errors[0].message.split('\n')[0]}`, '')];
+    let data;
+    if (kind === 'catalog') {
+        try {
+            data = JSON.parse(text);
+        }
+        catch (err) {
+            return [failure({ line: 1, column: 1 }, `not JSON: ${err.message}`, '')];
+        }
+    }
+    else
+        data = doc.toJS();
+    const own = data ?? {};
+    if (kind !== 'catalog' && typeof own.schema === 'string' && own.schema !== FORMAT)
+        return [];
+    if (kind !== 'catalog' && typeof own.id === 'string')
+        graph = own.id;
+    const { roots, validators } = schemas();
+    const validate = validators[kind];
+    if (validate(data))
+        return [];
+    const out = [];
+    for (const e of simplify((validate.errors ?? []))) {
+        const p = e.params;
+        const named = p.additionalProperty ?? p.unevaluatedProperty ?? p.propertyName;
+        const name = named === undefined ? undefined : String(named);
+        const where = place(doc, e.instancePath, name);
+        const path = steps(e.instancePath).join('.');
+        let said = `${path === '' ? 'the file' : path}: ${message(e, roots[kind])}`;
+        const because = e.because ?? (e.keyword === 'false schema' ? undefined : e.parentSchema?.$comment);
+        if (typeof because === 'string')
+            said += ` (${because})`;
+        // `{ title: Done, and paid }` is a title and a key "and paid": YAML ends a flow mapping's value at the comma
+        const empty = where.value === null || where.value?.value === null;
+        if (name !== undefined && where.map?.flow === true && empty)
+            said += '; a comma inside { } ends the value before it: quote that value';
+        const missing = e.keyword === 'required' ? p.missingProperty.join('|') : undefined;
+        const pointer = name !== undefined ? `${e.instancePath}/${escape(name)}` : missing !== undefined ? `${e.instancePath}/${escape(missing)}` : e.instancePath;
+        const range = where.at?.range;
+        const finding = failure(at(range?.[0]), said, pointer);
+        if (!out.some((x) => x.line === finding.line && x.column === finding.column && x.message === finding.message))
+            out.push(finding);
+    }
+    return out;
+}

package/dist/watch.js

@@ -0,0 +1,114 @@
+// `page --watch` writes the pages again whenever a graph file under the folder changes; with `--serve` it also shows
+// them at http://127.0.0.1:<port>/ and reloads the open page after each write, or shows why the write failed. Local
+// only: the server listens on the loopback address and serves the written pages and nothing else.
+import { existsSync, readFileSync, statSync, watch } from 'node:fs';
+import { createServer } from 'node:http';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+const WATCHED = new Set(['.yaml', '.yml', '.json']);
+const TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.json': 'application/json',
+    '.mmd': 'text/plain; charset=utf-8',
+};
+// added to every page the server sends, never to the files on disk
+const RELOAD = `<script>(() => {
+  const events = new EventSource('/__delurio/events');
+  events.addEventListener('reload', () => location.reload());
+  events.addEventListener('failed', (e) => {
+    let box = document.getElementById('__delurio');
+    if (!box) {
+      box = document.createElement('pre');
+      box.id = '__delurio';
+      box.setAttribute('role', 'alert');
+      box.style.cssText = 'position:fixed;inset:auto 0 0 0;margin:0;padding:12px 16px;background:#7f1d1d;color:#fff;font:13px/1.5 ui-monospace,Menlo,Consolas,monospace;white-space:pre-wrap;z-index:2147483647';
+      document.body.append(box);
+    }
+    box.textContent = 'delurio page: ' + e.data;
+  });
+})();</script>`;
+// whether a changed file can change a page: a graph file, not one of the pages being written
+function counts(root, out, name) {
+    const abs = resolve(root, name);
+    if (abs === out || abs.startsWith(out + sep))
+        return false;
+    if (abs.split(sep).includes('viz'))
+        return false;
+    return WATCHED.has(extname(abs));
+}
+function serve(out, port, clients) {
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        if (url.pathname === '/__delurio/events') {
+            res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
+            res.write(': delurio\n\n');
+            clients.add(res);
+            req.on('close', () => clients.delete(res));
+            return;
+        }
+        let wanted;
+        try {
+            wanted = decodeURIComponent(url.pathname);
+        }
+        catch {
+            res.writeHead(400).end();
+            return;
+        }
+        let path = join(out, normalize(wanted));
+        if (path !== out && !path.startsWith(out + sep)) {
+            res.writeHead(403).end();
+            return;
+        }
+        if (existsSync(path) && statSync(path).isDirectory())
+            path = join(path, 'index.html');
+        if (!existsSync(path)) {
+            res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' }).end('not found');
+            return;
+        }
+        const type = TYPES[extname(path)] ?? 'application/octet-stream';
+        let body = readFileSync(path);
+        if (type.startsWith('text/html')) {
+            const html = body.toString('utf8');
+            body = html.includes('</body>') ? html.replace('</body>', `${RELOAD}</body>`) : html + RELOAD;
+        }
+        res.writeHead(200, { 'Content-Type': type, 'Cache-Control': 'no-store' }).end(body);
+    });
+    server.listen(port, '127.0.0.1', () => console.log(`serving http://127.0.0.1:${port}/ (Ctrl-C stops)`));
+}
+// Runs until stopped. `render` writes every page once and says whether it could.
+export function watchPages(root, out, render, port) {
+    const clients = new Set();
+    const tell = (event, data) => {
+        for (const c of clients)
+            c.write(`event: ${event}\ndata: ${data.replace(/\n/g, ' ')}\n\n`);
+    };
+    if (port !== null)
+        serve(out, port, clients);
+    let timer = null;
+    let running = false;
+    let again = false;
+    const run = async () => {
+        if (running) {
+            again = true;
+            return;
+        }
+        running = true;
+        do {
+            again = false;
+            const done = await render();
+            tell(done.ok ? 'reload' : 'failed', done.ok ? '' : done.message);
+        } while (again);
+        running = false;
+    };
+    watch(root, { recursive: true }, (_event, name) => {
+        if (name === null || !counts(resolve(root), out, String(name)))
+            return;
+        if (timer !== null)
+            clearTimeout(timer);
+        timer = setTimeout(() => void run(), 150);
+    });
+    console.log(`watching ${root} for changes`);
+    return new Promise(() => { });
+}