@luigisbox/luma 0.0.0-stage → 0.2.0

package/a11y/axe.mjs

@@ -0,0 +1,73 @@
+// axe-core in a Playwright page, shared by Luma's browser
+// tests and `yarn luma a11y` (a11y/run.mjs).
+//
+// axe-core is a pinned dependency injected from node_modules (no network,
+// no CDN). Scoped to Luma's own roots, so the host page's issues never fail
+// us; the same run with those roots excluded is the host's (informational).
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { WCAG_TAGS } from './wcag.mjs';
+
+/** Luma's own subtrees: listings, recommenders, the dropdown (a shadow host or light DOM). */
+export const ROOTS = ['lbx-search', 'lbx-plp', 'lbx-reco', 'lbx-reco-pop', '[data-lbx="ac-overlay"]'];
+
+let source = '';
+const axeSource = () => (source ||= readFileSync(createRequire(import.meta.url).resolve('axe-core/axe.min.js'), 'utf8'));
+
+/**
+ * @typedef {{ target: unknown[], html: string, failureSummary?: string }} AxeNode
+ * @typedef {{ id: string, impact: string | null, help: string, helpUrl: string, tags: string[], nodes: AxeNode[] }} AxeRule
+ * @typedef {{ violations: AxeRule[], incomplete: AxeRule[], passes: { id: string, tags: string[] }[] }} AxeResult
+ */
+
+/**
+ * axe-core over `include` (selectors; a shadow host includes its shadow
+ * tree), or over the whole document minus `exclude`. `rules` turns rules on
+ * or off for this run. Throws when none of `include` is on the page.
+ * @param {import('playwright-core').Page} page
+ * @param {{ include?: string[], exclude?: string[], rules?: Record<string, boolean>, tags?: string[] }} opts
+ * @returns {Promise<AxeResult>}
+ */
+export const runAxe = async (page, { include, exclude = [], rules = {}, tags = WCAG_TAGS }) => {
+  if (!(await page.evaluate(() => !!(/** @type {any} */ (window).axe)))) await page.addScriptTag({ content: axeSource() });
+  return page.evaluate(
+    async ({ include, exclude, tags, rules }) => {
+      const a = /** @type {any} */ (window).axe;
+      /** @type {any} */
+      let context;
+      if (include) {
+        const present = include.filter((s) => document.querySelector(s));
+        if (!present.length) throw new Error(`axe: none of ${include.join(', ')} is on the page`);
+        context = { include: present.map((s) => [s]) };
+      } else {
+        const out = exclude.filter((s) => document.querySelector(s));
+        context = out.length ? { exclude: out.map((s) => [s]) } : document;
+      }
+      // A listing's re-render fades its list in (and back from its dim): text
+      // mid-fade is paler than it will be, colour-contrast would read that.
+      // Ours only (a host's endless animation would hold this); at most 2 s.
+      const fading = document.getAnimations().filter((an) => /** @type {any} */ (an.effect)?.target?.matches?.('[data-lbx-list]'));
+      await Promise.race([Promise.all(fading.map((an) => an.finished.catch(() => {}))), new Promise((r) => setTimeout(r, 2000))]);
+      const r = await a.run(context, {
+        runOnly: { type: 'tag', values: tags },
+        resultTypes: ['violations', 'incomplete'],
+        rules: Object.fromEntries(Object.entries(rules).map(([k, v]) => [k, { enabled: v }])),
+      });
+      /** @param {any} v */
+      const rule = (v) => ({
+        id: v.id,
+        impact: v.impact,
+        help: v.help,
+        helpUrl: v.helpUrl,
+        tags: v.tags,
+        nodes: v.nodes.map((/** @type {any} */ n) => ({ target: n.target, html: String(n.html).slice(0, 300), failureSummary: n.failureSummary })),
+      });
+      return {
+        violations: r.violations.map(rule),
+        incomplete: r.incomplete.map(rule),
+        passes: r.passes.map((/** @type {any} */ v) => ({ id: v.id, tags: v.tags })),
+      };
+    },
+    { include, exclude, tags, rules },
+  );
+};

package/a11y/report.mjs

@@ -0,0 +1,347 @@
+// What `yarn luma a11y` found, as a verdict per WCAG 2.2 success criterion: the
+// findings on Luma's nodes (they fail the run), the host page's own
+// (informational), axe's "needs review" items, and the criteria no automated
+// check can decide. Pure: no browser, no file system (the integration's files
+// are passed in for the template hints), so it is unit-tested offline
+// (Luma's own tests).
+import { ADVISORY, CHECK_SC, CRITERIA, DOC, FIX, bySc, scOfTags } from './wcag.mjs';
+
+/**
+ * @typedef {{ target: string, html: string, summary?: string, hint?: Hint | null }} Node
+ * @typedef {{ file: string, line: number, token: string }} Hint
+ * @typedef {{ widget: string, state: string, page: string }} Ctx
+ * @typedef {{ check: string, rule: string, sc: string[], impact: string, help: string, helpUrl?: string, fix: string,
+ *   advisory: boolean, widgets: string[], states: string[], pages: string[], nodes: Node[] }} Finding
+ *   (`states` as "widget: state")
+ * @typedef {{ rule: string, impact: string, help: string, helpUrl?: string, sc: string[], nodes: number, pages: string[] }} HostFinding
+ * @typedef {{ path: string, text: string }} SourceFile
+ */
+
+const IMPACT = { critical: 0, serious: 1, moderate: 2, minor: 3 };
+const rank = (i) => IMPACT[i] ?? 4;
+const uniq = (xs) => [...new Set(xs)];
+/** axe's target (a selector list, nested for shadow roots) as one readable selector. */
+export const targetOf = (t) => (Array.isArray(t) ? t.map((x) => (Array.isArray(x) ? x.join(' >>> ') : String(x))).join(' >>> ') : String(t));
+
+/** Collects the outcome of every check of a run. */
+export class Results {
+  constructor() {
+    /** @type {Map<string, Finding>} */
+    this.found = new Map();
+    /** @type {Map<string, Finding>} axe "needs review" (incomplete) on our nodes */
+    this.review = new Map();
+    /** @type {Map<string, HostFinding>} */
+    this.hostFound = new Map();
+    /** @type {Map<string, Set<string>>} SC -> states where a check of it ran */
+    this.covered = new Map();
+    /** @type {{ widget: string, state: string, page: string }[]} */
+    this.states = [];
+    /** @type {{ widget: string, reason: string }[]} */
+    this.skipped = [];
+    /** @type {string[]} */
+    this.notes = [];
+  }
+
+  /** @param {Ctx} ctx */
+  state(ctx) {
+    if (!this.states.some((s) => s.widget === ctx.widget && s.state === ctx.state && s.page === ctx.page)) this.states.push({ ...ctx });
+  }
+
+  /** @param {string[]} scs @param {Ctx} ctx */
+  cover(scs, ctx) {
+    this.state(ctx);
+    for (const sc of scs) {
+      if (!CRITERIA[sc]) continue;
+      if (!this.covered.has(sc)) this.covered.set(sc, new Set());
+      this.covered.get(sc).add(`${ctx.widget}: ${ctx.state}`);
+    }
+  }
+
+  /** One of the command's own checks passed. @param {string} check @param {Ctx} ctx */
+  pass(check, ctx) {
+    this.cover(CHECK_SC[check] ?? [], ctx);
+  }
+
+  /**
+   * One of the command's own checks failed, on `nodes` (or the widget as a whole).
+   * @param {string} check @param {Ctx} ctx @param {string} help
+   * @param {{ target?: string, html?: string, summary?: string }[]} [nodes]
+   */
+  fail(check, ctx, help, nodes = []) {
+    const sc = CHECK_SC[check] ?? [];
+    this.cover(sc, ctx);
+    this.add(this.found, {
+      check,
+      rule: check,
+      sc,
+      impact: ADVISORY.has(check) ? 'minor' : 'serious',
+      help,
+      fix: FIX[check] ?? '',
+      advisory: ADVISORY.has(check),
+      widgets: [ctx.widget],
+      states: [`${ctx.widget}: ${ctx.state}`],
+      pages: [ctx.page],
+      nodes: (nodes.length ? nodes : [{ target: ctx.widget }]).map((n) => ({ target: n.target ?? ctx.widget, html: n.html ?? '', summary: n.summary })),
+    });
+  }
+
+  /**
+   * axe on our roots in one state: violations are findings, incomplete are
+   * "needs review", passes cover their criteria.
+   * @param {import('./axe.mjs').AxeResult} r @param {Ctx} ctx
+   */
+  axe(r, ctx) {
+    this.state(ctx);
+    for (const p of r.passes) this.cover(scOfTags(p.tags), ctx);
+    for (const [list, into] of [[r.violations, this.found], [r.incomplete, this.review]]) {
+      for (const v of list) {
+        const sc = scOfTags(v.tags);
+        this.cover(sc, ctx);
+        if (!sc.length) continue; // best practice or AAA only: not this command's verdict
+        this.add(into, {
+          check: `axe:${v.id}`,
+          rule: v.id,
+          sc,
+          impact: v.impact ?? 'moderate',
+          help: v.help,
+          helpUrl: v.helpUrl,
+          fix: FIX[v.id] ?? '',
+          advisory: false,
+          widgets: [ctx.widget],
+          states: [`${ctx.widget}: ${ctx.state}`],
+          pages: [ctx.page],
+          nodes: v.nodes.map((n) => ({ target: targetOf(n.target), html: n.html, summary: n.failureSummary })),
+        });
+      }
+    }
+  }
+
+  /** axe on the host page (our roots excluded): informational. @param {import('./axe.mjs').AxeResult} r @param {string} page */
+  host(r, page) {
+    for (const v of r.violations) {
+      const sc = scOfTags(v.tags);
+      if (!sc.length) continue;
+      const h = this.hostFound.get(v.id);
+      if (h) {
+        h.nodes = Math.max(h.nodes, v.nodes.length);
+        h.pages = uniq([...h.pages, page]);
+      } else this.hostFound.set(v.id, { rule: v.id, impact: v.impact ?? 'moderate', help: v.help, helpUrl: v.helpUrl, sc, nodes: v.nodes.length, pages: [page] });
+    }
+  }
+
+  /** A widget the run could not exercise, and why. */
+  skip(widget, reason) {
+    this.skipped.push({ widget, reason });
+  }
+
+  note(text) {
+    this.notes.push(text);
+  }
+
+  /** Merges a finding into `into`: one per check, nodes merged by target, states and pages accumulated. @param {Map<string, Finding>} into @param {Finding} f */
+  add(into, f) {
+    const had = into.get(f.check);
+    if (!had) return void into.set(f.check, f);
+    had.widgets = uniq([...had.widgets, ...f.widgets]);
+    had.states = uniq([...had.states, ...f.states]);
+    had.pages = uniq([...had.pages, ...f.pages]);
+    if (rank(f.impact) < rank(had.impact)) had.impact = f.impact;
+    for (const n of f.nodes) if (!had.nodes.some((m) => m.target === n.target)) had.nodes.push(n);
+  }
+}
+
+/**
+ * Where a node's markup comes from in the integration: the file and line of
+ * the rarest class (or id, data-lbx-* attribute) of its start tag among the
+ * integration's templates and styles (templates win a tie). Null when none
+ * of its tokens is in any file (markup the framework or the host made).
+ * @param {Node} node @param {SourceFile[]} files @returns {Hint | null}
+ */
+export const hintFor = (node, files) => {
+  const tag = /^<[^>]*>/.exec(node.html ?? '')?.[0] ?? '';
+  const tokens = [];
+  for (const m of tag.matchAll(/\bclass\s*=\s*"([^"]*)"/g)) tokens.push(...m[1].split(/\s+/));
+  for (const m of tag.matchAll(/\b(data-lbx[\w-]*)/g)) tokens.push(m[1]);
+  // Luma's generic hooks and the state classes that every template shares are no clue to the file.
+  const words = uniq(tokens.filter((t) => t && t.length > 2 && !/^(active|selected|checked|disabled|open|hidden|show|is-\w+|data-lbx)$/.test(t) && !t.includes('${')));
+  if (!words.length) return null;
+  const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  let best = null;
+  for (const w of words) {
+    const re = new RegExp(`(^|[^\\w-])${esc(w)}($|[^\\w-])`);
+    const hits = [];
+    for (const f of files) {
+      const lines = f.text.split('\n');
+      for (let i = 0; i < lines.length; i++) if (re.test(lines[i])) hits.push({ file: f.path, line: i + 1 });
+    }
+    if (!hits.length) continue;
+    hits.sort((a, b) => Number(/\.css$/.test(a.file)) - Number(/\.css$/.test(b.file)));
+    if (!best || hits.length < best.n) best = { n: hits.length, file: hits[0].file, line: hits[0].line, token: w };
+  }
+  return best && { file: best.file, line: best.line, token: best.token };
+};
+
+/**
+ * The run's verdict per success criterion.
+ * @param {Results} r
+ * @param {{ files?: SourceFile[] }} [opts]
+ */
+export const summarize = (r, { files = [] } = {}) => {
+  const order = (a, b) => rank(a.impact) - rank(b.impact) || bySc(a.sc[0] ?? '9', b.sc[0] ?? '9');
+  /** @param {Finding} f @returns {Finding} */
+  const withHints = (f) => ({ ...f, nodes: f.nodes.map((n) => ({ ...n, hint: n.hint === undefined ? hintFor(n, files) : n.hint })) });
+  const findings = [...r.found.values()].map(withHints).sort(order);
+  const failing = findings.filter((f) => !f.advisory);
+  const advisories = findings.filter((f) => f.advisory);
+  const review = [...r.review.values()].map(withHints).sort(order);
+  const criteria = Object.entries(CRITERIA)
+    .map(([sc, c]) => {
+      const fails = failing.filter((f) => f.sc.includes(sc));
+      const states = [...(r.covered.get(sc) ?? [])];
+      const status = fails.length ? 'fail' : states.length ? 'pass' : c.auto ? 'not-applicable' : 'manual';
+      return { sc, ...c, status, findings: fails, states };
+    })
+    .sort((a, b) => bySc(a.sc, b.sc));
+  const exercised = uniq(r.states.map((s) => s.widget));
+  const verdict = failing.length ? 'fail' : exercised.length ? 'pass' : 'incomplete';
+  return {
+    verdict,
+    exitCode: verdict === 'pass' ? 0 : verdict === 'fail' ? 1 : 2,
+    criteria,
+    findings: failing,
+    advisories,
+    review,
+    host: [...r.hostFound.values()].sort((a, b) => rank(a.impact) - rank(b.impact)),
+    states: r.states,
+    exercised,
+    skipped: r.skipped,
+    notes: r.notes,
+  };
+};
+
+const C = { red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', dim: '\x1b[2m', bold: '\x1b[1m', off: '\x1b[0m' };
+
+/**
+ * The report for a terminal (or a CI log).
+ * @param {ReturnType<typeof summarize>} s
+ * @param {{ color?: boolean, meta?: Record<string, string> }} [opts]
+ */
+export const formatText = (s, { color = false, meta = {} } = {}) => {
+  const c = (k, t) => (color ? `${C[k]}${t}${C.off}` : t);
+  const out = [];
+  out.push(c('bold', 'WCAG 2.2 AA (EN 301 549 V4.1.1, the European Accessibility Act): Luma widgets'));
+  for (const [k, v] of Object.entries(meta)) out.push(c('dim', `  ${k}: ${v}`));
+  out.push('');
+  out.push(c('bold', 'Checked'));
+  const byWidget = {};
+  for (const st of s.states) (byWidget[st.widget] ??= []).push(st.state);
+  for (const [w, sts] of Object.entries(byWidget)) out.push(`  ${w}: ${uniq(sts).join(', ')}`);
+  for (const k of s.skipped) out.push(c('yellow', `  ${k.widget}: not checked (${k.reason})`));
+  out.push('');
+  const fail = s.criteria.filter((x) => x.status === 'fail');
+  const pass = s.criteria.filter((x) => x.status === 'pass');
+  if (fail.length) {
+    out.push(c('bold', `Failed: ${fail.length} success criteria`));
+    for (const cr of fail) {
+      out.push('');
+      out.push(c('red', `✗ ${cr.sc} ${cr.title} (${cr.level})`));
+      for (const f of cr.findings) {
+        if (f.sc[0] !== cr.sc && fail.some((x) => x.sc === f.sc[0])) {
+          out.push(c('dim', `    ${f.rule}: see ${f.sc[0]}`));
+          continue;
+        }
+        out.push(`    ${c('bold', f.rule)} [${f.impact}] ${f.help}`);
+        out.push(c('dim', `      where: ${f.states.join('; ')}`));
+        for (const n of f.nodes.slice(0, 5)) {
+          out.push(`      - ${n.target}`);
+          if (n.html) out.push(c('dim', `        ${n.html.replace(/\s+/g, ' ').slice(0, 160)}`));
+          if (n.hint) out.push(`        ${c('yellow', `→ ${n.hint.file}:${n.hint.line}`)} ${c('dim', `(.${n.hint.token})`)}`);
+          if (n.summary) out.push(c('dim', `        ${n.summary.replace(/\s+/g, ' ').slice(0, 240)}`));
+        }
+        if (f.nodes.length > 5) out.push(c('dim', `      … and ${f.nodes.length - 5} more`));
+        if (f.fix) out.push(`      fix: ${f.fix}`);
+        if (f.helpUrl) out.push(c('dim', `      ${f.helpUrl}`));
+      }
+    }
+    out.push('');
+  }
+  out.push(c('bold', `Passed: ${pass.length} success criteria`));
+  out.push(`  ${pass.map((x) => c('green', `✓ ${x.sc}`) + ` ${x.title}`).join('\n  ')}`);
+  if (s.advisories.length) {
+    out.push('');
+    out.push(c('bold', 'Advice (beyond AA, does not fail the run)'));
+    for (const f of s.advisories) {
+      out.push(`  ${f.rule}: ${f.help} (${f.states.join(', ')})`);
+      for (const n of f.nodes.slice(0, 3)) out.push(c('dim', `    - ${n.target}${n.summary ? `: ${n.summary}` : ''}`));
+      if (f.fix) out.push(`    fix: ${f.fix}`);
+    }
+  }
+  if (s.review.length) {
+    out.push('');
+    out.push(c('bold', 'Needs review (axe could not decide; check by eye)'));
+    for (const f of s.review) out.push(`  ${f.sc.join(', ')} ${f.rule}: ${f.help} (${f.nodes.length} node${f.nodes.length > 1 ? 's' : ''}, ${f.states.join(', ')})`);
+  }
+  if (s.host.length) {
+    out.push('');
+    out.push(c('bold', 'The host page\'s own issues (outside Luma\'s nodes; informational, they do not fail the run)'));
+    for (const h of s.host) out.push(c('dim', `  ${h.sc.join(', ')} ${h.rule} [${h.impact}] ${h.help} (${h.nodes} node${h.nodes > 1 ? 's' : ''})`));
+  }
+  const manual = s.criteria.filter((x) => x.status === 'manual' || x.status === 'not-applicable');
+  out.push('');
+  out.push(c('dim', `Not decided automatically (${manual.length}): ${manual.map((x) => x.sc).join(', ')}. A screen reader pass (VoiceOver, NVDA) through typing, a suggestion, a filter, the drawer and "show more" covers what is left for these widgets (${DOC} §7).`));
+  for (const n of s.notes) out.push(c('yellow', `Note: ${n}`));
+  out.push('');
+  const failed = s.findings.length;
+  out.push(
+    s.verdict === 'pass'
+      ? c('green', c('bold', `PASS: no WCAG 2.2 A/AA failure on Luma's widgets (${pass.length} criteria checked).`))
+      : s.verdict === 'fail'
+        ? c('red', c('bold', `FAIL: ${fail.length} success criteria, ${failed} issue${failed > 1 ? 's' : ''} on Luma's widgets.`))
+        : c('yellow', c('bold', 'INCOMPLETE: no Luma widget could be exercised.')),
+  );
+  return out.join('\n');
+};
+
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (ch) => `&#${ch.charCodeAt(0)};`);
+
+/**
+ * A self-contained HTML report (no external resources).
+ * @param {ReturnType<typeof summarize>} s
+ * @param {{ meta?: Record<string, string> }} [opts]
+ */
+export const formatHtml = (s, { meta = {} } = {}) => {
+  const badge = (st) => `<span class="b ${st}">${{ fail: 'fail', pass: 'pass', manual: 'by hand', 'not-applicable': 'not exercised' }[st] ?? st}</span>`;
+  const node = (n) => `<li><code>${esc(n.target)}</code>${n.hint ? ` <span class="hint">→ ${esc(n.hint.file)}:${n.hint.line}</span>` : ''}${n.html ? `<pre>${esc(n.html)}</pre>` : ''}${n.summary ? `<div class="sum">${esc(n.summary)}</div>` : ''}</li>`;
+  const finding = (f) => `<div class="f"><h4>${esc(f.rule)} <small>${esc(f.impact)}</small></h4><p>${esc(f.help)}</p>
+<p class="where">${esc(f.states.join('; '))}</p><ul>${f.nodes.map(node).join('')}</ul>${f.fix ? `<p class="fix"><b>Fix:</b> ${esc(f.fix)}</p>` : ''}${f.helpUrl ? `<p><a href="${esc(f.helpUrl)}">${esc(f.helpUrl)}</a></p>` : ''}</div>`;
+  const rows = s.criteria
+    .map((c) => `<tr class="${c.status}"><td>${c.sc}</td><td>${esc(c.title)}</td><td>${c.level}</td><td>${badge(c.status)}</td><td>${c.status === 'fail' ? c.findings.map(finding).join('') : c.status === 'pass' ? `<span class="dim">${esc(c.states.slice(0, 6).join(', '))}${c.states.length > 6 ? ', …' : ''}</span>` : ''}</td></tr>`)
+    .join('\n');
+  const verdict = s.verdict === 'pass' ? 'PASS' : s.verdict === 'fail' ? 'FAIL' : 'INCOMPLETE';
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Accessibility report</title>
+<style>
+:root { --fg: #1a1a1a; --bg: #fff; --dim: #555; --line: #ccc; --fail: #b00020; --pass: #0a6b2d; --warn: #7a5200; color-scheme: light dark; }
+@media (prefers-color-scheme: dark) { :root { --fg: #eee; --bg: #161616; --dim: #aaa; --line: #444; --fail: #ff7b8b; --pass: #6fd38f; --warn: #f0c060; } }
+body { font: 15px/1.5 system-ui, sans-serif; color: var(--fg); background: var(--bg); margin: 0 auto; max-width: 1100px; padding: 16px; }
+h1 { font-size: 1.4rem; } .verdict { font-size: 1.2rem; font-weight: 700; } .verdict.fail { color: var(--fail); } .verdict.pass { color: var(--pass); } .verdict.incomplete { color: var(--warn); }
+table { border-collapse: collapse; width: 100%; } td, th { border-bottom: 1px solid var(--line); padding: 6px; text-align: left; vertical-align: top; }
+.b { display: inline-block; padding: 0 6px; border: 1px solid; border-radius: 4px; font-size: .8rem; } .b.fail { color: var(--fail); } .b.pass { color: var(--pass); } .b.manual, .b.not-applicable { color: var(--dim); }
+pre { white-space: pre-wrap; word-break: break-all; font-size: .8rem; margin: 2px 0; color: var(--dim); } code { word-break: break-all; }
+.dim, .where, .sum { color: var(--dim); font-size: .85rem; } .hint { color: var(--warn); font-family: ui-monospace, monospace; font-size: .85rem; }
+.f { border-left: 3px solid var(--fail); padding-left: 8px; margin: 6px 0; } .f h4 { margin: 0; } .fix { margin: 4px 0; }
+a { color: inherit; }
+</style></head><body>
+<h1>WCAG 2.2 AA: Luma widgets</h1>
+<p class="verdict ${s.verdict}">${verdict}</p>
+<ul class="dim">${Object.entries(meta).map(([k, v]) => `<li>${esc(k)}: ${esc(v)}</li>`).join('')}</ul>
+<h2>Checked</h2><ul>${s.states.map((st) => `<li>${esc(st.widget)}: ${esc(st.state)} <span class="dim">${esc(st.page)}</span></li>`).join('')}${s.skipped.map((k) => `<li class="dim">${esc(k.widget)}: not checked (${esc(k.reason)})</li>`).join('')}</ul>
+<h2>Success criteria</h2>
+<table><thead><tr><th>SC</th><th>Title</th><th>Level</th><th>Result</th><th>Details</th></tr></thead><tbody>
+${rows}
+</tbody></table>
+${s.advisories.length ? `<h2>Advice (beyond AA)</h2>${s.advisories.map(finding).join('')}` : ''}
+${s.review.length ? `<h2>Needs review</h2><ul>${s.review.map((f) => `<li>${esc(f.sc.join(', '))} <b>${esc(f.rule)}</b>: ${esc(f.help)} <span class="dim">(${f.nodes.length} nodes; ${esc(f.states.join(', '))})</span></li>`).join('')}</ul>` : ''}
+${s.host.length ? `<h2>The host page's own issues (informational)</h2><ul>${s.host.map((h) => `<li>${esc(h.sc.join(', '))} <b>${esc(h.rule)}</b> [${esc(h.impact)}] ${esc(h.help)} <span class="dim">(${h.nodes} nodes)</span></li>`).join('')}</ul>` : ''}
+${s.notes.length ? `<h2>Notes</h2><ul>${s.notes.map((n) => `<li>${esc(n)}</li>`).join('')}</ul>` : ''}
+</body></html>`;
+};