dsh-desktop-kit 0.0.0-stage → 2.0.0

package/skills/wow-design/assets/scripts/audit.mjs

@@ -0,0 +1,1200 @@
+#!/usr/bin/env node
+/**
+ * audit.mjs — доступность и технический аудит страницы:
+ *   - axe-core (инжектится из node_modules/axe-core/axe.min.js);
+ *   - кастомные проверки: горизонтальный overflow на 390px, tap-targets < 40px,
+ *     порядок заголовков, alt у img, битые изображения, пустые ссылки/кнопки,
+ *     загрузка шрифтов, ошибки консоли/pageerror, сбои загрузки ресурсов.
+ *
+ * Usage:
+ *   node audit.mjs <путь|url> [--out <dir>] [--name <name>] [--json]
+ *       [--themes light,dark] [--preset aurora] [--serve] [--cdp <url>]
+ *
+ * Пишет audit.json + audit.md в --out (по умолчанию tmp/qa-artifacts).
+ * Коды выхода: 0 — нет critical/serious; 2 — есть critical/serious; 1 — сбой инструмента.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs, safeFileName, UsageError, printHelpAndExit } from './lib/args.mjs';
+import {
+  connectChrome,
+  disposeChrome,
+  resolveTarget,
+  startStaticServer,
+  openPage,
+  closePage,
+  gotoPage,
+  wireDiagnostics,
+  addThemeInitScript,
+  preparePage,
+  waitForFonts,
+  parseThemeList,
+  VIEWPORTS,
+} from './lib/browser.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const WORKSPACE = path.resolve(HERE, '..', '..');
+const DEFAULT_OUT = path.join(WORKSPACE, 'tmp', 'qa-artifacts');
+const AXE_PATH = path.join(HERE, 'node_modules', 'axe-core', 'axe.min.js');
+const AXE_PKG = path.join(HERE, 'node_modules', 'axe-core', 'package.json');
+
+const SEVERITY = ['critical', 'serious', 'moderate', 'minor'];
+const SEVERITY_RANK = { critical: 4, serious: 3, moderate: 2, minor: 1 };
+
+const FIX_HINTS = {
+  'color-contrast': 'Поднять контраст текста: обычный текст ≥ 4.5:1, крупный (≥24px/18.6px bold) ≥ 3:1. Проверить светлую И тёмную тему.',
+  'image-alt': 'Добавить alt: описательный — для смысловых изображений, alt="" — для декоративных.',
+  'button-name': 'Дать кнопке доступное имя: видимый текст, aria-label или aria-labelledby.',
+  'link-name': 'Добавить текст ссылке или aria-label (иконка-ссылка без имени недопустима).',
+  label: 'Связать поле с <label for="..."> (или aria-label/aria-labelledby).',
+  'html-has-lang': 'Указать lang="ru" на <html>.',
+  'html-lang-valid': 'Использовать корректный код языка: lang="ru".',
+  'heading-order': 'Выстроить иерархию h1 → h2 → h3 без пропуска уровней.',
+  'page-has-heading-one': 'Добавить один h1 (главный заголовок страницы).',
+  'landmark-one-main': 'Обернуть основное содержимое в <main>.',
+  region: 'Весь контент — внутри лендмарков: header / nav / main / footer.',
+  'duplicate-id': 'Убрать дублирующиеся id (на них ломаются aria-ссылки и якоря).',
+  'duplicate-id-aria': 'Убрать дубли id, на которые ссылается ARIA.',
+  'target-size': 'Увеличить интерактивные цели: минимум 24×24px, для мобильного — 40×40px.',
+  'label-content-name-mismatch': 'Видимый текст должен входить в доступное имя: aria-label = видимый текст + контекст (для свотчей включите hex).',
+  'aria-hidden-focus': 'Не скрывать через aria-hidden фокусируемые элементы.',
+  'aria-required-attr': 'Добавить обязательные ARIA-атрибуты роли.',
+  'aria-valid-attr-value': 'Исправить значения ARIA-атрибутов.',
+  'aria-allowed-attr': 'Убрать ARIA-атрибуты, недопустимые для роли.',
+  'aria-prohibited-attr': 'Убрать запрещённые ARIA-атрибуты.',
+  listitem: 'Элементы li допустимы только внутри ul/ol.',
+  list: 'ul/ol должны содержать только li.',
+  'select-name': 'Дать select доступное имя (label/aria-label).',
+  'input-button-name': 'Дать input[type=button/submit] доступное имя (value/aria-label).',
+  'frame-title': 'Добавить title для iframe.',
+  'svg-img-alt': 'Дать SVG с role="img" доступное имя (title/aria-label).',
+  'scrollable-region-focusable': 'Скролл-контейнеру добавить tabindex="0", чтобы он был доступен с клавиатуры.',
+  'nested-interactive': 'Убрать вложенные интерактивные элементы (кнопка внутри ссылки и т.п.).',
+  'meta-viewport': 'Не блокировать масштабирование (не ставить user-scalable=no, maximum-scale<5).',
+  'overflow-horizontal': 'Убрать фиксированные ширины/отрицательные margin/100vw с padding; таблицы обернуть в overflow-x:auto.',
+  'tap-target-small': 'Best practice: увеличить интерактивные цели до ≥40×40px (WCAG 2.5.8 обязательный минимум — 24×24px).',
+  'tap-target-tiny': 'Блокер WCAG 2.5.8: цель меньше 24×24px. Увеличить кнопку/иконку (padding) или кликабельную область ссылки.',
+  'image-broken': 'Исправить/убрать битое изображение (проверить путь и формат).',
+  'heading-skipped': 'Не пропускать уровни заголовков (после h2 — h3, а не h4).',
+  'heading-multiple-h1': 'Оставить ровно один h1 на страницу.',
+  'heading-none': 'Добавить h1 — главный заголовок страницы.',
+  'link-empty-name': 'Добавить ссылке текст или aria-label.',
+  'button-empty-name': 'Добавить кнопке текст или aria-label.',
+  'font-not-loaded': 'Дождаться/исправить загрузку веб-шрифтов: document.fonts.status должен быть "loaded".',
+  'font-face-error': 'Проверить путь/формат файла шрифта (status "error" у @font-face).',
+  'console-error': 'Исправить ошибки JS в консоли.',
+  'page-error': 'Исправить необработанное исключение JS (страница ломается).',
+  'request-failed': 'Исправить загрузку ресурса (404/битый путь/блокировка CORS).',
+};
+
+const HELP = `
+audit.mjs — axe-аудит + технические проверки страницы (overflow, tap-targets, заголовки, alt,
+шрифты, консоль). Пишет audit.json и audit.md.
+
+Использование:
+  node tools/design-qa/audit.mjs <путь-к-html|url> [--out <dir>] [--name <name>] [--json]
+
+Опции:
+  --out <dir>        Каталог для audit.json / audit.md (по умолчанию tmp/qa-artifacts)
+  --name <name>      Префикс отчётов: <name>-audit.json / <name>-audit.md
+  --themes <list>    light,dark (по умолчанию обе)
+  --preset <id>      Выставить data-preset на <html>
+  --serve            Отдавать страницу по http://127.0.0.1 (для ES-модулей)
+  --cdp <url>        CDP-эндпоинт (по умолчанию env CDP_URL или http://127.0.0.1:9333)
+  --timeout <ms>     Таймаут загрузки (по умолчанию 30000)
+  --json             Полный JSON в stdout (логи — в stderr)
+  -h, --help         Эта справка
+
+Проверки: axe-core (AA + best practice), overflow на 390px, tap-targets (WCAG 2.5.8: <24×24 —
+блокер, 24–39px — best practice, инлайновые ссылки в тексте/навигации не учитываются), порядок
+заголовков, alt/битые изображения, пустые ссылки/кнопки, шрифты (document.fonts.status),
+ошибки консоли/pageerror, сбои загрузки ресурсов. Контраст — через axe (обе темы).
+
+Коды выхода: 0 — нет critical/serious; 2 — есть critical/serious; 1 — сбой инструмента.
+`;
+
+const CUSTOM_CHECKS = () => {
+  const doc = document;
+  const de = doc.documentElement;
+  const vw = window.innerWidth || 0;
+  const norm = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+  const trunc = (s, n) => {
+    const t = norm(s);
+    return t.length > n ? t.slice(0, n) + '…' : t;
+  };
+  const selectorOf = (el) => {
+    if (!el || el.nodeType !== 1) return '?';
+    const parts = [];
+    let cur = el;
+    let depth = 0;
+    while (cur && cur.nodeType === 1 && depth++ < 6) {
+      let part = cur.tagName.toLowerCase();
+      if (cur.id) {
+        parts.unshift(`${part}#${cur.id}`);
+        break;
+      }
+      const cls = cur.classList ? Array.from(cur.classList).filter((c) => c.length < 40).slice(0, 2) : [];
+      if (cls.length) part += '.' + cls.join('.');
+      const parent = cur.parentElement;
+      if (parent) {
+        const idx = Array.from(parent.children).indexOf(cur) + 1;
+        if (idx > 1 || !cur.id) part += `:nth-child(${idx})`;
+      }
+      parts.unshift(part);
+      cur = cur.parentElement;
+    }
+    return parts.join(' > ');
+  };
+  const isVisible = (el) => {
+    if (!el || el.nodeType !== 1) return false;
+    const r = el.getBoundingClientRect();
+    const cs = getComputedStyle(el);
+    if (cs.display === 'none' || cs.visibility === 'hidden' || cs.visibility === 'collapse') return false;
+    if (Number(cs.opacity) === 0) {
+      // opacity:0 — типичный reveal-блок; считаем видимым, если участвует в layout
+      return r.width > 0 && r.height > 0;
+    }
+    return r.width > 0 || r.height > 0;
+  };
+  const rectOf = (el) => el.getBoundingClientRect();
+  // Кликабельная область: label расширяет цель для checkbox/radio.
+  const clickableRectOf = (el) => {
+    if (el.tagName === 'INPUT') {
+      const type = String(el.type || '').toLowerCase();
+      if (type === 'checkbox' || type === 'radio') {
+        const label =
+          el.closest('label') ||
+          (el.id ? doc.querySelector(`label[for="${CSS.escape(el.id)}"]`) : null);
+        if (label) return label.getBoundingClientRect();
+      }
+    }
+    return el.getBoundingClientRect();
+  };
+  const withinScroller = (el) => {
+    let p = el.parentElement;
+    while (p && p !== doc.body) {
+      const cs = getComputedStyle(p);
+      if (/(auto|scroll)/.test(cs.overflowX)) return true;
+      p = p.parentElement;
+    }
+    return false;
+  };
+  const accName = (el) => {
+    const aria = el.getAttribute && el.getAttribute('aria-label');
+    if (aria && aria.trim()) return aria.trim();
+    const by = el.getAttribute && el.getAttribute('aria-labelledby');
+    if (by) {
+      const t = by
+        .split(/\s+/)
+        .map((id) => doc.getElementById(id)?.textContent || '')
+        .join(' ')
+        .trim();
+      if (t) return t;
+    }
+    const title = el.getAttribute && el.getAttribute('title');
+    if (title && title.trim()) return title.trim();
+    const txt = (el.innerText || el.textContent || '').trim();
+    if (txt) return txt;
+    const img = el.querySelector && el.querySelector('img[alt]');
+    if (img && img.alt && img.alt.trim()) return img.alt.trim();
+    const svgTitle = el.querySelector && el.querySelector('svg title');
+    if (svgTitle) return norm(svgTitle.textContent);
+    const value = el.getAttribute && el.getAttribute('value');
+    if (value && value.trim()) return value.trim();
+    return '';
+  };
+
+  // ---------- overflow ----------
+  const clientWidth = de ? de.clientWidth : 0;
+  const scrollWidth = Math.max(de?.scrollWidth || 0, doc.body?.scrollWidth || 0, doc.scrollingElement?.scrollWidth || 0);
+  const bodyOverflowX = doc.body ? getComputedStyle(doc.body).overflowX : null;
+  const offenders = [];
+  if (scrollWidth > clientWidth + 1) {
+    for (const el of doc.querySelectorAll('body *')) {
+      if (offenders.length >= 15) break;
+      const r = rectOf(el);
+      if (r.width <= 0 || r.height <= 0) continue;
+      if (!(r.right > clientWidth + 1 || r.left < -1)) continue;
+      if (el.tagName === 'HTML' || el.tagName === 'BODY') continue;
+      if (withinScroller(el)) continue;
+      offenders.push({
+        tag: el.tagName.toLowerCase(),
+        selector: selectorOf(el),
+        left: Math.round(r.left),
+        right: Math.round(r.right),
+        width: Math.round(r.width),
+        text: trunc(el.textContent, 100),
+      });
+    }
+  }
+
+  // ---------- tap targets ----------
+  const INTERACTIVE =
+    'a[href], button, input:not([type="hidden"]), select, textarea, summary, [role="button"], [role="link"], [role="tab"], [role="checkbox"], [role="switch"], [role="radio"], [role="menuitem"], [contenteditable="true"]';
+  const tapTargets = [];
+  const tapTargetsAdvisory = [];
+  // WCAG 2.5.8: инлайновые ссылки в тексте/навигации — не цели (advisory, не влияет на вердикт).
+  const isInlineContextLink = (el) => {
+    if (el.tagName !== 'A') return false;
+    const cs = getComputedStyle(el);
+    if (cs.display === 'inline') return true;
+    let p = el.parentElement;
+    while (p && p !== doc.body) {
+      const tag = p.tagName.toLowerCase();
+      if (tag === 'p' || tag === 'li' || tag === 'nav') return true;
+      const cls = typeof p.className === 'string' ? p.className : '';
+      if (/breadcrumb/i.test(cls)) return true;
+      p = p.parentElement;
+    }
+    return false;
+  };
+  for (const el of doc.querySelectorAll(INTERACTIVE)) {
+    if (tapTargets.length >= 60) break;
+    if (!isVisible(el)) continue;
+    if (el.disabled || el.getAttribute('aria-disabled') === 'true') continue;
+    const cs = getComputedStyle(el);
+    if (cs.pointerEvents === 'none') continue;
+    const tag = el.tagName.toLowerCase();
+    const role = el.getAttribute('role');
+    let kind = 'control';
+    if (tag === 'a' || role === 'link') kind = 'link';
+    else if (tag === 'button' || tag === 'summary' || role === 'button') kind = 'button';
+    const r = clickableRectOf(el);
+    const width = Math.round(r.width);
+    const height = Math.round(r.height);
+    if (width <= 0 || height <= 0) continue;
+    if (width >= 40 && height >= 40) continue;
+    const acc = accName(el);
+    const record = {
+      tag,
+      kind,
+      selector: selectorOf(el),
+      text: trunc(acc, 100),
+      hasText: norm(el.textContent).length > 0,
+      width,
+      height,
+    };
+    if (kind === 'link' && isInlineContextLink(el)) {
+      if (tapTargetsAdvisory.length < 20) tapTargetsAdvisory.push({ ...record, reason: 'inline-link' });
+      continue;
+    }
+    tapTargets.push(record);
+  }
+
+  // ---------- headings ----------
+  const headings = [];
+  for (const h of doc.querySelectorAll('h1,h2,h3,h4,h5,h6')) {
+    if (!isVisible(h)) continue;
+    headings.push({
+      level: Number(h.tagName[1]),
+      text: trunc(h.textContent, 120),
+      selector: selectorOf(h),
+    });
+  }
+  const headingIssues = [];
+  const h1s = headings.filter((h) => h.level === 1);
+  if (!headingIssues.length && h1s.length === 0) {
+    headingIssues.push({
+      type: 'heading-none',
+      message: 'На странице нет h1',
+      severity: 'moderate',
+      nodes: [],
+    });
+  }
+  if (h1s.length > 1) {
+    headingIssues.push({
+      type: 'heading-multiple-h1',
+      message: `Несколько h1 на странице: ${h1s.length}`,
+      severity: 'moderate',
+      nodes: h1s.map((h) => ({ target: h.selector, html: h.text })),
+    });
+  }
+  for (let i = 1; i < headings.length; i++) {
+    const prev = headings[i - 1];
+    const cur = headings[i];
+    if (cur.level - prev.level > 1) {
+      headingIssues.push({
+        type: 'heading-skipped',
+        message: `Пропуск уровня: h${prev.level} → h${cur.level}`,
+        severity: 'serious',
+        nodes: [
+          { target: prev.selector, html: `h${prev.level}: ${prev.text}` },
+          { target: cur.selector, html: `h${cur.level}: ${cur.text}` },
+        ],
+      });
+      if (headingIssues.length >= 20) break;
+    }
+  }
+
+  // ---------- images ----------
+  const images = [];
+  for (const img of Array.from(doc.images)) {
+    images.push({
+      selector: selectorOf(img),
+      src: (img.currentSrc || img.src || '').slice(0, 200),
+      hasAlt: img.hasAttribute('alt'),
+      alt: img.getAttribute('alt'),
+      complete: img.complete,
+      naturalWidth: img.naturalWidth,
+      visible: isVisible(img),
+    });
+  }
+  const imagesMissingAlt = images.filter((i) => !i.hasAlt);
+  const imagesBroken = images.filter((i) => i.complete && i.naturalWidth === 0);
+  const imagesPending = images.filter((i) => !i.complete);
+
+  // ---------- links & buttons без доступного имени ----------
+  const nameIssues = [];
+  for (const a of doc.querySelectorAll('a[href]')) {
+    if (!isVisible(a)) continue;
+    if (accName(a)) continue;
+    nameIssues.push({
+      type: 'link-empty-name',
+      message: 'Ссылка без доступного имени',
+      severity: 'serious',
+      nodes: [{ target: selectorOf(a), html: trunc(a.outerHTML, 200) }],
+    });
+    if (nameIssues.length >= 25) break;
+  }
+  for (const b of doc.querySelectorAll('button, [role="button"]')) {
+    if (!isVisible(b)) continue;
+    if (accName(b)) continue;
+    nameIssues.push({
+      type: 'button-empty-name',
+      message: 'Кнопка без доступного имени',
+      severity: 'serious',
+      nodes: [{ target: selectorOf(b), html: trunc(b.outerHTML, 200) }],
+    });
+    if (nameIssues.length >= 25) break;
+  }
+
+  // ---------- шрифты ----------
+  const fonts = { status: null, size: 0, faces: [] };
+  try {
+    fonts.status = doc.fonts.status;
+    fonts.size = doc.fonts.size;
+    doc.fonts.forEach((f) =>
+      fonts.faces.push({ family: f.family, weight: f.weight, style: f.style, status: f.status }),
+    );
+  } catch {
+    /* ignore */
+  }
+
+  return {
+    viewportWidth: vw,
+    clientWidth,
+    scrollWidth,
+    bodyOverflowX,
+    overflow: { overflowing: scrollWidth > clientWidth + 1, offenders },
+    tapTargets,
+    tapTargetsAdvisory,
+    headings,
+    headingIssues,
+    images: {
+      total: images.length,
+      missingAlt: imagesMissingAlt,
+      broken: imagesBroken,
+      pending: imagesPending,
+    },
+    nameIssues,
+    fonts,
+  };
+};
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2), {
+    booleans: ['help', 'json', 'serve', 'motion', 'quiet'],
+    values: ['out', 'name', 'themes', 'preset', 'serve-root', 'cdp', 'timeout'],
+    aliases: { h: 'help' },
+    defaults: {
+      help: false,
+      json: false,
+      serve: false,
+      motion: false,
+      quiet: false,
+      out: undefined,
+      name: undefined,
+      themes: 'light,dark',
+      preset: undefined,
+      cdp: undefined,
+      timeout: '30000',
+    },
+  });
+  if (args.help) printHelpAndExit(HELP);
+  const log = args.json ? (...a) => console.error(...a) : (...a) => console.log(...a);
+
+  const target = args._[0];
+  if (!target) throw new UsageError('Не указан путь к HTML-файлу или URL (см. --help)');
+  if (!fs.existsSync(AXE_PATH)) {
+    throw new Error(`Не найден axe-core: ${AXE_PATH}. Установите: npm i axe-core --cache <...> (в tools/design-qa)`);
+  }
+  const axeSource = fs.readFileSync(AXE_PATH, 'utf8');
+  const axeVersion = readJsonSafe(AXE_PKG)?.version || 'unknown';
+
+  const themes = parseThemeList(args.themes);
+  const preset = args.preset ? String(args.preset) : null;
+  const timeout = Number(args.timeout) || 30000;
+  const resolved = resolveTarget(String(target), { serve: args.serve });
+  const name = safeFileName(args.name || defaultName(resolved), 'page');
+  const outDir = path.resolve(process.cwd(), args.out || DEFAULT_OUT);
+  fs.mkdirSync(outDir, { recursive: true });
+  const files = args.name
+    ? { json: path.join(outDir, `${name}-audit.json`), md: path.join(outDir, `${name}-audit.md`) }
+    : { json: path.join(outDir, 'audit.json'), md: path.join(outDir, 'audit.md') };
+
+  const startedAt = new Date();
+  const t0 = Date.now();
+  const viewports = [
+    { id: 'desktop', ...VIEWPORTS.desktop },
+    { id: 'mobile', ...VIEWPORTS.mobile },
+  ];
+
+  const result = {
+    tool: 'design-qa/audit',
+    schemaVersion: 1,
+    name,
+    source: resolved.source,
+    url: resolved.url,
+    startedAt: startedAt.toISOString(),
+    finishedAt: null,
+    durationMs: null,
+    browser: null,
+    options: { themes, viewports, preset, axeVersion, reducedMotion: args.motion ? 'no-preference' : 'reduce' },
+    summary: null,
+    issues: [],
+    axe: [],
+    custom: [],
+    console: { consoleErrors: [], pageErrors: [], failedRequests: [] },
+    fonts: { status: 'unknown', faces: [] },
+    fatalError: null,
+    exitCode: 0,
+  };
+
+  let conn = null;
+  let server = null;
+  try {
+    conn = await connectChrome({ cdpUrl: args.cdp || undefined, log });
+    result.browser = {
+      endpoint: conn.endpoint,
+      launched: conn.launched,
+      browser: conn.version?.Browser || conn.version?.browser || null,
+    };
+    log(`[audit] ${resolved.source}`);
+    log(`[audit] браузер: ${result.browser.browser || '?'} (${conn.launched ? 'запущен fallback' : 'CDP ' + conn.endpoint}); axe-core ${axeVersion}`);
+
+    if (args.serve) {
+      if (!resolved.abs) throw new UsageError('--serve поддерживается только для локальных html-файлов');
+      server = await startStaticServer(process.cwd());
+      const rel = path.relative(process.cwd(), resolved.abs).split(path.sep).join('/');
+      resolved.url = `${server.origin}/${rel}`;
+      result.url = resolved.url;
+    }
+
+    const allFonts = [];
+    for (const theme of themes) {
+      for (const vp of viewports) {
+        const tag = `${theme}/${vp.id}`;
+        const load = { theme, viewport: vp.id, width: vp.width, height: vp.height };
+        log(`[audit] ${tag}: загрузка...`);
+        try {
+          const handle = await openPage(conn.browser, {
+            viewport: vp,
+            dpr: 1,
+            theme,
+            reducedMotion: args.motion ? 'no-preference' : 'reduce',
+          });
+          const page = handle.page;
+          const diag = wireDiagnostics(page);
+          try {
+            await addThemeInitScript(page, { theme, preset });
+            await gotoPage(page, resolved.url, { timeout });
+            await preparePage(page, { theme, preset, animations: true, scroll: true });
+            const fonts = await waitForFonts(page);
+            allFonts.push({ tag, ...fonts });
+            // Снимок диагностики ДО инжекта axe: axe-core сам делает XHR к CSS (на file://
+            // это CORS-ошибки), и без снимка они бы приписывались странице.
+            const diagBeforeAxe = {
+              consoleErrors: diag.consoleErrors.slice(),
+              pageErrors: diag.pageErrors.slice(),
+              failedRequests: diag.failedRequests.slice(),
+            };
+
+            // axe-core
+            await page.addScriptTag({ content: axeSource });
+            const axeRaw = await page.evaluate(async () => {
+              try {
+                return await window.axe.run(document, {
+                  runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa', 'best-practice'] },
+                  resultTypes: ['violations', 'incomplete'],
+                });
+              } catch (e) {
+                return { error: String(e && e.message ? e.message : e) };
+              }
+            });
+            const axe = trimAxeResult(axeRaw);
+            result.axe.push({ theme, viewport: vp.id, ...axe });
+
+            // кастомные проверки
+            const custom = await page.evaluate(CUSTOM_CHECKS);
+            result.custom.push({ theme, viewport: vp.id, ...trimCustom(custom) });
+            result.console.consoleErrors.push(...diagBeforeAxe.consoleErrors.map((e) => ({ tag, ...e })));
+            result.console.pageErrors.push(...diagBeforeAxe.pageErrors.map((e) => ({ tag, ...e })));
+            result.console.failedRequests.push(...diagBeforeAxe.failedRequests.map((e) => ({ tag, ...e })));
+          } finally {
+            await closePage(handle);
+          }
+        } catch (err) {
+          const message = `${err?.name || 'Error'}: ${err?.message || err}`;
+          log(`[audit] ✖ ${tag}: ${message}`);
+          result.custom.push({ theme, viewport: vp.id, error: message });
+        }
+      }
+    }
+    result.fonts = mergeFonts(allFonts);
+  } catch (err) {
+    result.fatalError = `${err?.name || 'Error'}: ${err?.message || err}`;
+    log(`[audit] ОШИБКА: ${result.fatalError}`);
+    result.exitCode = 1;
+  } finally {
+    if (server) await server.close().catch(() => {});
+    if (conn) await disposeChrome(conn);
+  }
+
+  result.finishedAt = new Date().toISOString();
+  result.durationMs = Date.now() - t0;
+
+  // ---------- агрегируем issues ----------
+  const issues = [];
+  for (const axeLoad of result.axe) {
+    for (const v of axeLoad.violations || []) {
+      issues.push({
+        source: 'axe',
+        id: v.id,
+        severity: normalizeSeverity(v.impact),
+        theme: axeLoad.theme,
+        viewport: axeLoad.viewport,
+        description: v.description,
+        help: v.help,
+        helpUrl: v.helpUrl,
+        tags: v.tags,
+        nodes: v.nodes,
+        nodeCount: v.nodeCount,
+        fix: FIX_HINTS[v.id] || v.help,
+      });
+    }
+  }
+  for (const load of result.custom) {
+    if (!load.overflow && !load.tapTargets) continue;
+    const where = { theme: load.theme, viewport: load.viewport };
+    if (load.overflow && load.overflow.overflowing) {
+      issues.push({
+        source: 'custom',
+        id: 'overflow-horizontal',
+        severity: 'critical',
+        ...where,
+        help: `Горизонтальный overflow: scrollWidth ${load.overflow.scrollWidth} > clientWidth ${load.overflow.clientWidth}px`,
+        fix: FIX_HINTS['overflow-horizontal'],
+        nodes: load.overflow.offenders.map((o) => ({
+          target: o.selector,
+          html: o.text,
+          extra: `${o.width}px, ${o.left}..${o.right}`,
+        })),
+        nodeCount: load.overflow.offenders.length || 1,
+      });
+    }
+    const taps = load.tapTargets || [];
+    if (taps.length) {
+      // WCAG 2.5.8: <24×24 у иконочных целей — блокер; 24–39 — best practice (minor).
+      // Нативные контролы (checkbox/radio/select) и текстовые ссылки малой высоты —
+      // spacing/UA-исключения: только minor, чтобы не блокировать витрины.
+      const isTiny = (t) => t.width < 24 || t.height < 24;
+      const tinyBlocking = taps.filter((t) => isTiny(t) && t.kind !== 'control' && !(t.kind === 'link' && t.hasText));
+      const minor = taps.filter((t) => !tinyBlocking.includes(t));
+      if (tinyBlocking.length) {
+        issues.push({
+          source: 'custom',
+          id: 'tap-target-tiny',
+          severity: 'critical',
+          ...where,
+          help: `Иконочные цели меньше 24×24px: ${tinyBlocking.length} (WCAG 2.5.8, viewport ${load.viewport})`,
+          fix: FIX_HINTS['tap-target-tiny'],
+          nodes: tinyBlocking.slice(0, 25).map((t) => ({
+            target: t.selector,
+            html: `${t.tag} ${t.width}×${t.height}px «${t.text}»`,
+            extra: `${t.width}×${t.height}`,
+          })),
+          nodeCount: tinyBlocking.length,
+        });
+      }
+      if (minor.length) {
+        issues.push({
+          source: 'custom',
+          id: 'tap-target-small',
+          severity: 'minor',
+          ...where,
+          help: `Цели 24–39px или текстовые ссылки малой высоты (best practice, не блокер): ${minor.length} (viewport ${load.viewport})`,
+          fix: FIX_HINTS['tap-target-small'],
+          nodes: minor.slice(0, 25).map((t) => ({
+            target: t.selector,
+            html: `${t.tag} ${t.width}×${t.height}px «${t.text}»`,
+            extra: `${t.width}×${t.height}`,
+          })),
+          nodeCount: minor.length,
+        });
+      }
+    }
+    for (const h of load.headingIssues || []) {
+      issues.push({
+        source: 'custom',
+        id: h.type,
+        severity: h.severity,
+        theme: load.theme,
+        viewport: load.viewport,
+        help: h.message,
+        fix: FIX_HINTS[h.type] || FIX_HINTS['heading-order'],
+        nodes: h.nodes || [],
+        nodeCount: (h.nodes || []).length || 1,
+      });
+    }
+    for (const img of load.images?.missingAlt || []) {
+      issues.push({
+        source: 'custom',
+        id: 'image-alt-missing',
+        severity: 'serious',
+        theme: load.theme,
+        viewport: load.viewport,
+        help: 'У <img> нет атрибута alt',
+        fix: FIX_HINTS['image-alt'],
+        nodes: [{ target: img.selector, html: img.src }],
+        nodeCount: 1,
+      });
+    }
+    for (const img of load.images?.broken || []) {
+      issues.push({
+        source: 'custom',
+        id: 'image-broken',
+        severity: 'serious',
+        theme: load.theme,
+        viewport: load.viewport,
+        help: 'Изображение не загрузилось (naturalWidth = 0)',
+        fix: FIX_HINTS['image-broken'],
+        nodes: [{ target: img.selector, html: img.src }],
+        nodeCount: 1,
+      });
+    }
+    for (const ni of load.nameIssues || []) {
+      issues.push({
+        source: 'custom',
+        id: ni.type,
+        severity: ni.severity,
+        theme: load.theme,
+        viewport: load.viewport,
+        help: ni.message,
+        fix: FIX_HINTS[ni.type] || 'Дать элементу доступное имя.',
+        nodes: ni.nodes,
+        nodeCount: (ni.nodes || []).length || 1,
+      });
+    }
+    if (load.fonts && load.fonts.status && load.fonts.status !== 'loaded') {
+      issues.push({
+        source: 'custom',
+        id: 'font-not-loaded',
+        severity: 'critical',
+        theme: load.theme,
+        viewport: load.viewport,
+        help: `document.fonts.status = "${load.fonts.status}" (ожидалось "loaded")`,
+        fix: FIX_HINTS['font-not-loaded'],
+        nodes: (load.fonts.faces || []).filter((f) => f.status !== 'loaded').slice(0, 10).map((f) => ({
+          target: `${f.family} ${f.weight} ${f.style}`,
+          html: `status: ${f.status}`,
+        })),
+        nodeCount: 1,
+      });
+    }
+    for (const face of (load.fonts?.faces || []).filter((f) => f.status === 'error')) {
+      issues.push({
+        source: 'custom',
+        id: 'font-face-error',
+        severity: 'serious',
+        theme: load.theme,
+        viewport: load.viewport,
+        help: `Шрифт не загрузился: ${face.family} ${face.weight} ${face.style}`,
+        fix: FIX_HINTS['font-face-error'],
+        nodes: [],
+        nodeCount: 1,
+      });
+    }
+  }
+  for (const e of result.console.pageErrors) {
+    issues.push({
+      source: 'custom',
+      id: 'page-error',
+      severity: 'critical',
+      theme: e.tag?.split('/')[0],
+      viewport: e.tag?.split('/')[1],
+      help: 'Необработанное исключение JS',
+      fix: FIX_HINTS['page-error'],
+      nodes: [{ target: 'console', html: e.text }],
+      nodeCount: 1,
+    });
+  }
+  for (const e of result.console.consoleErrors) {
+    issues.push({
+      source: 'custom',
+      id: 'console-error',
+      severity: 'serious',
+      theme: e.tag?.split('/')[0],
+      viewport: e.tag?.split('/')[1],
+      help: 'Ошибка в консоли браузера',
+      fix: FIX_HINTS['console-error'],
+      nodes: [{ target: 'console', html: e.text }],
+      nodeCount: 1,
+    });
+  }
+  for (const e of result.console.failedRequests) {
+    issues.push({
+      source: 'custom',
+      id: 'request-failed',
+      severity: ['script', 'stylesheet'].includes(e.resourceType) ? 'serious' : 'moderate',
+      theme: e.tag?.split('/')[0],
+      viewport: e.tag?.split('/')[1],
+      help: `Сбой загрузки ресурса: ${e.url}`,
+      fix: FIX_HINTS['request-failed'],
+      nodes: [{ target: e.url, html: e.error || `HTTP ${e.status}` }],
+      nodeCount: 1,
+    });
+  }
+
+  // дедупликация кросс-комбинационных повторов (одни и те же DOM-проблемы в 2 темах/вьюпортах)
+  const deduped = dedupeIssues(issues);
+  deduped.sort(compareIssues);
+  result.issues = deduped;
+
+  const counts = countSeverities(deduped);
+  result.summary = {
+    verdict: counts.critical + counts.serious > 0 ? 'FAIL' : 'PASS',
+    exitCode: counts.critical + counts.serious > 0 ? 2 : 0,
+    counts,
+    axeViolationIds: unique(deduped.filter((i) => i.source === 'axe').map((i) => i.id)).length,
+    axeNodes: deduped.filter((i) => i.source === 'axe').reduce((s, i) => s + (i.nodeCount || 0), 0),
+    customIssues: deduped.filter((i) => i.source === 'custom').length,
+    consoleErrors: result.console.consoleErrors.length,
+    pageErrors: result.console.pageErrors.length,
+    failedRequests: result.console.failedRequests.length,
+    fontsStatus: result.fonts.status,
+    fontsTotal: result.fonts.total,
+    fontsErrors: result.fonts.faces.filter((f) => f.status === 'error').length,
+  };
+  result.exitCode = result.fatalError ? 1 : result.summary.exitCode;
+
+  const json = JSON.stringify(result, null, 2);
+  fs.writeFileSync(files.json, json, 'utf8');
+  const md = renderMarkdown(result);
+  fs.writeFileSync(files.md, md, 'utf8');
+
+  log('');
+  log(`[audit] вердикт: ${result.fatalError ? 'ОШИБКА ИНСТРУМЕНТА' : result.summary.verdict}`);
+  log(
+    `[audit] critical=${counts.critical} serious=${counts.serious} moderate=${counts.moderate} minor=${counts.minor}; ` +
+      `axe-нарушений: ${result.summary.axeViolationIds} (${result.summary.axeNodes} узлов); ` +
+      `console.error=${result.summary.consoleErrors}, pageerror=${result.summary.pageErrors}, failedRequests=${result.summary.failedRequests}`,
+  );
+  log(`[audit] отчёт: ${files.json}`);
+  log(`[audit] сводка: ${files.md}`);
+  const top = deduped.slice(0, 10);
+  if (top.length) {
+    log('[audit] что чинить в первую очередь:');
+    top.forEach((i, n) => log(`  ${n + 1}. [${i.severity}] ${i.id} — ${shorten(i.help, 120)}`));
+  }
+
+  if (args.json) process.stdout.write(json + '\n');
+  process.exitCode = result.exitCode;
+}
+
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function defaultName(resolved) {
+  if (resolved.abs) return path.basename(resolved.abs, path.extname(resolved.abs));
+  try {
+    const u = new URL(resolved.url);
+    const last = u.pathname.split('/').filter(Boolean).pop() || 'page';
+    return path.basename(last, path.extname(last));
+  } catch {
+    return 'page';
+  }
+}
+
+function normalizeSeverity(impact) {
+  return SEVERITY.includes(impact) ? impact : 'moderate';
+}
+
+function shorten(text, n) {
+  const s = String(text || '').replace(/\s+/g, ' ').trim();
+  return s.length > n ? s.slice(0, n) + '…' : s;
+}
+
+function trimAxeResult(raw) {
+  if (!raw || raw.error) {
+    return { error: raw?.error || 'axe.run вернул пустой результат', violations: [], incomplete: [] };
+  }
+  return {
+    engine: raw.testEngine?.name && raw.testEngine?.version ? `${raw.testEngine.name} ${raw.testEngine.version}` : null,
+    violations: (raw.violations || []).map((v) => ({
+      id: v.id,
+      impact: v.impact,
+      tags: v.tags || [],
+      description: v.description,
+      help: v.help,
+      helpUrl: v.helpUrl,
+      nodeCount: v.nodes?.length || 0,
+      nodes: (v.nodes || []).slice(0, 25).map((n) => ({
+        target: Array.isArray(n.target) ? n.target.join(' >>> ') : String(n.target || ''),
+        html: shorten(n.html, 300),
+        failureSummary: shorten(n.failureSummary, 400),
+      })),
+    })),
+    incompleteCount: (raw.incomplete || []).reduce((s, v) => s + (v.nodes?.length || 0), 0),
+    incompleteIds: unique((raw.incomplete || []).map((v) => v.id)),
+  };
+}
+
+function trimCustom(raw) {
+  const trimNode = (n) => ({ target: n.target, html: shorten(n.html, 200) });
+  return {
+    viewportWidth: raw.viewportWidth,
+    clientWidth: raw.clientWidth,
+    scrollWidth: raw.scrollWidth,
+    overflow: {
+      overflowing: raw.overflow?.overflowing || false,
+      clientWidth: raw.clientWidth ?? null,
+      scrollWidth: raw.scrollWidth ?? null,
+      offenders: (raw.overflow?.offenders || []).slice(0, 15),
+    },
+    tapTargets: (raw.tapTargets || []).slice(0, 60),
+    tapTargetsAdvisory: (raw.tapTargetsAdvisory || []).slice(0, 20),
+    headings: {
+      total: (raw.headings || []).length,
+      h1: (raw.headings || []).filter((h) => h.level === 1).length,
+      issues: (raw.headingIssues || []).map((h) => ({ ...h, nodes: (h.nodes || []).map(trimNode) })),
+    },
+    images: {
+      total: raw.images?.total || 0,
+      missingAlt: (raw.images?.missingAlt || []).slice(0, 25).map((i) => ({ selector: i.selector, src: i.src })),
+      broken: (raw.images?.broken || []).slice(0, 25).map((i) => ({ selector: i.selector, src: i.src })),
+      pending: (raw.images?.pending || []).length,
+    },
+    nameIssues: (raw.nameIssues || []).slice(0, 25).map((n) => ({ ...n, nodes: (n.nodes || []).map(trimNode) })),
+    fonts: {
+      status: raw.fonts?.status ?? null,
+      size: raw.fonts?.size ?? 0,
+      faces: (raw.fonts?.faces || []).slice(0, 40),
+    },
+  };
+}
+
+function mergeFonts(allFonts) {
+  const faces = [];
+  const seen = new Set();
+  let status = 'unknown';
+  let total = 0;
+  for (const entry of allFonts) {
+    if (entry.status === 'error' || status === 'error') status = 'error';
+    else if (entry.status === 'loading') status = 'loading';
+    else if (entry.status && status !== 'error' && status !== 'loading') status = entry.status;
+    total = Math.max(total, entry.size || 0);
+    for (const f of entry.faces || []) {
+      const key = `${f.family}|${f.weight}|${f.style}|${f.status}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      faces.push(f);
+    }
+  }
+  return { status, total, faces, loads: allFonts.length };
+}
+
+/** Одинаковые DOM-находки из разных тем/вьюпортов схлопываем, сохраняя где встречались. */
+function dedupeIssues(issues) {
+  const byKey = new Map();
+  for (const issue of issues) {
+    const firstNode = issue.nodes?.[0] || {};
+    // Контраст зависит от темы — не склеиваем между темами (внутри темы склеиваем
+    // desktop/mobile). Остальные axe-правила склеиваем по id+узлу, чтобы одна и та же
+    // находка не дублировалась на light/dark (html-атрибуты у тем разные).
+    const themeScoped = issue.source === 'axe' && issue.id === 'color-contrast';
+    const keyParts = [
+      issue.source,
+      issue.id,
+      themeScoped ? issue.theme || '' : '',
+      firstNode.target || '',
+      issue.help || '',
+    ];
+    const key = keyParts.join('|');
+    const prev = byKey.get(key);
+    const where = `${issue.theme || '?'}/${issue.viewport || '?'}`;
+    if (prev) {
+      prev.seenIn = unique([...(prev.seenIn || []), where]);
+      prev.nodeCount = Math.max(prev.nodeCount || 0, issue.nodeCount || 0);
+      continue;
+    }
+    byKey.set(key, { ...issue, seenIn: [where] });
+  }
+  // склеиваем «сиротские» повторы document-проверок между темами (heading/image/name)
+  const docScoped = new Set([
+    'heading-none',
+    'heading-multiple-h1',
+    'heading-skipped',
+    'image-alt-missing',
+    'image-broken',
+    'link-empty-name',
+    'button-empty-name',
+    'font-not-loaded',
+    'font-face-error',
+  ]);
+  const out = [];
+  const docKeys = new Map();
+  for (const issue of byKey.values()) {
+    if (docScoped.has(issue.id)) {
+      const nodeKey = (issue.nodes || []).map((n) => n.target).join(',');
+      const k = `${issue.id}|${nodeKey}|${issue.help}`;
+      const prev = docKeys.get(k);
+      if (prev) {
+        prev.seenIn = unique([...(prev.seenIn || []), ...(issue.seenIn || [])]);
+        continue;
+      }
+      docKeys.set(k, issue);
+      const nodes = issue.nodes || [];
+      issue.nodes = nodes;
+    }
+    out.push(issue);
+  }
+  return out;
+}
+
+function compareIssues(a, b) {
+  const bySeverity = (SEVERITY_RANK[b.severity] || 0) - (SEVERITY_RANK[a.severity] || 0);
+  if (bySeverity) return bySeverity;
+  const bySource = (a.source === 'custom' ? 0 : 1) - (b.source === 'custom' ? 0 : 1);
+  if (bySource) return bySource;
+  return String(a.id).localeCompare(String(b.id));
+}
+
+function countSeverities(issues) {
+  const counts = { critical: 0, serious: 0, moderate: 0, minor: 0 };
+  for (const i of issues) counts[normalizeSeverity(i.severity)]++;
+  return counts;
+}
+
+function unique(arr) {
+  return [...new Set(arr.filter((v) => v !== undefined && v !== null && v !== ''))];
+}
+
+// ---------------------------------------------------------------------------
+// Markdown-отчёт
+// ---------------------------------------------------------------------------
+
+function renderMarkdown(result) {
+  const lines = [];
+  const s = result.summary;
+  const push = (...l) => lines.push(...l);
+
+  push(`# Визуальный аудит: ${result.name}`, '');
+  push(`- **Источник:** \`${result.source}\``);
+  if (result.url && result.url !== result.source) push(`- **URL:** ${result.url}`);
+  push(`- **Дата:** ${result.finishedAt} (${(result.durationMs / 1000).toFixed(1)} c)`);
+  push(`- **Браузер:** ${result.browser?.browser || '—'}${result.browser?.launched ? ' (запущен fallback)' : ' (CDP)'}`);
+  push(`- **axe-core:** ${result.options.axeVersion}; темы: ${result.options.themes.join(', ')}; вьюпорты: ${result.options.viewports.map((v) => `${v.id} ${v.width}×${v.height}`).join(', ')}`);
+  if (result.options.preset) push(`- **Пресет:** \`${result.options.preset}\``);
+  push('');
+
+  if (result.fatalError) {
+    push('## Вердикт: ОШИБКА ИНСТРУМЕНТА', '', '```', result.fatalError, '```', '');
+    return lines.join('\n');
+  }
+
+  push(
+    `## Вердикт: ${s.verdict === 'PASS' ? 'PASS ✅' : 'FAIL ❌'}`,
+    '',
+    `- critical: **${s.counts.critical}**, serious: **${s.counts.serious}**, moderate: ${s.counts.moderate}, minor: ${s.counts.minor}`,
+    `- axe-нарушений: ${s.axeViolationIds} (${s.axeNodes} узлов); кастомных замечаний: ${s.customIssues}`,
+    `- ошибок консоли: ${s.consoleErrors}; pageerror: ${s.pageErrors}; сбоев загрузки: ${s.failedRequests}`,
+    `- шрифты: document.fonts.status = **${s.fontsStatus}** (faces: ${s.fontsTotal}, ошибок: ${s.fontsErrors})`,
+    `- код выхода: **${s.exitCode}** (${s.exitCode === 2 ? 'есть critical/serious' : 'критичных проблем нет'})`,
+    '',
+  );
+
+  const top = result.issues.slice(0, 10);
+  push('## Что чинить в первую очередь', '');
+  if (!top.length) {
+    push('Критичных и серьёзных проблем не найдено. Проверьте moderate/minor ниже.', '');
+  } else {
+    top.forEach((issue, idx) => {
+      const where = issue.seenIn?.length ? ` — ${issue.seenIn.join(', ')}` : '';
+      push(
+        `${idx + 1}. **[${issue.severity}] ${issue.id}** (${issue.source}) — ${shorten(issue.help, 220)}${where}`,
+        `   - *Как исправить:* ${shorten(issue.fix || '', 260)}`,
+      );
+      const nodes = (issue.nodes || []).slice(0, 3);
+      if (nodes.length) {
+        for (const n of nodes) push(`   - \`${shorten(n.target, 140)}\`${n.html ? ` — ${shorten(n.html, 160)}` : ''}`);
+      }
+    });
+    push('');
+  }
+
+  push('## Сводка по severity и источникам', '', '| severity | axe | custom | всего |', '|---|---:|---:|---:|');
+  for (const sev of SEVERITY) {
+    const axe = result.issues.filter((i) => i.source === 'axe' && i.severity === sev).length;
+    const custom = result.issues.filter((i) => i.source === 'custom' && i.severity === sev).length;
+    if (!axe && !custom) continue;
+    push(`| ${sev} | ${axe} | ${custom} | ${axe + custom} |`);
+  }
+  push('');
+
+  const axeViolations = result.issues.filter((i) => i.source === 'axe');
+  push('## Axe: нарушения', '');
+  if (!axeViolations.length) {
+    push('Нарушений axe-core нет.', '');
+  } else {
+    for (const v of axeViolations) {
+      const where = v.seenIn?.length ? ` — ${v.seenIn.join(', ')}` : '';
+      push(`### ${v.id} — ${v.severity}${where}`, '');
+      push(`${v.help || ''}`);
+      if (v.helpUrl) push(`Справка: <${v.helpUrl}>`);
+      push(`Узлов: ${v.nodeCount}; *как исправить:* ${v.fix || '—'}`, '');
+      for (const n of (v.nodes || []).slice(0, 10)) {
+        push(`- \`${shorten(n.target, 180)}\``);
+        if (n.failureSummary) push(`  - ${shorten(n.failureSummary, 300)}`);
+      }
+      if ((v.nodes || []).length > 10) push(`- …ещё ${v.nodes.length - 10} узлов в audit.json`);
+      push('');
+    }
+  }
+
+  push('## Кастомные проверки', '');
+  const firstLoad = result.custom.find((c) => !c.error) || {};
+  push('### Горизонтальный overflow (390px)', '');
+  const overflowLoads = result.custom.filter((c) => c.overflow?.overflowing);
+  if (overflowLoads.length === 0) {
+    push('Горизонтального скролла нет на всех проверенных ширинах. ✅', '');
+  } else {
+    for (const load of overflowLoads) {
+      push(`- **${load.theme}/${load.viewport}**: scrollWidth ${load.overflow.scrollWidth} > clientWidth ${load.overflow.clientWidth}px`);
+      for (const o of load.overflow.offenders.slice(0, 10)) {
+        push(`  - \`${shorten(o.selector, 160)}\` — ${o.width}px (${o.left}..${o.right}) ${shorten(o.text, 100)}`);
+      }
+    }
+    push('');
+  }
+
+  push('### Tap-targets < 40×40px (WCAG 2.5.8)', '');
+  const tapIssues = result.issues.filter((i) => i.id === 'tap-target-tiny' || i.id === 'tap-target-small');
+  const tapAdvisory = result.custom.reduce((s, c) => s + (c.tapTargetsAdvisory?.length || 0), 0);
+  if (!tapIssues.length) {
+    push('Все интерактивные цели не меньше 40×40px (кроме инлайновых ссылок). ✅', '');
+  } else {
+    for (const issue of tapIssues) {
+      push(`- **[${issue.severity}]** ${issue.help}${issue.seenIn?.length ? ` — ${issue.seenIn.join(', ')}` : ''}`);
+      for (const n of (issue.nodes || []).slice(0, 10)) {
+        push(`  - \`${shorten(n.target, 140)}\` — ${shorten(n.html, 80)}`);
+      }
+      if ((issue.nodes || []).length > 10) push(`  - …ещё ${issue.nodes.length - 10} целей в audit.json`);
+    }
+  }
+  if (tapAdvisory) {
+    push(`_Advisory (не влияет на вердикт): не учитывались инлайновые ссылки в тексте/навигации — ${tapAdvisory}._`);
+  }
+  push('');
+
+  push('### Заголовки', '');
+  const headingIssues = result.issues.filter((i) => String(i.id).startsWith('heading-'));
+  if (!headingIssues.length) {
+    push(`Порядок заголовков корректный (h1: ${firstLoad.headings?.h1 ?? '?'}, всего ${firstLoad.headings?.total ?? '?'}). ✅`, '');
+  } else {
+    for (const h of headingIssues) {
+      push(`- [${h.severity}] ${h.help} — ${(h.nodes || []).map((n) => `\`${shorten(n.target, 80)}\` ${shorten(n.html, 80)}`).join('; ')}`);
+    }
+    push('');
+  }
+
+  push('### Изображения', '');
+  const imgIssues = result.issues.filter((i) => ['image-alt-missing', 'image-broken'].includes(i.id));
+  if (!imgIssues.length) {
+    push(`У всех изображений есть alt, битых нет (всего изображений: ${firstLoad.images?.total ?? 0}). ✅`, '');
+  } else {
+    for (const i of imgIssues) {
+      push(`- [${i.severity}] ${i.id}: ${(i.nodes || []).map((n) => `\`${shorten(n.target, 120)}\` ${shorten(n.html, 120)}`).join('; ')}`);
+    }
+    push('');
+  }
+
+  push('### Ссылки и кнопки без доступного имени', '');
+  const nameIssues = result.issues.filter((i) => ['link-empty-name', 'button-empty-name'].includes(i.id));
+  if (!nameIssues.length) {
+    push('Пустых ссылок/кнопок без имени нет. ✅', '');
+  } else {
+    for (const i of nameIssues) {
+      push(`- [${i.severity}] ${i.id}: ${(i.nodes || []).map((n) => `\`${shorten(n.target, 120)}\``).join('; ')}`);
+    }
+    push('');
+  }
+
+  push('### Шрифты', '');
+  push(`document.fonts.status = **${s.fontsStatus}**; загружено faces: ${s.fontsTotal}; ошибок: ${s.fontsErrors}.`);
+  const fontIssues = result.issues.filter((i) => ['font-not-loaded', 'font-face-error'].includes(i.id));
+  if (!fontIssues.length) push('Все веб-шрифты загрузились. ✅');
+  for (const i of fontIssues) push(`- [${i.severity}] ${i.help}`);
+  push('');
+
+  push('## Консоль и сеть', '');
+  if (!result.console.consoleErrors.length && !result.console.pageErrors.length && !result.console.failedRequests.length) {
+    push('Ошибок консоли, pageerror и сбоев загрузки нет. ✅', '');
+  } else {
+    if (result.console.pageErrors.length) {
+      push('**pageerror:**');
+      for (const e of result.console.pageErrors.slice(0, 10)) push(`- [${e.tag}] ${shorten(e.text, 300)}`);
+      push('');
+    }
+    if (result.console.consoleErrors.length) {
+      push('**console.error:**');
+      for (const e of result.console.consoleErrors.slice(0, 15)) push(`- [${e.tag}] ${shorten(e.text, 300)}`);
+      push('');
+    }
+    if (result.console.failedRequests.length) {
+      push('**Сбои загрузки:**');
+      for (const e of result.console.failedRequests.slice(0, 20)) push(`- [${e.tag}] ${e.resourceType || ''} ${shorten(e.url, 240)} — ${e.error || `HTTP ${e.status}`}`);
+      push('');
+    }
+  }
+
+  push('## Детали прогонов', '', '| тема | viewport | axe-нарушений | overflow | tap-targets | шрифты |', '|---|---|---:|---|---|---|');
+  for (const load of result.custom) {
+    const axeLoad = result.axe.find((a) => a.theme === load.theme && a.viewport === load.viewport);
+    push(
+      `| ${load.theme} | ${load.viewport} | ${axeLoad?.violations?.length ?? 0} | ${load.overflow?.overflowing ? '⚠️ yes' : 'ok'} | ${load.tapTargets?.length ?? 0} | ${load.fonts?.status ?? '—'} |`,
+    );
+  }
+  push('');
+  push('---', '');
+  push('_Отчёт сгенерирован tools/design-qa/audit.mjs. Подробности (все узлы, HTML, failureSummary) — в audit.json._');
+
+  return lines.join('\n');
+}
+
+main().catch((err) => {
+  if (err?.isUsageError) {
+    console.error(`[audit] ${err.message}`);
+    console.error('[audit] подсказка: запустите node tools/design-qa/audit.mjs --help');
+    process.exitCode = 1;
+    return;
+  }
+  console.error('[audit] НЕОЖИДАННАЯ ОШИБКА:', err);
+  process.exitCode = 1;
+});