@operstack/audit 0.19.2 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.19.2",
+  "version": "0.20.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",

package/src/index.mjs

@@ -6,4 +6,4 @@ export { localiseChecks, localiseBasisNote, untranslated, AREAS_RU } from './i18
 export { buildFixPlan, renderFixPlan, renderFixChecklist, buildFixReport, renderFixReport, FIX_ACTIONS } from './fix.mjs';
 export { buildFoundationScope, renderFoundationScope, renderFoundationChecklist } from './foundation.mjs';
 export { draftNarrative, stillEmpty } from './narrative.mjs';
-export { agentPrompt, agentPrompts, renderAgentPrompts } from './prompts.mjs';
+export { agentPrompt, agentPrompts, renderAgentPrompts, firstFixParts, FIRST_FIX_IDS } from './prompts.mjs';

package/src/prompts.mjs

@@ -174,3 +174,84 @@ export function renderAgentPrompts(audit, opts = {}) {
        'You do not need to know any code. Your job is to say what to do and look at the result.', ''];
   return [intro.join('\n').trimEnd(), ...list.map((x) => x.text)].join('\n\n');
 }
+
+/**
+ * Первая правка на бесплатной странице тремя частями: что сейчас, что поменять, как проверить.
+ *
+ * Зачем: бесплатная проверка (`checkVisibility`) отдаёт находки как { id, area, text }, а
+ * задания выше написаны по строкам аудита с другими ключами (`llms` против `llms-missing`).
+ * Страница показывала только текст находки, а три части приходили лишь письмом. Здесь каждая
+ * находка бесплатной проверки сопоставлена с заданием явно, по одному ключу на id; для находок,
+ * у которых задания в наборе нет, текст написан тут же. Неизвестный id даёт null: страница
+ * тогда честно показывает одну находку, а не чужое указание по чужому сайту.
+ *
+ * «Сейчас» это сам текст находки: он уже измерен и назван, второй раз не формулируем.
+ */
+const FIRST_FIX_BY_PROMPT = {
+  'robots-all-blocked': 'robots',
+  'robots-fetchers-blocked': 'ai-search-access',
+  'llms-missing': 'llms',
+  'canonical-missing': 'canonical',
+  'og-missing': 'og',
+  'schema-org-missing': 'schema',
+  'schema-faq-missing': 'faq-schema',
+  'dates-missing': 'dates',
+  'answer-first-missing': 'answer-first',
+  'sources-missing': 'sources',
+  'thin-pages': 'thin',
+};
+
+const FIRST_FIX_OWN = {
+  'robots-training-blocked': {
+    ru: { task: 'Реши, хочешь ли ты, чтобы модели ИИ учились на сайте. Если да, убери из robots.txt запреты для обучающих роботов, которые названы в строке «Сейчас». Если нет, оставь как есть: это осознанный выбор, а не ошибка, и балл он снижает немного.', verify: 'В robots.txt для названных обучающих роботов нет строки Disallow, либо решение закрыть их записано владельцем словами.' },
+    en: { task: 'Decide whether you want AI models to learn from the site. If yes, remove the robots.txt rules that block the training crawlers named under Now. If no, leave it: that is a deliberate choice, not a mistake, and it costs only a little of the score.', verify: 'robots.txt has no Disallow for the training crawlers named, or the decision to keep them out is written down by the owner.' },
+  },
+  'noai-meta': {
+    ru: { task: 'На одной из страниц стоит мета-тег robots со значением noai: он просит системы ИИ не использовать содержимое. Если хочешь, чтобы сайт цитировали в ответах, убери это значение из шаблона страниц. Если это осознанный запрет, оставь.', verify: 'В HTML проверенных страниц нет мета-тега robots со значением noai.' },
+    en: { task: 'One of the pages carries a robots meta tag with the value noai: it asks AI systems not to use the content. If you want the site quoted in answers, remove that value from the page template. If the ban is deliberate, leave it.', verify: 'The HTML of the sampled pages has no robots meta tag with the value noai.' },
+  },
+  'llms-foreign': {
+    ru: { task: 'Перепиши llms.txt так, чтобы ссылки в нём вели на страницы этого сайта, а не на чужие домены. Чужую ссылку оставь только там, где без неё нельзя (например, профиль в каталоге), и не в начале файла.', verify: 'Большинство ссылок в llms.txt ведут на этот же домен, и первые из них тоже.' },
+    en: { task: 'Rewrite llms.txt so its links point at pages of this site rather than other domains. Keep an outside link only where it cannot be avoided (a directory profile, say), and never at the top of the file.', verify: 'Most links in llms.txt point at this domain, and so do the first ones.' },
+  },
+  'llms-not-text': {
+    ru: { task: 'Адрес /llms.txt отдаёт HTML-страницу вместо текста. Сделай так, чтобы по этому адресу отдавался сам текстовый файл с типом text/plain, а не страница сайта и не заглушка «не найдено» с кодом 200.', verify: '/llms.txt отвечает кодом 200 с типом text/plain, и в ответе текстовый указатель, а не разметка HTML.' },
+    en: { task: '/llms.txt serves an HTML page instead of text. Make that address return the text file itself with the type text/plain, not a site page and not a "not found" page with a 200 status.', verify: '/llms.txt answers 200 with text/plain, and the body is a text index rather than HTML markup.' },
+  },
+  'schema-article-missing': {
+    ru: { task: 'Добавь на страницы статей и записей разметку Article или BlogPosting в JSON-LD: заголовок, дата публикации, дата изменения, автор, издатель. Бери данные со страницы, ничего не придумывай.', verify: 'На странице статьи есть JSON-LD с типом Article или BlogPosting, и проверка разметки не показывает ошибок.' },
+    en: { task: 'Add Article or BlogPosting markup in JSON-LD to the article pages: headline, date published, date modified, author, publisher. Take the data from the page, invent nothing.', verify: 'An article page carries JSON-LD of type Article or BlogPosting and the markup validator shows no errors.' },
+  },
+  'few-h2': {
+    ru: { task: 'Разбей длинные страницы на разделы: каждый начинается заголовком H2, который звучит как вопрос или тема раздела. На странице должно быть не меньше трёх таких разделов. Ради объёма ничего не дописывай, только структурируй то, что есть.', verify: 'На каждой проверенной странице не меньше трёх заголовков H2, и по ним понятно, о чём страница, без чтения текста.' },
+    en: { task: 'Split the long pages into sections, each opening with an H2 that reads as the question or topic of that section. A page needs at least three. Add nothing for length, only structure what is there.', verify: 'Every sampled page has at least three H2 headings, and they alone tell what the page is about.' },
+  },
+  'no-tables': {
+    ru: { task: 'Там, где на странице есть цифры, которые сравнивают (цены, сроки, площади, условия), собери их в таблицу с подписанными столбцами. Строй её только из данных, которые уже есть на странице или у владельца.', verify: 'На страницах со сравниваемыми цифрами есть хотя бы одна настоящая таблица (тег table), а не картинка и не список.' },
+    en: { task: 'Where a page has figures that get compared (prices, timings, areas, terms), put them in a table with labelled columns. Build it only from data already on the page or held by the owner.', verify: 'Pages with comparable figures carry at least one real table (a table tag), not an image and not a list.' },
+  },
+  'sitemap-no-lastmod': {
+    ru: { task: 'Проставь в карте сайта (sitemap.xml) каждой странице поле lastmod с настоящей датой последнего изменения содержимого. Дату сборки или сегодняшнее число во все строки не ставь: это хуже, чем пустое поле.', verify: 'У каждого url в sitemap.xml есть lastmod, даты различаются между страницами и совпадают с датой изменения на самой странице.' },
+    en: { task: 'Give every page in sitemap.xml a lastmod with the real date its content last changed. Do not stamp the build date or today on every line: that is worse than leaving it empty.', verify: 'Every url in sitemap.xml has a lastmod, the dates differ between pages and match the modified date on the page itself.' },
+  },
+};
+
+/** Все id находок бесплатной проверки, для которых есть три части. */
+export const FIRST_FIX_IDS = [...Object.keys(FIRST_FIX_BY_PROMPT), ...Object.keys(FIRST_FIX_OWN)];
+
+/**
+ * @param {{id?: string, area?: string, text?: string}} finding элемент `fixes[]` из `checkVisibility`
+ * @param {{lang?: 'ru'|'en'}} opts
+ * @returns {{now: string, task: string, verify: string, rule: string, labels: {now: string, task: string, verify: string}}|null}
+ */
+export function firstFixParts(finding, opts = {}) {
+  const lang = opts.lang === 'ru' ? 'ru' : 'en';
+  const h = HEAD[lang];
+  const id = finding && finding.id;
+  const now = String((finding && finding.text) || '').trim();
+  if (!id || !now) return null;
+  const own = FIRST_FIX_OWN[id] ? withLang(FIRST_FIX_OWN[id], lang)
+    : (FIRST_FIX_BY_PROMPT[id] && P[FIRST_FIX_BY_PROMPT[id]] ? withLang(P[FIRST_FIX_BY_PROMPT[id]], lang) : null);
+  if (!own || !own.task || !own.verify) return null;
+  return { now, task: own.task, verify: own.verify, rule: h.rule, labels: { now: h.now, task: h.task, verify: h.verify } };
+}

package/src/test-blocked.mjs

@@ -80,5 +80,21 @@ const CLOSED = 'User-agent: GPTBot\nDisallow: /\n\nUser-agent: ClaudeBot\nDisall
   ok('в английском нет кириллицы', !/[А-Яа-яЁё]/.test(blockedNote({ status: 403, challenged: true, robotsText: OPEN, lang: 'en' }).text));
 }
 
+// ---- несуществующий адрес: человек чаще всего просто опечатался
+//
+// Стояло «Сайт ответил ничем на https://…»: и коряво, и бесполезно. Человек, который ошибся в
+// букве, должен узнать об этом первым делом, а не гадать, что с его сайтом.
+{
+  const { checkVisibility } = await import('./visibility.mjs');
+  for (const lang of ['ru', 'en']) {
+    const v = await checkVisibility('https://takogo-domena-tochno-net-4f7a2b9c.ru/', { budgetMs: 8500, samplePages: 3, lang });
+    ok(`${lang}: балла у несуществующего адреса нет`, v.ok === false);
+    ok(`${lang}: названа вероятная причина, опечатка`, lang === 'ru' ? /опечатка в адресе/.test(v.error) : /typo in the address/.test(v.error));
+    ok(`${lang}: сказано, что делать`, lang === 'ru' ? /проверьте написание/.test(v.error) : /check the spelling/.test(v.error));
+    ok(`${lang}: нет старого «ответил ничем»`, lang === 'ru' ? !/ответил ничем/.test(v.error) : !/answered nothing/.test(v.error));
+    ok(`${lang}: чужого языка нет`, lang === 'ru' ? !/[A-Za-z]{5}/.test(v.error.replace(/https?:\/\/[^\s]+/g, '')) : !/[А-Яа-яЁё]/.test(v.error));
+  }
+}
+
 if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
 console.log('\nпро чужой сайт говорим только измеренное');

package/src/test-prompts.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 /** Задания для ИИ-агента: полнота, язык, запрет на выдумки. */
-import { agentPrompt, agentPrompts, renderAgentPrompts } from './prompts.mjs';
+import { readFileSync } from 'node:fs';
+import { agentPrompt, agentPrompts, renderAgentPrompts, firstFixParts, FIRST_FIX_IDS } from './prompts.mjs';
 import { FIX_ACTIONS } from './fix.mjs';
 
 let bad = 0;
@@ -79,5 +80,33 @@ ok('и предупреждает делать по одной', /по одно
 ok('и обещает, что код знать не нужно', /кода знать не нужно/i.test(head));
 ok('в файле нет пустых сдвоенных строк', !/\n\n\n/.test(head));
 
+// ---- первая правка на бесплатной странице тремя частями.
+// Список id берётся из исходника бесплатной проверки, а не из головы: новая находка без
+// сопоставления уронит этот тест, а не оставит покупателя без задачи молча.
+{
+  const src = readFileSync(new URL('./visibility.mjs', import.meta.url), 'utf8');
+  const ids = [...new Set([...src.matchAll(/id: '([a-z0-9-]+)', level: (?!'na')/g)].map((m) => m[1]))];
+  ok(`находок бесплатной проверки в исходнике больше десяти (${ids.length})`, ids.length > 10);
+  const missing = [];
+  for (const id of ids) for (const lang of ['ru', 'en']) {
+    const p = firstFixParts({ id, area: 'x', text: 'что-то измерено' }, { lang });
+    if (!p || !p.now || p.task.length < 30 || p.verify.length < 20 || /null|undefined/.test(JSON.stringify(p))) missing.push(`${id}/${lang}`);
+    else if (lang === 'en' && /[А-Яа-яЁё]/.test(p.task + p.verify + p.rule + Object.values(p.labels).join(''))) missing.push(`${id}/en: кириллица`);
+  }
+  is('у каждой находки бесплатной проверки есть три части на обоих языках', missing, []);
+  is('и в списке экспорта нет лишних id, которых проверка не выдаёт', FIRST_FIX_IDS.filter((id) => !ids.includes(id)), []);
+  is('неизвестная находка даёт null, а не чужое указание', firstFixParts({ id: 'что-то-новое', text: 'x' }, { lang: 'ru' }), null);
+  is('находка без текста даёт null', firstFixParts({ id: 'llms-missing', text: '' }, { lang: 'ru' }), null);
+  is('пустой вход даёт null', firstFixParts(null), null);
+  const p = firstFixParts({ id: 'robots-fetchers-blocked', area: 'Пускает ли роботов ИИ', text: 'Закрыты поисковые роботы ответных систем: OAI-SearchBot.' }, { lang: 'ru' });
+  is('«сейчас» это сам текст находки', p.now, 'Закрыты поисковые роботы ответных систем: OAI-SearchBot.');
+  ok('задача про открытие поисковых роботов', /Открой в robots\.txt/.test(p.task));
+  ok('подписи на русском', p.labels.now === 'Сейчас' && p.labels.task === 'Задача' && p.labels.verify === 'Как проверить');
+  ok('правило про выдумки на месте', /не выдумывай факты/.test(p.rule));
+  const e = firstFixParts({ id: 'llms-missing', text: 'No llms.txt.' }, { lang: 'en' });
+  ok('английские подписи', e.labels.now === 'Now' && e.labels.verify === 'How to check');
+  ok('незнакомый язык падает в английский', firstFixParts({ id: 'llms-missing', text: 'x' }, { lang: 'de' }).labels.now === 'Now');
+}
+
 if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
 console.log('\nвсе тесты заданий прошли');

package/src/visibility.mjs

@@ -48,7 +48,9 @@ export const MESSAGES = {
   en: {
     badInput: 'Enter a public site address, for example example.com',
     tooSlow: 'The site took too long to answer',
-    badAnswer: (status, url) => `The site answered ${status || 'nothing'} for ${url}`,
+    badAnswer: (status, url) => `The site answered ${status} for ${url}`,
+    // Чаще всего это опечатка в адресе, и сказать об этом надо первым делом, а не после разбора.
+    unreachable: (url) => `Nothing answered at ${url}. Most often that is a typo in the address: check the spelling, and if the site really is there, it may be down right now.`,
     botWall: (status) => `The site refuses unknown clients (HTTP ${status}), so this check could not read a single page.`,
     botChallenge: (status) => `The site sits behind a browser challenge (Cloudflare, HTTP ${status}), so this check could not read a single page.`,
     // Что мы знаем про роботов ИИ, когда нас самих развернули: ровно то, что написано в правилах
@@ -98,7 +100,8 @@ export const MESSAGES = {
   ru: {
     badInput: 'Введите адрес публичного сайта, например example.ru',
     tooSlow: 'Сайт слишком долго не отвечал',
-    badAnswer: (status, url) => `Сайт ответил ${status ? `кодом ${status}` : 'ничем'} на ${url}`,
+    badAnswer: (status, url) => `Сайт ответил кодом ${status} на ${url}`,
+    unreachable: (url) => `По адресу ${url} никто не ответил. Чаще всего это опечатка в адресе: проверьте написание. Если сайт там действительно есть, значит он сейчас недоступен.`,
     botWall: (status) => `Сайт отказывает незнакомым клиентам (код ${status}), поэтому прочитать хотя бы одну страницу проверка не смогла.`,
     botChallenge: (status) => `Сайт закрыт проверкой браузера (Cloudflare, код ${status}), поэтому прочитать хотя бы одну страницу проверка не смогла.`,
     rulesAllowBots: (list) => ` Правила самого сайта роботов ИИ при этом пускают (${list}), а защита такого типа проверенных роботов нередко пропускает. Пустят ли их на деле, решает защита, а не эта проверка, поэтому в плюс или в минус сайту это не зачтено.`,
@@ -403,8 +406,9 @@ export async function checkVisibility(input, { budgetMs = 8500, lang = 'en', sam
      */
     const note = blockedNote({ status: home.status, challenged, blocked, robotsText: robotsRes.ok ? robotsRes.text : null, lang });
     const error = home.error === 'timeout' ? T.tooSlow
-      : blocked ? note.text
-        : T.badAnswer(home.status, url);
+      : home.error === 'unreachable' || !home.status ? T.unreachable(url)
+        : blocked ? note.text
+          : T.badAnswer(home.status, url);
     // `botsBlocked` говорит только про написанные правила, а не про поведение защиты: по нему
     // нельзя утверждать, что робота не пустили, можно лишь, что ему не разрешали.
     return { ok: false, blocked, challenged, status: home.status, error, botsBlocked: note.botsBlocked };