@operstack/audit 0.25.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.25.0",
+  "version": "0.27.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 && node src/test-sample-fairness.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 && node test-engines.mjs",
     "sample": "node bin/audit.mjs render examples/sample-audit.json --pdf",
     "verify:live": "node src/verify-live.mjs"
   },

package/src/prompts.mjs

@@ -128,6 +128,80 @@ const HEAD = {
  * @param {object} check строка проверки из аудита
  * @param {{lang?: 'ru'|'en', urls?: string[]}} opts
  */
+
+/**
+ * Где именно делать правку, смотря на чём собран сайт.
+ *
+ * Простым языком. Задание «поставьте разметку организации» верно для всех, но человек на WordPress
+ * спрашивает «где?», и человек на Astro спрашивает то же про другое место. Раньше он искал сам.
+ * Здесь названо конкретное место для четырёх самых частых случаев.
+ *
+ * Платформа не угадывается: берётся из проверки `cms`, то есть из того, что сайт сам о себе сказал
+ * в мета-теге generator. Молчит, значит показываем все варианты, а не выбираем наугад.
+ *
+ * Добавлено 17.09.2026 после разбора конкурентов: у обоих код правки даётся под конкретный стек, и
+ * это единственное место, где их подсказка была полезнее нашей.
+ */
+const WHERE = {
+  'org-schema': {
+    wordpress: { ru: 'тема: header.php или functions.php через wp_head, либо плагин разметки', en: 'theme: header.php, or functions.php via wp_head, or a schema plugin' },
+    astro: { ru: 'src/layouts, ваш общий макет, внутрь <head>', en: 'src/layouts, your shared layout, inside <head>' },
+    next: { ru: 'app/layout.tsx, тег <script type="application/ld+json">', en: 'app/layout.tsx, a <script type="application/ld+json"> tag' },
+    shopify: { ru: 'theme.liquid, перед </head>', en: 'theme.liquid, before </head>' },
+  },
+  'og-title': {
+    wordpress: { ru: 'плагин SEO (Yoast, Rank Math) заполняет og:title из заголовка записи', en: 'an SEO plugin (Yoast, Rank Math) fills og:title from the post title' },
+    astro: { ru: 'общий макет, где собирается <head>', en: 'the shared layout where <head> is assembled' },
+    next: { ru: 'export const metadata, поле openGraph.title', en: 'export const metadata, the openGraph.title field' },
+    shopify: { ru: 'theme.liquid, секция мета-тегов', en: 'theme.liquid, the meta tag section' },
+  },
+  'og-image': {
+    wordpress: { ru: 'изображение записи подставляется в og:image плагином SEO', en: 'the featured image becomes og:image through the SEO plugin' },
+    astro: { ru: 'общий макет, поле ogImage у страницы', en: 'the shared layout, the page ogImage field' },
+    next: { ru: 'export const metadata, поле openGraph.images', en: 'export const metadata, the openGraph.images field' },
+    shopify: { ru: 'theme.liquid, мета-теги', en: 'theme.liquid, the meta tags' },
+  },
+  canonical: {
+    wordpress: { ru: 'плагин SEO ставит canonical сам; проверьте, не выключен ли он для этого типа записей', en: 'the SEO plugin sets canonical; check it is not switched off for this post type' },
+    astro: { ru: 'общий макет, <link rel="canonical">', en: 'the shared layout, <link rel="canonical">' },
+    next: { ru: 'export const metadata, поле alternates.canonical', en: 'export const metadata, the alternates.canonical field' },
+    shopify: { ru: 'theme.liquid, {{ canonical_url }}', en: 'theme.liquid, {{ canonical_url }}' },
+  },
+  favicon: {
+    wordpress: { ru: 'Внешний вид, Свойства сайта, Значок сайта', en: 'Appearance, Site Identity, Site Icon' },
+    astro: { ru: 'public/favicon.svg и <link rel="icon"> в макете', en: 'public/favicon.svg and <link rel="icon"> in the layout' },
+    next: { ru: 'app/icon.png или app/favicon.ico', en: 'app/icon.png or app/favicon.ico' },
+    shopify: { ru: 'Настройки темы, Favicon', en: 'Theme settings, Favicon' },
+  },
+  'redirect-chain': {
+    wordpress: { ru: 'плагин переадресаций: замените цепочку одним правилом на конечный адрес', en: 'the redirect plugin: replace the chain with one rule to the final address' },
+    astro: { ru: 'vercel.json или netlify.toml, раздел redirects', en: 'vercel.json or netlify.toml, the redirects section' },
+    next: { ru: 'next.config.js, функция redirects()', en: 'next.config.js, the redirects() function' },
+    shopify: { ru: 'Интернет-магазин, Навигация, Переадресации адресов', en: 'Online Store, Navigation, URL Redirects' },
+  },
+};
+
+const PLATFORM_LABEL = { wordpress: 'WordPress', astro: 'Astro', next: 'Next.js', shopify: 'Shopify' };
+
+/** На чём собран сайт, по словам самого сайта. Не угадываем: молчит, значит показываем все. */
+export function detectPlatform(audit) {
+  const cms = (audit?.checks || []).find((c) => c.id === 'cms');
+  const said = String(cms?.value || '').toLowerCase();
+  if (/wordpress|woocommerce/.test(said)) return 'wordpress';
+  if (/astro/.test(said)) return 'astro';
+  if (/next/.test(said)) return 'next';
+  if (/shopify/.test(said)) return 'shopify';
+  return null;
+}
+
+function whereLine(id, platform, lang) {
+  const map = WHERE[id];
+  if (!map) return '';
+  const head = lang === 'ru' ? 'Где' : 'Where';
+  if (platform && map[platform]) return `**${head}:** ${PLATFORM_LABEL[platform]}, ${map[platform][lang]}`;
+  return `**${head}:** ${Object.entries(map).map(([k, v]) => `${PLATFORM_LABEL[k]}, ${v[lang]}`).join('; ')}`;
+}
+
 export function agentPrompt(check, opts = {}) {
   const lang = opts.lang === 'ru' ? 'ru' : 'en';
   const h = HEAD[lang];
@@ -138,6 +212,8 @@ export function agentPrompt(check, opts = {}) {
   const lines = [`### ${check.label}`, '', `**${h.now}:** ${check.value}`, '', `**${h.task}:** ${own ? own.task : fallback}`];
   // Проверка обязательна у каждого задания: без неё агент не знает, когда остановиться.
   lines.push('', `**${h.verify}:** ${own ? own.verify : h.genericVerify}`);
+  const where = whereLine(check.id, opts.platform || null, lang);
+  if (where) lines.push('', where);
   if (opts.urls && opts.urls.length) { lines.push('', `**${h.pages}:** ${opts.urls.slice(0, 8).join(', ')}`); }
   lines.push('', h.rule);
   return lines.join('\n');
@@ -153,7 +229,8 @@ export function agentPrompts(audit, opts = {}) {
   const checks = source.filter((c) => c.status === 'bad' || c.status === 'warn');
   const ordered = [...checks.filter((c) => c.status === 'bad'), ...checks.filter((c) => c.status === 'warn')];
   const chosen = limit > 0 ? ordered.slice(0, limit) : ordered;
-  return chosen.map((c) => ({ id: c.id, hasOwnText: Boolean(P[c.id]), text: agentPrompt(c, { lang }) }));
+  const platform = opts.platform || detectPlatform(audit);
+  return chosen.map((c) => ({ id: c.id, hasOwnText: Boolean(P[c.id]), text: agentPrompt(c, { lang, platform }) }));
 }
 
 /** Файл, который отдаётся клиенту вместе с отчётом. */

package/src/visibility.mjs

@@ -40,6 +40,36 @@ const AI_AGENTS = [
   { agent: 'duckassistbot', label: 'DuckDuckGo AI (DuckAssistBot)', labelRu: 'DuckDuckGo AI (DuckAssistBot)', kind: 'search' },
 ];
 
+/**
+ * Готовность по каждому движку отдельно.
+ *
+ * Простым языком. «Цитируемость 20 из 25» человеку ничего не говорит, а «Gemini 61» говорит сразу.
+ * Поэтому те же самые измерения пересобираются в одно число на движок.
+ *
+ * Здесь не придумано ни одного нового замера. Число собирается ТОЛЬКО из того, что мы уже
+ * измерили, и под каждым движком видно, из чего оно сложилось. Это принципиально: конкурент
+ * показывает такие числа без объяснения, откуда они, и мы за это его же и критикуем.
+ *
+ * Почему веса у движков разные. ChatGPT, Perplexity и Claude достают страницу живьём в момент
+ * ответа, поэтому у них решает доступ их собственным роботам и то, есть ли что процитировать.
+ * Gemini и Copilot отвечают из чужого индекса, Google и Bing, поэтому у них сильнее весит
+ * разметка: в индексе страницу сначала надо понять. Веса названы здесь и больше нигде, чтобы
+ * их нельзя было тихо поменять в двух местах по-разному.
+ *
+ * Неизмеренная область в расчёт не идёт вовсе, и оставшиеся веса делятся заново. Правило то же,
+ * что и у общего балла: не измерили, значит не считаем ни в плюс, ни в минус.
+ */
+const LIVE_MIX = Object.freeze({ access: 0.45, content: 0.30, trust: 0.15, entity: 0.10 });
+const INDEX_MIX = Object.freeze({ access: 0.30, entity: 0.30, content: 0.25, trust: 0.15 });
+
+const ENGINES = [
+  { id: 'chatgpt', label: 'ChatGPT', agents: ['oai-searchbot', 'chatgpt-user'], mix: LIVE_MIX, live: true },
+  { id: 'perplexity', label: 'Perplexity', agents: ['perplexitybot', 'perplexity-user'], mix: LIVE_MIX, live: true },
+  { id: 'claude', label: 'Claude', agents: ['claude-searchbot', 'claude-user'], mix: LIVE_MIX, live: true },
+  { id: 'gemini', label: 'Gemini', agents: ['google-extended'], mix: INDEX_MIX, live: false },
+  { id: 'copilot', label: 'Copilot', agents: ['bingbot'], mix: INDEX_MIX, live: false },
+];
+
 /**
  * Russian plural form: pl(1, ...) is "страница", pl(2, ...) "страницы", pl(5, ...) "страниц".
  * Two shapes are needed and they differ: a bare count takes the counted form, while "из N"
@@ -66,6 +96,8 @@ export const MESSAGES = {
     rulesUnknown: ' Its robots.txt could not be read either, so there is nothing to say about AI crawlers: that is not counted for or against the site.',
     howToCheckBots: ' To know for certain, open the server log and look for GPTBot, ClaudeBot and PerplexityBot, or ask whoever runs the protection which bots are on the allowlist.',
     area: { access: 'Can AI crawlers read it', index: 'Is there a map for agents (llms.txt)', entity: 'Is the entity clear (schema)', content: 'Is there something to quote', trust: 'Can it be dated and trusted' },
+    engineLive: 'fetches the page live when it answers',
+    engineIndex: 'answers from an index, so schema weighs more',
     llmsUnreadable: (status) => `The site did not let this check read llms.txt${status ? ` (HTTP ${status})` : ''}, so whether the site has a map for agents could not be measured. It is not counted for or against the site: a file we were refused is not the same as a file that is not there.`,
     robotsMissing: 'There is no robots.txt on the site. By the standard that means nothing is disallowed, so every AI crawler may read it. A file is not required; add one only when something needs closing off.',
     sampleShort: (read, wanted) => `Only ${read} of ${wanted} pages answered in time, twice in a row, so there was not enough of the site to score. We do not show a number here: a score that goes up because we read less is a score nobody can defend. The site may simply be slow right now; run the check again in a minute.`,
@@ -117,6 +149,8 @@ export const MESSAGES = {
     rulesUnknown: ' Файл robots.txt прочитать тоже не вышло, поэтому про роботов ИИ сказать нечего, и в плюс или в минус сайту это не зачтено.',
     howToCheckBots: ' Чтобы знать точно, посмотрите в журнале сервера, приходят ли GPTBot, ClaudeBot и PerplexityBot, либо спросите у тех, кто настраивал защиту, кто у неё в белом списке.',
     area: { access: 'Могут ли роботы ИИ прочитать сайт', index: 'Есть ли карта для агентов (llms.txt)', entity: 'Понятно ли, кто вы (разметка)', content: 'Есть ли что процитировать', trust: 'Можно ли датировать и доверять' },
+    engineLive: 'достаёт страницу живьём в момент ответа',
+    engineIndex: 'отвечает из индекса, поэтому разметка весит больше',
     llmsUnreadable: (status) => `Сайт не дал этой проверке прочитать llms.txt${status ? ` (код ${status})` : ''}, поэтому есть ли у сайта карта для агентов, измерить не вышло. В плюс или в минус это не зачтено: файл, который нам не отдали, это не то же самое, что файла нет.`,
     robotsMissing: 'Файла robots.txt на сайте нет. По стандарту это значит, что не запрещено ничего, то есть читать сайт может любой робот ИИ. Заводить файл необязательно: он нужен, только когда есть что закрывать.',
     sampleShort: (read, wanted) => `Из ${wanted} страниц ответили ${read}, и со второй попытки тоже, поэтому считать балл не по чему. Числа здесь не будет: балл, который растёт оттого, что мы прочитали меньше, защитить нельзя. Возможно, сайт сейчас просто медленный: запустите проверку через минуту.`,
@@ -316,7 +350,55 @@ function analysePage(html, url) {
     const named = Boolean(blockText.match(SOURCE_RE)) || Boolean(blockText.match(ILLUSTRATIVE_RE)) || OUTBOUND_LINK_RE.test(block);
     if (!named) unsourcedFigures += found;
   }
-  return { url, title, description, robotsMeta, canonical, ogTitle, schemaTypes: [...types], datePublished, dateModified, words, h1, h2Count, tables, firstPara: firstPara.slice(0, 220), answerFirst, claimFigures, unsourcedFigures, noai: /noai|noimageai/.test(robotsMeta) };
+  // Ссылки и картинки считаются по тому же телу, из которого выброшена обвязка сайта: меню и
+  // подвал есть на каждой странице одинаково, и в свойствах страницы им делать нечего.
+  const links = (bodyHtml.match(/<a[^>]+href=/gi) || []).length;
+  const images = (bodyHtml.match(/<img[\s>]/gi) || []).length;
+  return { url, title, description, robotsMeta, canonical, ogTitle, schemaTypes: [...types], datePublished, dateModified, words, h1, h2Count, tables, links, images, firstPara: firstPara.slice(0, 220), answerFirst, claimFigures, unsourcedFigures, noai: /noai|noimageai/.test(robotsMeta) };
+}
+
+
+/**
+ * Сводит измеренное в одно число на движок. Возвращает и само число, и подписи под ним: какие
+ * роботы этого движка пущены, и какая из областей тянет сильнее всего вниз. Без подписей число
+ * было бы гаданием, а мы обещаем обратное.
+ */
+export function engineReadiness(verdicts, parts, T, label = (v) => v.label) {
+  const byAgent = new Map(verdicts.map((v) => [v.agent, v]));
+  return ENGINES.map((e) => {
+    const own = e.agents.map((a) => byAgent.get(a)).filter(Boolean);
+    const known = own.filter((v) => v.verdict !== 'unknown');
+    const share = {
+      // Доступ считается по роботам ЭТОГО движка, а не по всем четырнадцати: закрытый Applebot
+      // не мешает ChatGPT процитировать страницу.
+      access: known.length ? known.filter((v) => v.verdict !== 'blocked').length / known.length : null,
+      entity: parts.entity,
+      content: parts.content,
+      trust: parts.trust,
+    };
+    let sum = 0;
+    let weight = 0;
+    for (const [key, w] of Object.entries(e.mix)) {
+      if (share[key] === null || share[key] === undefined) continue;
+      sum += share[key] * w;
+      weight += w;
+    }
+    const score = weight ? Math.round((sum / weight) * 100) : null;
+    const blocked = own.filter((v) => v.verdict === 'blocked').map(label);
+    // Что тянет вниз: самая слабая из измеренных областей, кроме доступа, о нём сказано отдельно.
+    const areasByWeak = [['content', share.content], ['trust', share.trust], ['entity', share.entity]]
+      .filter(([, v]) => v !== null && v !== undefined)
+      .sort((a, b) => a[1] - b[1]);
+    const weakest = areasByWeak.length && areasByWeak[0][1] < 0.999 ? T.area[areasByWeak[0][0]] : null;
+    return {
+      id: e.id,
+      label: e.label,
+      score,
+      how: e.live ? T.engineLive : T.engineIndex,
+      blocked,
+      weakest,
+    };
+  });
 }
 
 async function readSitemap(origin, robotsText, timeoutFn = () => 3000) {
@@ -720,8 +802,24 @@ export async function checkVisibility(input, { budgetMs = 8500, lang = 'en', sam
   return {
     ok: true, url: home.url, host, checkedAt: new Date().toISOString(), ms: Date.now() - started,
     score: total, grade, areas, fixes,
-    sample: pages.map((p) => ({ url: p.url, title: p.title, words: p.words, answerFirst: p.answerFirst, dated: Boolean(p.datePublished || p.dateModified), schema: p.schemaTypes.slice(0, 4) })),
+    /*
+     * Свойства каждой прочитанной страницы. Заголовок, H1, подзаголовки, таблицы, ссылки и
+     * картинки считались и раньше, но наружу не отдавались, и человек видел «19 из 25», не видя,
+     * из чего это сложилось. Показать то, что уже измерено, дешевле, чем объяснять словами.
+     */
+    sample: pages.map((p) => ({
+      url: p.url, title: p.title, h1: p.h1, words: p.words, h2: p.h2Count, tables: p.tables,
+      links: p.links, images: p.images,
+      answerFirst: p.answerFirst, dated: Boolean(p.datePublished || p.dateModified),
+      schema: p.schemaTypes.slice(0, 4),
+    })),
     sitemap: { found: sitemap.found, count: sitemap.count, lastmod: sitemap.lastmod, unchecked: Boolean(!sitemap.found && (sitemap.timedOut || sitemap.skipped)) },
     crawlers: verdicts.map((v) => ({ label: agentLabel(v), kind: v.kind, verdict: v.verdict })),
+    engines: engineReadiness(verdicts, {
+      access: null, // считается внутри по роботам каждого движка
+      entity: entity / 20,
+      content: sampleOk ? content / 25 : null,
+      trust: sampleOk ? trust / 15 : null,
+    }, T, agentLabel),
   };
 }