@operstack/audit 0.17.2 → 0.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.17.2",
+  "version": "0.18.1",
   "description": "SEO, AEO and GEO audit generator: collect public signals from a site into audit.json, let an analyst or an agent fill the narrative, render the OperStack report as HTML and PDF.",
   "type": "module",
   "license": "MIT",

package/src/collect.mjs

@@ -460,7 +460,7 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
     for (const t of targets) {
       if (!t.url) continue;
       log(`rendering ${t.url} in a real browser`);
-      const dom = renderedDom(t.url);
+      const dom = await renderedDom(t.url);
       if (!dom) { log('no browser here, the JavaScript check will say it was not measured'); break; }
       const rawHtml = t.raw || (await get(t.url)).text;
       if (!rawHtml) continue;

package/src/index.mjs

@@ -1,7 +1,7 @@
 export { collect, computeScores, computeOverall, verifyScores, SCORE_AREAS } from './collect.mjs';
 // Единственная копия движка видимости. Сайты и актор зовут его отсюда, своих копий больше нет.
 export { checkVisibility, normaliseInput, parseRobots, agentVerdict, MESSAGES as VISIBILITY_MESSAGES, VISIBILITY_DEFAULTS } from './visibility.mjs';
-export { render, checkNarrative } from './render.mjs';
+export { render, checkNarrative, overallSummary } from './render.mjs';
 export { localiseChecks, localiseBasisNote, untranslated, AREAS_RU } from './i18n.mjs';
 export { buildFixPlan, renderFixPlan, renderFixChecklist, buildFixReport, renderFixReport, FIX_ACTIONS } from './fix.mjs';
 export { buildFoundationScope, renderFoundationScope, renderFoundationChecklist } from './foundation.mjs';

package/src/render.mjs

@@ -9,6 +9,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { computeScores, computeOverall } from './collect.mjs';
 import { localiseBasisNote, AREAS_RU } from './i18n.mjs';
+import { MESSAGES as VISIBILITY_MESSAGES } from './visibility.mjs';
 import { softenHex } from './agency.mjs';
 
 const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
@@ -102,6 +103,38 @@ const ruPoints = (n) => { const a = Math.abs(n) % 100; const b = a % 10; if (a >
 
 const scoreClass = (n) => (n === null || n === undefined ? '' : n <= 3 ? 'low' : n <= 6 ? 'mid' : 'ok');
 
+/**
+ * Балл видимости и всё, что про него надо сказать словами, одним объектом.
+ *
+ * Простым языком: это тот самый блок, который стоит на первой странице отчёта. Письмо печатает
+ * его же. Раньше письмо собирало свою формулировку и свою цифру, и человек получал на странице
+ * одно, в письме другое, а в PDF третье. Теперь текст ровно один и живёт здесь.
+ *
+ * Названия областей берутся по `id`, а не по готовой подписи из замера: замер мог пройти на
+ * английской странице, а отчёт уходить русскому покупателю, и тогда подпись пришла бы на чужом
+ * языке. Язык отчёта главнее языка замера.
+ *
+ * Возвращает null, если балла нет: движок отказывается мерить закрытые и приватные адреса, и в
+ * этом случае честнее не называть цифру вовсе, чем подставить ноль.
+ */
+export function overallSummary(overall, { lang = 'en' } = {}) {
+  if (!overall || overall.score === null || overall.score === undefined) return null;
+  const key = lang === 'ru' ? 'ru' : 'en';
+  const L = LABELS[key];
+  const names = VISIBILITY_MESSAGES[key].area;
+  return {
+    label: L.overallLabel,
+    score: overall.score,
+    grade: (L.grades && L.grades[overall.grade]) || overall.grade,
+    note: L.overallNote(overall),
+    areas: (Array.isArray(overall.areas) ? overall.areas : []).map((x) => ({
+      id: x.id, label: (x.id && names[x.id]) || x.label, score: x.score, max: x.max,
+    })),
+    secondMeasure: L.secondMeasure,
+    secondMeasureFoot: L.scorecardFoot.replace(/<\/?strong>/g, ''),
+  };
+}
+
 export function checkNarrative(audit) {
   const out = [];
   const walk = (v, path) => {
@@ -211,14 +244,13 @@ export function toHtml(audit, brand = null) {
    * независимое измерение по проверкам самого отчёта, а не разбивка заголовка. Сводить их с
    * заголовком не нужно и не получится, и об этом сказано словами.
    */
-  const overall = a.overall && a.overall.score !== undefined ? a.overall : null;
-  const overallAreas = overall && Array.isArray(overall.areas) ? overall.areas : [];
-  const overallBlock = !overall || overall.score === null ? '' : `<div class="overall">
-    <div class="overall-num ${scoreClass(Math.round(overall.score / 10))}">${overall.score}<span>/100</span></div>
-    <div class="overall-side"><div class="overall-label">${esc(L.overallLabel)}</div>
-      <div class="overall-grade">${esc((L.grades && L.grades[overall.grade]) || overall.grade)}</div>
-      <div class="overall-note">${esc(L.overallNote(overall))}</div></div></div>`
-    + (overallAreas.length ? `<table class="areas"><tr>${overallAreas.map((x) => `<th>${esc(x.label)}</th>`).join('')}</tr><tr>${overallAreas.map((x) => `<td>${x.score}<span>/${x.max}</span></td>`).join('')}</tr></table>` : '');
+  const head = overallSummary(a.overall, { lang: a.meta?.lang === 'ru' ? 'ru' : 'en' });
+  const overallBlock = !head ? '' : `<div class="overall">
+    <div class="overall-num ${scoreClass(Math.round(head.score / 10))}">${head.score}<span>/100</span></div>
+    <div class="overall-side"><div class="overall-label">${esc(head.label)}</div>
+      <div class="overall-grade">${esc(head.grade)}</div>
+      <div class="overall-note">${esc(head.note)}</div></div></div>`
+    + (head.areas.length ? `<table class="areas"><tr>${head.areas.map((x) => `<th>${esc(x.label)}</th>`).join('')}</tr><tr>${head.areas.map((x) => `<td>${x.score}<span>/${x.max}</span></td>`).join('')}</tr></table>` : '');
   const scoreCards = Object.entries(measured).map(([label, n]) => {
     const basis = scoreBasis[label] || {};
     const shown = (L.areas && L.areas[label]) || label;

package/src/rendered.mjs

@@ -10,11 +10,31 @@
  * Браузер берётся тот же, которым печатается PDF отчёта: свой Chrome или Chromium. Если его нет,
  * проверка не выдумывает результат, а говорит, что не измеряла, и почему.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
+/**
+ * Это страница сайта или собственная страница ошибки браузера.
+ *
+ * Простым языком: браузер не смог открыть сайт и вместо него напечатал свою страницу «не удалось
+ * подключиться». В ней сотни слов интерфейса самого браузера. Если принять её за «как сайт
+ * выглядит со скриптами», получится, что у покупателя почти весь текст появляется только в
+ * браузере, и мы напишем ему в отчёте, что его сайт не читается без скриптов. Это была бы
+ * выдуманная находка по чужому сайту, худший вид ошибки в платном отчёте.
+ *
+ * Поэтому такую страницу мы не меряем вовсе и честно говорим, что не мерили.
+ */
+export function isBrowserErrorPage(html) {
+  const s = String(html || '');
+  if (!s) return false;
+  // Своя страница ошибки Chrome собирается из этих кусков и ни на одном настоящем сайте их нет
+  // всех сразу: контейнер ошибки, скрипт neterror и копирайт Chromium в собственных стилях.
+  const marks = [/id="main-frame-error"/i, /neterror/i, /chrome-error:/i, /Chromium Authors/].filter((re) => re.test(s)).length;
+  return marks >= 2;
+}
+
 /** Тот же поиск браузера, что у печати PDF: одна привычка на весь пакет. */
 export function findChrome() {
   const candidates = [
@@ -34,17 +54,74 @@ export function findChrome() {
 /** Текст страницы после выполнения скриптов. null, если браузера нет или он не справился. */
 export function renderedDom(url, { chrome = null, timeoutMs = 45000, waitMs = 8000 } = {}) {
   const bin = chrome || findChrome();
-  if (!bin) return null;
+  if (!bin) return Promise.resolve(null);
   const profile = mkdtempSync(join(tmpdir(), 'operstack-render-'));
-  try {
-    const r = spawnSync(bin, [
+
+  /*
+   * Почему не spawnSync с таймаутом, хотя так было и так короче.
+   *
+   * 14.09.2026 отчёт по habr.com встал на этой стадии и не двигался сорок минут при нулевой
+   * загрузке процессора. Таймаут spawnSync отправляет сигнал только самому Chrome, а тот
+   * запускает десяток вспомогательных процессов, и они наследуют тот же канал вывода. Главный
+   * умирает, помощники живут, канал не закрывается, и ожидание чтения не кончается никогда.
+   * Таймаут при этом честно сработал: висел не Chrome, висело чтение его вывода.
+   *
+   * Поэтому запускаем своей группой процессов (`detached`) и по истечении срока убиваем всю
+   * группу разом, отрицательным номером. Помощники уходят вместе с главным, канал закрывается,
+   * и стадия заканчивается в срок при любом поведении чужого сайта.
+   */
+  /** Похоже ли прочитанное на целую страницу, а не на обрывок. */
+  const complete = (html) => /<\/html\s*>\s*$/i.test(String(html).trimEnd());
+
+  return new Promise((resolve) => {
+    let out = ''; let size = 0; let done = false;
+    const child = spawn(bin, [
       '--headless=new', '--disable-gpu', '--no-first-run', '--no-default-browser-check',
       '--disable-extensions', '--mute-audio', '--hide-scrollbars',
       `--user-data-dir=${profile}`, `--virtual-time-budget=${waitMs}`, '--dump-dom', url,
-    ], { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 });
-    if (r.status !== 0 || !r.stdout) return null;
-    return r.stdout;
-  } catch { return null; } finally { rmSync(profile, { recursive: true, force: true }); }
+    ], { detached: true, stdio: ['ignore', 'pipe', 'ignore'] });
+
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      // Страница ошибки браузера это не сайт покупателя: меряли бы интерфейс Chrome.
+      if (value && isBrowserErrorPage(value)) value = null;
+      clearTimeout(timer);
+      stopGroup();
+      rmSync(profile, { recursive: true, force: true });
+      resolve(value);
+    };
+    const stopGroup = () => {
+      // Отрицательный номер это вся группа: сам Chrome и все его помощники.
+      try { process.kill(-child.pid, 'SIGKILL'); } catch { /* уже ушли */ }
+    };
+
+    // По сроку отдаём то, что успели прочитать: браузер мог допечатать страницу целиком и не
+    // суметь завершиться. Выбрасывать готовый DOM только потому, что Chrome не ушёл сам, значит
+    // сказать покупателю «не измеряли» там, где измерили.
+    const timer = setTimeout(() => finish(complete(out) ? out : null), timeoutMs);
+    child.stdout.on('data', (chunk) => {
+      size += chunk.length;
+      // Страница может оказаться огромной. Читаем до потолка и прекращаем: DOM на шестьдесят
+      // мегабайт всё равно не нужен, а память нужна.
+      if (size > 64 * 1024 * 1024) { finish(complete(out) ? out : null); return; }
+      out += chunk;
+      // Как только страница допечатана до закрывающего тега, ждать больше нечего: `--dump-dom`
+      // печатает разметку целиком и одним куском. Chrome после этого может не завершиться сам,
+      // и раньше каждая страница стоила полного срока ожидания вместо секунды.
+      if (complete(out)) finish(out);
+    });
+    child.on('error', () => finish(null));
+    /*
+     * Ждём именно `exit`, а не `close`.
+     *
+     * `close` ждёт, пока закроются все потоки, а канал вывода держат вспомогательные процессы
+     * Chrome, которые живут дольше главного. Из-за этого стадия не заканчивалась даже на
+     * example.com: DOM был давно прочитан, а событие не приходило. `exit` приходит, когда ушёл
+     * сам браузер, и этого достаточно: всё, что он собирался напечатать, уже у нас.
+     */
+    child.on('exit', (code) => finish(code === 0 && out ? out : (complete(out) ? out : null)));
+  });
 }
 
 const CHROME_STRIP = /<(nav|footer|aside|script|style|noscript|template)[\s\S]*?<\/\1>/gi;

package/src/test-overall.mjs

@@ -12,7 +12,7 @@ import { readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { collect, computeOverall, computeScores, verifyScores, SCORE_AREAS } from './collect.mjs';
 import { checkVisibility, VISIBILITY_DEFAULTS } from './visibility.mjs';
-import { toHtml } from './render.mjs';
+import { toHtml, overallSummary } from './render.mjs';
 
 let bad = 0;
 const ok = (n, c) => { if (c) console.log(`ok   ${n}`); else { bad++; console.error(`FAIL ${n}`); } };
@@ -186,6 +186,42 @@ ok('параметры нельзя поменять на ходу', Object.isFr
   }
 }
 
+// ---- один блок «балл и области» на отчёт и на письмо
+//
+// Письмо собирало свою формулировку и свою цифру, отчёт свою. Разошлись. Теперь обе стороны
+// зовут overallSummary, и разойтись нечему: текст ровно один и живёт в пакете.
+{
+  const areas = [{ id: 'access', label: 'Can AI crawlers read it', score: 20, max: 25 },
+    { id: 'index', label: 'Is there a map for agents (llms.txt)', score: 5, max: 15 },
+    { id: 'entity', label: 'Is the entity clear (schema)', score: 12, max: 20 },
+    { id: 'content', label: 'Is there something to quote', score: 18, max: 25 },
+    { id: 'trust', label: 'Can it be dated and trusted', score: 8, max: 15 }];
+  const overall = { score: 63, grade: 'B', areas, source: 'visibility:reused', measuredAt: '2026-09-14T20:00:00.000Z', basis: { pages: 4, sitemapRead: true, sitemapUnchecked: false } };
+
+  const ru = overallSummary(overall, { lang: 'ru' });
+  const en = overallSummary(overall, { lang: 'en' });
+  is('заголовок письма это заголовок отчёта', ru.score, 63);
+  is('сумма пяти областей даёт заголовок', ru.areas.reduce((a, x) => a + x.score, 0), ru.score);
+  ok('оценка словом переведена', ru.grade === 'Рабочее состояние' && en.grade === 'Workable');
+  const fixture = JSON.parse(readFileSync(new URL('../examples/sample-audit.json', import.meta.url), 'utf8'));
+  fixture.meta.lang = 'ru'; fixture.overall = overall;
+  ok('подпись та же, что печатает отчёт', ru.note === (toHtml(fixture, null).match(/overall-note">([^<]*)</) || [])[1]);
+
+  // Замер мог пройти на английской странице, а отчёт уходит русскому покупателю: язык отчёта главнее.
+  ok('названия областей на языке отчёта, а не замера', ru.areas[0].label === 'Могут ли роботы ИИ прочитать сайт');
+  ok('и в английском они английские', en.areas[0].label === 'Can AI crawlers read it');
+  ok('в русском блоке нет английских названий', !ru.areas.some((x) => /[A-Za-z]{4}/.test(x.label.replace('llms.txt', ''))));
+
+  // Шесть областей отчёта это второе измерение, и подпись обязана это говорить в обоих языках.
+  ok('подзаголовок второго измерения есть', /Второе, отдельное измерение/.test(ru.secondMeasure) && /second, separate measurement/.test(en.secondMeasure));
+  ok('и сказано, что складывать их с заголовком не надо', /в сумме его не дают/.test(ru.secondMeasureFoot) && /will not add up to it/.test(en.secondMeasureFoot));
+  ok('в подписи второго измерения нет разметки', !/</.test(ru.secondMeasureFoot) && !/</.test(en.secondMeasureFoot));
+
+  // Балла может не быть: движок не мерит закрытые адреса. Тогда письмо не называет цифру вовсе.
+  is('без балла блока нет', overallSummary({ score: null, grade: 'not measured', areas: [] }, { lang: 'ru' }), null);
+  is('и на пустом объекте тоже', overallSummary(null, { lang: 'en' }), null);
+}
+
 // ---- движок в пакете это та же программа, что стоит на сайтах
 {
   const here = readFileSync(new URL('./visibility.mjs', import.meta.url), 'utf8');

package/src/test-rendered.mjs

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 /** Слепота к скриптам: считаем честно, не измерив, так и говорим. */
-import { compareReadings, jsBlindnessCheck } from './rendered.mjs';
+import { chmodSync, mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { compareReadings, jsBlindnessCheck, isBrowserErrorPage, renderedDom } from './rendered.mjs';
 
 let bad = 0;
 const is = (n, a, b) => { const ok = JSON.stringify(a) === JSON.stringify(b); if (!ok) { bad++; console.error(`FAIL ${n}\n  ждали ${JSON.stringify(b)}\n  вышло ${JSON.stringify(a)}`); } else console.log(`ok   ${n}`); };
@@ -57,5 +60,57 @@ ok('и сказано почему', /нет браузера/.test(none.value))
 const en = jsBlindnessCheck([{ url: 'https://x.com/', raw: 10, rendered: 400, hiddenShare: 98, verdict: 'bad' }], 'en');
 ok('английская версия без кириллицы', !/[А-Яа-яЁё]/.test(JSON.stringify(en)));
 
+// ---- страница ошибки браузера это не сайт покупателя
+//
+// 14.09.2026 браузер не смог открыть сайт и напечатал свою страницу «не удалось подключиться»:
+// сто восемьдесят килобайт интерфейса Chrome. Приняв её за «как выглядит со скриптами», мы бы
+// написали покупателю в платном отчёте, что его сайт не читается без скриптов. Выдуманная
+// находка по чужому сайту это худшее, что может быть в отчёте за деньги.
+{
+  const errorPage = '<!DOCTYPE html><html dir="ltr" lang="ru"><head><style>/* Copyright 2017 The Chromium Authors */</style>'
+    + '<script>function neterror(){}</script></head><body><div id="main-frame-error"><span>Не удалось открыть страницу</span></div></body></html>';
+  ok('страница ошибки браузера распознана', isBrowserErrorPage(errorPage));
+  ok('настоящая страница не принята за ошибку', !isBrowserErrorPage(body(text(300))));
+  ok('пустой ответ не принят за ошибку', !isBrowserErrorPage(''));
+  // Одного совпадения мало: слово neterror может встретиться в статье про ошибки браузера.
+  ok('одного слова недостаточно', !isBrowserErrorPage('<html><body><p>Статья про neterror и как его читать</p></body></html>'));
+}
+
+// ---- браузер обязан отпускать, даже если сам не уходит
+//
+// Chrome печатает разметку и может не завершиться: его вспомогательные процессы держат канал
+// вывода открытым. Отчёт по habr.com из-за этого стоял сорок минут при нулевой загрузке.
+{
+  const dir = mkdtempSync(join(tmpdir(), 'operstack-fake-chrome-'));
+  const fake = (script) => {
+    const f = join(dir, `chrome-${Math.random().toString(36).slice(2)}.sh`);
+    writeFileSync(f, `#!/bin/sh\n${script}\n`);
+    chmodSync(f, 0o755);
+    return f;
+  };
+
+  // Напечатал страницу целиком и завис. Ждать его незачем: всё уже у нас.
+  const printsThenHangs = fake(`printf '%s' '<html><body><p>текст страницы</p></body></html>'\nsleep 60`);
+  const t0 = Date.now();
+  const dom = await renderedDom('https://example.com/', { chrome: printsThenHangs, timeoutMs: 10000 });
+  const took = Date.now() - t0;
+  ok('разметка получена, хотя браузер не вышел', typeof dom === 'string' && dom.includes('текст страницы'));
+  ok(`и получена сразу, а не по сроку (${(took / 1000).toFixed(1)} с)`, took < 5000);
+
+  // Ничего не печатает и не уходит. Здесь обязан сработать срок, и вернуться «не измеряли».
+  const silentHang = fake('sleep 60');
+  const t1 = Date.now();
+  const none = await renderedDom('https://example.com/', { chrome: silentHang, timeoutMs: 2500 });
+  const waited = Date.now() - t1;
+  is('молчащий браузер это «не измеряли», а не выдумка', none, null);
+  ok(`и ожидание кончилось в срок (${(waited / 1000).toFixed(1)} с)`, waited >= 2000 && waited < 9000);
+
+  // Напечатал свою страницу ошибки: не мерим.
+  const printsError = fake(`printf '%s' '<html><head><style>/* Copyright The Chromium Authors */</style></head><body><div id="main-frame-error">нет связи</div></body></html>'`);
+  is('страница ошибки не идёт в измерение', await renderedDom('https://example.com/', { chrome: printsError, timeoutMs: 8000 }), null);
+
+  rmSync(dir, { recursive: true, force: true });
+}
+
 if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
 console.log('\nвсе тесты слепоты к скриптам прошли');