@operstack/audit 0.9.0 → 0.10.0

package/README.md

@@ -46,6 +46,20 @@ An agent can fill these fields from the JSON: the Claude Code plugin `operstack-
 
 Ten A4 pages: cover, executive summary with a scorecard, site overview with the sampled pages, critical issues, technical and on-page checklist, content and structure, AEO and GEO, off-page and conversion and limitations, roadmap in three phases, closing message. HTML always; PDF with `--pdf` when Chrome or Chromium is installed (`CHROME_PATH` overrides the lookup).
 
+## What an AI does not see: the JavaScript check
+
+**In plain words.** Some sites draw themselves with scripts. A person opens the page and sees the
+full text; a robot that does not run scripts sees an empty frame. The robots that pull a page into
+an AI answer are exactly that kind of robot. So the owner reads his own page, sees plenty of text,
+and cannot understand why nobody quotes it. This check reads the page twice, as a plain request and
+in a real browser, and tells you how much of the text only exists in the second reading.
+
+**What it does.** `collect` runs Chrome or Chromium over the homepage and two sampled pages, strips
+the navigation and footer from both readings, and compares the word counts. Forty percent hidden, or
+a page that is nearly empty without scripts, fails. Ten to forty warns. Under ten passes. With no
+browser installed the check says it was not measured and why. `--no-rendered` skips it,
+`--rendered-pages N` changes how many pages are opened; each page costs roughly half a minute.
+
 ## Writing the report: `draft`
 
 **If you have never done SEO, start here.** An audit tells you what a search engine and an AI see when they open your site. This tool writes that report for you. It does not guess anything about your business: every sentence in it comes from something that was measured on your pages, and where nothing could be measured it says so instead of filling the gap with words. You read it, correct what only you know, and send it.

package/bin/audit.mjs

@@ -40,8 +40,9 @@ const has = (k) => rest.includes(k);
 if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log([
     'Usage:',
-    '  operstack-audit collect <url> [--pages 20] [--out audit.json] [--backlinks links.json] [--lang ru]',
-    '      collect the public signals of a site into audit.json',
+    '  operstack-audit collect <url> [--pages 20] [--out audit.json] [--lang ru] [--no-rendered]',
+    '      collect the public signals of a site into audit.json; a real browser also measures how',
+    '      much of the text is invisible without JavaScript (--no-rendered skips that)',
     '  operstack-audit render <audit.json> [--out report.html] [--pdf]',
     '      render the report; --pdf also prints a PDF with headless Chrome',
     '  operstack-audit draft <audit.json> [--lang ru|en] [--out audit.json]',
@@ -64,7 +65,14 @@ if (cmd === 'collect') {
   if (!/^https?:\/\//.test(target || '')) { console.error('collect needs an absolute URL'); process.exit(2); }
   const backlinksFile = opt('--backlinks', '');
   const backlinks = backlinksFile ? JSON.parse(readFileSync(resolve(backlinksFile), 'utf8')) : null;
-  const audit = await collect(target, { pages: Number(opt('--pages', 20)), backlinks, lang: opt('--lang', 'en'), log: (m) => console.error(`  ${m}`) });
+  // Проверка «виден ли текст без скриптов» требует браузера и добавляет полминуты на страницу.
+  // В платном аудите она нужна всегда: именно здесь мы можем соврать про чужой сайт. Выключается
+  // флагом --no-rendered, например когда браузера нет или прогон идёт по расписанию.
+  const audit = await collect(target, {
+    pages: Number(opt('--pages', 20)), backlinks, lang: opt('--lang', 'en'),
+    rendered: !has('--no-rendered'), renderedPages: Number(opt('--rendered-pages', 3)),
+    log: (m) => console.error(`  ${m}`),
+  });
   const out = resolve(opt('--out', 'audit.json'));
   writeFileSync(out, JSON.stringify(audit, null, 2));
   console.log(`wrote ${out}: ${audit.checks.length} checks, ${audit.sample.length} pages sampled, scores ${Object.entries(audit.scores).map(([k, v]) => `${k} ${v === null ? 'not measured' : v}`).join(', ')}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.9.0",
+  "version": "0.10.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",
@@ -15,7 +15,8 @@
     "./fix": "./src/fix.mjs",
     "./foundation": "./src/foundation.mjs",
     "./narrative": "./src/narrative.mjs",
-    "./prompts": "./src/prompts.mjs"
+    "./prompts": "./src/prompts.mjs",
+    "./rendered": "./src/rendered.mjs"
   },
   "files": [
     "bin",
@@ -26,7 +27,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 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-rendered.mjs && 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

@@ -3,6 +3,7 @@
  * robots.txt, sitemaps, llms.txt, the homepage and a sample of pages from the sitemap.
  * No Search Console, no analytics. The narrative fields are left for the analyst.
  */
+import { renderedDom, compareReadings, jsBlindnessCheck } from './rendered.mjs';
 import { parse } from 'node-html-parser';
 import { localiseChecks } from './i18n.mjs';
 
@@ -162,7 +163,7 @@ async function readSitemap(url, seen = new Set(), depth = 0) {
   return out;
 }
 
-export async function collect(startUrl, { pages = 20, log = () => {}, backlinks = null, lang = 'en' } = {}) {
+export async function collect(startUrl, { pages = 20, log = () => {}, backlinks = null, lang = 'en', rendered = false, renderedPages = 3 } = {}) {
   const opts = { backlinks };
   const origin = new URL(startUrl).origin;
   const host = new URL(startUrl).host;
@@ -335,6 +336,25 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
 
   const { scores, scoreBasis } = computeScores(checks);
   // Оценки считаются до перевода: язык на цифры не влияет.
+  // Сколько текста не видно без выполнения скриптов. Меряется настоящим браузером и только по
+  // просьбе: запуск браузера это десятки секунд на страницу, и еженедельному мониторингу это ни к
+  // чему. Для платного аудита включено, потому что именно здесь мы можем соврать про чужой сайт.
+  if (rendered) {
+    const targets = [{ url: home.final, raw: home.response.ok ? home.response.text : '' },
+      ...good.filter((p) => p.url !== home.final).slice(0, Math.max(0, renderedPages - 1)).map((p) => ({ url: p.url, raw: '' }))];
+    const measured = [];
+    for (const t of targets) {
+      if (!t.url) continue;
+      log(`rendering ${t.url} in a real browser`);
+      const dom = renderedDom(t.url);
+      if (!dom) { log('no browser here, the JavaScript check will say it was not measured'); break; }
+      const rawHtml = t.raw || (await get(t.url)).text;
+      if (!rawHtml) continue;
+      measured.push({ url: t.url, ...compareReadings(rawHtml, dom) });
+    }
+    checks.push(jsBlindnessCheck(measured, lang));
+  }
+
   const localised = localiseChecks(checks, lang);
   const critical = checks.filter((c) => c.status === 'bad').map((c) => ({ title: c.label, text: `${c.value}${c.comment ? `. ${c.comment}` : ''}`, level: 'bad' }));
 

package/src/fix.mjs

@@ -66,6 +66,7 @@ export const FIX_ACTIONS = {
   thin: { scope: 'client', why: { ru: 'наполнение тонких страниц это тексты по фактам клиента', en: 'filling thin pages means writing from your facts' } },
   sections: { scope: 'client', why: { ru: 'разбивка на разделы это переписывание текста', en: 'splitting into sections means rewriting the text' } },
   tables: { scope: 'client', why: { ru: 'таблица собирается из данных клиента', en: 'a table is built from your data' } },
+  'js-content': { scope: 'files', action: { ru: 'Отдавать текст страницы сразу в HTML, а не дорисовывать его скриптами: предрендер или серверная отрисовка тех страниц, где текст сейчас появляется только в браузере', en: 'Serve the page text in the HTML itself instead of drawing it with scripts: prerender or server-render the pages whose text currently appears only in a browser' } },
   'links-profile': { scope: 'never', why: { ru: 'данные по ссылкам платные и ни в одну оценку не входят', en: 'link data is paid, and it moves no score of ours' } },
 };
 

package/src/prompts.mjs

@@ -94,6 +94,10 @@ const P = {
     ru: { task: 'Пройди по абзацам, где есть цифры, и подпиши к каждой, откуда она: ссылкой на первоисточник или словами («по данным реестра за 2026 год»). Если источника нет ни у тебя, ни у владельца, цифру надо убрать, а не оставлять голой. Не ставь ссылку наугад: неверный источник хуже отсутствующего.', verify: 'В каждом абзаце с цифрой есть либо ссылка на чужой сайт, либо названный словами источник.' },
     en: { task: 'Go through the paragraphs carrying figures and name where each came from: a link to the primary source, or words ("per the 2026 registry"). If neither you nor the owner has a source, the figure comes out rather than standing bare. Do not guess a link: a wrong source is worse than none.', verify: 'Every paragraph with a figure carries either an outbound link or a source named in words.' },
   },
+  'js-content': {
+    ru: { task: 'Найди страницы, где основной текст появляется только после выполнения скриптов, и сделай так, чтобы он отдавался сразу в HTML: предрендер при сборке или серверная отрисовка. Проверить просто: открой адрес страницы командой curl и посмотри, есть ли в ответе текст статьи. Не прячь текст в атрибуты и не дублируй его скрытым блоком ради роботов: это считается обманом и наказывается.', verify: 'В ответе на обычный запрос без браузера виден весь основной текст страницы, а не только каркас.' },
+    en: { task: 'Find the pages whose main text appears only after scripts run, and make that text arrive in the HTML itself: prerender at build time or render on the server. Checking is simple: fetch the URL with curl and see whether the article text is in the response. Do not hide the text in attributes and do not duplicate it in a hidden block for robots: that counts as cloaking and is punished.', verify: 'A plain request without a browser returns the whole main text of the page, not just the shell.' },
+  },
   thin: {
     ru: { task: 'Возьми страницы короче трёхсот слов и допиши их фактами, которые знает владелец: условия, цены, сроки, ограничения, частые вопросы покупателей с ответами. Не разбавляй текст водой ради объёма. Если фактов нет, выпиши владельцу список вопросов и оставь страницу как есть.', verify: 'Страница стала длиннее трёхсот слов, и каждый добавленный абзац содержит факт, а не общие слова.' },
     en: { task: 'Take the pages under three hundred words and fill them with facts the owner has: terms, prices, timings, limits, the questions buyers actually ask with the answers. Do not pad for length. Where the facts are missing, write the owner a list of questions and leave the page alone.', verify: 'The page is over three hundred words and every added paragraph carries a fact rather than filler.' },

package/src/rendered.mjs

@@ -0,0 +1,103 @@
+/**
+ * Сколько текста страницы не видит тот, кто не выполняет JavaScript.
+ *
+ * Человеческими словами: если сайт рисует себя скриптами, то поисковый робот и особенно робот,
+ * который достаёт страницу для ответа ИИ, могут увидеть пустую страницу. Владелец при этом видит
+ * полный текст и не понимает, почему его не цитируют. Здесь это измеряется прямо: страница
+ * читается дважды, как обычный запрос без скриптов и как настоящий браузер, и считается, какая
+ * доля текста появляется только во втором случае.
+ *
+ * Браузер берётся тот же, которым печатается PDF отчёта: свой Chrome или Chromium. Если его нет,
+ * проверка не выдумывает результат, а говорит, что не измеряла, и почему.
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/** Тот же поиск браузера, что у печати PDF: одна привычка на весь пакет. */
+export function findChrome() {
+  const candidates = [
+    process.env.CHROME_PATH,
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  ].filter(Boolean);
+  for (const c of candidates) {
+    const r = spawnSync(c, ['--version'], { encoding: 'utf8', timeout: 8000 });
+    if (r.status === 0) return c;
+  }
+  return null;
+}
+
+/** Текст страницы после выполнения скриптов. null, если браузера нет или он не справился. */
+export function renderedDom(url, { chrome = null, timeoutMs = 45000, waitMs = 8000 } = {}) {
+  const bin = chrome || findChrome();
+  if (!bin) return null;
+  const profile = mkdtempSync(join(tmpdir(), 'operstack-render-'));
+  try {
+    const r = spawnSync(bin, [
+      '--headless=new', '--disable-gpu', '--no-first-run', '--no-default-browser-check',
+      '--disable-extensions', '--mute-audio', '--hide-scrollbars',
+      `--user-data-dir=${profile}`, `--virtual-time-budget=${waitMs}`, '--dump-dom', url,
+    ], { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 });
+    if (r.status !== 0 || !r.stdout) return null;
+    return r.stdout;
+  } catch { return null; } finally { rmSync(profile, { recursive: true, force: true }); }
+}
+
+const CHROME_STRIP = /<(nav|footer|aside|script|style|noscript|template)[\s\S]*?<\/\1>/gi;
+const plain = (html) => String(html)
+  .replace(/<!--[\s\S]*?-->/g, ' ')
+  .replace(CHROME_STRIP, ' ')
+  .replace(/<[^>]+>/g, ' ')
+  .replace(/&nbsp;/g, ' ')
+  .replace(/\s+/g, ' ')
+  .trim();
+const countWords = (s) => (s.match(/[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu) || []).length;
+
+/**
+ * Сравнение двух чтений одной страницы.
+ * @returns {{raw:number, rendered:number, hiddenShare:number, verdict:'ok'|'warn'|'bad'}}
+ */
+export function compareReadings(rawHtml, renderedHtml) {
+  const raw = countWords(plain(rawHtml));
+  const rendered = countWords(plain(renderedHtml));
+  // Отрицательной разницы не бывает: если браузер увидел меньше, значит он не досчитал, а не
+  // страница уменьшилась. Такой случай считаем нулевой разницей, а не отрицательной долей.
+  const extra = Math.max(0, rendered - raw);
+  const hiddenShare = rendered > 0 ? Math.round((extra / rendered) * 100) : 0;
+  const verdict = hiddenShare >= 40 || (raw < 50 && rendered >= 200) ? 'bad' : hiddenShare >= 10 ? 'warn' : 'ok';
+  return { raw, rendered, hiddenShare, verdict };
+}
+
+const WORD = { ru: (n) => `${n} ${n % 10 === 1 && n % 100 !== 11 ? 'слово' : n % 10 >= 2 && n % 10 <= 4 && (n % 100 < 10 || n % 100 >= 20) ? 'слова' : 'слов'}` };
+
+/** Строка проверки для аудита. Текст пишется так, чтобы владелец понял, чем ему это грозит. */
+export function jsBlindnessCheck(pages, lang = 'en') {
+  const measured = pages.filter((p) => p && p.rendered > 0);
+  if (!measured.length) {
+    return {
+      id: 'js-content', group: 'technical',
+      label: lang === 'ru' ? 'Виден ли текст без выполнения скриптов' : 'Text visible without running JavaScript',
+      status: 'na',
+      value: lang === 'ru' ? 'не измеряли: на этой машине нет браузера Chrome или Chromium' : 'not measured: no Chrome or Chromium on this machine',
+      comment: lang === 'ru' ? 'проверка сравнивает страницу, прочитанную без скриптов, с ней же в настоящем браузере' : 'the check compares the page read without scripts against the same page in a real browser',
+    };
+  }
+  const worst = measured.slice().sort((a, b) => b.hiddenShare - a.hiddenShare)[0];
+  const median = measured.map((p) => p.hiddenShare).sort((a, b) => a - b)[Math.floor(measured.length / 2)];
+  const status = measured.some((p) => p.verdict === 'bad') ? 'bad' : measured.some((p) => p.verdict === 'warn') ? 'warn' : 'ok';
+  const value = lang === 'ru'
+    ? `без скриптов видно всё, кроме ${median} процентов текста (медиана по ${measured.length} ${measured.length === 1 ? 'странице' : 'страницам'}), хуже всего ${worst.url}: там скрыто ${worst.hiddenShare} процентов, ${WORD.ru(worst.raw)} без скриптов против ${WORD.ru(worst.rendered)} в браузере`
+    : `${median}% of the text is invisible without JavaScript (median over ${measured.length} page${measured.length === 1 ? '' : 's'}); worst is ${worst.url} at ${worst.hiddenShare}%, ${worst.raw} words without scripts against ${worst.rendered} in a browser`;
+  // Слова по размеру беды: на четырнадцати процентах писать «страница почти пустая» это враньё
+  // в ту же сторону, от которого мы уходим.
+  const comment = status === 'ok'
+    ? (lang === 'ru' ? 'страницы читаются целиком и без браузера, это то, что нужно поиску и ИИ' : 'the pages read whole without a browser, which is what search and AI need')
+    : status === 'bad'
+      ? (lang === 'ru' ? 'для простых роботов поиска и для роботов, которые достают страницу в ответ ИИ, эта страница почти пустая: они не выполняют скрипты' : 'to simple search crawlers and to the fetchers that pull a page into an AI answer this page is nearly empty: they do not run scripts')
+      : (lang === 'ru' ? 'эта часть текста не доходит до роботов, которые не выполняют скрипты, а именно они приносят страницу в ответ ИИ' : 'this part of the text does not reach the robots that do not run scripts, and those are the ones that bring a page into an AI answer');
+  return { id: 'js-content', group: 'technical', label: lang === 'ru' ? 'Виден ли текст без выполнения скриптов' : 'Text visible without running JavaScript', status, value, comment };
+}

package/src/test-rendered.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/** Слепота к скриптам: считаем честно, не измерив, так и говорим. */
+import { compareReadings, jsBlindnessCheck } from './rendered.mjs';
+
+let bad = 0;
+const is = (n, a, b) => { const ok = JSON.stringify(a) === JSON.stringify(b); if (!ok) { bad++; console.error(`FAIL ${n}\n  ждали ${JSON.stringify(b)}\n  вышло ${JSON.stringify(a)}`); } else console.log(`ok   ${n}`); };
+const ok = (n, c) => is(n, Boolean(c), true);
+
+const text = (n) => '<p>' + 'слово '.repeat(n) + '</p>';
+const body = (inner) => `<html><body>${inner}</body></html>`;
+
+is('одинаковые чтения дают ноль скрытого', compareReadings(body(text(300)), body(text(300))).hiddenShare, 0);
+is('и вердикт «в порядке»', compareReadings(body(text(300)), body(text(300))).verdict, 'ok');
+
+const empty = compareReadings(body('<div id="root"></div>'), body(text(300)));
+is('пустой каркас против полной страницы это сто процентов', empty.hiddenShare, 100);
+is('и это приговор', empty.verdict, 'bad');
+
+const half = compareReadings(body(text(100)), body(text(200)));
+is('половина текста за скриптами считается верно', half.hiddenShare, 50);
+is('и это тоже приговор', half.verdict, 'bad');
+
+is('пять процентов за скриптами это ещё в порядке', compareReadings(body(text(285)), body(text(300))).verdict, 'ok');
+const tenth = compareReadings(body(text(270)), body(text(300)));
+is('десятая часть текста за скриптами это уже предупреждение', tenth.verdict, 'warn');
+is('и доля посчитана', tenth.hiddenShare, 10);
+
+// Меню и подвал не считаются: их и так никто не цитирует
+const chrome = compareReadings(body('<nav>меню меню меню</nav>' + text(100)), body('<nav>меню меню меню другое</nav>' + text(100)));
+is('разница только в меню не считается скрытым текстом', chrome.hiddenShare, 0);
+
+// Браузер увидел меньше: это его беда, а не отрицательная доля
+is('отрицательной доли не бывает', compareReadings(body(text(300)), body(text(100))).hiddenShare, 0);
+
+// Строка проверки
+const good = jsBlindnessCheck([{ url: 'https://x.ru/', raw: 300, rendered: 300, hiddenShare: 0, verdict: 'ok' }], 'ru');
+is('чистый сайт получает «ok»', good.status, 'ok');
+ok('и понятный текст', /читаются целиком/.test(good.comment));
+
+const worst = jsBlindnessCheck([
+  { url: 'https://x.ru/a', raw: 300, rendered: 300, hiddenShare: 0, verdict: 'ok' },
+  { url: 'https://x.ru/b', raw: 10, rendered: 400, hiddenShare: 98, verdict: 'bad' },
+], 'ru');
+is('одна плохая страница делает проверку проваленной', worst.status, 'bad');
+ok('в тексте названа худшая страница', worst.value.includes('https://x.ru/b'));
+ok('и сказано, сколько слов видно без скриптов', /10 слов без скриптов против 400/.test(worst.value));
+ok('приговор говорит про роботов ИИ', /достают страницу в ответ ИИ/.test(worst.comment));
+
+const mild = jsBlindnessCheck([{ url: 'https://x.ru/', raw: 86, rendered: 100, hiddenShare: 14, verdict: 'warn' }], 'ru');
+ok('на четырнадцати процентах не пишем «страница почти пустая»', !/почти пустая/.test(mild.comment));
+ok('а пишем, что часть текста не доходит', /не доходит/.test(mild.comment));
+
+const none = jsBlindnessCheck([], 'ru');
+is('без браузера статус «не измеряли»', none.status, 'na');
+ok('и сказано почему', /нет браузера/.test(none.value));
+
+const en = jsBlindnessCheck([{ url: 'https://x.com/', raw: 10, rendered: 400, hiddenShare: 98, verdict: 'bad' }], 'en');
+ok('английская версия без кириллицы', !/[А-Яа-яЁё]/.test(JSON.stringify(en)));
+
+if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
+console.log('\nвсе тесты слепоты к скриптам прошли');