@operstack/audit 0.15.4 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.15.4",
+  "version": "0.16.0",
   "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",
@@ -28,7 +28,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node src/test-scores.mjs && node src/test-fix.mjs && node src/test-foundation.mjs && node src/test-narrative.mjs && node src/test-prompts.mjs && node src/test-rendered.mjs && node src/test-agent-surface.mjs && node src/test-agency.mjs && node src/test-i18n.mjs examples/sample-audit.json && node bin/audit.mjs check examples/sample-audit.json && node bin/audit.mjs render examples/sample-audit.json --out /tmp/operstack-audit-sample.html",
+    "test": "node src/test-scores.mjs && node src/test-fix.mjs && node src/test-foundation.mjs && node src/test-narrative.mjs && node src/test-prompts.mjs && node src/test-sitemap.mjs && node src/test-overall.mjs && node src/test-rendered.mjs && node src/test-agent-surface.mjs && node src/test-agency.mjs && node src/test-i18n.mjs examples/sample-audit.json && node bin/audit.mjs check examples/sample-audit.json && node bin/audit.mjs render examples/sample-audit.json --out /tmp/operstack-audit-sample.html",
     "sample": "node bin/audit.mjs render examples/sample-audit.json --pdf"
   },
   "keywords": [

package/src/collect.mjs

@@ -19,7 +19,11 @@ const VERSION = (() => {
 
 const UA = `Mozilla/5.0 (compatible; OperStackAudit/${VERSION}; +https://oper-stack.com)`;
 
-async function get(url, { method = 'GET', timeout = 15000 } = {}) {
+/** Таймаут запроса раньше был зашит числом и наружу не выводился, поэтому поднять его со стороны
+ *  очереди писем было нельзя. Теперь это значение по умолчанию, которое collect() выставляет из опций. */
+let REQUEST_TIMEOUT = 15000;
+
+async function get(url, { method = 'GET', timeout = REQUEST_TIMEOUT } = {}) {
   const c = new AbortController(); const t = setTimeout(() => c.abort(), timeout);
   const started = Date.now();
   try {
@@ -161,21 +165,49 @@ function analysePage(url, html) {
   return { url, title, citedParagraphs, figureParagraphs, titleLength: title.length, description, descriptionLength: description.length, descriptionGarbage: shortcode, h1Count: h1s.length, h1: h1s[0] || '', images: imgs.length, imagesNoAlt: imgsNoAlt, canonical, robots, viewport, og, twitter, generator, hreflang, scripts, stylesheets, schemaTypes: [...new Set(schemaTypes)], words, links, dates, firstPara: firstPara.slice(0, 220), firstParaWords, answerFirst, h2Count, tables, sourcePhrases , telLinks, mailLinks, messengerLinks, contactPages, forms: realForms.length, formFields, formDepth, ctaFirstScreen, trust };
 }
 
-async function readSitemap(url, seen = new Set(), depth = 0) {
-  if (seen.has(url) || depth > 3) return [];
-  seen.add(url);
-  const r = await get(url);
-  if (!r.ok) return [];
-  const locs = [...r.text.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)].map((m) => m[1]);
-  const out = [];
-  for (const l of locs) {
-    if (/\.xml(\.gz)?$/i.test(l) || /sitemap/i.test(l) && !/\.(html?|php)$/i.test(l) && r.text.includes('<sitemapindex')) out.push(...(await readSitemap(l, seen, depth + 1)));
-    else out.push(l);
+/** Карты сайта на живых коммерческих сайтах бывают вложенными десятками: у одного московского
+ *  агентства недвижимости в sitemap.xml лежит 79 вложенных карт. Раньше мы заходили в каждую без
+ *  ограничений, по 15 секунд на запрос, и бесплатная проверка упиралась в таймаут ещё до того, как
+ *  прочитает хоть одну страницу: отчёт приходил пустым или не приходил вовсе.
+ *
+ *  Поэтому три ограничителя: сколько файлов читаем, сколько всего на это тратим и сколько адресов
+ *  набираем. Для выборки в двадцать страниц первых файлов хватает с запасом.
+ *
+ *  Если остановились раньше, это возвращается наружу и попадает в отчёт словами. Выдать часть за
+ *  целое нельзя: «1 200 адресов в карте сайта» на сайте с сорока тысячами адресов это неверное
+ *  измерение, а не округление. */
+async function readSitemap(startUrl, { maxFiles = 6, budgetMs = 45000, maxUrls = 5000, timeout } = {}) {
+  const deadline = Date.now() + budgetMs;
+  const seen = new Set();
+  const queue = [{ url: startUrl, depth: 0 }];
+  const urls = [];
+  let filesRead = 0; let nestedFound = 0; let stopped = '';
+  while (queue.length) {
+    if (filesRead >= maxFiles) { stopped = 'files'; break; }
+    if (Date.now() > deadline) { stopped = 'time'; break; }
+    if (urls.length >= maxUrls) { stopped = 'urls'; break; }
+    const { url, depth } = queue.shift();
+    if (seen.has(url) || depth > 3) continue;
+    seen.add(url);
+    const r = await get(url, timeout ? { timeout } : {});
+    filesRead++;
+    if (!r.ok) continue;
+    // Спускаться вглубь можно только из индекса карт. Прежнее условие из-за приоритета операторов
+    // читало `A || (B && C && D)` и уходило в рекурсию по любой ссылке на .xml, даже из обычного urlset.
+    const isIndex = /<sitemapindex/i.test(r.text);
+    for (const m of r.text.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)) {
+      const l = m[1];
+      if (isIndex && (/\.xml(\.gz)?$/i.test(l) || (/sitemap/i.test(l) && !/\.(html?|php)$/i.test(l)))) { nestedFound += 1; queue.push({ url: l, depth: depth + 1 }); }
+      else urls.push(l);
+    }
   }
-  return out;
+  return { urls, filesRead, nestedFound, pending: queue.length, stopped };
 }
 
-export async function collect(startUrl, { pages = 20, log = () => {}, backlinks = null, lang = 'en', rendered = false, renderedPages = 3, preparedBy = '' } = {}) {
+export const __readSitemap = readSitemap;
+
+export async function collect(startUrl, { pages = 20, log = () => {}, backlinks = null, lang = 'en', rendered = false, renderedPages = 3, preparedBy = '', requestTimeout = 15000, sitemapBudgetMs = 45000, sitemapMaxFiles = 6 } = {}) {
+  REQUEST_TIMEOUT = requestTimeout;
   const opts = { backlinks };
   const origin = new URL(startUrl).origin;
   const host = new URL(startUrl).host;
@@ -226,12 +258,22 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
   log('sitemaps');
   const candidates = sitemapUrls.length ? sitemapUrls : [`${origin}/sitemap.xml`, `${origin}/sitemap_index.xml`, `${origin}/sitemap-index.xml`];
   let sitemapPages = []; let sitemapStatus = 'missing'; let sitemapSource = '';
+  let sitemapRead = { filesRead: 0, nestedFound: 0, pending: 0, stopped: '' };
   for (const u of candidates) {
     const r = await get(u);
-    if (r.ok && /<(urlset|sitemapindex)/.test(r.text)) { sitemapPages = await readSitemap(u); sitemapStatus = 'ok'; sitemapSource = u; break; }
+    if (r.ok && /<(urlset|sitemapindex)/.test(r.text)) {
+      sitemapRead = await readSitemap(u, { budgetMs: sitemapBudgetMs, maxFiles: sitemapMaxFiles });
+      sitemapPages = sitemapRead.urls; sitemapStatus = 'ok'; sitemapSource = u; break;
+    }
     if (sitemapUrls.includes(u)) { sitemapStatus = `HTTP ${r.status}`; sitemapSource = u; }
   }
-  checks.push(row('sitemap', 'technical', 'XML sitemap', sitemapStatus === 'ok' ? 'ok' : 'bad', sitemapStatus === 'ok' ? `${sitemapPages.length} URL(s) in ${sitemapSource}` : sitemapSource ? `${sitemapSource} answers ${sitemapStatus}` : 'no sitemap found at the usual paths', sitemapStatus !== 'ok' && sitemapUrls.length ? 'robots.txt points at a sitemap that does not answer' : ''));
+  // Когда обход остановлен ограничителем, в отчёте стоит число прочитанного, а не выдуманное целое.
+  const sitemapValue = sitemapStatus !== 'ok'
+    ? (sitemapSource ? `${sitemapSource} answers ${sitemapStatus}` : 'no sitemap found at the usual paths')
+    : sitemapRead.stopped
+      ? `${sitemapPages.length} URL(s) read from ${sitemapRead.filesRead} of ${sitemapRead.filesRead + sitemapRead.pending} sitemap file(s) in ${sitemapSource}`
+      : `${sitemapPages.length} URL(s) in ${sitemapSource}`;
+  checks.push(row('sitemap', 'technical', 'XML sitemap', sitemapStatus === 'ok' ? 'ok' : 'bad', sitemapValue, sitemapStatus !== 'ok' && sitemapUrls.length ? 'robots.txt points at a sitemap that does not answer' : sitemapRead.stopped ? 'a large nested sitemap: the pages below were sampled from the files that were read, not from every file' : ''));
   const foreign = sitemapPages.filter((u) => { try { return new URL(u).host !== host && new URL(u).host !== altHost; } catch { return true; } });
   if (foreign.length) checks.push(row('sitemap-foreign', 'technical', 'Sitemap lists other hosts', 'bad', `${foreign.length} URL(s) on other hosts, e.g. ${foreign[0]}`));
 
@@ -407,6 +449,10 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
   checks.push(row('conv-messenger', 'conversion', 'A messenger link', msg.length ? 'ok' : 'warn', msg.length ? `on ${msg.length} of ${pagesForTrust.length} sampled page(s)` : 'none on the sampled pages', msg.length ? '' : 'for an international audience reading on a phone, one messenger link is usually worth more than a form'));
 
   const { scores, scoreBasis } = computeScores(checks);
+
+  // Один балл на весь отчёт: его же берут страница проверки и письмо, чтобы цифры не спорили.
+
+  const overall = computeOverall(checks);
   // Оценки считаются до перевода: язык на цифры не влияет.
   // Сколько текста не видно без выполнения скриптов. Меряется настоящим браузером и только по
   // просьбе: запуск браузера это десятки секунд на страницу, и еженедельному мониторингу это ни к
@@ -433,6 +479,7 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
   return {
     meta: { site: home.final, host, reachable: homeAnswered, collectedAt: new Date().toISOString(), tool: `@operstack/audit ${VERSION}`, auditType: lang === 'ru' ? 'Аудит по публичным сигналам' : 'External audit (no Search Console or analytics access)', lang, language: hp ? (hp.og?.locale || '') : '' },
     client: { name: '{{CLIENT NAME}}', subject: '{{What the site sells and where}}', reportDate: new Date().toISOString().slice(0, 10), preparedBy: preparedBy || process.env.OPERSTACK_PREPARED_BY || 'OperStack' },
+    overall,
     scores,
     scoreBasis,
     summary: { lead: '{{Three sentences: what the site is, what works, what holds it back.}}', verdict: '{{Key takeaway in three sentences, ending with how fast the critical issues can be fixed.}}', priorities: ['{{Priority one}}', '{{Priority two}}', '{{Priority three}}'] },
@@ -498,14 +545,45 @@ function median(a) { const s = [...a].sort((x, y) => x - y); return s.length ? s
  * "not measured", never as a low score. Nothing in a report may be scored by hand.
  */
 export const SCORE_AREAS = [
-  { label: 'SEO, technical', groups: ['technical'] },
-  { label: 'SEO, content and structure', groups: ['onpage', 'content'] },
-  { label: 'AEO, answers and snippets', groups: ['aeo'] },
-  { label: 'GEO, visibility in AI systems', groups: ['geo'] },
-  { label: 'Off-page and trust', groups: ['offpage'] },
-  { label: 'Conversion and UX', groups: ['conversion'] },
+  { label: 'SEO, technical', groups: ['technical'], weight: 20 },
+  { label: 'SEO, content and structure', groups: ['onpage', 'content'], weight: 20 },
+  { label: 'AEO, answers and snippets', groups: ['aeo'], weight: 15 },
+  { label: 'GEO, visibility in AI systems', groups: ['geo'], weight: 20 },
+  { label: 'Off-page and trust', groups: ['offpage'], weight: 15 },
+  { label: 'Conversion and UX', groups: ['conversion'], weight: 10 },
 ];
 
+/**
+ * Один балл из ста на весь продукт.
+ *
+ * 14.09.2026 Максим получил письмо, где в теле стояло «45 из 100», а во вложенном PDF шесть
+ * областей давали 44 из 60, то есть 73 процента. Человек читает в одном документе «ужас» и «почти
+ * всё хорошо» и делает единственный возможный вывод: цифры выдуманы. Считали их два разных движка
+ * с разными рамками, и это обесценивало оба продукта сразу.
+ *
+ * Поэтому балл считается здесь и только здесь, а страница проверки, письмо и отчёт берут его
+ * отсюда. Веса ниже это решение, а не измерение, и поэтому они напечатаны в самом отчёте: покупатель
+ * должен уметь пересчитать цифру руками, а не верить ей на слово.
+ *
+ * Область, которую этот прогон не измерял, не штрафуется и не считается за ноль: её вес выкидывается
+ * из знаменателя, и отчёт говорит, из чего именно сложился балл. Ноль за неизмеренное это враньё,
+ * ровно как «0 знаков» вместо «описания нет».
+ */
+export function computeOverall(checks) {
+  const { scores, scoreBasis } = computeScores(checks);
+  const parts = SCORE_AREAS
+    .map((a) => ({ label: a.label, weight: a.weight, score: scores[a.label], basis: scoreBasis[a.label] }))
+    .filter((p) => p.score !== null && p.score !== undefined);
+  const weighed = parts.reduce((sum, p) => sum + p.weight, 0);
+  if (!weighed) return { score: null, grade: 'not measured', weighed: 0, parts: [], note: 'nothing was measured, so there is no score' };
+  const score = Math.round(parts.reduce((sum, p) => sum + (p.score / 10) * p.weight, 0) / weighed * 100);
+  const grade = score >= 80 ? 'strong' : score >= 60 ? 'workable' : score >= 40 ? 'weak' : 'critical';
+  const note = weighed === 100
+    ? `weighted from all ${parts.length} areas`
+    : `weighted from ${parts.length} of ${SCORE_AREAS.length} areas: ${weighed} of 100 points were measurable on this site`;
+  return { score, grade, weighed, parts, note };
+}
+
 /**
  * Score every area from the collected checks: ok 1, warn 0.5, bad 0, na ignored, rounded to 0-10.
  * Returns the scores and the count each one came from, so the report can print its own evidence.
@@ -534,6 +612,18 @@ export function verifyScores(audit) {
   const { scores } = computeScores(audit.checks || []);
   const show = (v) => (v === null || v === undefined ? 'not measured' : `${v}/10`);
   const problems = [];
+  // Общий балл проверяется первым: именно он стоит в заголовке отчёта, в письме и на странице,
+  // и именно он обесценивает всё остальное, если разойдётся со своими же проверками.
+  //
+  // Сверяем только когда поле есть. Отчёт, собранный версией до 0.16.0, его не содержит, и это не
+  // ложь, а старый формат: в вёрстке заголовок всё равно считается из проверок этого же файла,
+  // поэтому отсутствие поля не может напечатать неверное число.
+  if (audit.overall && audit.overall.score !== undefined) {
+    const overall = computeOverall(audit.checks || []);
+    const stored = audit.overall.score;
+    const show = (v) => (v === null || v === undefined ? 'not measured' : `${v}/100`);
+    if (stored !== overall.score) problems.push(`overall: the report says ${show(stored)}, the checks give ${show(overall.score)}`);
+  }
   for (const [label, expected] of Object.entries(scores)) {
     const stored = (audit.scores || {})[label];
     const actual = stored === undefined ? null : stored;

package/src/i18n.mjs

@@ -69,7 +69,15 @@ const RU = {
   },
   sitemap: {
     label: 'Карта сайта XML',
-    value: (v) => (/URL\(s\) in/.test(v) ? `${plural(Number(nums(v)[0]), 'адрес', 'адреса', 'адресов')} в карте сайта` : /not found|missing/i.test(v) ? 'не найдена' : `не отдаётся, код ${nums(v)[0]}`),
+    // Обход больших вложенных карт останавливается ограничителем, и по-русски это надо сказать
+    // словами, иначе прочитанная часть выглядит как полное измерение.
+    value: (v) => {
+      const n = nums(v);
+      if (/read from/.test(v)) return `${plural(Number(n[0]), 'адрес', 'адреса', 'адресов')} прочитано из ${n[1]} файлов карты, всего файлов ${n[2]}`;
+      if (/URL\(s\) in/.test(v)) return `${plural(Number(n[0]), 'адрес', 'адреса', 'адресов')} в карте сайта`;
+      if (/not found|missing/i.test(v)) return 'не найдена';
+      return `не отдаётся, код ${n[0]}`;
+    },
   },
   'sitemap-foreign': { label: 'В карте сайта чужие хосты', value: (v) => `${plural(Number(nums(v)[0]), 'адрес', 'адреса', 'адресов')} на других хостах` },
   'sitemap-health': { label: 'Адреса из карты сайта отвечают 200', value: (v) => { const n = nums(v); return `${n[0]} из ${n[1]} проверенных адресов отвечают 200${/redirect/.test(v) ? `, ${n[2]} перенаправляют` : ''}${/broken/.test(v) ? ', есть битые' : ''}`; } },

package/src/index.mjs

@@ -1,4 +1,4 @@
-export { collect, computeScores, verifyScores, SCORE_AREAS } from './collect.mjs';
+export { collect, computeScores, computeOverall, verifyScores, SCORE_AREAS } from './collect.mjs';
 export { render, checkNarrative } from './render.mjs';
 export { localiseChecks, localiseBasisNote, untranslated, AREAS_RU } from './i18n.mjs';
 export { buildFixPlan, renderFixPlan, renderFixChecklist, buildFixReport, renderFixReport, FIX_ACTIONS } from './fix.mjs';

package/src/render.mjs

@@ -7,7 +7,7 @@ import { writeFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { computeScores } from './collect.mjs';
+import { computeScores, computeOverall } from './collect.mjs';
 import { localiseBasisNote, AREAS_RU } from './i18n.mjs';
 import { softenHex } from './agency.mjs';
 
@@ -25,6 +25,13 @@ const LABELS = {
     secSummary: 'Executive summary', summaryEyebrow: '01 · Summary', keyTakeaway: 'Key takeaway:', threePriorities: 'Three priorities',
     scorecardFoot: 'Each score counts the checks in this report: a check that passes scores one, a check that needs attention a half, a failing check nothing. An area marked <strong>not measured</strong> is an area this audit does not test, and is never scored on an impression. Every figure here can be recomputed from section 04 onwards.',
     notMeasured: 'not measured',
+    overallLabel: 'Overall score',
+    grades: { strong: 'Strong', workable: 'Workable', weak: 'Weak', critical: 'Critical' },
+    // Веса это решение, а не измерение, поэтому они напечатаны здесь: балл должен пересчитываться руками.
+    overallNote: (o) => `Weighted from the areas below: ${o.parts.map((x) => `${x.label} ${x.weight}`).join(', ')}. `
+      + (o.weighed === 100
+        ? 'Every area was measurable on this site.'
+        : `Only ${o.weighed} of 100 points were measurable here, so the areas this audit could not read are left out of the total rather than scored zero.`),
     secOverview: 'Site overview', overviewEyebrow: '02 · Overview', whatSiteIs: 'What the site is', parameter: 'Parameter', value: 'Value', pagesSampled: 'Pages sampled', colUrl: 'URL', colTitle: 'Title', colWords: 'Words',
     secCritical: 'Critical issues', criticalEyebrow: '03 · P0', criticalTitle: 'Critical issues, fix first', whatItCosts: 'What it costs', theFix: 'Fix', noBody: 'This issue has no description in the audit file.', noCritical: 'No critical defects were found in the public signals.',
     secTechnical: 'Technical SEO', technicalEyebrow: '04 · Technical', technicalTitle: 'Technical and on-page checklist', colCheck: 'Check', colStatus: 'Status', colFinding: 'Finding',
@@ -48,6 +55,12 @@ const LABELS = {
     secSummary: 'Главное', summaryEyebrow: '01 · Итог', keyTakeaway: 'Главный вывод:', threePriorities: 'Три приоритета',
     scorecardFoot: 'Каждая оценка считает проверки из этого же отчёта: пройденная проверка это балл, спорная половина балла, проваленная ноль. Область с пометкой <strong>не измерялось</strong> это область, которую аудит не проверяет, и она никогда не оценивается на глаз. Любую цифру отсюда можно пересчитать по разделам начиная с четвёртого.',
     notMeasured: 'не измерялось',
+    overallLabel: 'Общий балл',
+    grades: { strong: 'Сильно', workable: 'Рабочее состояние', weak: 'Слабо', critical: 'Критично' },
+    overallNote: (o) => `Взвешен по областям ниже: ${o.parts.map((x) => `${AREAS_RU[x.label] || x.label} ${x.weight}`).join(', ')}. `
+      + (o.weighed === 100
+        ? 'Все области на этом сайте удалось измерить.'
+        : `Измеримыми здесь оказались ${o.weighed} ${ruPoints(o.weighed)} из 100, поэтому области, которые аудит прочитать не смог, не попали в знаменатель, а не получили ноль.`),
     secOverview: 'О сайте', overviewEyebrow: '02 · Обзор', whatSiteIs: 'Что это за сайт', parameter: 'Параметр', value: 'Значение', pagesSampled: 'Проверенные страницы', colUrl: 'Адрес', colTitle: 'Заголовок', colWords: 'Слов',
     secCritical: 'Критичное', criticalEyebrow: '03 · Срочно', criticalTitle: 'Что чинить первым', whatItCosts: 'Чем это грозит', theFix: 'Как чинится', noBody: 'У этой проблемы нет описания в файле аудита.', noCritical: 'Критичных дефектов в публичных сигналах не найдено.',
     secTechnical: 'Техническое SEO', technicalEyebrow: '04 · Техника', technicalTitle: 'Техническая проверка и страницы', colCheck: 'Проверка', colStatus: 'Статус', colFinding: 'Что нашли',
@@ -68,6 +81,9 @@ const LABELS = {
 const STATUS_KEYS = { ok: 'statusOk', warn: 'statusWarn', bad: 'statusBad', na: 'statusNa' };
 const STATUS_CLASS = { ok: 'status-ok', warn: 'status-warn', bad: 'status-bad', na: 'status-na' };
 const STATUS_UNUSED = { ok: ['✓ OK', 'status-ok'], warn: ['△ Partial', 'status-warn'], bad: ['✗ Problem', 'status-bad'], na: ['· Note', 'status-na'] };
+/** Склонение «балл» для русской подписи под общим баллом: 21 балл, 72 балла, 75 баллов. */
+const ruPoints = (n) => { const a = Math.abs(n) % 100; const b = a % 10; if (a > 10 && a < 20) return 'баллов'; if (b === 1) return 'балл'; if (b >= 2 && b <= 4) return 'балла'; return 'баллов'; };
+
 const scoreClass = (n) => (n === null || n === undefined ? '' : n <= 3 ? 'low' : n <= 6 ? 'mid' : 'ok');
 
 export function checkNarrative(audit) {
@@ -110,6 +126,13 @@ function css() {
   .page-header { display: flex; justify-content: space-between; align-items: center; padding-bottom: 3mm; margin-bottom: 6mm; border-bottom: 1px solid var(--rule); font-size: 8pt; color: var(--muted); }
   .page-header strong { color: var(--accent); }
   .page-footer { position: absolute; bottom: 9mm; left: var(--pad); right: var(--pad); display: flex; justify-content: space-between; font-size: 8pt; color: var(--muted); border-top: 1px solid var(--rule); padding-top: 2.5mm; }
+  .overall { display: flex; align-items: center; gap: 6mm; border: 1px solid var(--rule); border-radius: 5px; padding: 5mm 6mm; background: #f4f8f8; margin: 5mm 0 4mm; }
+  .overall-num { font-family: "Fraunces", Georgia, serif; font-size: 44pt; font-weight: 600; line-height: 1; color: var(--accent); font-variant-numeric: tabular-nums; }
+  .overall-num span { font-size: 18pt; color: var(--muted); }
+  .overall-num.low { color: var(--danger); } .overall-num.mid { color: var(--warn); } .overall-num.ok { color: var(--ok); }
+  .overall-label { font-size: 8pt; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); }
+  .overall-grade { font-family: "Fraunces", Georgia, serif; font-size: 15pt; font-weight: 600; margin: 1mm 0 1.5mm; }
+  .overall-note { font-size: 8.5pt; color: var(--muted); line-height: 1.45; }
   .scorecard { display: grid; grid-template-columns: 1fr 1fr; gap: 3mm; margin: 5mm 0 6mm; }
   .score { border: 1px solid var(--rule); border-radius: 4px; padding: 3.5mm 4mm; background: #fafbfb; }
   .score .label { font-size: 8pt; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); margin-bottom: 1.5mm; }
@@ -157,6 +180,15 @@ export function toHtml(audit, brand = null) {
   const groups = [['technical', 'Technical'], ['onpage', 'On-page'], ['content', 'Content'], ['aeo', 'Answer engines'], ['geo', 'Generative engines'], ['offpage', 'Off-page and trust'], ['conversion', 'Conversion'], ['overview', 'Overview']];
   const checksBy = (g) => (a.checks || []).filter((c) => c.group === g);
   const { scores: measured, scoreBasis } = computeScores(a.checks || []);
+  // Один балл на весь отчёт стоит заголовком, шесть областей под ним расшифровкой. До 14.09.2026
+  // в письме и в PDF стояли числа из двух разных движков, и читатель делал единственный возможный
+  // вывод: цифры выдуманы. Веса печатаются рядом, чтобы балл можно было пересчитать руками.
+  const overall = computeOverall(a.checks || []);
+  const overallBlock = 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[overall.grade] || overall.grade)}</div>
+      <div class="overall-note">${esc(L.overallNote(overall))}</div></div></div>`;
   const scoreCards = Object.entries(measured).map(([label, n]) => {
     const basis = scoreBasis[label] || {};
     const shown = (L.areas && L.areas[label]) || label;
@@ -177,7 +209,7 @@ export function toHtml(audit, brand = null) {
     <dl class="cover-meta"><div><dt>${L.auditSubject}</dt><dd>${t(a.client.name)}</dd></div><div><dt>${L.reportDate}</dt><dd>${esc(a.client.reportDate)}</dd></div><div><dt>${L.auditType}</dt><dd>${esc(a.meta.auditType)}</dd></div><div><dt>${L.preparedBy}</dt><dd>${esc(preparedBy)}</dd></div></dl></div>
     ${toolLine}</div></div>`);
   n++;
-  pages.push(`<div class="page">${header(a, L.secSummary, L)}<div class="eyebrow">${L.summaryEyebrow}</div><h2>${L.secSummary}</h2><p class="lead">${t(a.summary.lead)}</p><div class="scorecard">${scoreCards}</div><p class="scorecard-foot">${L.scorecardFoot}</p><div class="verdict"><p><strong>${L.keyTakeaway}</strong> ${t(a.summary.verdict)}</p></div><h3>${L.threePriorities}</h3>${olist(a.summary.priorities)}${footer(a, n++, preparedBy)}</div>`);
+  pages.push(`<div class="page">${header(a, L.secSummary, L)}<div class="eyebrow">${L.summaryEyebrow}</div><h2>${L.secSummary}</h2><p class="lead">${t(a.summary.lead)}</p>${overallBlock}<div class="scorecard">${scoreCards}</div><p class="scorecard-foot">${L.scorecardFoot}</p><div class="verdict"><p><strong>${L.keyTakeaway}</strong> ${t(a.summary.verdict)}</p></div><h3>${L.threePriorities}</h3>${olist(a.summary.priorities)}${footer(a, n++, preparedBy)}</div>`);
   pages.push(`<div class="page">${header(a, L.secOverview, L)}<div class="eyebrow">${L.overviewEyebrow}</div><h2>${L.whatSiteIs}</h2><table><tr><th>${L.parameter}</th><th>${L.value}</th></tr>${(a.overview.rows || []).map(([k, v]) => `<tr><td>${t(k)}</td><td>${t(v)}</td></tr>`).join('')}</table><p>${t(a.overview.note)}</p><h3>${L.pagesSampled}</h3><table><tr><th>${L.colUrl}</th><th>${L.colTitle}</th><th>${L.colWords}</th><th>H1</th><th>Alt</th></tr>${(a.sample || []).filter((p) => p.title !== undefined).slice(0, 14).map((p) => `<tr><td><code>${esc(new URL(p.url).pathname)}</code></td><td>${esc(p.title)}</td><td>${p.words}</td><td>${p.h1Count}</td><td>${p.images ? `${p.images - p.imagesNoAlt}/${p.images}` : '·'}</td></tr>`).join('')}</table>${footer(a, n++, preparedBy)}</div>`);
   const cardBody = (c) => [
     c.text ? `<p>${t(c.text)}</p>` : '',

package/src/test-overall.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/** Один балл из ста: и в объекте аудита, и в отчёте, и на обоих языках.
+ *
+ *  14.09.2026 человек получил письмо с «45 из 100» и приложенный PDF, где шесть областей давали
+ *  44 из 60, то есть 73 процента. Два разных движка в одном документе читаются как выдуманные
+ *  цифры. Эти тесты держат единственный источник балла и запрет считать неизмеренное нулём. */
+import { readFileSync } from 'node:fs';
+import { computeOverall, computeScores, verifyScores, SCORE_AREAS } from './collect.mjs';
+import { toHtml } from './render.mjs';
+
+let bad = 0;
+const ok = (n, c) => { if (c) console.log(`ok   ${n}`); else { bad++; console.error(`FAIL ${n}`); } };
+const is = (n, a, b) => ok(`${n} (ждали ${JSON.stringify(b)}, вышло ${JSON.stringify(a)})`, JSON.stringify(a) === JSON.stringify(b));
+
+const c = (group, status, i = 0) => ({ id: `${group}-${status}-${i}`, group, status, label: group, value: 'x' });
+
+// Веса это решение, а не измерение, но сумма обязана быть сотней, иначе балл не из ста.
+is('веса дают ровно сто', SCORE_AREAS.reduce((s, a) => s + a.weight, 0), 100);
+
+// Всё пройдено это сто, всё провалено это ноль.
+const every = (status) => SCORE_AREAS.flatMap((a) => a.groups.map((g) => c(g, status)));
+is('все проверки пройдены: сто', computeOverall(every('ok')).score, 100);
+is('все проверки провалены: ноль', computeOverall(every('bad')).score, 0);
+is('все спорные: половина', computeOverall(every('warn')).score, 50);
+
+// Неизмеренная область выкидывается из знаменателя, а не получает ноль. Ноль за то, чего не
+// мерили, это неверное измерение, ровно как «0 знаков» вместо «описания у страницы нет».
+{
+  const partial = [c('technical', 'ok'), c('geo', 'ok')];
+  const o = computeOverall(partial);
+  is('измеренное на отлично даёт сто даже при неполном покрытии', o.score, 100);
+  is('в знаменатель попали только измеренные веса', o.weighed, 40);
+  ok('и отчёт об этом говорит', /40 of 100 points were measurable/.test(o.note));
+  ok('неизмеренные области в разбивку не попали', o.parts.length === 2);
+}
+
+// Пустой аудит не выдаёт ноль: нечего мерить это не то же самое, что всё плохо.
+{
+  const o = computeOverall([]);
+  is('пустой набор проверок не даёт нуля', o.score, null);
+  is('и называется неизмеренным', o.grade, 'not measured');
+}
+
+// Проверки со статусом na не считаются ни в плюс, ни в минус.
+{
+  const withNa = [c('technical', 'ok'), { ...c('technical', 'na'), status: 'na' }];
+  is('na не портит и не улучшает балл', computeOverall(withNa).score, 100);
+}
+
+// Балл в отчёте обязан сходиться с проверками этого же отчёта.
+{
+  const audit = JSON.parse(readFileSync(new URL('../examples/sample-audit.json', import.meta.url), 'utf8'));
+  const o = computeOverall(audit.checks || []);
+  audit.overall = o;
+  const problems = verifyScores(audit);
+  ok('честный отчёт проходит проверку', !problems.some((p) => p.startsWith('overall')));
+  audit.overall = { ...o, score: (o.score + 7) % 101 };
+  ok('подделанный балл ловится', verifyScores(audit).some((p) => p.startsWith('overall')));
+}
+
+// Оба языка. Сегодня дважды чинили русскую ветку и оставляли английскую сломанной.
+{
+  const audit = JSON.parse(readFileSync(new URL('../examples/sample-audit.json', import.meta.url), 'utf8'));
+  const expected = computeOverall(audit.checks || []).score;
+  for (const [lang, grade, note] of [['en', /Strong|Workable|Weak|Critical/, /Weighted from the areas below/], ['ru', /Сильно|Рабочее состояние|Слабо|Критично/, /Взвешен по областям ниже/]]) {
+    audit.meta.lang = lang;
+    const html = toHtml(audit, null);
+    const num = (html.match(/overall-num[^>]*>(\d+)<span>/) || [])[1];
+    is(`${lang}: в отчёте стоит тот же балл, что считают проверки`, Number(num), expected);
+    ok(`${lang}: оценка словом на своём языке`, grade.test((html.match(/overall-grade">([^<]*)</) || [])[1] || ''));
+    ok(`${lang}: веса напечатаны, балл можно пересчитать руками`, note.test(html));
+    ok(`${lang}: в подписи нет чужого языка`, lang === 'en'
+      ? !/[А-Яа-яЁё]/.test((html.match(/overall-note">([^<]*)</) || [])[1] || '')
+      : !/Weighted|measurable/.test((html.match(/overall-note">([^<]*)</) || [])[1] || ''));
+  }
+  // Русское склонение: 75 баллов, а не 75 балла.
+  audit.meta.lang = 'ru';
+  ok('русское склонение «баллов» верное', !/\d+ балла из 100/.test(toHtml(audit, null)));
+}
+
+// Шесть областей никуда не делись: общий балл их дополняет, а не заменяет.
+{
+  const audit = JSON.parse(readFileSync(new URL('../examples/sample-audit.json', import.meta.url), 'utf8'));
+  const { scores } = computeScores(audit.checks || []);
+  const html = toHtml(audit, null);
+  ok('разбивка по областям осталась под общим баллом', Object.keys(scores).every((k) => html.includes('/10') || scores[k] === null));
+}
+
+if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
+console.log('\nвсе тесты общего балла прошли');

package/src/test-sitemap.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/** Обход карт сайта: ограничители и честность отчёта.
+ *
+ *  14.09.2026 бесплатная проверка не собрала отчёт по whitewill.ru. В его sitemap.xml 79 вложенных
+ *  карт, обход заходил в каждую по 15 секунд, и прогон умирал по таймауту, не дочитав до страниц.
+ *  Тесты поднимают такой же сайт локально, чтобы это не вернулось. */
+import { createServer } from 'node:http';
+import { __readSitemap } from './collect.mjs';
+import { localiseChecks } from './i18n.mjs';
+
+let bad = 0;
+const ok = (n, c) => { if (c) console.log(`ok   ${n}`); else { bad++; console.error(`FAIL ${n}`); } };
+const is = (n, a, b) => ok(`${n} (ждали ${JSON.stringify(b)}, вышло ${JSON.stringify(a)})`, JSON.stringify(a) === JSON.stringify(b));
+
+const index = (hrefs) => `<?xml version="1.0"?><sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${hrefs.map((h) => `<sitemap><loc>${h}</loc></sitemap>`).join('')}</sitemapindex>`;
+const urlset = (hrefs) => `<?xml version="1.0"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${hrefs.map((h) => `<url><loc>${h}</loc></url>`).join('')}</urlset>`;
+
+/** Сервер отвечает медленно, как настоящий сайт на другом континенте. */
+const start = (delayMs, nested) => new Promise((resolve) => {
+  const server = createServer(async (req, res) => {
+    if (delayMs) await new Promise((r) => setTimeout(r, delayMs));
+    const base = `http://127.0.0.1:${server.address().port}`;
+    res.setHeader('content-type', 'application/xml');
+    if (req.url === '/sitemap.xml') return res.end(index(Array.from({ length: nested }, (_, i) => `${base}/map-${i}.xml`)));
+    if (req.url === '/plain.xml') return res.end(urlset([`${base}/page`, `${base}/feed.xml`]));
+    const i = (req.url.match(/map-(\d+)/) || [])[1] ?? '0';
+    return res.end(urlset([`${base}/p-${i}-a`, `${base}/p-${i}-b`]));
+  });
+  server.listen(0, '127.0.0.1', () => resolve({ server, base: `http://127.0.0.1:${server.address().port}` }));
+});
+
+// 1. Семьдесят девять вложенных карт: читаем несколько файлов, а не все, и говорим об этом.
+{
+  const { server, base } = await start(30, 79);
+  const began = Date.now();
+  const r = await __readSitemap(`${base}/sitemap.xml`, { maxFiles: 6, budgetMs: 45000 });
+  const took = Date.now() - began;
+  is('прочитано ровно столько файлов, сколько разрешено', r.filesRead, 6);
+  is('остановились по числу файлов', r.stopped, 'files');
+  is('нашли все вложенные карты', r.nestedFound, 79);
+  ok('непрочитанные файлы посчитаны', r.pending === 74);
+  ok('адресов хватает на выборку страниц', r.urls.length >= 10);
+  ok(`уложились в разумное время (${took} мс)`, took < 5000);
+  server.close();
+}
+
+// 2. Маленький сайт читается целиком, и тогда про ограничители в отчёте ни слова.
+{
+  const { server, base } = await start(0, 2);
+  const r = await __readSitemap(`${base}/sitemap.xml`);
+  is('маленькая карта прочитана целиком', r.stopped, '');
+  is('файлов прочитано: индекс и две карты', r.filesRead, 3);
+  is('собраны все адреса', r.urls.length, 4);
+  server.close();
+}
+
+// 3. Из обычного urlset вглубь не спускаемся, даже если адрес заканчивается на .xml.
+//    Прежнее условие из-за приоритета операторов читало `A || (B && C && D)` и уходило в рекурсию.
+{
+  const { server, base } = await start(0, 2);
+  const r = await __readSitemap(`${base}/plain.xml`);
+  is('из urlset рекурсии нет', r.filesRead, 1);
+  is('ссылка на .xml осталась адресом страницы', r.urls.length, 2);
+  server.close();
+}
+
+// 4. Общий бюджет времени соблюдается, даже если файлов мало, а сайт медленный.
+{
+  const { server, base } = await start(200, 40);
+  const began = Date.now();
+  const r = await __readSitemap(`${base}/sitemap.xml`, { maxFiles: 100, budgetMs: 700 });
+  const took = Date.now() - began;
+  is('остановились по времени', r.stopped, 'time');
+  ok(`бюджет времени соблюдён (${took} мс)`, took < 2500);
+  server.close();
+}
+
+// 5. По-русски усечённый обход называется словами, а не «не отдаётся, код 1200».
+//    Локализатор подбирает строку регулярным выражением, поэтому новая формулировка без своей
+//    ветки молча проваливается в числовую. Ровно это уже случалось с нулями в отчёте.
+{
+  const en = [{ id: 'sitemap', group: 'technical', label: 'XML sitemap', status: 'ok', value: '1200 URL(s) read from 6 of 79 sitemap file(s) in https://example.ru/sitemap.xml', comment: '' }];
+  const ru = localiseChecks(en, 'ru')[0].value;
+  ok(`усечение названо словами: "${ru}"`, /прочитано из 6 файлов карты, всего файлов 79/.test(ru));
+  ok('и это не выдано за код ответа', !/не отдаётся/.test(ru));
+  const whole = localiseChecks([{ ...en[0], value: '1200 URL(s) in https://example.ru/sitemap.xml' }], 'ru')[0].value;
+  ok(`целая карта по-прежнему читается нормально: "${whole}"`, /в карте сайта/.test(whole));
+}
+
+if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
+console.log('\nвсе тесты обхода карт прошли');