@operstack/audit 0.15.4 → 0.15.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operstack/audit",
-  "version": "0.15.4",
+  "version": "0.15.5",
   "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",
@@ -28,7 +28,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 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",
+    "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-rendered.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",
     "sample": "node bin/audit.mjs render examples/sample-audit.json --pdf"
   },
   "keywords": [

package/src/collect.mjs

@@ -19,7 +19,11 @@ const VERSION = (() => {
 
 const UA = `Mozilla/5.0 (compatible; OperStackAudit/${VERSION}; +https://oper-stack.com)`;
 
-async function get(url, { method = 'GET', timeout = 15000 } = {}) {
+/** Таймаут запроса раньше был зашит числом и наружу не выводился, поэтому поднять его со стороны
+ *  очереди писем было нельзя. Теперь это значение по умолчанию, которое collect() выставляет из опций. */
+let REQUEST_TIMEOUT = 15000;
+
+async function get(url, { method = 'GET', timeout = REQUEST_TIMEOUT } = {}) {
   const c = new AbortController(); const t = setTimeout(() => c.abort(), timeout);
   const started = Date.now();
   try {
@@ -161,21 +165,49 @@ function analysePage(url, html) {
   return { url, title, citedParagraphs, figureParagraphs, titleLength: title.length, description, descriptionLength: description.length, descriptionGarbage: shortcode, h1Count: h1s.length, h1: h1s[0] || '', images: imgs.length, imagesNoAlt: imgsNoAlt, canonical, robots, viewport, og, twitter, generator, hreflang, scripts, stylesheets, schemaTypes: [...new Set(schemaTypes)], words, links, dates, firstPara: firstPara.slice(0, 220), firstParaWords, answerFirst, h2Count, tables, sourcePhrases , telLinks, mailLinks, messengerLinks, contactPages, forms: realForms.length, formFields, formDepth, ctaFirstScreen, trust };
 }
 
-async function readSitemap(url, seen = new Set(), depth = 0) {
-  if (seen.has(url) || depth > 3) return [];
-  seen.add(url);
-  const r = await get(url);
-  if (!r.ok) return [];
-  const locs = [...r.text.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)].map((m) => m[1]);
-  const out = [];
-  for (const l of locs) {
-    if (/\.xml(\.gz)?$/i.test(l) || /sitemap/i.test(l) && !/\.(html?|php)$/i.test(l) && r.text.includes('<sitemapindex')) out.push(...(await readSitemap(l, seen, depth + 1)));
-    else out.push(l);
+/** Карты сайта на живых коммерческих сайтах бывают вложенными десятками: у одного московского
+ *  агентства недвижимости в sitemap.xml лежит 79 вложенных карт. Раньше мы заходили в каждую без
+ *  ограничений, по 15 секунд на запрос, и бесплатная проверка упиралась в таймаут ещё до того, как
+ *  прочитает хоть одну страницу: отчёт приходил пустым или не приходил вовсе.
+ *
+ *  Поэтому три ограничителя: сколько файлов читаем, сколько всего на это тратим и сколько адресов
+ *  набираем. Для выборки в двадцать страниц первых файлов хватает с запасом.
+ *
+ *  Если остановились раньше, это возвращается наружу и попадает в отчёт словами. Выдать часть за
+ *  целое нельзя: «1 200 адресов в карте сайта» на сайте с сорока тысячами адресов это неверное
+ *  измерение, а не округление. */
+async function readSitemap(startUrl, { maxFiles = 6, budgetMs = 45000, maxUrls = 5000, timeout } = {}) {
+  const deadline = Date.now() + budgetMs;
+  const seen = new Set();
+  const queue = [{ url: startUrl, depth: 0 }];
+  const urls = [];
+  let filesRead = 0; let nestedFound = 0; let stopped = '';
+  while (queue.length) {
+    if (filesRead >= maxFiles) { stopped = 'files'; break; }
+    if (Date.now() > deadline) { stopped = 'time'; break; }
+    if (urls.length >= maxUrls) { stopped = 'urls'; break; }
+    const { url, depth } = queue.shift();
+    if (seen.has(url) || depth > 3) continue;
+    seen.add(url);
+    const r = await get(url, timeout ? { timeout } : {});
+    filesRead++;
+    if (!r.ok) continue;
+    // Спускаться вглубь можно только из индекса карт. Прежнее условие из-за приоритета операторов
+    // читало `A || (B && C && D)` и уходило в рекурсию по любой ссылке на .xml, даже из обычного urlset.
+    const isIndex = /<sitemapindex/i.test(r.text);
+    for (const m of r.text.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)) {
+      const l = m[1];
+      if (isIndex && (/\.xml(\.gz)?$/i.test(l) || (/sitemap/i.test(l) && !/\.(html?|php)$/i.test(l)))) { nestedFound += 1; queue.push({ url: l, depth: depth + 1 }); }
+      else urls.push(l);
+    }
   }
-  return out;
+  return { urls, filesRead, nestedFound, pending: queue.length, stopped };
 }
 
-export async function collect(startUrl, { pages = 20, log = () => {}, backlinks = null, lang = 'en', rendered = false, renderedPages = 3, preparedBy = '' } = {}) {
+export const __readSitemap = readSitemap;
+
+export async function collect(startUrl, { pages = 20, log = () => {}, backlinks = null, lang = 'en', rendered = false, renderedPages = 3, preparedBy = '', requestTimeout = 15000, sitemapBudgetMs = 45000, sitemapMaxFiles = 6 } = {}) {
+  REQUEST_TIMEOUT = requestTimeout;
   const opts = { backlinks };
   const origin = new URL(startUrl).origin;
   const host = new URL(startUrl).host;
@@ -226,12 +258,22 @@ export async function collect(startUrl, { pages = 20, log = () => {}, backlinks
   log('sitemaps');
   const candidates = sitemapUrls.length ? sitemapUrls : [`${origin}/sitemap.xml`, `${origin}/sitemap_index.xml`, `${origin}/sitemap-index.xml`];
   let sitemapPages = []; let sitemapStatus = 'missing'; let sitemapSource = '';
+  let sitemapRead = { filesRead: 0, nestedFound: 0, pending: 0, stopped: '' };
   for (const u of candidates) {
     const r = await get(u);
-    if (r.ok && /<(urlset|sitemapindex)/.test(r.text)) { sitemapPages = await readSitemap(u); sitemapStatus = 'ok'; sitemapSource = u; break; }
+    if (r.ok && /<(urlset|sitemapindex)/.test(r.text)) {
+      sitemapRead = await readSitemap(u, { budgetMs: sitemapBudgetMs, maxFiles: sitemapMaxFiles });
+      sitemapPages = sitemapRead.urls; sitemapStatus = 'ok'; sitemapSource = u; break;
+    }
     if (sitemapUrls.includes(u)) { sitemapStatus = `HTTP ${r.status}`; sitemapSource = u; }
   }
-  checks.push(row('sitemap', 'technical', 'XML sitemap', sitemapStatus === 'ok' ? 'ok' : 'bad', sitemapStatus === 'ok' ? `${sitemapPages.length} URL(s) in ${sitemapSource}` : sitemapSource ? `${sitemapSource} answers ${sitemapStatus}` : 'no sitemap found at the usual paths', sitemapStatus !== 'ok' && sitemapUrls.length ? 'robots.txt points at a sitemap that does not answer' : ''));
+  // Когда обход остановлен ограничителем, в отчёте стоит число прочитанного, а не выдуманное целое.
+  const sitemapValue = sitemapStatus !== 'ok'
+    ? (sitemapSource ? `${sitemapSource} answers ${sitemapStatus}` : 'no sitemap found at the usual paths')
+    : sitemapRead.stopped
+      ? `${sitemapPages.length} URL(s) read from ${sitemapRead.filesRead} of ${sitemapRead.filesRead + sitemapRead.pending} sitemap file(s) in ${sitemapSource}`
+      : `${sitemapPages.length} URL(s) in ${sitemapSource}`;
+  checks.push(row('sitemap', 'technical', 'XML sitemap', sitemapStatus === 'ok' ? 'ok' : 'bad', sitemapValue, sitemapStatus !== 'ok' && sitemapUrls.length ? 'robots.txt points at a sitemap that does not answer' : sitemapRead.stopped ? 'a large nested sitemap: the pages below were sampled from the files that were read, not from every file' : ''));
   const foreign = sitemapPages.filter((u) => { try { return new URL(u).host !== host && new URL(u).host !== altHost; } catch { return true; } });
   if (foreign.length) checks.push(row('sitemap-foreign', 'technical', 'Sitemap lists other hosts', 'bad', `${foreign.length} URL(s) on other hosts, e.g. ${foreign[0]}`));
 

package/src/i18n.mjs

@@ -69,7 +69,15 @@ const RU = {
   },
   sitemap: {
     label: 'Карта сайта XML',
-    value: (v) => (/URL\(s\) in/.test(v) ? `${plural(Number(nums(v)[0]), 'адрес', 'адреса', 'адресов')} в карте сайта` : /not found|missing/i.test(v) ? 'не найдена' : `не отдаётся, код ${nums(v)[0]}`),
+    // Обход больших вложенных карт останавливается ограничителем, и по-русски это надо сказать
+    // словами, иначе прочитанная часть выглядит как полное измерение.
+    value: (v) => {
+      const n = nums(v);
+      if (/read from/.test(v)) return `${plural(Number(n[0]), 'адрес', 'адреса', 'адресов')} прочитано из ${n[1]} файлов карты, всего файлов ${n[2]}`;
+      if (/URL\(s\) in/.test(v)) return `${plural(Number(n[0]), 'адрес', 'адреса', 'адресов')} в карте сайта`;
+      if (/not found|missing/i.test(v)) return 'не найдена';
+      return `не отдаётся, код ${n[0]}`;
+    },
   },
   'sitemap-foreign': { label: 'В карте сайта чужие хосты', value: (v) => `${plural(Number(nums(v)[0]), 'адрес', 'адреса', 'адресов')} на других хостах` },
   'sitemap-health': { label: 'Адреса из карты сайта отвечают 200', value: (v) => { const n = nums(v); return `${n[0]} из ${n[1]} проверенных адресов отвечают 200${/redirect/.test(v) ? `, ${n[2]} перенаправляют` : ''}${/broken/.test(v) ? ', есть битые' : ''}`; } },

package/src/test-sitemap.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/** Обход карт сайта: ограничители и честность отчёта.
+ *
+ *  14.09.2026 бесплатная проверка не собрала отчёт по whitewill.ru. В его sitemap.xml 79 вложенных
+ *  карт, обход заходил в каждую по 15 секунд, и прогон умирал по таймауту, не дочитав до страниц.
+ *  Тесты поднимают такой же сайт локально, чтобы это не вернулось. */
+import { createServer } from 'node:http';
+import { __readSitemap } from './collect.mjs';
+import { localiseChecks } from './i18n.mjs';
+
+let bad = 0;
+const ok = (n, c) => { if (c) console.log(`ok   ${n}`); else { bad++; console.error(`FAIL ${n}`); } };
+const is = (n, a, b) => ok(`${n} (ждали ${JSON.stringify(b)}, вышло ${JSON.stringify(a)})`, JSON.stringify(a) === JSON.stringify(b));
+
+const index = (hrefs) => `<?xml version="1.0"?><sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${hrefs.map((h) => `<sitemap><loc>${h}</loc></sitemap>`).join('')}</sitemapindex>`;
+const urlset = (hrefs) => `<?xml version="1.0"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${hrefs.map((h) => `<url><loc>${h}</loc></url>`).join('')}</urlset>`;
+
+/** Сервер отвечает медленно, как настоящий сайт на другом континенте. */
+const start = (delayMs, nested) => new Promise((resolve) => {
+  const server = createServer(async (req, res) => {
+    if (delayMs) await new Promise((r) => setTimeout(r, delayMs));
+    const base = `http://127.0.0.1:${server.address().port}`;
+    res.setHeader('content-type', 'application/xml');
+    if (req.url === '/sitemap.xml') return res.end(index(Array.from({ length: nested }, (_, i) => `${base}/map-${i}.xml`)));
+    if (req.url === '/plain.xml') return res.end(urlset([`${base}/page`, `${base}/feed.xml`]));
+    const i = (req.url.match(/map-(\d+)/) || [])[1] ?? '0';
+    return res.end(urlset([`${base}/p-${i}-a`, `${base}/p-${i}-b`]));
+  });
+  server.listen(0, '127.0.0.1', () => resolve({ server, base: `http://127.0.0.1:${server.address().port}` }));
+});
+
+// 1. Семьдесят девять вложенных карт: читаем несколько файлов, а не все, и говорим об этом.
+{
+  const { server, base } = await start(30, 79);
+  const began = Date.now();
+  const r = await __readSitemap(`${base}/sitemap.xml`, { maxFiles: 6, budgetMs: 45000 });
+  const took = Date.now() - began;
+  is('прочитано ровно столько файлов, сколько разрешено', r.filesRead, 6);
+  is('остановились по числу файлов', r.stopped, 'files');
+  is('нашли все вложенные карты', r.nestedFound, 79);
+  ok('непрочитанные файлы посчитаны', r.pending === 74);
+  ok('адресов хватает на выборку страниц', r.urls.length >= 10);
+  ok(`уложились в разумное время (${took} мс)`, took < 5000);
+  server.close();
+}
+
+// 2. Маленький сайт читается целиком, и тогда про ограничители в отчёте ни слова.
+{
+  const { server, base } = await start(0, 2);
+  const r = await __readSitemap(`${base}/sitemap.xml`);
+  is('маленькая карта прочитана целиком', r.stopped, '');
+  is('файлов прочитано: индекс и две карты', r.filesRead, 3);
+  is('собраны все адреса', r.urls.length, 4);
+  server.close();
+}
+
+// 3. Из обычного urlset вглубь не спускаемся, даже если адрес заканчивается на .xml.
+//    Прежнее условие из-за приоритета операторов читало `A || (B && C && D)` и уходило в рекурсию.
+{
+  const { server, base } = await start(0, 2);
+  const r = await __readSitemap(`${base}/plain.xml`);
+  is('из urlset рекурсии нет', r.filesRead, 1);
+  is('ссылка на .xml осталась адресом страницы', r.urls.length, 2);
+  server.close();
+}
+
+// 4. Общий бюджет времени соблюдается, даже если файлов мало, а сайт медленный.
+{
+  const { server, base } = await start(200, 40);
+  const began = Date.now();
+  const r = await __readSitemap(`${base}/sitemap.xml`, { maxFiles: 100, budgetMs: 700 });
+  const took = Date.now() - began;
+  is('остановились по времени', r.stopped, 'time');
+  ok(`бюджет времени соблюдён (${took} мс)`, took < 2500);
+  server.close();
+}
+
+// 5. По-русски усечённый обход называется словами, а не «не отдаётся, код 1200».
+//    Локализатор подбирает строку регулярным выражением, поэтому новая формулировка без своей
+//    ветки молча проваливается в числовую. Ровно это уже случалось с нулями в отчёте.
+{
+  const en = [{ id: 'sitemap', group: 'technical', label: 'XML sitemap', status: 'ok', value: '1200 URL(s) read from 6 of 79 sitemap file(s) in https://example.ru/sitemap.xml', comment: '' }];
+  const ru = localiseChecks(en, 'ru')[0].value;
+  ok(`усечение названо словами: "${ru}"`, /прочитано из 6 файлов карты, всего файлов 79/.test(ru));
+  ok('и это не выдано за код ответа', !/не отдаётся/.test(ru));
+  const whole = localiseChecks([{ ...en[0], value: '1200 URL(s) in https://example.ru/sitemap.xml' }], 'ru')[0].value;
+  ok(`целая карта по-прежнему читается нормально: "${whole}"`, /в карте сайта/.test(whole));
+}
+
+if (bad) { console.error(`\n${bad} тест(ов) упало`); process.exit(1); }
+console.log('\nвсе тесты обхода карт прошли');