@operstack/audit 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.22.0",
+  "version": "0.24.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",
@@ -29,7 +29,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-sitemap.mjs && node src/test-overall.mjs && node src/test-blocked.mjs && node src/test-unmeasured.mjs && node src/test-rendered.mjs && node src/test-sample.mjs && node src/test-demand.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 && node src/test-ru-sources.mjs",
+    "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-blocked.mjs && node src/test-unmeasured.mjs && node src/test-rendered.mjs && node src/test-sample.mjs && node src/test-demand.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 && node src/test-ru-sources.mjs && node src/test-sample-fairness.mjs",
     "sample": "node bin/audit.mjs render examples/sample-audit.json --pdf",
     "verify:live": "node src/verify-live.mjs"
   },

package/src/test-overall.mjs

@@ -33,7 +33,9 @@ is('пустой набор не даёт нуля', computeOverall([]).score, n
 
 // ---- параметры измерения зафиксированы: их расхождение и есть расхождение чисел
 is('бюджет времени один на всех', VISIBILITY_DEFAULTS.budgetMs, 8500);
-is('глубина выборки одна на всех', VISIBILITY_DEFAULTS.samplePages, 3);
+// Девять плюс главная это десять. Число стоит на витрине словами «другие проверяют одну
+// страницу, мы проверяем десять», поэтому оно обязано совпадать с тем, что движок правда читает.
+is('глубина выборки одна на всех', VISIBILITY_DEFAULTS.samplePages, 9);
 ok('параметры нельзя поменять на ходу', Object.isFrozen(VISIBILITY_DEFAULTS));
 
 // ---- балл видимости сходится сам с собой

package/src/test-sample-fairness.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Мы меряем то, что человек станет чинить, и говорим ему, что именно измерили.
+ *
+ * 16.09.2026 живой пользователь прошёл путь с 63 до 95 и назвал два узких места подряд:
+ * в выборку попали расшифровки на семь тысяч слов, а таблицу, добавленную на главную, проверка
+ * не увидела. Оба оказались правдой. Отбор шёл сортировкой по длине адреса по убыванию, то есть
+ * наверх поднимались самые глубокие страницы, а главная в оценку содержания не входила вовсе.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const src = readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), 'visibility.mjs'), 'utf8');
+
+let bad = 0;
+const ok = (n, c) => { if (c) console.log(`ok   ${n}`); else { bad++; console.error(`FAIL ${n}`); } };
+
+ok('главная входит в оценку содержания наравне с остальными',
+  /const contentPages = \[homePage, \.\.\.sampled\]/.test(src));
+ok('сортировки по длине адреса по убыванию больше нет',
+  !/sort\(\(a, b\) => b\.length - a\.length\)/.test(src));
+ok('страницы отбираются по близости к корню', /depth\(a\) - depth\(b\)/.test(src));
+ok('и по одной из каждого раздела', /usedSections/.test(src));
+ok('отчёт называет измеренные страницы', /measured: \(list\)/.test(src) && /T\.measured\(/.test(src));
+ok('находка про абзац-ответ называет страницы', /answerFirstMissing: \(n, total, where\)/.test(src));
+
+// Отбор должен быть строго определённым: два прогона по одному сайту берут одни и те же страницы,
+// иначе балл гуляет и человек не понимает, что изменилось от его правки.
+const depth = (u) => new URL(u).pathname.replace(/\/$/, '').split('/').filter(Boolean).length;
+const section = (u) => new URL(u).pathname.split('/').filter(Boolean)[0] || '';
+const pick = (pages, want) => {
+  const byDepth = [...pages].sort((a, b) => depth(a) - depth(b) || a.length - b.length || (a < b ? -1 : 1));
+  const out = []; const used = new Set();
+  for (const p of byDepth) { if (out.length >= want) break; const s = section(p); if (used.has(s)) continue; used.add(s); out.push(p); }
+  for (const p of byDepth) { if (out.length >= want) break; if (!out.includes(p)) out.push(p); }
+  return out;
+};
+const site = [
+  'https://x.ru/blog/rasshifrovka-vypuska-nomer-sorok-dva-pro-vsyo-na-svete/',
+  'https://x.ru/blog/rasshifrovka-vypuska-nomer-sorok-tri-pro-vsyo-na-svete/',
+  'https://x.ru/uslugi/', 'https://x.ru/ceny/', 'https://x.ru/o-nas/', 'https://x.ru/blog/',
+];
+const got = pick(site, 3);
+ok('расшифровки больше не вытесняют витрину', !got.some((u) => u.includes('rasshifrovka')));
+ok('взяты разные разделы', new Set(got.map(section)).size === got.length);
+ok('отбор повторяем', JSON.stringify(pick(site, 3)) === JSON.stringify(got));
+
+console.log(bad ? `\nпровалов: ${bad}` : '\nвсё сходится');
+process.exit(bad ? 1 : 0);

package/src/visibility.mjs

@@ -1,16 +1,22 @@
 /**
  * AI visibility check: can ChatGPT, Perplexity, Copilot, Claude and Gemini read, understand
  * and cite this site? Public signals only, one homepage fetch plus robots, llms.txt, the
- * sitemap head and up to three sampled pages, all in parallel, under a hard time budget so it
+ * sitemap head and up to nine sampled pages, all in parallel, under a hard time budget so it
  * runs inside a serverless function. Plain ESM so the same module runs in Node for tests.
  *
+ * Почему девять, а не три. До 17.09.2026 проверка читала главную и три страницы, а на витрине мы
+ * собирались написать «другие проверяют одну страницу, мы проверяем десять». Это было бы неправдой:
+ * платный аудит читал десять, бесплатная проверка четыре. Замерено: десять страниц укладываются в
+ * 598 мс при бюджете 8500, потому что страницы берутся параллельно. Сайту с пятью страницами это не
+ * вредит: берётся столько, сколько есть, и отчёт называет настоящее число прочитанного.
+ *
  * The measurement is language-neutral; only the words a person reads come from the MESSAGES
  * table below, picked by the `lang` option ('en' by default, 'ru' on oper-stack.ru). Finding ids
  * and area ids never change with the language, so task lists and reports can key on them.
  *
  * This file is also vendored by the Apify actor (OperStack/apify-ai-visibility/src). The two
  * copies must stay byte for byte identical, and `npm test` in the actor fails if they drift.
- * That is why `samplePages` lives here although both sites leave it at three: a copy that has
+ * That is why `samplePages` lives here and every caller spreads VISIBILITY_DEFAULTS: a copy that has
  * to differ is a copy nobody keeps in sync, and this one had drifted by 304 lines.
  */
 
@@ -84,10 +90,11 @@ export const MESSAGES = {
     ogMissing: 'No Open Graph tags on the homepage: shared links and previews render without a title or image.',
     thinPages: (thin, total) => `${thin} of ${total} sampled page(s) hold under 300 words. Engines rarely cite thin pages.`,
     avgWords: (avg) => `Sampled pages carry ${avg} words on average.`,
-    answerFirstMissing: (n, total) => `${n} of ${total} sampled page(s) open with an answer-first paragraph (20 to 90 words with a figure right after the H1). That paragraph is what gets quoted.`,
+    answerFirstMissing: (n, total, where) => `${n} of ${total} measured page(s) open with an answer-first paragraph (20 to 90 words with a figure right after the H1). That paragraph is what gets quoted. Missing on: ${where}.`,
     answerFirstOk: 'Every sampled page opens with an answer-first paragraph carrying a figure.',
     fewH2: (n) => `${n} sampled page(s) have fewer than three H2 sections.`,
-    noTables: 'No tables on the sampled pages. Tables are the second most quoted format after the first paragraph.',
+    noTables: 'No tables on the measured pages. Tables are the second most quoted format after the first paragraph.',
+    measured: (list) => `Measured on these pages: ${list}. Every content finding is a share of them, so a fix on one page moves the score by its share.`,
     homeOnly: 'Only the homepage could be read, so this area is measured on one page rather than several. A sitemap that answers would give a fuller picture.',
     datesMissing: (n) => `${n} sampled page(s) expose no publication or modified date. Engines prefer sources they can date.`,
     datesOk: 'Sampled pages expose publication dates.',
@@ -136,14 +143,15 @@ export const MESSAGES = {
       ? 'Единственная проверенная страница короче 300 слов. Короткие страницы цитируют редко.'
       : `Из ${total} ${ofPages(total)} ${thin} короче 300 слов. Короткие страницы цитируют редко.`),
     avgWords: (avg) => `На проверенных страницах в среднем ${avg} ${pl(avg, 'слово', 'слова', 'слов')}.`,
-    answerFirstMissing: (n, total) => (total === 1
-      ? 'Единственная проверенная страница не начинается с абзаца-ответа (20-90 слов с цифрой сразу после H1). Именно этот абзац попадает в цитату.'
-      : `Из ${total} ${ofPages(total)} с абзаца-ответа (20-90 слов с цифрой сразу после H1) ${n === 0 ? 'не начинается ни одна' : n === 1 ? 'начинается одна' : `начинаются ${n}`}. Именно этот абзац попадает в цитату.`),
+    answerFirstMissing: (n, total, where) => (total === 1
+      ? `Единственная проверенная страница не начинается с абзаца-ответа (20-90 слов с цифрой сразу после H1). Именно этот абзац попадает в цитату. Чинить здесь: ${where}.`
+      : `Из ${total} ${ofPages(total)} с абзаца-ответа (20-90 слов с цифрой сразу после H1) ${n === 0 ? 'не начинается ни одна' : n === 1 ? 'начинается одна' : `начинаются ${n}`}. Именно этот абзац попадает в цитату. Чинить здесь: ${where}.`),
     answerFirstOk: 'Каждая проверенная страница начинается с абзаца-ответа с цифрой.',
     fewH2: (n, total) => (total === 1
       ? 'У единственной проверенной страницы меньше трёх подзаголовков H2.'
       : `У ${n} из ${total} ${ofPages(total)} меньше трёх подзаголовков H2.`),
     noTables: 'На проверенных страницах нет таблиц. Таблица второй по цитируемости формат после первого абзаца.',
+    measured: (list) => `Мерили по этим страницам: ${list}. Каждая находка по содержанию считается долей от них, поэтому правка на одной странице двигает балл на свою долю.`,
     homeOnly: 'Прочитать удалось только главную, поэтому эта область измерена по одной странице, а не по нескольким. Отвечающая карта сайта дала бы полную картину.',
     datesMissing: (n, total) => (total === 1
       ? 'Единственная проверенная страница не показывает дату публикации или изменения. Системы предпочитают источники, которые можно датировать.'
@@ -344,7 +352,7 @@ async function readSitemap(origin, robotsText, timeoutFn = () => 3000) {
  * в аудите и в акторе. Если где-то дать больше страниц или времени, число про один и тот же сайт
  * разойдётся, и мы вернёмся к тому, ради чего всё это затевалось.
  */
-export const VISIBILITY_DEFAULTS = Object.freeze({ budgetMs: 8500, samplePages: 3 });
+export const VISIBILITY_DEFAULTS = Object.freeze({ budgetMs: 8500, samplePages: 9 });
 
 /**
  * Что писать владельцу сайта, который нас не пустил.
@@ -373,7 +381,7 @@ export function blockedNote({ status, challenged, blocked = true, robotsText = n
   return { text: head + tail + T.howToCheckBots, botsBlocked: closed.length > 0 };
 }
 
-export async function checkVisibility(input, { budgetMs = 8500, lang = 'en', samplePages = 3 } = {}) {
+export async function checkVisibility(input, { budgetMs = 8500, lang = 'en', samplePages = 9 } = {}) {
   const T = MESSAGES[lang] || MESSAGES.en;
   const agentLabel = (a) => (lang === 'ru' ? a.labelRu : a.label);
   const started = Date.now();
@@ -455,7 +463,38 @@ export async function checkVisibility(input, { budgetMs = 8500, lang = 'en', sam
   let wantedPages = 0;
   if (left() > 2000 && sitemap.pages.length) {
     const norm = (u) => u.replace(/\/$/, '').toLowerCase();
-    const picks = sitemap.pages.filter((p) => norm(p) !== norm(home.url) && p.startsWith(origin)).sort((a, b) => b.length - a.length).slice(0, Math.max(12, samplePages * 4)).filter((_, i) => i % 4 === 0).slice(0, samplePages);
+    /*
+     * Какие страницы берём в выборку.
+     *
+     * До 16.09.2026 здесь стояла сортировка по длине адреса по убыванию, то есть наверх
+     * поднимались самые глубокие страницы: расшифровки, архивы, служебные разделы. Живой
+     * пользователь увидел это на своём сайте: в выборку попали расшифровки на семь тысяч слов.
+     * Он чинил витрину, а балл почти не двигался, потому что каждая находка по содержанию
+     * считается долей от всех измеренных страниц, и одна поправленная главная из четырёх даёт
+     * четверть балла.
+     *
+     * Теперь берём страницы поближе к корню и по одной из каждого раздела: это то, ради чего
+     * сайт сделан, и то, что человек станет чинить. Порядок строго определён, чтобы два прогона
+     * по одному сайту брали одни и те же страницы и балл не гулял.
+     */
+    const depth = (u) => { try { return new URL(u).pathname.replace(/\/$/, '').split('/').filter(Boolean).length; } catch { return 99; } };
+    const section = (u) => { try { return new URL(u).pathname.split('/').filter(Boolean)[0] || ''; } catch { return ''; } };
+    const candidates = sitemap.pages.filter((p) => norm(p) !== norm(home.url) && p.startsWith(origin));
+    const byDepth = [...candidates].sort((a, b) => depth(a) - depth(b) || a.length - b.length || (a < b ? -1 : 1));
+    const picks = [];
+    const usedSections = new Set();
+    for (const p of byDepth) {
+      if (picks.length >= samplePages) break;
+      const sec = section(p);
+      if (usedSections.has(sec)) continue;
+      usedSections.add(sec);
+      picks.push(p);
+    }
+    // Разделов может оказаться меньше, чем нужно страниц: добираем ближайшими к корню.
+    for (const p of byDepth) {
+      if (picks.length >= samplePages) break;
+      if (!picks.includes(p)) picks.push(p);
+    }
     const read = async (list) => Promise.all(list.map((p) => get(p, { timeout: Math.min(4000, left() - 300) })));
     let rs = await read(picks);
     // Одна повторная попытка по тем, что не ответили: страницы маленькие, а разница в балле
@@ -574,7 +613,16 @@ export async function checkVisibility(input, { budgetMs = 8500, lang = 'en', sam
   if (homePage.ogTitle) entity += 2; else entityFindings.push({ id: 'og-missing', level: 'warn', text: T.ogMissing });
 
   // Area 4: answer-first content (25)
-  const contentPages = sampled.length ? sampled : [homePage];
+  /*
+   * Главная считается наравне с остальными.
+   *
+   * До 16.09.2026 здесь стояло `sampled.length ? sampled : [homePage]`, то есть главную мы
+   * смотрели только когда больше ничего не нашлось. На любом сайте с картой сайта самая важная
+   * страница выпадала из оценки содержания целиком: ни таблицы, ни абзац-ответ, ни объём.
+   * Живой пользователь добавил таблицу на главную, балл не сдвинулся, и он не понял почему.
+   * Понять было нельзя: мы туда не смотрели.
+   */
+  const contentPages = [homePage, ...sampled];
   /* Say so. A score built from one page is not the same measurement as one built from four. */
   const homeOnly = !sampled.length;
   const thin = contentPages.filter((p) => p.words < 300).length;
@@ -585,11 +633,18 @@ export async function checkVisibility(input, { budgetMs = 8500, lang = 'en', sam
   content += Math.round(10 * (1 - thin / contentPages.length));
   if (thin) contentFindings.push({ id: 'thin-pages', level: thin === contentPages.length ? 'fail' : 'warn', text: T.thinPages(thin, contentPages.length) }); else contentFindings.push({ level: 'pass', text: T.avgWords(Math.round(contentPages.reduce((a, p) => a + p.words, 0) / contentPages.length)) });
   content += Math.round(8 * (answerFirst / contentPages.length));
-  if (answerFirst < contentPages.length) contentFindings.push({ id: 'answer-first-missing', level: answerFirst ? 'warn' : 'fail', text: T.answerFirstMissing(answerFirst, contentPages.length) }); else contentFindings.push({ level: 'pass', text: T.answerFirstOk });
+  // Адрес страницы в находке это разница между «полдня искали» и «поправил за минуту»: живой
+  // пользователь 16.09.2026 потратил полдня, чтобы понять, какая именно страница виновата.
+  const shortPath = (u) => { try { const x = new URL(u); return (x.pathname === '/' ? '/' : x.pathname.replace(/\/$/, '')); } catch { return u; } };
+  const pageList = (list) => list.map(shortPath).join(', ');
+  if (answerFirst < contentPages.length) contentFindings.push({ id: 'answer-first-missing', level: answerFirst ? 'warn' : 'fail', text: T.answerFirstMissing(answerFirst, contentPages.length, pageList(contentPages.filter((p) => !p.answerFirst).map((p) => p.url))) }); else contentFindings.push({ level: 'pass', text: T.answerFirstOk });
   content += Math.round(4 * (structured / contentPages.length)) + Math.round(3 * (withTables / contentPages.length));
   if (structured < contentPages.length) contentFindings.push({ id: 'few-h2', level: 'warn', text: T.fewH2(contentPages.length - structured, contentPages.length) });
   if (!withTables) contentFindings.push({ id: 'no-tables', level: 'warn', text: T.noTables });
   if (homeOnly) contentFindings.push({ level: 'warn', text: T.homeOnly });
+  // Какие именно страницы мы мерили. Без этой строки человек чинит витрину, видит движение балла
+  // на один пункт и не понимает, почему: находки считаются долей от всех измеренных страниц.
+  contentFindings.push({ level: 'pass', text: T.measured(pageList(contentPages.map((p) => p.url))) });
 
   // Area 5: freshness and sources (15)
   const dated = contentPages.filter((p) => p.datePublished || p.dateModified).length;