@operstack/audit 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.11.0",
+  "version": "0.13.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",
@@ -27,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 src/test-rendered.mjs && node src/test-agent-surface.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 src/test-agent-surface.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",
     "sample": "node bin/audit.mjs render examples/sample-audit.json --pdf"
   },
   "keywords": [

package/src/collect.mjs

@@ -3,11 +3,21 @@
  * 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 { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { renderedDom, compareReadings, jsBlindnessCheck } from './rendered.mjs';
 import { parse } from 'node-html-parser';
 import { localiseChecks } from './i18n.mjs';
 
-const UA = 'Mozilla/5.0 (compatible; OperStackAudit/0.1; +https://oper-stack.com)';
+/** Версия читается из своего package.json. Зашитая строка врала в каждом отчёте с первого релиза:
+ *  в подвале стояло 0.1.0, когда пакет был уже 0.12.0, и покупатель не мог понять, чем его мерили. */
+const VERSION = (() => {
+  try { return JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')).version; }
+  catch { return '0'; }
+})();
+
+const UA = `Mozilla/5.0 (compatible; OperStackAudit/${VERSION}; +https://oper-stack.com)`;
 
 async function get(url, { method = 'GET', timeout = 15000 } = {}) {
   const c = new AbortController(); const t = setTimeout(() => c.abort(), timeout);
@@ -229,6 +239,34 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
     !llms.ok ? 'not present' : !llmsIsText ? 'answers with an HTML page, not a text index' : `${llmsLinks.length} link(s), ${llmsForeign.length} to other hosts`,
     !llms.ok ? 'answer engines get nothing to read; a generated index is a one-day job' : llmsForeign.length > 3 ? `links to ${[...new Set(llmsForeign.map((u) => new URL(u).host))].slice(0, 3).join(', ')}: an AI system may misidentify the business` : ''));
 
+  // Здоровье llms.txt: мы проверяем не только то, что файл есть, но и то, что он ведёт в живые
+  // страницы. Индекс для ИИ разъезжается тихо: страницу переименовали, закрыли от индексации или
+  // удалили, а в индексе она осталась, и ИИ идёт цитировать редирект или пустоту. Проверяем
+  // выборку своих ссылок, а не все: на большом сайте их тысячи, а беда видна и по двадцати.
+  const llmsOwn = llmsLinks.filter((u) => { try { const h = new URL(u).host; return h === host || h === altHost; } catch { return false; } });
+  if (llmsOwn.length) {
+    const sampleSize = Math.min(20, llmsOwn.length);
+    const step = Math.max(1, Math.floor(llmsOwn.length / sampleSize));
+    const picked = llmsOwn.filter((_, i) => i % step === 0).slice(0, sampleSize);
+    const broken = [];
+    const redirected = [];
+    const closed = [];
+    for (const u of picked) {
+      const r = await get(u);
+      if (r.status >= 300 && r.status < 400) { redirected.push(u); continue; }
+      if (!r.ok) { broken.push(u); continue; }
+      if (/<meta[^>]+name=["\']robots["\'][^>]+noindex/i.test(r.text || '')) closed.push(u);
+    }
+    const sick = broken.length + redirected.length + closed.length;
+    const parts = [];
+    if (broken.length) parts.push(`${broken.length} dead`);
+    if (redirected.length) parts.push(`${redirected.length} redirecting`);
+    if (closed.length) parts.push(`${closed.length} closed to indexing`);
+    checks.push(row('llms-health', 'geo', 'Pages listed in llms.txt', sick > picked.length / 4 ? 'bad' : sick ? 'warn' : 'ok',
+      sick ? `${parts.join(', ')} of ${picked.length} checked: ${[...broken, ...redirected, ...closed][0]}` : `all ${picked.length} checked page(s) answer and are open to indexing`,
+      sick ? 'an answer engine reads this file instead of crawling: every dead or closed entry is a page it will quote wrongly or not at all' : ''));
+  }
+
   // Агентная поверхность: карточки, по которым ИИ-агент понимает, с чем имеет дело и что тут можно
   // вызвать. Стандарты молодые, поэтому отсутствие это не провал, а предупреждение, и в тексте
   // прямо сказано, что это раннее и необязательное. Врать про обязательность мы не будем.
@@ -385,7 +423,7 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
   const critical = checks.filter((c) => c.status === 'bad').map((c) => ({ title: c.label, text: `${c.value}${c.comment ? `. ${c.comment}` : ''}`, level: 'bad' }));
 
   return {
-    meta: { site: home.final, host, collectedAt: new Date().toISOString(), tool: '@operstack/audit 0.1.0', auditType: lang === 'ru' ? 'Аудит по публичным сигналам' : 'External audit (no Search Console or analytics access)', lang, language: hp ? (hp.og?.locale || '') : '' },
+    meta: { site: home.final, host, collectedAt: new Date().toISOString(), tool: `@operstack/audit ${VERSION}`, auditType: lang === 'ru' ? 'Аудит по публичным сигналам' : 'External audit (no Search Console or analytics access)', lang, language: hp ? (hp.og?.locale || '') : '' },
     client: { name: '{{CLIENT NAME}}', subject: '{{What the site sells and where}}', reportDate: new Date().toISOString().slice(0, 10), preparedBy: 'OperStack' },
     scores,
     scoreBasis,

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' } },
+  'llms-health': { scope: 'always', action: { ru: 'Пересобрать llms.txt по живым страницам: убрать мёртвые адреса, заменить переадресованные на конечные, исключить закрытые от индексации', en: 'Rebuild llms.txt from the live pages: drop dead URLs, replace redirecting ones with their destination, leave out anything closed to indexing' } },
   'agent-card': { scope: 'always', action: { ru: 'Положить в /.well-known/agent.json карточку с названием компании, одной строкой о том, чем она занимается, адресом сайта и способом связи', en: 'Put an agent card at /.well-known/agent.json with the company name, one line on what it does, the site address and a way to get in touch' } },
   'api-catalog': { scope: 'never', why: { ru: 'нужен только тем, у кого есть API для агентов, выдумывать его ради галочки незачем', en: 'only for a business that actually exposes an API for agents; inventing one for the sake of a tick is pointless' } },
   'agent-markdown': { scope: 'files', action: { ru: 'Отдавать markdown-версию каждой страницы и объявлять её заголовком Link рядом с HTML', en: 'Serve a markdown version of every page and declare it with a Link header beside the HTML' } },

package/src/i18n.mjs

@@ -10,8 +10,10 @@
  *   audit.checks = localiseChecks(audit.checks, 'ru')
  */
 
-/** Достаёт все целые и дробные числа из строки по порядку. */
-const nums = (s) => (String(s).match(/\d+(?:[.,]\d+)?/g) || []).map((x) => x.replace(',', '.'));
+/** Достаёт все целые и дробные числа из строки по порядку.
+ *  Сборщик пишет по-английски, и там запятая это разделитель тысяч: «median 1,600 words».
+ *  Пока её принимали за дробную часть, 1600 слов превращались в 1,6 и уезжали в отчёт покупателю. */
+const nums = (s) => (String(s).match(/\d+(?:[.,]\d{3})*(?:\.\d+)?/g) || []).map((x) => x.replace(/,(?=\d{3}\b)/g, ''));
 /** Склонение: 1 страница, 2 страницы, 5 страниц. */
 const plural = (n, one, few, many) => {
   const d = Math.abs(n) % 10; const dd = Math.abs(n) % 100;
@@ -78,12 +80,12 @@ const RU = {
         : `${plural(Number(nums(v)[0]), 'ссылка', 'ссылки', 'ссылок')}, ${nums(v)[1]} на другие хосты`),
     comment: (c) => (/nothing to read/.test(c) ? 'ответным системам нечего читать, генерация индекса это работа на день' : c ? 'система ИИ может принять сайт за чужой' : ''),
   },
-  title: { label: 'Заголовок главной', value: (v) => { const n = nums(v); return `${plural(Number(n[n.length - 1]), 'знак', 'знака', 'знаков')}${Number(n[n.length - 1]) > 60 ? ', в выдаче обрежется' : ', укладывается в выдачу'}`; } },
-  description: { label: 'Описание главной', value: (v) => (/missing|none/i.test(v) ? 'нет' : /shortcode|garbage/i.test(v) ? 'содержит служебный код вместо текста' : `${plural(Number(nums(v)[0]), 'знак', 'знака', 'знаков')}`) },
-  h1: { label: 'Заголовок H1 на главной', value: (v) => `${plural(Number(nums(v)[0] || 0), 'заголовок', 'заголовка', 'заголовков')} H1` },
+  title: { label: 'Заголовок главной', value: (v) => { const n = nums(v); return `${plural(Number(n[n.length - 1]), 'знак', 'знака', 'знаков')}${Number(n[n.length - 1]) > 60 ? ', в выдаче обрежется' : ', укладывается в выдачу'}`; }, comment: (c) => (/^short/.test(c) ? 'коротко: в заголовке нет слов, ради которых по нему кликают' : /cut in results/.test(c) ? 'в выдаче обрежется' : '') },
+  description: { label: 'Описание главной', value: (v) => (/missing|none/i.test(v) ? 'нет' : /shortcode|garbage/i.test(v) ? 'содержит служебный код вместо текста' : `${plural(Number(nums(v)[0]), 'знак', 'знака', 'знаков')}`), comment: (c) => (/technical garbage/.test(c) ? 'в сниппете покажется технический мусор вместо текста' : /missing/.test(c) ? 'описания нет' : '') },
+  h1: { label: 'Заголовок H1 на главной', value: (v) => `${plural(Number(nums(v)[0] || 0), 'заголовок', 'заголовка', 'заголовков')} H1`, comment: (c) => (/dilutes/.test(c) ? 'больше одного H1 размывает тему страницы' : /no H1/.test(c) ? 'H1 на странице нет' : '') },
   canonical: { label: 'Канонический адрес', value: (v) => (/missing|none/i.test(v) ? 'не указан' : 'указан') },
   viewport: { label: 'Мобильный viewport', value: (v) => (/missing/.test(v) ? 'не задан' : v), comment: (c) => (c ? 'запрещает масштабирование: плохо для доступности и мобильного поиска' : '') },
-  og: { label: 'Карточки для соцсетей', value: (v) => (/none/.test(v) ? 'нет' : v) },
+  og: { label: 'Карточки для соцсетей', value: (v) => (/none/.test(v) ? 'нет' : v), comment: (c) => (/shortcode/.test(c) ? 'в описании служебный код вместо текста' : '') },
   schema: { label: 'Разметка на главной', value: (v) => (/no JSON-LD/.test(v) ? 'разметки нет' : /invalid/.test(v) ? 'разметка есть, но с ошибкой' : v) },
   'faq-schema': { label: 'Разметка вопросов FAQPage', value: (v) => (/not found/.test(v) ? 'не найдена в выборке' : `есть на ${pages(nums(v)[0])} выборки`) },
   'org-schema': { label: 'Разметка организации', value: (v) => (/not found/.test(v) ? 'не найдена: ответным системам не к чему привязать сайт' : 'есть') },
@@ -105,6 +107,7 @@ const RU = {
   tables: { label: 'Таблицы в тексте', value: (v) => (/no table/.test(v) ? 'на проверенных страницах таблиц нет' : `${nums(v)[0]} из ${pages(nums(v)[1])} выборки используют таблицу`), comment: (c) => (c ? 'таблица это второй по частоте формат цитирования после первого абзаца' : '') },
   sources: { label: 'Названные источники цифр', value: (v) => { const n = nums(v); return `${n[0]} из ${pages(n[1])} выборки называют, откуда взята цифра, словами или ссылкой рядом с ней`; }, comment: (c) => (c ? 'цифра без источника это первое, что система выбрасывает' : '') },
   dates: { label: 'Открытые даты публикации', value: (v) => (/no article dates/.test(v) ? 'дат в выборке нет: ответные системы не поймут, что здесь актуально' : `${nums(v)[0]} из ${pages(nums(v)[1])} выборки показывают дату`) },
+  'llms-health': { label: 'Страницы из llms.txt', value: (v) => (/^all /.test(v) ? `все ${nums(v)[0]} проверенных страниц отвечают и открыты для индексации` : v.replace(/(\d+) dead/, '$1 мёртвых').replace(/(\d+) redirecting/, '$1 с переадресацией').replace(/(\d+) closed to indexing/, '$1 закрытых от индексации').replace(/ of (\d+) checked: /, ' из $1 проверенных: ')), comment: (c) => (c ? 'ИИ читает этот файл вместо обхода сайта: каждая мёртвая или закрытая запись это страница, которую он процитирует неверно или не процитирует вовсе' : '') },
   'agent-card': { label: 'Карточка агента (/.well-known/agent.json)', value: (v) => (/valid JSON/.test(v) ? 'есть, и это правильный JSON' : /not JSON/.test(v) ? 'есть, но это не JSON' : 'нет'), comment: (c) => (c ? 'ранний и необязательный стандарт: этот файл читают каталоги ИИ-агентов, чтобы понять, кто вы и что предлагаете' : '') },
   'api-catalog': { label: 'Каталог API (RFC 9727)', value: (v) => (/^present/.test(v) ? 'есть' : 'нет'), comment: (c) => (c ? 'необязательно, и нужно только если у бизнеса действительно есть API, который агент мог бы вызвать' : '') },
   'agent-markdown': { label: 'Markdown-версия страниц', value: (v) => (/Link header/.test(v) ? 'предлагается через заголовок Link' : /next to the page/.test(v) ? 'лежит рядом со страницей' : 'не предлагается'), comment: (c) => (c ? 'агент, который просит text/markdown, получает HTML и вынужден его разбирать: отдать markdown дёшево и снимает догадки' : '') },

package/src/narrative.mjs

@@ -123,6 +123,9 @@ const open = (c) => c && (c.status === 'warn' || c.status === 'bad');
  * @param {object} audit результат collect()
  * @param {{lang?: 'ru'|'en'}} opts
  */
+/** Проверки, которые закрывает только текст клиента: у них есть своя формулировка работы. */
+const TEXT_WORK_IDS = new Set(['thin', 'answer-first', 'sources', 'sections', 'tables']);
+
 export function draftNarrative(audit, opts = {}) {
   const lang = opts.lang || audit.meta?.lang || 'en';
   const t = T[lang === 'ru' ? 'ru' : 'en'];
@@ -169,7 +172,14 @@ export function draftNarrative(audit, opts = {}) {
     return c.label;
   };
   const action = (c) => `${actionText(c)}. ${lang === 'ru' ? 'Сейчас' : 'Now'}: ${c.value}`;
-  const top = [...bad, ...warn].slice(0, 3);
+  // В приоритеты идут только те находки, для которых есть действие. У части проверок в FIX_ACTIONS
+  // вместо действия стоит довод против («это имеет смысл только тем, у кого правда есть API»), и
+  // такая строка первым пунктом плана читается как отговорка, а не как задача.
+  const actionable = (c) => {
+    const rule = FIX_ACTIONS[c.id];
+    return Boolean((rule && rule.action) || TEXT_WORK_IDS.has(c.id));
+  };
+  const top = [...bad.filter(actionable), ...warn.filter(actionable), ...bad.filter((c) => !actionable(c)), ...warn.filter((c) => !actionable(c))].slice(0, 3);
   a.summary.priorities = (a.summary.priorities || []).map((p, i) => {
     if (!String(p).includes('{{')) return p;
     const c = top[i];

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.' },
   },
+  'llms-health': {
+    ru: { task: 'Пересобери llms.txt из списка живых страниц сайта. Каждый адрес в файле должен отвечать кодом 200 и быть открыт для индексации. Переадресованные адреса замени на конечные, мёртвые убери, закрытые от индексации не включай. Если файл собирается скриптом при сборке, почини скрипт, а не файл: иначе он разъедется снова на следующей выкладке.', verify: 'Каждая ссылка из llms.txt отвечает 200, ни одна не ведёт на переадресацию, и ни у одной нет метки noindex.' },
+    en: { task: 'Rebuild llms.txt from the site\'s live pages. Every URL in it must answer 200 and be open to indexing. Replace redirecting URLs with their destination, drop dead ones, leave out anything marked noindex. If the file is generated at build time, fix the generator rather than the file, or it drifts again on the next deploy.', verify: 'Every link in llms.txt answers 200, none redirects, and none carries a noindex marker.' },
+  },
   'agent-card': {
     ru: { task: 'Собери файл /.well-known/agent.json: название компании, одна строка о том, чем она занимается, адрес сайта, способ связи и перечень того, что вы предлагаете. Пиши только правду: это читают каталоги агентов, и выдуманная возможность обернётся жалобой. Файл отдавай с типом application/json.', verify: 'Адрес /.well-known/agent.json отвечает 200, тип application/json, и JSON разбирается без ошибок.' },
     en: { task: 'Build a /.well-known/agent.json: the company name, one line on what it does, the site address, a way to get in touch and a list of what you offer. Put only true things in it: agent directories read this, and an invented capability turns into a complaint. Serve it as application/json.', verify: '/.well-known/agent.json answers 200 with application/json and parses as valid JSON.' },

package/src/test-i18n.mjs

@@ -20,7 +20,11 @@ ok('статусы не тронуты', ru.every((c, i) => c.status === all[i].
 ok('идентификаторы не тронуты', ru.every((c, i) => c.id === all[i].id));
 
 // в русском тексте не должно остаться английских слов, кроме технических имён
-const TECH = /https?|robots\.txt|llms\.txt|sitemap|xmlrpc|HTTP|HTTPS|H1|H2|og:|twitter:|JSON-LD|FAQPage|Organization|WebSite|Article|LocalBusiness|viewport|width|initial-scale|device-width|user-scalable|maximum-scale|Disallow|User-agent|gptbot|google-extended|ccbot|anthropic-ai|claudebot|applebot-extended|facebookbot|meta-externalagent|bytespider|oai-searchbot|chatgpt-user|perplexitybot|claude-searchbot|duckassistbot|applebot|sameAs|com|ru|org|io|me|net|dev|github|npmjs|apify|producthunt|wikidata|moregroup|estate|Content|Type|Cache|Control|OperStack|SEO|AEO|GEO|AI|XML|CMS|PDF|URL/gi;
+// Технические имена, которые обязаны остаться латиницей. Границы слова здесь не украшение:
+// без них \bio\b съедало «io» внутри description, а Estate внутри RealEstateAgent, и тест
+// докладывал о несуществующих английских хвостах вроде «descriptn» и «RealAgent».
+const SCHEMA_TYPES = 'RealEstateAgent|Corporation|BreadcrumbList|WebPage|Product|Service|Place|Person|ItemList|HowTo|QAPage|NewsArticle|BlogPosting|CollectionPage|AboutPage|ContactPage|SoftwareApplication';
+const TECH = new RegExp(`\\b(?:https?|robots\.txt|llms\.txt|sitemap|xmlrpc|HTTP|HTTPS|H1|H2|og:|twitter:|JSON-LD|FAQPage|Organization|WebSite|Article|LocalBusiness|viewport|width|initial-scale|device-width|user-scalable|maximum-scale|Disallow|User-agent|gptbot|google-extended|ccbot|anthropic-ai|claudebot|applebot-extended|facebookbot|meta-externalagent|bytespider|oai-searchbot|chatgpt-user|perplexitybot|claude-searchbot|duckassistbot|applebot|sameAs|com|ru|org|io|me|net|dev|github|npmjs|apify|producthunt|wikidata|moregroup|estate|Content|Type|Cache|Control|OperStack|SEO|AEO|GEO|AI|XML|CMS|PDF|URL|${SCHEMA_TYPES})\\b`, 'gi');
 const leftovers = [];
 for (const c of ru) {
   for (const field of ['label', 'value', 'comment']) {
@@ -36,11 +40,12 @@ for (const c of ru) {
 is('английских слов в русском тексте не осталось', leftovers, []);
 
 // числа не потерялись
-const digits = (s) => (String(s).match(/\d+/g) || []).join(',');
+// Английские тысячи пишутся через запятую, русские слитно: 1,600 и 1600 это одно число.
+const digits = (s) => (String(s).replace(/,(?=\d{3}\b)/g, '').match(/\d+/g) || []).join('|');
 const lostNumbers = ru.filter((c, i) => {
   const before = digits(all[i].value);
   const after = digits(c.value);
-  return before && after && before.split(',').some((n) => !after.split(',').includes(n));
+  return before && after && before.split('|').some((n) => !after.split('|').includes(n));
 }).map((c) => `${c.id}: было ${digits(all[all.findIndex((x) => x.id === c.id)].value)}, стало ${digits(c.value)}`);
 is('числа в тексте сохранились', lostNumbers, []);