@operstack/audit 0.19.0 → 0.19.2

package/package.json

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

@@ -27,9 +27,11 @@ const is = (n, a, b) => ok(`${n} (ждали ${JSON.stringify(b)}, вышло ${
 const PAGE = `<!doctype html><html lang="ru"><head><title>Пример</title><meta name="description" content="Описание"></head>
 <body><main><h1>Пример сайта</h1>${'<p>Обычный абзац текста про товар и цену, без цифр, чтобы было что цитировать. </p>'.repeat(40)}</main></body></html>`;
 
-const serve = ({ robots }) => new Promise((resolve) => {
+const serve = ({ robots, status = null, llmsStatus = 404 }) => new Promise((resolve) => {
   const s = createServer((req, res) => {
+    if (req.url.startsWith('/llms.txt')) { res.writeHead(llmsStatus, { 'content-type': 'text/html' }); res.end('<html>нет</html>'); return; }
     if (req.url.startsWith('/robots.txt')) {
+      if (status) { res.writeHead(status, { 'content-type': 'text/html' }); res.end('<html>нет</html>'); return; }
       if (robots === null) { res.writeHead(403, { 'content-type': 'text/html' }); res.end('<html>denied</html>'); return; }
       res.writeHead(200, { 'content-type': 'text/plain' }); res.end(robots); return;
     }
@@ -99,5 +101,71 @@ if (!dnsOk) {
   ok('подпись в отчёте прежняя', /дают в сумме ровно/.test((toHtml({ ...fixture, meta: { ...fixture.meta, lang: 'ru' }, overall: { ...fixture.overall, score: v2.score, areas: v2.areas } }, null).match(/overall-note">([^<]*)</) || [])[1] || ''));
 }
 
+  // ---- файла нет это ОТВЕТ, а не незнание
+  //
+  // Первая версия правки считала неизмеренным любой неуспех, и сайт без robots.txt терял 25
+  // заслуженных баллов: по стандарту отсутствие файла означает, что не запрещено ничего.
+  // Поймано на живом example.com сразу после выкладки: балл упал с 30 до 7.
+  for (const code of [404, 410]) {
+    const { s: s3, url: url3 } = await serve({ status: code });
+    let v3;
+    try { v3 = await checkVisibility(url3, { budgetMs: 8500, samplePages: 3, lang: 'ru' }); } finally { s3.close(); }
+    const a3 = v3.areas.find((a) => a.id === 'access');
+    is(`robots.txt ${code}: область измерена`, a3.measured, true);
+    is(`robots.txt ${code}: и оценена полностью`, a3.score, 25);
+    ok(`robots.txt ${code}: сказано, что файла нет`, /Файла robots\.txt на сайте нет/.test(a3.findings[0].text));
+    ok(`robots.txt ${code}: и что это значит «не запрещено ничего»`, /не запрещено ничего/.test(a3.findings[0].text));
+    ok(`robots.txt ${code}: не назвали это непрочитанным`, !a3.findings.some((f) => f.id === 'robots-unreadable'));
+    is(`robots.txt ${code}: балл это прямая сумма`, v3.score, v3.areas.reduce((t, a) => t + a.score, 0));
+  }
+
+  // ---- а отказ и сбой это по-прежнему незнание
+  for (const code of [401, 403, 429, 500]) {
+    const { s: s4, url: url4 } = await serve({ status: code });
+    let v4;
+    try { v4 = await checkVisibility(url4, { budgetMs: 8500, samplePages: 3, lang: 'ru' }); } finally { s4.close(); }
+    const a4 = v4.areas.find((a) => a.id === 'access');
+    is(`robots.txt ${code}: область не измерена`, a4.measured, false);
+    ok(`robots.txt ${code}: код назван в тексте`, new RegExp(`код ${code}`).test(a4.findings[0].text));
+  }
+
+  // ---- llms.txt: та же граница между «нет файла» и «не дали файл»
+  //
+  // Сайт за защитой отдавал 403 на llms.txt, и мы писали владельцу «у вас нет карты для агентов»
+  // с нулём баллов. Файл мог быть, мы его просто не получили.
+  {
+    const cases = [[404, 'missing'], [410, 'missing'], [403, 'unknown'], [429, 'unknown'], [500, 'unknown']];
+    for (const [code, kind] of cases) {
+      const { s: s5, url: url5 } = await serve({ robots: 'User-agent: *\nDisallow: /admin/\n', llmsStatus: code });
+      let v5;
+      try { v5 = await checkVisibility(url5, { budgetMs: 8500, samplePages: 3, lang: 'ru' }); } finally { s5.close(); }
+      const a5 = v5.areas.find((a) => a.id === 'index');
+      if (kind === 'missing') {
+        is(`llms.txt ${code}: область измерена`, a5.measured, true);
+        is(`llms.txt ${code}: и это честный ноль`, a5.score, 0);
+        ok(`llms.txt ${code}: находка называет отсутствие`, a5.findings.some((f) => f.id === 'llms-missing'));
+      } else {
+        is(`llms.txt ${code}: область не измерена`, a5.measured, false);
+        is(`llms.txt ${code}: балла нет, а не ноль`, a5.score, null);
+        ok(`llms.txt ${code}: не пишем «у вас нет файла»`, !a5.findings.some((f) => f.id === 'llms-missing'));
+        ok(`llms.txt ${code}: сказано, что не отдали`, /не дал этой проверке прочитать llms\.txt/.test(a5.findings[0].text));
+        is(`llms.txt ${code}: знаменатель без этой области`, v5.score, Math.round((v5.areas.filter((a) => a.measured !== false).reduce((t, a) => t + a.score, 0) / v5.areas.filter((a) => a.measured !== false).reduce((t, a) => t + a.max, 0)) * 100));
+      }
+    }
+  }
+
+  // ---- две неизмеренные области сразу: знаменатель считается по оставшимся трём
+  {
+    const { s: s6, url: url6 } = await serve({ robots: null, llmsStatus: 403 });
+    let v6;
+    try { v6 = await checkVisibility(url6, { budgetMs: 8500, samplePages: 3, lang: 'ru' }); } finally { s6.close(); }
+    const un = v6.areas.filter((a) => a.measured === false);
+    is('неизмеренных областей две', un.length, 2);
+    const meas = v6.areas.filter((a) => a.measured !== false);
+    is('знаменатель 60', meas.reduce((t, a) => t + a.max, 0), 60);
+    is('балл по оставшимся', v6.score, Math.round((meas.reduce((t, a) => t + a.score, 0) / 60) * 100));
+    ok('ни одна из них не получила ноль', un.every((a) => a.score === null));
+  }
+
 if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
-console.log('\nнепрочитанное не считается ни в плюс, ни в минус');
+console.log('\nнепрочитанное не считается ни в плюс, ни в минус, а отсутствующее это ответ');

package/src/visibility.mjs

@@ -58,6 +58,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' },
+    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.',
     robotsUnreadable: (status) => `The site did not let this check read robots.txt${status ? ` (HTTP ${status})` : ''}, so whether AI crawlers are allowed could not be measured. It is not counted for or against the site: an unread file is not good news. The owner can open it in a browser, or ask whoever runs the site's protection.`,
     robotsAllBlocked: 'robots.txt disallows the whole site for every crawler. Nothing can read it.',
     fetchersBlocked: (list) => `Blocked answer-engine fetchers: ${list}. These are the bots that cite pages live.`,
@@ -104,6 +106,8 @@ export const MESSAGES = {
     rulesUnknown: ' Файл robots.txt прочитать тоже не вышло, поэтому про роботов ИИ сказать нечего, и в плюс или в минус сайту это не зачтено.',
     howToCheckBots: ' Чтобы знать точно, посмотрите в журнале сервера, приходят ли GPTBot, ClaudeBot и PerplexityBot, либо спросите у тех, кто настраивал защиту, кто у неё в белом списке.',
     area: { access: 'Могут ли роботы ИИ прочитать сайт', index: 'Есть ли карта для агентов (llms.txt)', entity: 'Понятно ли, кто вы (разметка)', content: 'Есть ли что процитировать', trust: 'Можно ли датировать и доверять' },
+    llmsUnreadable: (status) => `Сайт не дал этой проверке прочитать llms.txt${status ? ` (код ${status})` : ''}, поэтому есть ли у сайта карта для агентов, измерить не вышло. В плюс или в минус это не зачтено: файл, который нам не отдали, это не то же самое, что файла нет.`,
+    robotsMissing: 'Файла robots.txt на сайте нет. По стандарту это значит, что не запрещено ничего, то есть читать сайт может любой робот ИИ. Заводить файл необязательно: он нужен, только когда есть что закрывать.',
     robotsUnreadable: (status) => `Сайт не дал этой проверке прочитать robots.txt${status ? ` (код ${status})` : ''}, поэтому допущены роботы ИИ или нет, измерить не вышло. В плюс или в минус сайту это не зачтено: непрочитанный файл это не хорошая новость. Владелец может открыть его в браузере сам или спросить у тех, кто настраивал защиту сайта.`,
     robotsAllBlocked: 'robots.txt закрывает весь сайт для всех роботов. Его никто не может прочитать.',
     fetchersBlocked: (list) => `Закрыты поисковые роботы ответных систем: ${list}. Именно они достают страницу, чтобы процитировать её в ответе.`,
@@ -439,12 +443,25 @@ export async function checkVisibility(input, { budgetMs = 8500, lang = 'en', sam
    * Незнание это не хорошая новость. Область помечается неизмеренной, из знаменателя выпадает,
    * и балл считается по тому, что действительно прочитано.
    */
-  const robotsRead = robotsRes.ok;
+  /*
+   * «Файла нет» и «нам его не дали» это разные вещи, и путать их нельзя ни в одну сторону.
+   *
+   * 404 и 410 это определённый ответ: файла на сайте нет, а по стандарту отсутствие robots.txt
+   * означает, что не запрещено ничего. Это измерение, и область получает свои баллы честно.
+   * Первая версия правки 15.09.2026 считала неизмеренным любой неуспех, и сайт без robots.txt
+   * (таких много среди небольших) терял 25 заслуженных баллов: example.com упал с 30 до 7.
+   *
+   * Неизмеренное это только отказ и сбой: 401, 403, 405, 429, пятисотые, таймаут, недоступность.
+   * Тогда мы действительно не знаем, что в файле написано.
+   */
+  const robotsMissing = robotsRes.status === 404 || robotsRes.status === 410;
+  const robotsRead = robotsRes.ok || robotsMissing;
   let access = 25;
   if (starBlocked) access = 0; else { access -= Math.min(15, blockedSearch.length * 4); access -= Math.min(8, blockedTrain.length * 2); if (noai) access -= 5; }
   access = Math.max(0, access);
   const accessFindings = [];
   if (!robotsRead) accessFindings.push({ id: 'robots-unreadable', level: 'na', text: T.robotsUnreadable(robotsRes.status || 0) });
+  else if (robotsMissing && !accessFindings.length) accessFindings.push({ level: 'pass', text: T.robotsMissing });
   if (starBlocked) accessFindings.push({ id: 'robots-all-blocked', level: 'fail', text: T.robotsAllBlocked });
   if (blockedSearch.length) accessFindings.push({ id: 'robots-fetchers-blocked', level: 'fail', text: T.fetchersBlocked(blockedSearch.map(agentLabel).join(', ')) });
   if (blockedTrain.length) accessFindings.push({ id: 'robots-training-blocked', level: 'warn', text: T.trainingBlocked(blockedTrain.map(agentLabel).join(', ')) });
@@ -452,8 +469,18 @@ export async function checkVisibility(input, { budgetMs = 8500, lang = 'en', sam
   if (!accessFindings.length) accessFindings.push({ level: 'pass', text: T.allAllowed(AI_AGENTS.length, robots.signal) });
 
   // Area 2: agent index (15)
+  /*
+   * Та же граница, что у robots.txt: «файла нет» и «нам его не дали» это разные вещи.
+   *
+   * До 15.09.2026 любой неуспех давал вывод «у вас нет llms.txt» и ноль баллов. На сайте за
+   * защитой это выдуманная находка: файл может быть, мы его просто не получили. 404 и 410
+   * означают, что файла действительно нет, и вот это честная находка с нулём.
+   */
+  const llmsMissing = llmsRes.status === 404 || llmsRes.status === 410;
+  const llmsRead = llmsRes.ok || llmsMissing;
   let index = 0; const indexFindings = [];
-  if (!llmsRes.ok) indexFindings.push({ id: 'llms-missing', level: 'fail', text: T.llmsMissing });
+  if (!llmsRead) indexFindings.push({ id: 'llms-unreadable', level: 'na', text: T.llmsUnreadable(llmsRes.status || 0) });
+  else if (!llmsRes.ok) indexFindings.push({ id: 'llms-missing', level: 'fail', text: T.llmsMissing });
   else if (!llmsIsText) { index = 3; indexFindings.push({ id: 'llms-not-text', level: 'fail', text: T.llmsNotText }); }
   else if (llmsLinks.length && llmsForeign.length > llmsLinks.length / 2) { index = 5; indexFindings.push({ id: 'llms-foreign', level: 'fail', text: T.llmsForeign([...new Set(llmsForeign.map((l) => new URL(l).host))].slice(0, 3).join(', ')) }); }
   else { index = llmsLinks.length >= 5 ? 15 : 10; indexFindings.push({ level: 'pass', text: T.llmsOk(llmsLinks.length) }); }
@@ -542,7 +569,7 @@ export async function checkVisibility(input, { budgetMs = 8500, lang = 'en', sam
 
   const areas = [
     { id: 'access', label: T.area.access, score: robotsRead ? access : null, max: 25, measured: robotsRead, findings: accessFindings },
-    { id: 'index', label: T.area.index, score: index, max: 15, findings: indexFindings },
+    { id: 'index', label: T.area.index, score: llmsRead ? index : null, max: 15, measured: llmsRead, findings: indexFindings },
     { id: 'entity', label: T.area.entity, score: entity, max: 20, findings: entityFindings },
     { id: 'content', label: T.area.content, score: content, max: 25, findings: contentFindings },
     { id: 'trust', label: T.area.trust, score: trust, max: 15, findings: trustFindings },