@delurio/cli 0.1.0 → 0.2.0

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(() => { });
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@delurio/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The open checker and page of delurio-graph/0: check every graph in a project's own CI, offline, with GNU error lines and SARIF.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": { "delurio": "dist/cli.js" },
-  "files": ["dist", "SPEC.md", "NOTICE"],
+  "files": ["dist", "schemas", "SPEC.md", "NOTICE", "CHANGELOG.md"],
   "engines": { "node": ">=22.18" },
   "repository": { "type": "git", "url": "git+https://github.com/delurio-labs/delurio.git" },
   "homepage": "https://delur.io",
@@ -17,6 +17,8 @@
     "test": "node src/cli.ts check examples --strict"
   },
   "dependencies": {
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
     "elkjs": "0.12.0",
     "yaml": "2.9.1"
   },

package/schemas/catalog.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/@delurio/cli@0.2.0/schemas/catalog.schema.json",
+  "title": "delurio catalog (catalog/<locale>.json)",
+  "description": "The words of a UI graph in one locale (SPEC.md §4): a JSON object from key to an ICU MessageFormat message. The file is named by its BCP 47 locale (en.json, tr.json, pt-BR.json). A captured catalog is copied from the app as it is, so its keys may be in any form.",
+  "type": "object",
+  "propertyNames": { "minLength": 1 },
+  "additionalProperties": {
+    "type": "string",
+    "description": "An ICU MessageFormat message. Today the tools fill simple arguments: `{param}` is filled from the node's `params`, which name sample or data values.",
+    "examples": ["{client} wants access to your account"]
+  }
+}