htmlboard 0.4.0 → 0.5.0

package/src/catalog.js

@@ -0,0 +1,449 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { COMPONENTS_FOLDER, isPage, isTagName } from './components.js';
+import { attributes, scanDesigns } from './designs.js';
+
+// The catalog: what the designs in a folder share, read from the files every time, so it is never
+// out of date. It describes whatever the project has and asks for none of it:
+//
+//   - the stylesheets the designs link, whatever their name or folder (and the ones at the top of
+//     the folder, linked or not yet), with each local one's variables, classes, @keyframes and fonts;
+//   - the scripts the designs load;
+//   - the components in components/, with their attributes, slots, example and where they're used.
+//
+// As text it takes a few lines (`htmlboard catalog`), so an agent learns what exists without
+// reading every file.
+
+const WIDTH = 100; // the text wraps here
+const LONGEST_VALUE = 120; // a variable's value is cut after this many characters
+const MOST_ITEMS = 200; // a stylesheet's classes or variables shown; the rest are counted
+const MOST_NAMED = 3; // designs named; more are counted
+
+const byName = (a, b) => a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' });
+
+function read(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------- CSS
+
+/** Split `text` at `separator`, except inside strings, parentheses and brackets */
+function splitTopLevel(text, separator) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (quote) {
+      if (char === '\\') i++;
+      else if (char === quote || char === '\n') quote = null;
+    } else if (char === '"' || char === "'") quote = char;
+    else if (char === '(' || char === '[') depth++;
+    else if ((char === ')' || char === ']') && depth) depth--;
+    else if (char === separator && !depth) {
+      parts.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+/**
+ * A stylesheet as a tree of rules, enough to read what it defines: each rule's prelude (a selector
+ * or an at-rule), the text of its own declarations, and the rules inside it. Comments are dropped.
+ */
+function parseCss(css) {
+  const root = { prelude: '', text: '', rules: [] };
+  const open = [root];
+  let text = '';
+  let quote = null;
+  for (let i = 0; i < css.length; i++) {
+    const char = css[i];
+    if (quote) {
+      text += char;
+      if (char === '\\') text += css[++i] ?? '';
+      else if (char === quote || char === '\n') quote = null;
+    } else if (char === '/' && css[i + 1] === '*') {
+      const end = css.indexOf('*/', i + 2);
+      i = end < 0 ? css.length : end + 1;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      text += char;
+    } else if (char === '{') {
+      // The declarations before a nested rule end with ";", then comes its prelude
+      const parts = splitTopLevel(text, ';');
+      const rule = { prelude: parts.pop().trim(), text: '', rules: [] };
+      open.at(-1).text += parts.map((part) => `${part};`).join('');
+      open.at(-1).rules.push(rule);
+      open.push(rule);
+      text = '';
+    } else if (char === '}') {
+      open.at(-1).text += text;
+      text = '';
+      if (open.length > 1) open.pop();
+    } else {
+      text += char;
+    }
+  }
+  open.at(-1).text += text;
+  return root;
+}
+
+const IMPORT = /^@import\s+(?:url\(\s*(?:"([^"]*)"|'([^']*)'|([^)\s]*))\s*\)|"([^"]*)"|'([^']*)')/i;
+
+/** The URLs a stylesheet @imports */
+function importsOf(tree) {
+  return splitTopLevel(tree.text, ';')
+    .map((statement) => statement.trim().match(IMPORT))
+    .filter(Boolean)
+    .map((match) => match.slice(1).find((value) => value !== undefined));
+}
+
+/** The class names in a selector, not counting its strings and attribute selectors */
+function classesOf(selector) {
+  const bare = selector.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g, '').replace(/\[[^\]]*\]/g, '');
+  return [...bare.matchAll(/\.(-?(?:[_a-zA-Z\u0080-\uFFFF]|\\.)(?:[\w\u0080-\uFFFF-]|\\.)*)/g)].map((match) => match[1]);
+}
+
+/** A nested rule's selector, written out (`&` is the rule around it) */
+function nest(outer, inner) {
+  const scope = splitTopLevel(outer, ',').length > 1 ? `:is(${outer})` : outer;
+  return splitTopLevel(inner, ',')
+    .map((part) => part.trim())
+    .map((part) => (part.includes('&') ? part.replaceAll('&', scope) : `${scope} ${part}`))
+    .join(', ');
+}
+
+/** At-rules that hold rules for the page; the others (@keyframes, @font-face, @page…) don't */
+const GROUPING_RULES = new Set(['media', 'supports', 'layer', 'container', 'scope', 'starting-style', 'document']);
+
+const unquote = (text) => text.trim().replace(/^(["'])(.*)\1$/, '$2');
+
+/**
+ * What a stylesheet defines: its variables (with the selector that declares them), its classes,
+ * @keyframes and font families, and what it @imports.
+ */
+function readStylesheet(css) {
+  const tree = parseCss(css);
+  const variables = new Map(); // where → Map(name → value)
+  const classes = new Set();
+  const keyframes = new Set();
+  const fonts = new Set();
+  const declare = (where, text) => {
+    for (const declaration of splitTopLevel(text, ';')) {
+      const match = declaration.match(/^\s*(--[^:\s]+)\s*:([\s\S]*)$/);
+      if (!match) continue;
+      if (!variables.has(where)) variables.set(where, new Map());
+      variables.get(where).set(match[1], match[2].replace(/\s+/g, ' ').trim());
+    }
+  };
+  const walk = (rules, at, selector) => {
+    for (const { prelude, text, rules: inner } of rules) {
+      if (prelude.startsWith('@')) {
+        const name = prelude.match(/^@(?:-[a-z]+-)?([\w-]+)/i)?.[1].toLowerCase();
+        if (name === 'keyframes') keyframes.add(unquote(prelude.replace(/^@[\w-]+/, '')));
+        else if (name === 'font-face') {
+          const family = splitTopLevel(text, ';').map((d) => d.match(/^\s*font-family\s*:([\s\S]*)$/i)?.[1]).find(Boolean);
+          if (family) fonts.add(unquote(family));
+        } else if (GROUPING_RULES.has(name)) {
+          const where = at ? `${at} ${prelude}` : prelude;
+          if (selector) declare(`${where} ${selector}`, text);
+          walk(inner, where, selector);
+        }
+      } else if (prelude) {
+        const resolved = selector ? nest(selector, prelude) : prelude;
+        for (const name of classesOf(prelude)) classes.add(name);
+        declare(at ? `${at} ${resolved}` : resolved, text);
+        walk(inner, at, resolved);
+      }
+    }
+  };
+  walk(tree.rules, '', '');
+  return {
+    variables: [...variables].flatMap(([where, names]) => [...names].map(([name, value]) => ({ where, name, value }))),
+    classes: [...classes],
+    keyframes: [...keyframes],
+    fonts: [...fonts],
+    imports: importsOf(tree)
+  };
+}
+
+// ---------------------------------------------------------------- pages and components
+
+/** What a page or a component loads: its <link rel="stylesheet">s, <script src>s and <style> @imports */
+function loads(html) {
+  html = html.replace(/<!--[\s\S]*?-->/g, '');
+  const stylesheets = [];
+  const scripts = [];
+  const tags = html.replace(/(<(script|style)\b[^>]*>)[\s\S]*?<\/\2\s*>/gi, '$1');
+  for (const [tag, name] of tags.matchAll(/<(link|script)\b[^>]*>/gi)) {
+    const attrs = attributes(tag);
+    if (name.toLowerCase() === 'link' && /\bstylesheet\b/i.test(attrs.rel || '') && attrs.href) stylesheets.push(attrs.href);
+    else if (name.toLowerCase() === 'script' && attrs.src) scripts.push(attrs.src);
+  }
+  for (const [, css] of html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)) stylesheets.push(...importsOf(parseCss(css)));
+  return { stylesheets, scripts };
+}
+
+const ATTRIBUTE_SELECTOR = /\[\s*([\w-]+)\s*(?:[~|^$*]?=\s*(?:"([^"]*)"|'([^']*)'|([^\s\]]+))(?:\s+[is])?)?\s*\]/gi;
+
+/**
+ * How a component is used, from its file: its attributes (the {{name}}s in its markup, the ones its
+ * script reads, and the ones its CSS styles on the element: `&[positive]`, `&[size="lg"]`), its slots
+ * and the example it starts with. And its markup, to find the components it uses.
+ */
+function readComponent(source) {
+  const example = source.match(/^\s*<!--([\s\S]*?)-->/)?.[1].replace(/\s+/g, ' ').trim() || null;
+  const css = [...source.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)].map((match) => match[1]).join('\n')
+    .replace(/\/\*[\s\S]*?\*\//g, '');
+  const code = [...source.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi)]
+    .filter(([, attrs]) => !/\bsrc\s*=/i.test(attrs)).map((match) => match[2]).join('\n');
+  const markup = source.replace(/<!--[\s\S]*?-->/g, '').replace(/<(style|script)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, '');
+  const found = new Map(); // name → { text, flag, values }
+  const add = (name, kind, value) => {
+    if (!found.has(name)) found.set(name, { values: new Set() });
+    if (value !== undefined) found.get(name).values.add(value);
+    else found.get(name)[kind] = true;
+  };
+  for (const [, name] of markup.matchAll(/\{\{\s*([^{}\s]+)\s*\}\}/g)) add(name, 'text');
+  for (const [, verb, , name] of code.matchAll(/\b(get|has)Attribute\(\s*(['"`])([^'"`]+)\2/g)) add(name, verb === 'has' ? 'flag' : 'text');
+  for (const [, name] of code.matchAll(/\bdataset\.([A-Za-z_$][\w$]*)/g)) add(`data-${name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`, 'text');
+  for (const [, selectors] of css.matchAll(/&((?:\[[^\]]*\])+)/g)) {
+    for (const [, name, ...values] of selectors.matchAll(ATTRIBUTE_SELECTOR)) add(name, 'flag', values.find((v) => v !== undefined));
+  }
+  for (const [, name] of css.matchAll(/&:not\(\s*\[\s*([\w-]+)\s*\]/g)) add(name, 'flag');
+  const slots = [...markup.matchAll(/<slot\b[^>]*>/gi)].map(([tag]) => attributes(tag).name || '');
+  return {
+    attributes: [...found].map(([name, { text, values }]) => {
+      if (values.size) return { name, values: [...values] };
+      return text ? { name } : { name, flag: true };
+    }),
+    slots: [...new Set(slots)],
+    example,
+    markup
+  };
+}
+
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// ---------------------------------------------------------------- the catalog
+
+/**
+ * What the designs in a folder share: the stylesheets and scripts they load (with what each local
+ * stylesheet defines) and the components in its components/ (with how each is used, and where).
+ *
+ * @param {string} [dir=process.cwd()] The designs folder
+ * @param {object} [options]
+ * @param {string} [options.root] The folder the server serves from (`--root`), for links that
+ *   start with "/" (default: the designs folder)
+ * @returns {{dir: string, designs: string[], stylesheets: object[], scripts: object[], components: object[]}}
+ *   Paths are from the designs folder. Each stylesheet, script and component has its `users`:
+ *   `{ design }` (a file), `{ component }` (a tag) or `{ stylesheet }` (one that @imports it).
+ */
+export function buildCatalog(dir = process.cwd(), { root } = {}) {
+  const designsDir = path.resolve(dir);
+  if (!fs.statSync(designsDir, { throwIfNoEntry: false })?.isDirectory()) throw new Error(`There is no folder ${dir}`);
+  const rootDir = root ? path.resolve(root) : designsDir;
+  const fromDesigns = (file) => path.relative(designsDir, file).split(path.sep).join('/');
+
+  // Where a link points: a URL as it is, a file by its path from the designs folder
+  const locate = (href, from) => {
+    href = href.trim();
+    if (!href || /^(#|data:|about:|javascript:)/i.test(href)) return null;
+    if (/^([a-z][a-z\d+.-]*:|\/\/)/i.test(href)) return { key: href, path: href, external: true };
+    let clean = href.replace(/[?#][\s\S]*$/, '');
+    try {
+      clean = decodeURIComponent(clean);
+    } catch {
+      // as it is
+    }
+    const file = clean.startsWith('/') ? path.join(rootDir, clean) : path.resolve(path.dirname(from), clean);
+    return { key: file, path: fromDesigns(file), file };
+  };
+  const addUser = (entry, user) => {
+    const [[kind, name]] = Object.entries(user);
+    if (!entry.users.some((other) => other[kind] === name)) entry.users.push(user);
+  };
+
+  const stylesheets = new Map(); // URL or file → what it is and who loads it
+  const addStylesheet = (where, user) => {
+    if (!where) return;
+    let entry = stylesheets.get(where.key);
+    if (!entry) {
+      entry = { path: where.path, users: [] };
+      stylesheets.set(where.key, entry);
+      const css = where.external ? null : read(where.file);
+      if (where.external) entry.external = true;
+      else if (css === null) entry.missing = true;
+      else {
+        const { imports, ...defines } = readStylesheet(css);
+        Object.assign(entry, defines);
+        for (const href of imports) addStylesheet(locate(href, where.file), { stylesheet: entry.path });
+      }
+    }
+    if (user) addUser(entry, user);
+  };
+  const scripts = new Map();
+  const addScript = (where, user) => {
+    if (!where) return;
+    if (!scripts.has(where.key)) {
+      const entry = { path: where.path, users: [] };
+      if (where.external) entry.external = true;
+      else if (!fs.existsSync(where.file)) entry.missing = true;
+      scripts.set(where.key, entry);
+    }
+    addUser(scripts.get(where.key), user);
+  };
+
+  const designs = scanDesigns(designsDir).filter((design) => !design.variantOf).map((design) => design.file);
+  const pages = designs.map((file) => {
+    const full = path.join(designsDir, file);
+    const html = (read(full) ?? '').replace(/<!--[\s\S]*?-->/g, '');
+    const { stylesheets: hrefs, scripts: srcs } = loads(html);
+    for (const href of hrefs) addStylesheet(locate(href, full), { design: file });
+    for (const src of srcs) addScript(locate(src, full), { design: file });
+    return [file, html];
+  });
+
+  const components = [];
+  const markups = new Map();
+  const componentsDir = path.join(designsDir, COMPONENTS_FOLDER);
+  let names = [];
+  try {
+    names = fs.readdirSync(componentsDir).filter((name) => name.endsWith('.html') && isTagName(name.slice(0, -5))).sort(byName);
+  } catch {
+    // no components
+  }
+  for (const name of names) {
+    const full = path.join(componentsDir, name);
+    const source = read(full);
+    if (source === null || isPage(source)) continue; // a whole page is a design
+    const tag = name.slice(0, -5);
+    const { markup, ...usage } = readComponent(source);
+    components.push({ tag, file: `${COMPONENTS_FOLDER}/${name}`, ...usage, users: [] });
+    markups.set(tag, markup);
+    const { stylesheets: hrefs, scripts: srcs } = loads(source);
+    for (const href of hrefs) addStylesheet(locate(href, full), { component: tag });
+    for (const src of srcs) addScript(locate(src, full), { component: tag });
+  }
+  for (const component of components) {
+    const used = new RegExp(`<${escapeRegExp(component.tag)}[\\s/>]`, 'i');
+    for (const [file, html] of pages) if (used.test(html)) component.users.push({ design: file });
+    for (const [tag, markup] of markups) if (tag !== component.tag && used.test(markup)) component.users.push({ component: tag });
+  }
+
+  // The stylesheets at the top of the folder are there to be shared, even before a design links them
+  const top = fs.readdirSync(designsDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && /\.css$/i.test(entry.name))
+    .map((entry) => entry.name)
+    .sort(byName);
+  for (const name of top) addStylesheet({ key: path.join(designsDir, name), path: name, file: path.join(designsDir, name) });
+
+  return {
+    dir: designsDir,
+    designs,
+    stylesheets: [...stylesheets.values()],
+    scripts: [...scripts.values()],
+    components
+  };
+}
+
+// ---------------------------------------------------------------- as text
+
+/** `head`, the items after it (the first MOST_ITEMS) and `end`, wrapped at WIDTH, indented under head */
+function wrap(head, items, end) {
+  if (items.length > MOST_ITEMS) items = [...items.slice(0, MOST_ITEMS), `… and ${items.length - MOST_ITEMS} more`];
+  if (end) items = [...items, end];
+  const indent = ' '.repeat(head.length - head.trimStart().length + 2);
+  const lines = [];
+  let line = head;
+  let count = 0;
+  for (const item of items) {
+    if (count && line.length + 1 + item.length > WIDTH) {
+      lines.push(line);
+      line = indent + item;
+    } else {
+      line += ` ${item}`;
+    }
+    count++;
+  }
+  lines.push(line);
+  return lines;
+}
+
+/** Who loads or uses something: the designs (named when few), components and stylesheets */
+function describeUsers(users, total, none) {
+  if (!users.length) return none;
+  const parts = [];
+  const designs = users.filter((user) => user.design).map((user) => user.design);
+  if (designs.length === total && total > 1) parts.push(`all ${total} designs`);
+  else if (designs.length > MOST_NAMED) parts.push(`${designs.length} designs`);
+  else if (designs.length) parts.push(`${designs.length} design${designs.length === 1 ? '' : 's'}: ${designs.join(', ')}`);
+  const components = users.filter((user) => user.component).map((user) => `<${user.component}>`);
+  if (components.length) parts.push(components.join(' '));
+  const sheets = users.filter((user) => user.stylesheet).map((user) => user.stylesheet);
+  if (sheets.length) parts.push(`imported by ${sheets.join(', ')}`);
+  return parts.join('; ');
+}
+
+const cut = (value) => (value.length > LONGEST_VALUE ? `${value.slice(0, LONGEST_VALUE - 1)}…` : value);
+
+/** How a component is written: its tag with its attributes, then what goes inside */
+function signature({ tag, attributes: attrs, slots }) {
+  const names = attrs.map(({ name, values, flag }) => (values ? `${name}=${values.join('|')}` : flag ? `[${name}]` : name));
+  const inside = slots.map((slot) => (slot ? `slot="${slot}"` : 'children'));
+  return `<${[tag, ...names].join(' ')}>${inside.length ? ` + ${inside.join(', ')}` : ''}`;
+}
+
+/**
+ * The catalog as text, a few lines per stylesheet, script and component (what `htmlboard catalog`
+ * prints).
+ *
+ * @param {ReturnType<typeof buildCatalog>} catalog
+ * @param {object} [options]
+ * @param {string} [options.name] How to call the designs folder (default: its full path)
+ */
+export function formatCatalog(catalog, { name = catalog.dir } = {}) {
+  const total = catalog.designs.length;
+  const lines = [`${name}: ${total ? `${total} design${total === 1 ? '' : 's'}` : 'no designs yet'}.`];
+  if (catalog.stylesheets.length || catalog.scripts.length || catalog.components.length) {
+    lines[0] += ' Paths below are from this folder.';
+  } else if (total) {
+    lines.push('', 'Nothing shared yet: no stylesheet, script or component.');
+  }
+  if (catalog.stylesheets.length) {
+    lines.push('', 'Stylesheets');
+    for (const sheet of catalog.stylesheets) {
+      lines.push(`  ${sheet.path}${sheet.missing ? ' (not found)' : ''} · ${describeUsers(sheet.users, total, 'not linked yet')}`);
+      const groups = new Map();
+      for (const { where, name: variable, value } of sheet.variables ?? []) {
+        if (!groups.has(where)) groups.set(where, []);
+        groups.get(where).push(`${variable}: ${cut(value)};`);
+      }
+      for (const [where, declarations] of groups) lines.push(...wrap(`    ${where} {`, declarations, '}'));
+      if (sheet.classes?.length) lines.push(...wrap('    classes', sheet.classes.map((className) => `.${className}`)));
+      if (sheet.keyframes?.length) lines.push(...wrap('    @keyframes', sheet.keyframes.map((n, i, all) => (i < all.length - 1 ? `${n},` : n))));
+      if (sheet.fonts?.length) lines.push(...wrap('    @font-face', sheet.fonts.map((n, i, all) => (i < all.length - 1 ? `${n},` : n))));
+    }
+  }
+  if (catalog.scripts.length) {
+    lines.push('', 'Scripts');
+    for (const script of catalog.scripts) {
+      lines.push(`  ${script.path}${script.missing ? ' (not found)' : ''} · ${describeUsers(script.users, total)}`);
+    }
+  }
+  if (catalog.components.length) {
+    lines.push('', `Components (${COMPONENTS_FOLDER}/)`);
+    for (const component of catalog.components) {
+      lines.push(`  ${signature(component)} · ${describeUsers(component.users, total, 'not used yet')}`);
+      if (component.example) lines.push(`    e.g. ${component.example}`);
+    }
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/check.js

@@ -0,0 +1,173 @@
+import http from 'node:http';
+import path from 'node:path';
+
+// `htmlboard check`: the canvas running for a folder, open in a browser, loads its designs and says
+// what went wrong in each (see client/check.js); this finds that canvas, asks it, and puts the
+// answer in a few lines of text.
+
+/** Where htmlboard listens unless told otherwise: 3000, or the next free port */
+const PORTS = Array.from({ length: 21 }, (_, i) => 3000 + i);
+
+/** A problem the check couldn't get past (no canvas running, none open in a browser): exit code 2 */
+export class CheckError extends Error {}
+
+function get(url, { timeout = 0 } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = http.get(url, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString('utf8') }));
+      res.on('error', reject);
+    });
+    req.on('error', reject);
+    if (timeout) req.setTimeout(timeout, () => req.destroy(new Error('timeout')));
+  });
+}
+
+const isInside = (base, target) => {
+  const rel = path.relative(base, target);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+};
+
+/** The htmlboard servers listening on these ports, each with its designs folder (dir) and root */
+async function findCanvases(ports) {
+  const found = await Promise.all(ports.map(async (port) => {
+    try {
+      const { status, body } = await get(`http://127.0.0.1:${port}/api/health`, { timeout: 1500 });
+      const health = JSON.parse(body);
+      return status === 200 && health.status === 'ok' && health.dir ? { ...health, port, url: `http://localhost:${port}` } : null;
+    } catch {
+      return null;
+    }
+  }));
+  return found.filter(Boolean);
+}
+
+/**
+ * Check designs with the canvas that shows them: a designs folder, a folder in it, or a design's
+ * file (default: all the designs of the canvas found). The canvas must be open in a browser, where
+ * the check runs.
+ *
+ * @param {string} [target] A path; without one, the canvas's whole folder (looked for from the current one)
+ * @param {object} [options]
+ * @param {number} [options.port] The canvas's port (default: looked for on 3000 to 3020)
+ * @returns {Promise<{canvas: object, report: object}>} The canvas (its url, dir, root) and its report
+ */
+export async function runCheck(target, { port } = {}) {
+  const full = path.resolve(target || process.cwd());
+  const canvases = await findCanvases(port ? [Number(port)] : PORTS);
+  // The canvas whose folder holds the target (the deepest one), else the only one inside it
+  const holding = canvases.filter((canvas) => isInside(canvas.dir, full)).sort((a, b) => b.dir.length - a.dir.length);
+  const within = canvases.filter((canvas) => isInside(full, canvas.dir));
+  let canvas = holding[0] ?? (within.length === 1 ? within[0] : null);
+  if (!canvas && port && !target && canvases.length) canvas = canvases[0];
+  if (!canvas) {
+    const shown = path.relative(process.cwd(), full) || '.';
+    if (within.length > 1) {
+      throw new CheckError(`Several canvases show folders in ${shown}: ${within.map((c) => `${path.relative(process.cwd(), c.dir)} (${c.url})`).join(', ')}. Say which one.`);
+    }
+    if (port) throw new CheckError(canvases.length ? `The canvas at ${canvases[0].url} shows ${canvases[0].dir}, not ${shown}.` : `No htmlboard is running at http://localhost:${port}.`);
+    throw new CheckError(`No htmlboard canvas is running for ${shown}. Start it (npx htmlboard <designs folder>) and open it in a browser.`);
+  }
+  const only = holding[0] === canvas && full !== canvas.dir ? path.relative(canvas.dir, full).split(path.sep).join('/') : '';
+  let answer;
+  try {
+    const { status, body } = await get(`http://127.0.0.1:${canvas.port}/api/check${only ? `?only=${encodeURIComponent(only)}` : ''}`);
+    answer = { status, ...JSON.parse(body) };
+  } catch (error) {
+    throw new CheckError(`The canvas at ${canvas.url} didn't answer (${error.message}).`);
+  }
+  if (answer.status === 409) {
+    throw new CheckError(`The canvas at ${canvas.url} isn't open in a browser, and the check runs there. Open it and try again.`);
+  }
+  if (answer.status !== 200) throw new CheckError(`${answer.error || `The canvas answered ${answer.status}`}.`);
+  const { status, ...report } = answer;
+  return { canvas, report };
+}
+
+const LEVELS = ['error', 'layout', 'note'];
+// The page as a whole first, then its scripts, its components and its files
+const KINDS = ['blank', 'timeout', 'check', 'script', 'console', 'component', 'missing', 'load', 'font', 'beyond', 'cut', 'spill', 'below'];
+
+/** Whether the report has something to fix (notes aside) */
+export const hasProblems = (report) => report.designs.some((design) => design.problems.some((problem) => problem.level !== 'note'));
+
+/**
+ * The report as text: the designs with problems, each followed by its problems (errors, then
+ * layout, then notes), with paths from the designs folder.
+ *
+ * @param {object} report What runCheck returns as `report` (or GET /api/check answers)
+ * @param {object} [options]
+ * @param {string} [options.name] How to call the designs folder (default: its path)
+ * @param {string} [options.url] The canvas's address, to say where the check ran
+ */
+export function formatReport(report, { name = report.dir, url } = {}) {
+  const prefix = path.relative(report.root, report.dir).split(path.sep).join('/');
+  // A path from the server's root ("/design/app.js"), from the designs folder instead ("app.js")
+  const show = (file) => {
+    const bare = String(file).replace(/^\/+/, '');
+    return prefix ? path.posix.relative(prefix, bare) : bare;
+  };
+  const designs = report.designs;
+  const failing = designs.filter((design) => design.problems.some((problem) => problem.level !== 'note')).length;
+  const noted = designs.filter((design) => design.problems.length && design.problems.every((problem) => problem.level === 'note')).length;
+  const lines = [`Checked ${count(designs.length, 'design')} in ${name}${url ? ` (the canvas at ${url})` : ''}: ${
+    failing ? `${failing} with problems` : 'no problems found'}${noted ? `, ${noted} with notes` : ''}.`];
+  const order = (problem) => LEVELS.indexOf(problem.level) * KINDS.length + KINDS.indexOf(problem.kind);
+  for (const design of designs.filter((d) => d.problems.length)) {
+    lines.push('', `${show(design.file)}${design.title ? ` · ${design.title}` : ''}`);
+    for (const problem of [...design.problems].sort((a, b) => order(a) - order(b))) {
+      lines.push(`  ${problem.level.padEnd(6)} ${describe(problem, show)}`);
+    }
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/** A problem in words (see client/check.js for what each kind holds) */
+function describe(problem, show) {
+  const times = problem.count > 1 ? ` (${problem.count} times)` : '';
+  const file = problem.path ? show(problem.path) : problem.url;
+  switch (problem.kind) {
+    case 'script': {
+      const source = problem.source ? (problem.source.startsWith('/') ? show(problem.source) : problem.source) : '';
+      return `${problem.message}${source ? ` (${source}${problem.line ? `:${problem.line}` : ''})` : ''}${times}`;
+    }
+    case 'console':
+      return `console.error: ${problem.message}${times}`;
+    case 'missing':
+      return `missing file: ${file}${problem.tag ? ` (<${problem.tag}>)` : ''}${times}`;
+    case 'load':
+      return file ? `<${problem.tag}> couldn't load ${file}${times}` : `<${problem.tag}> has nothing to load${times}`;
+    case 'font':
+      return `font "${problem.family}" didn't load`;
+    case 'component':
+      if (problem.loader === false) return `<${problem.tag}> isn't built: the page doesn't load components.js`;
+      if (problem.found === false) return `<${problem.tag}> isn't built: there is no ${file}`;
+      return `<${problem.tag}> isn't built, though ${file || 'its file'} is there (see the errors)`;
+    case 'blank':
+      return 'the page shows nothing';
+    case 'timeout':
+      return `still loading after ${problem.seconds} s, checked as it was`;
+    case 'beyond':
+      return `cut at the right edge (the frame is ${problem.frame} px wide): ${problem.elements
+        .map((element) => `${element.selector} reaches ${element.right}`).join(', ')}${problem.more ? `, and ${problem.more} more` : ''}`;
+    case 'cut':
+      if (problem.more) return `and ${moreBoxes(problem.more)} cut text off`;
+      return `text cut off by ${problem.selector} (overflow: ${problem.overflow}): "${problem.text}"${problem.count > 1 ? ` and ${problem.count - 1} more` : ''}`;
+    case 'spill':
+      if (problem.more) return `and ${moreBoxes(problem.more)} with text spilling out`;
+      return `text spills out of ${problem.selector}: "${problem.text}"${problem.count > 1 ? ` and ${problem.count - 1} more` : ''}`;
+    case 'below':
+      return `content goes on below the frame, down to ${problem.bottom} px (the frame is ${problem.frame} px tall)`;
+    case 'check':
+      return `couldn't check it: ${problem.message}`;
+    default:
+      return JSON.stringify(problem);
+  }
+}
+
+function count(n, what) {
+  return `${n} ${what}${n === 1 ? '' : 's'}`;
+}
+
+const moreBoxes = (n) => `${n} more ${n === 1 ? 'box' : 'boxes'}`;