@operstack/audit 0.17.0 → 0.17.1

package/package.json

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

@@ -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,26 @@ 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 overall = visibility && visibility.ok
+    ? { score: visibility.score, grade: visibility.grade, areas: visibility.areas, source: givenVisibility ? 'visibility:reused' : 'visibility', measuredAt, ms: visibility.ms }
+    : { score: null, grade: 'not measured', areas: [], source: givenVisibility ? 'visibility:reused' : 'visibility', error: (visibility && visibility.error) || 'no visibility result' };
   // Шесть областей отчёта остаются, но это другое измерение, а не разбивка общего балла.
   const reportScore = computeOverall(checks);
 

package/src/test-overall.mjs

@@ -107,6 +107,46 @@ 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 here = readFileSync(new URL('./visibility.mjs', import.meta.url), 'utf8');