@delurio/cli 0.1.0 → 0.1.1

package/README.md

@@ -6,10 +6,17 @@ This package is the part a project's own CI runs: it reads graph files and nothi
 
 ## Install
 
-Pin an exact version:
+Run it once, without installing:
+
+```sh
+npx @delurio/cli@0.1.1 check graphs --strict
+```
+
+or pin an exact version in a project, after which the command is `delurio`:
 
 ```sh
 npm install --save-dev --save-exact @delurio/cli
+npx delurio check graphs --strict
 ```
 
 or the container image, pinned by its digest:
@@ -23,15 +30,15 @@ Node 22.18 or later.
 ## Check every graph
 
 ```sh
-npx delurio check graphs --strict
+npx @delurio/cli check graphs --strict
 ```
 
 - **Findings:** one line each, in the GNU error format that compilers, editors and CI logs read:
 
   ```
-  graphs/billing/payment/flow.yaml:176:7: error: restricted-only-when-retries-ran-out is broken: … [assertion-violated]
-  graphs/billing/payment/flow.yaml:176:7: note: start: role = manager, paid = false
-  graphs/billing/payment/flow.yaml:176:7: note: step 1: RETRIES_RAN_OUT
+  graphs/billing/billing.payment/flow.yaml:176:7: error: restricted-only-when-retries-ran-out is broken: … [assertion-violated]
+  graphs/billing/billing.payment/flow.yaml:176:7: note: start: role = manager, paid = false
+  graphs/billing/billing.payment/flow.yaml:176:7: note: step 1: RETRIES_RAN_OUT
   ```
 
 - **SARIF:** `--format sarif --output delurio.sarif` writes SARIF 2.1.0 for code scanning. The same input gives the same bytes.
@@ -46,15 +53,21 @@ npx delurio check graphs --strict
 ## A graph's page
 
 ```sh
-npx delurio page graphs/billing/payment --out viz/payment
+npx @delurio/cli page examples/qauth-authorize --out viz/qauth-authorize
 ```
 
 The page shows the flow in words: its main story, every way it ends, its guarantees and whether they hold, its screens as wireframes, and its diagram. `examples/qauth-authorize` is a small graph to try it on.
 
+Given a folder of graphs instead, it writes the page of every graph under it, each at its own path, and `index.html` listing them all with what their check found:
+
+```sh
+npx @delurio/cli page graphs --out viz
+```
+
 ## What a revision changes, in words
 
 ```sh
-npx delurio diff graphs/billing/payment --base origin/main
+npx @delurio/cli diff examples/qauth-authorize --base origin/main
 ```
 
 This prints Markdown for a pull request. It covers what the flow does differently (found by running both revisions) and what changed in the graph.

package/dist/check.js

@@ -39,6 +39,7 @@ const RULES = [
     { id: 'nav-note', text: 'A note on the navigation graph', level: 'warning' },
 ];
 const LEVEL = new Map(RULES.map((r) => [r.id, r.level]));
+export const count = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
 // 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))
@@ -51,7 +52,8 @@ function placeOf(abs, needle) {
     }
     return { line: 1, column: 1 };
 }
-function graphDirs(root, out = []) {
+// every graph folder at or under root, in path order
+export 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()) {
@@ -260,7 +262,9 @@ export function checkMain(args) {
                 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}`);
+        const errors = results.filter((r) => r.level === 'error').length;
+        const warnings = results.filter((r) => r.level === 'warning').length;
+        console.error(`delurio check: ${count(graphs, 'graph')}, ${count(errors, 'error')}, ${count(warnings, 'warning')}; exit ${exitCode}`);
     }
     return exitCode;
 }

package/dist/cli.js

@@ -2,9 +2,9 @@
 // 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 { existsSync, statSync } from 'node:fs';
+import { basename, join, relative, resolve, sep } from 'node:path';
+import { GraphError, humanize, load } from './graph.js';
 import { checkAssertions, explore, finalPaths, Model, ModelError } from './model.js';
 import { renderMermaid } from './mermaid.js';
 import { renderSpine } from './spine.js';
@@ -17,20 +17,21 @@ 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';
+import { CHECK_USAGE, checkMain, count, graphDirs } from './check.js';
+import { renderIndexPage } from './index-page.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)',
+    '  delurio page <graph dir | graphs folder> [--out <dir>] [--kit <kit>] [--locale <code>] [--strict]',
+    '    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)',
     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'));
+function navPage(dir, out, args) {
     const { g, warnings } = loadNav(dir, flag(args, '--locale'));
     const views = g.personas.map((p) => viewOf(g, p));
     const rows = menuRows(g, views);
@@ -40,14 +41,15 @@ function navPage(dir, args) {
     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`);
+    console.log(`${g.id}: ${count(Object.keys(g.pages).length, 'page')}, ${count(g.specs.length, 'way')} to move, ${g.personas.length} ${g.personas.length === 1 ? 'kind' : 'kinds'} of user; ${count(problems.length, 'problem')}, ${count(found.length - problems.length, 'note')}`);
     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;
+    return {
+        code: args.includes('--strict') && (warnings.length > 0 || problems.length > 0) ? 2 : 0,
+        entry: { path: '', kind: 'nav', id: g.id, title: `${g.title}: where people go`, status: g.status, holds: 0, total: problems.length, warnings, error: null },
+    };
 }
-async function flowPage(dir, args) {
-    const out = resolve(flag(args, '--out') ?? join(dir, 'viz'));
+async function flowPage(dir, out, args) {
     const warnings = [];
     const warn = (m) => {
         if (!warnings.includes(m))
@@ -78,13 +80,51 @@ async function flowPage(dir, args) {
     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`);
+    console.log(`${g.flow.id}: ${count(Object.keys(g.flow.states).length, 'state')}, ${count(ex.configs.length, 'configuration')} from ${count(ex.starts, 'start')}, ${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;
+    return {
+        code: args.includes('--strict') && (violated.length > 0 || warnings.length > 0) ? 2 : 0,
+        entry: { path: '', kind: 'flow', id: g.flow.id, title: g.flow.title ?? humanize(g.flow.id), status: g.flow.status ?? null, holds: assertions.length - violated.length, total: assertions.length, warnings, error: null },
+    };
+}
+const isGraph = (dir) => existsSync(join(dir, 'flow.yaml')) || existsSync(join(dir, 'nav.yaml'));
+// 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) {
+    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 out = resolve(flag(args, '--out') ?? join(root, 'viz'));
+    const entries = [];
+    let broken = false;
+    let failing = false;
+    for (const dir of dirs) {
+        const path = relative(root, dir).split(sep).join('/');
+        const nav = !existsSync(join(dir, 'flow.yaml'));
+        try {
+            const { code, entry } = nav ? navPage(dir, join(out, path), args) : await flowPage(dir, join(out, path), args);
+            entries.push({ ...entry, path });
+            failing ||= code !== 0;
+        }
+        catch (err) {
+            if (!(err instanceof GraphError || err instanceof ModelError || err instanceof KitError || (err instanceof Error && err.name === 'YAMLParseError')))
+                throw err;
+            broken = true;
+            const message = err.message.split('\n')[0].replace(/:$/, '');
+            console.error(`error: ${path}: ${message}`);
+            entries.push({ path, kind: nav ? 'nav' : 'flow', id: null, title: path, status: null, holds: 0, total: 0, warnings: [], error: message });
+        }
+    }
+    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;
 }
 async function main() {
     const args = process.argv.slice(2);
@@ -100,7 +140,16 @@ async function main() {
             console.error(USAGE);
             return 1;
         }
-        return existsSync(join(dir, 'flow.yaml')) ? flowPage(dir, rest) : navPage(dir, rest);
+        if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+            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;
     }
     console.error(USAGE);
     return args.length === 0 || args.includes('--help') ? 0 : 1;

package/dist/index-page.js

@@ -0,0 +1,50 @@
+// The index of `page` on a folder of graphs: one row per graph, grouped by the folder it sits in, with what its check
+// found and a link to its page.
+import { CSS } from './html.js';
+import { count } from './check.js';
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const INDEX_CSS = `
+.groups h2 { font-size: 18px; margin: 32px 0 10px; } .groups table { table-layout: fixed; } .groups col.check { width: 9em; }
+.groups a { color: var(--accent); } .groups td { overflow-wrap: anywhere; }
+.meta { margin-top: 2px; } .meta .tag { margin-left: 6px; } .warn { margin-top: 6px; color: var(--muted); font-size: 14px; } .warn ul { margin: 4px 0 0; padding-left: 18px; }
+`;
+function stateCell(e) {
+    if (e.error !== null)
+        return `<span class="bad">cannot be loaded</span>`;
+    if (e.kind === 'nav')
+        return `<span class="${e.total === 0 ? 'ok' : 'bad'}">${esc(count(e.total, 'problem'))}</span>`;
+    if (e.total === 0)
+        return '<span class="muted">no guarantees</span>';
+    return e.holds === e.total ? `<span class="ok">${e.holds}/${e.total} hold</span>` : `<span class="bad">${e.total - e.holds} of ${e.total} broken</span>`;
+}
+// root: the indexed folder's name, which also heads the graphs that sit right in it
+export function renderIndexPage(root, entries) {
+    const out = [];
+    const failing = entries.filter((e) => e.error !== null || (e.kind === 'flow' ? e.holds < e.total : e.total > 0));
+    const flows = entries.filter((e) => e.kind === 'flow').length;
+    const navs = entries.length - flows;
+    out.push('<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">');
+    out.push(`<title>All graphs</title><style>${CSS}${INDEX_CSS}</style></head><body><main>`);
+    out.push(`<p class="eyebrow"><span class="mono">${esc(root)}/</span> · delurio-graph/0</p><h1>All graphs</h1>`);
+    const kinds = [flows > 0 ? count(flows, 'flow') : '', navs > 0 ? count(navs, 'navigation graph') : ''].filter((s) => s !== '').join(' and ');
+    out.push(`<p class="lede">${esc(kinds)}. ${failing.length === 0 ? 'Every guarantee holds and nothing blocks anyone.' : `${esc(count(failing.length, 'graph'))} need${failing.length === 1 ? 's' : ''} a look: marked in red below.`}</p>`);
+    const groups = new Map();
+    for (const e of entries) {
+        const slash = e.path.lastIndexOf('/');
+        const folder = slash < 0 ? root : e.path.slice(0, slash);
+        groups.set(folder, [...(groups.get(folder) ?? []), e]);
+    }
+    out.push('<div class="groups">');
+    for (const [folder, rows] of groups) {
+        out.push(`<h2>${esc(folder)}</h2><div class="scroll"><table><colgroup><col><col class="check"></colgroup><thead><tr><th>Graph</th><th>Check</th></tr></thead><tbody>`);
+        for (const e of rows) {
+            const name = e.error !== null ? esc(e.title) : `<a href="${esc(e.path)}/index.html">${esc(e.title)}</a>`;
+            const meta = e.id === null ? '' : `<div class="meta"><span class="mono muted">${esc(e.id)}</span>${e.status === null ? '' : `<span class="tag">${esc(e.status)}</span>`}</div>`;
+            const warn = e.error !== null ? `<div class="warn">${esc(e.error)}</div>` : e.warnings.length === 0 ? '' : `<div class="warn">${esc(count(e.warnings.length, 'warning'))}<ul>${e.warnings.map((w) => `<li>${esc(w)}</li>`).join('')}</ul></div>`;
+            out.push(`<tr><td>${name}${meta}${warn}</td><td class="state">${stateCell(e)}</td></tr>`);
+        }
+        out.push('</tbody></table></div>');
+    }
+    out.push('</div></main></body></html>');
+    return out.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delurio/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",