@operstack/audit 0.17.0 → 0.17.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "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

@@ -207,7 +207,7 @@ async function readSitemap(startUrl, { maxFiles = 6, budgetMs = 45000, maxUrls =
 
 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 } = {}) {
+export async function collect(startUrl, { pages = 20, log = () => {}, backlinks = null, lang = 'en', rendered = false, renderedPages = 3, preparedBy = '', visibility: givenVisibility = null, requestTimeout = 15000, sitemapBudgetMs = 45000, sitemapMaxFiles = 6 } = {}) {
   REQUEST_TIMEOUT = requestTimeout;
   const opts = { backlinks };
   const origin = new URL(startUrl).origin;
@@ -483,11 +483,31 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
    * тут больше страниц или времени, и число снова разойдётся со страницей. Глубина аудита живёт в
    * его собственных шести областях и в списке задач, а не в этом числе.
    */
-  log('visibility score');
-  const visibility = await checkVisibility(startUrl, { ...VISIBILITY_DEFAULTS, lang });
-  const overall = visibility.ok
-    ? { score: visibility.score, grade: visibility.grade, areas: visibility.areas, source: 'visibility', ms: visibility.ms }
-    : { score: null, grade: 'not measured', areas: [], source: 'visibility', error: visibility.error };
+  /*
+   * Если балл уже измерен, второй раз не меряем.
+   *
+   * Живая сверка 14.09.2026 на whitewill.ru дала 47 и 44 в двух прогонах подряд, а на habr.com
+   * один прогон вернул отказ. Код один и тот же, разная только удача сети: бюджет у проверки
+   * 8,5 секунды, и на медленном сайте карта сайта то успевает прочитаться, то нет, а движок
+   * честно не штрафует за непрочитанное. Два измерения одного сайта дают два числа, и покупателю
+   * всё равно, что оба честные: он видит 44 на странице и 47 в письме.
+   *
+   * Поэтому в воронке балл измеряется РОВНО ОДИН РАЗ, на странице, и приезжает сюда готовым
+   * через опцию `visibility`. Тогда страница, письмо и отчёт несут одно число по построению,
+   * а не по совпадению. Меряем сами только когда аудит запускают отдельно и мерить больше некому.
+   */
+  let visibility = givenVisibility;
+  if (visibility) log('visibility score: taken from the check the visitor already ran');
+  else { log('visibility score'); visibility = await checkVisibility(startUrl, { ...VISIBILITY_DEFAULTS, lang }); }
+  const measuredAt = visibility && visibility.checkedAt ? visibility.checkedAt : null;
+  /* Из чего сложился балл, словами для отчёта: сколько страниц прочитано и дочиталась ли карта
+   * сайта. Без этого подпись под баллом обещает точность, которой у восьмисекундной проверки нет. */
+  const basis = visibility && visibility.ok
+    ? { pages: (visibility.sample || []).length, sitemapRead: Boolean(visibility.sitemap && visibility.sitemap.found), sitemapUnchecked: Boolean(visibility.sitemap && visibility.sitemap.unchecked) }
+    : null;
+  const overall = visibility && visibility.ok
+    ? { score: visibility.score, grade: visibility.grade, areas: visibility.areas, basis, source: givenVisibility ? 'visibility:reused' : 'visibility', measuredAt, ms: visibility.ms }
+    : { score: null, grade: 'not measured', areas: [], basis: null, source: givenVisibility ? 'visibility:reused' : 'visibility', error: (visibility && visibility.error) || 'no visibility result' };
   // Шесть областей отчёта остаются, но это другое измерение, а не разбивка общего балла.
   const reportScore = computeOverall(checks);
 

package/src/render.mjs

@@ -29,7 +29,15 @@ const LABELS = {
     grades: { A: 'Strong', B: 'Workable', C: 'Weak', D: 'Poor', E: 'Critical' },
     // Заголовок это то же измерение, что на странице проверки. Подпись обязана это говорить,
     // иначе читатель снова начнёт сводить его с шестью областями ниже.
-    overallNote: 'The same measurement the free check at oper-stack.com/ai-visibility gives for this site: the same code, the same settings. The five areas below add up to it exactly, so you can recompute it by hand.',
+    // Подпись обязана сказать три вещи: откуда число, что именно успели прочитать, и почему
+    // повтор может дать на пункт-другой иначе. Без последнего человек читает разницу как ошибку.
+    overallNote: (o) => {
+      const read = o.basis ? `It was read from ${o.basis.pages} page${o.basis.pages === 1 ? '' : 's'} of the site${o.basis.sitemapUnchecked ? ', and the sitemap did not answer in time, which is not counted against the score either way' : o.basis.sitemapRead ? ' and its sitemap' : ''}. ` : '';
+      const where = o.source === 'visibility:reused'
+        ? `This is the same figure you already saw on the free check${o.measuredAt ? ` on ${String(o.measuredAt).slice(0, 10)}` : ''}. It is not measured again here, so the page, the email and this report always carry one number. `
+        : 'Measured here by the same code and the same settings as the free check at oper-stack.com/ai-visibility. ';
+      return `${where}${read}The five areas below add up to it exactly, so you can recompute it by hand. Running the check again can move it by a point or two: a check that answers in time on one run may not on the next, and this score never counts against a site what it could not read.`;
+    },
     secondMeasure: 'A second, separate measurement: how this report scores its own checks',
     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.',
@@ -56,7 +64,15 @@ const LABELS = {
     notMeasured: 'не измерялось',
     overallLabel: 'Балл видимости в ИИ',
     grades: { A: 'Сильно', B: 'Рабочее состояние', C: 'Слабо', D: 'Плохо', E: 'Критично' },
-    overallNote: 'То же измерение, что даёт бесплатная проверка на oper-stack.com/ai-visibility для этого сайта: тот же код, те же настройки. Пять областей ниже дают в сумме ровно этот балл, его можно сложить руками.',
+    overallNote: (o) => {
+      const p = o.basis ? o.basis.pages : 0;
+      const pl = ruPages(p);
+      const read = o.basis ? `Прочитано ${p} ${pl} сайта${o.basis.sitemapUnchecked ? ', а карта сайта не ответила вовремя, и это не зачтено ни в плюс, ни в минус' : o.basis.sitemapRead ? ' и его карта' : ''}. ` : '';
+      const where = o.source === 'visibility:reused'
+        ? `Это ровно то число, которое вы уже видели в бесплатной проверке${o.measuredAt ? ` ${String(o.measuredAt).slice(0, 10)}` : ''}. Здесь оно не меряется заново, поэтому страница, письмо и этот отчёт всегда несут одно число. `
+        : 'Измерено здесь тем же кодом и с теми же настройками, что у бесплатной проверки на oper-stack.com/ai-visibility. ';
+      return `${where}${read}Пять областей ниже дают в сумме ровно этот балл, его можно сложить руками. Повторная проверка может дать на пункт-другой иначе: проверка, которая успела ответить в один прогон, может не успеть в следующий, а балл никогда не засчитывает сайту в минус то, что не удалось прочитать.`;
+    },
     secondMeasure: 'Второе, отдельное измерение: как этот отчёт оценивает собственные проверки',
     secOverview: 'О сайте', overviewEyebrow: '02 · Обзор', whatSiteIs: 'Что это за сайт', parameter: 'Параметр', value: 'Значение', pagesSampled: 'Проверенные страницы', colUrl: 'Адрес', colTitle: 'Заголовок', colWords: 'Слов',
     secCritical: 'Критичное', criticalEyebrow: '03 · Срочно', criticalTitle: 'Что чинить первым', whatItCosts: 'Чем это грозит', theFix: 'Как чинится', noBody: 'У этой проблемы нет описания в файле аудита.', noCritical: 'Критичных дефектов в публичных сигналах не найдено.',
@@ -78,6 +94,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'] };
+/** Склонение «страница»: 1 страница, 4 страницы, 5 страниц. Подпись под баллом читает человек. */
+const ruPages = (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 'страниц'; };
+
 /** Склонение «балл» для русской подписи под общим баллом: 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 'баллов'; };
 
@@ -198,7 +217,7 @@ export function toHtml(audit, brand = null) {
     <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)}</div></div></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 scoreCards = Object.entries(measured).map(([label, n]) => {
     const basis = scoreBasis[label] || {};

package/src/test-overall.mjs

@@ -107,6 +107,85 @@ ok('параметры нельзя поменять на ходу', Object.isFr
   }
 }
 
+/*
+ * Балл, уже измеренный на странице, приезжает в отчёт готовым и не перемеряется.
+ *
+ * Живая сверка 14.09.2026: whitewill.ru дал 47 и 44 в двух прогонах подряд, habr.com в одном
+ * прогоне вернул отказ. Тот же код, разная удача сети: бюджет 8,5 секунды, и карта сайта то
+ * успевает прочитаться, то нет. Покупателю всё равно, что оба числа честные, он видит два разных.
+ * Поэтому в воронке измерение происходит один раз.
+ */
+{
+  const server = createServer((req, res) => {
+    res.setHeader('content-type', 'text/html');
+    res.end('<!doctype html><html><head><title>Local</title></head><body><h1>Local</h1><p>Text.</p></body></html>');
+  });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const base = `http://127.0.0.1:${server.address().port}/`;
+
+  const fromPage = { ok: true, score: 63, grade: 'B', checkedAt: '2026-09-14T20:00:00.000Z', ms: 4200, areas: [
+    { id: 'access', label: 'Access for AI crawlers', score: 25, max: 25 },
+    { id: 'index', label: 'Agent index', score: 10, max: 15 },
+    { id: 'entity', label: 'Entity and structure', score: 12, max: 20 },
+    { id: 'content', label: 'Answer-first content', score: 11, max: 25 },
+    { id: 'trust', label: 'Freshness and sources', score: 5, max: 15 }] };
+
+  const audit = await collect(base, { pages: 2, log: () => {}, visibility: fromPage });
+  server.close();
+
+  is('готовый балл берётся как есть', audit.overall.score, 63);
+  is('и оценка буквой тоже', audit.overall.grade, 'B');
+  is('видно, что балл переиспользован, а не измерен заново', audit.overall.source, 'visibility:reused');
+  is('сохранено, когда его измерили', audit.overall.measuredAt, '2026-09-14T20:00:00.000Z');
+  is('пять областей приехали целиком', audit.overall.areas.length, 5);
+  is('и складываются в заголовок', audit.overall.areas.reduce((a, x) => a + x.score, 0), 63);
+  is('отчёт сходится сам с собой', verifyScores(audit), []);
+  // Локальный адрес движок бы мерить отказался, а балл всё равно есть: значит второго измерения не было.
+  ok('второго измерения не случилось', audit.overall.score === 63 && !audit.overall.error);
+
+  audit.meta.lang = 'ru';
+  is('и отчёт печатает именно его', Number((toHtml(audit, null).match(/overall-num[^>]*>(\d+)<span>/) || [])[1]), 63);
+}
+
+/*
+ * Подпись под баллом обязана объяснить человеку три вещи, иначе он прочитает разницу в пару
+ * пунктов как ошибку: откуда взялось число, что успели прочитать, и почему повтор может дать
+ * иначе. Это критерий приёмки, а не украшение: человек, прочитавший сначала страницу, а потом
+ * отчёт, не должен удивиться.
+ */
+{
+  const audit = JSON.parse(readFileSync(new URL('../examples/sample-audit.json', import.meta.url), 'utf8'));
+  const areas = [{ id: 'access', label: 'Access', score: 20, max: 25 }, { id: 'index', label: 'Index', score: 10, max: 15 },
+    { id: 'entity', label: 'Entity', score: 12, max: 20 }, { id: 'content', label: 'Content', score: 14, max: 25 }, { id: 'trust', label: 'Trust', score: 5, max: 15 }];
+  const note = (a) => ((toHtml(a, null).match(/overall-note">([^<]*)</) || [])[1] || '');
+
+  for (const lang of ['en', 'ru']) {
+    audit.meta.lang = lang;
+
+    audit.overall = { score: 61, grade: 'B', areas, source: 'visibility:reused', measuredAt: '2026-09-14T20:00:00.000Z', basis: { pages: 4, sitemapRead: true, sitemapUnchecked: false } };
+    const reused = note(audit);
+    ok(`${lang}: сказано, что число уже видели на проверке`, lang === 'en' ? /already saw on the free check/.test(reused) : /уже видели в бесплатной проверке/.test(reused));
+    ok(`${lang}: сказано, что здесь не меряли заново`, lang === 'en' ? /not measured again here/.test(reused) : /не меряется заново/.test(reused));
+    ok(`${lang}: названа дата измерения`, /2026-09-14/.test(reused));
+    ok(`${lang}: сказано, сколько страниц прочитано`, /4/.test(reused));
+    ok(`${lang}: предупреждает про разброс в пункт-другой`, lang === 'en' ? /a point or two/.test(reused) : /на пункт-другой/.test(reused));
+
+    audit.overall = { score: 61, grade: 'B', areas, source: 'visibility', basis: { pages: 1, sitemapRead: false, sitemapUnchecked: true } };
+    const fresh = note(audit);
+    ok(`${lang}: при собственном измерении сказано именно это`, lang === 'en' ? /Measured here by the same code/.test(fresh) : /Измерено здесь тем же кодом/.test(fresh));
+    ok(`${lang}: непрочитанная карта сайта названа, а не спрятана`, lang === 'en' ? /sitemap did not answer in time/.test(fresh) : /карта сайта не ответила вовремя/.test(fresh));
+    ok(`${lang}: и сказано, что она не зачтена в минус`, lang === 'en' ? /not counted against the score/.test(fresh) : /не зачтено ни в плюс, ни в минус/.test(fresh));
+    ok(`${lang}: в подписи нет чужого языка`, lang === 'en' ? !/[А-Яа-яЁё]/.test(fresh) : !/Measured|sitemap did/.test(fresh));
+  }
+
+  // Русское склонение в подписи: человек это читает.
+  audit.meta.lang = 'ru';
+  for (const [n, word] of [[1, 'страница'], [2, 'страницы'], [5, 'страниц'], [11, 'страниц'], [21, 'страница']]) {
+    audit.overall = { score: 61, grade: 'B', areas, source: 'visibility', basis: { pages: n, sitemapRead: true, sitemapUnchecked: false } };
+    ok(`ru: ${n} ${word}`, new RegExp(`Прочитано ${n} ${word} сайта`).test(note(audit)));
+  }
+}
+
 // ---- движок в пакете это та же программа, что стоит на сайтах
 {
   const here = readFileSync(new URL('./visibility.mjs', import.meta.url), 'utf8');