@operstack/audit 0.21.4 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.21.4",
+  "version": "0.23.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",
+    "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/collect.mjs

@@ -52,6 +52,13 @@ async function follow(url, max = 5) {
 
 const row = (id, group, label, status, value, comment = '') => ({ id, group, label, status, value, comment });
 
+/**
+ * Чем в тексте называют источник цифры, по-английски и по-русски. Список слово в слово совпадает
+ * с SOURCE_RE в visibility.mjs: два движка должны считать одно и то же, иначе балл в бесплатной
+ * проверке и в платном отчёте разойдётся на ровном месте.
+ */
+const SOURCE_RE = /(?<!\p{L})(according to|source:|sources:|data from|reported by|published by|registry|statistics office|central bank|по данным|источник:|источники:|согласно|по информации|по сведениям|росстат|центробанк|банк россии|росреестр|минфин|минэкономразвития)(?!\p{L})/giu;
+
 function analysePage(url, html) {
   const root = parse(html, { blockTextElements: { script: true, style: true, noscript: true } });
   const attr = (sel, a) => root.querySelector(sel)?.getAttribute(a) ?? '';
@@ -147,7 +154,13 @@ function analysePage(url, html) {
   const tables = (bodyHtml.match(/<table[\s>]/gi) || []).length;
   // A source is named either in words, or the way careful writing actually does it: a link to
   // somebody else's site sitting in the same paragraph as the figure it backs.
-  const sourcePhrases = (text.match(/\b(according to|source:|sources:|data from|reported by|published by|registry|statistics office|central bank)\b/gi) || []).length;
+  // Слова, которыми называют источник цифры. Список и границы слова те же, что в движке
+  // бесплатной проверки (visibility.mjs, SOURCE_RE): до 16.09.2026 здесь были только английские
+  // выражения, и русский сайт, честно написавший «по данным Росстата», получал ноль. Живой
+  // пользователь сказал об этом прямо: на русском сайте эти баллы недостижимы.
+  // Обычная граница слова \b для кириллицы не работает, она построена на латинице, поэтому
+  // границы заданы через отсутствие буквы рядом.
+  const sourcePhrases = (text.match(SOURCE_RE) || []).length;
   const ownHostname = (() => { try { return new URL(url).hostname.replace(/^www\./, ''); } catch { return ''; } })();
   // Абзацы, в которых вообще есть цифра. Без этого счётчика «цифры без источника» вменяется
   // странице, где цифр нет ни одной, например политике конфиденциальности.

package/src/test-ru-sources.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Русский сайт, который честно называет источник цифры, получает за это балл.
+ *
+ * 16.09.2026 живой пользователь сказал прямо: «поиск источника цифр англоязычный, на русском
+ * сайте эти пять баллов недостижимы честно». Так и было: в движке платного аудита список слов
+ * состоял только из английских выражений, хотя в движке бесплатной проверки русские уже были.
+ * Два движка считали одно и то же по-разному.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const src = readFileSync(resolve(here, 'collect.mjs'), 'utf8');
+const vis = readFileSync(resolve(here, 'visibility.mjs'), 'utf8');
+
+let bad = 0;
+const ok = (n, c) => { if (c) console.log(`ok   ${n}`); else { bad++; console.error(`FAIL ${n}`); } };
+
+const line = (text) => (text.match(/^const SOURCE_RE = .+$/m) || [''])[0];
+ok('списки слов в обоих движках совпадают слово в слово', line(src) === line(vis) && line(src).length > 60);
+
+const RE = new RegExp(line(src).replace(/^const SOURCE_RE = \//, '').replace(/\/giu;$/, ''), 'giu');
+const count = (t) => (t.match(RE) || []).length;
+
+for (const t of ['По данным Росстата, рынок вырос на 12%.',
+                 'Источник: отчёт Банка России за 2025 год.',
+                 'Согласно исследованию, доля выросла до 40%.',
+                 'По информации Минфина, ставка снижена.',
+                 'По сведениям Росреестра, сделок стало больше.'])
+  ok(`русский источник виден: ${t.slice(0, 34)}…`, count(t) > 0);
+
+for (const t of ['According to Rosstat, the market grew 12%.', 'Source: Bank of Russia report.'])
+  ok(`английский по-прежнему виден: ${t.slice(0, 30)}…`, count(t) > 0);
+
+for (const t of ['Мы выросли на 12% за год.', 'Наша команда работает с 2019 года.', 'Согласнее всех был директор.'])
+  ok(`пустая похвальба источником не считается: ${t.slice(0, 28)}…`, count(t) === 0);
+
+console.log(bad ? `\nпровалов: ${bad}` : '\nвсё сходится');
+process.exit(bad ? 1 : 0);

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

@@ -84,10 +84,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 +137,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
       ? 'Единственная проверенная страница не показывает дату публикации или изменения. Системы предпочитают источники, которые можно датировать.'
@@ -455,7 +457,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 +607,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 +627,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;