ai-search-auditor 0.1.2 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.1.5](https://github.com/a-bibikov/ai-search-audit/compare/v0.1.4...v0.1.5) (2026-11-03)
+
+
+### Fixes
+
+* checks that cannot run are marked not checked, not passed ([e01eec5](https://github.com/a-bibikov/ai-search-audit/commit/e01eec5674c5f313ffa7b957af6c3520b86e840c))
+* checks that cannot run are marked not checked, not passed ([9281b96](https://github.com/a-bibikov/ai-search-audit/commit/9281b96ad2c6dee10d4a756b11e825fe858fc563))
+
+## [0.1.4](https://github.com/a-bibikov/ai-search-audit/compare/v0.1.3...v0.1.4) (2026-11-03)
+
+
+### Internal
+
+* release 0.1.4 ([2c8056d](https://github.com/a-bibikov/ai-search-audit/commit/2c8056d386588262362e66c5fce78726df9127d8))
+
+## [0.1.3](https://github.com/a-bibikov/ai-search-audit/compare/v0.1.2...v0.1.3) (2026-11-03)
+
+
+### Fixes
+
+* CLI help names the npm package, --version flag ([31887fa](https://github.com/a-bibikov/ai-search-audit/commit/31887fada369eb41024f119b79359e5a98c03126))
+
 ## [0.1.2](https://github.com/a-bibikov/ai-search-audit/compare/v0.1.1...v0.1.2) (2026-11-03)
 
 

package/README.md

@@ -68,7 +68,7 @@ Gaps in the numbering are taken by the checks on the [roadmap](#roadmap).
 
 Levels: `error` — AI search cannot read the page or reads it wrong; `warn` — lowers the chance of a citation; `info` — a recommendation.
 
-The report lists the findings with fixes first, then ends with a checklist of every check by group: ✓ OK, ✖ error, ⚠ warning, ℹ note.
+The report lists the findings with fixes first, then ends with a checklist of every check by group: ✓ OK, ✖ error, ⚠ warning, ℹ note, – not checked. A check that cannot run on a site — articles on a site without articles, `llms.txt` links when there is no `llms.txt` — is marked «not checked» with the reason, never as passed.
 
 **Score:** 100 minus 15 per rule with an error and 5 per rule with a warning. A rule counts once, not per page, so one template bug does not sink a large site. A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F below.
 

package/dist/cli.js

@@ -2,11 +2,16 @@
 import { existsSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { DEFAULT_LANG, LANGS, audit, isLang, rules, toMarkdown } from "./index.js";
-const HELP = `ai-search-audit — can ChatGPT, Claude and Perplexity read, understand and cite your site?
+// package.json sits one level up both from src/cli.ts (development) and dist/cli.js (published package).
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const HELP = `ai-search-auditor ${version} — can ChatGPT, Claude and Perplexity read, understand and cite your site?
 
 Usage:
-  ai-search-audit <url> [options]
-  ai-search-audit llms-txt <url>        check only llms.txt and llms-full.txt
+  ai-search-auditor <url> [options]
+  ai-search-auditor llms-txt <url>      check only llms.txt and llms-full.txt
+
+  npm package: ai-search-auditor (npx ai-search-auditor, npm i -g ai-search-auditor).
+  After install the command also works as ai-search-audit.
 
 Options:
   --base <url>        public origin when auditing a local build (links in sitemap point there)
@@ -16,6 +21,7 @@ Options:
   --json              print the JSON report instead of Markdown
   --out <file>        also write the report to a file (.json or .md)
   --config <file>     config file (default: ai-search-audit.config.json if present)
+  -v, --version       print the version
   -h, --help
 
 Examples:
@@ -34,8 +40,13 @@ const { values, positionals } = parseArgs({
         out: { type: "string" },
         config: { type: "string" },
         help: { type: "boolean", short: "h", default: false },
+        version: { type: "boolean", short: "v", default: false },
     },
 });
+if (values.version) {
+    process.stdout.write(`${version}\n`);
+    process.exit(0);
+}
 const llmsOnly = positionals[0] === "llms-txt";
 const target = llmsOnly ? positionals[1] : positionals[0];
 if (values.help || !target) {

package/dist/crawl.d.ts

@@ -9,6 +9,9 @@ export interface CrawlOptions {
 /**
  * Picks pages so that every template is seen: URLs grouped by their path with the last segment masked
  * (/blog/a and /blog/b are one group), then taken round-robin, home page first.
+ * Sites that repeat one page under many prefixes (/moscow/prices, /kazan/prices…) would fill the sample with copies,
+ * so a page whose path after the first segment was already picked waits until every other page had its turn.
+ * Language prefixes (/ru/, /en-us/) are not treated as such copies: other languages are worth auditing.
  */
 export declare function pickPages(home: string, urls: string[], max: number): string[];
 export declare function crawl(targetInput: string, baseInput: string | undefined, opts: CrawlOptions): Promise<Site>;

package/dist/crawl.js

@@ -7,32 +7,52 @@ const origin = (url) => new URL(url).origin;
 /**
  * Picks pages so that every template is seen: URLs grouped by their path with the last segment masked
  * (/blog/a and /blog/b are one group), then taken round-robin, home page first.
+ * Sites that repeat one page under many prefixes (/moscow/prices, /kazan/prices…) would fill the sample with copies,
+ * so a page whose path after the first segment was already picked waits until every other page had its turn.
+ * Language prefixes (/ru/, /en-us/) are not treated as such copies: other languages are worth auditing.
  */
 export function pickPages(home, urls, max) {
     // https://site.com and https://site.com/ are the same page: compare without the trailing slash.
     const norm = (u) => u.replace(/\/$/, "");
+    const segments = (u) => new URL(u).pathname.split("/").filter(Boolean);
+    const tailOf = (u) => {
+        const segs = segments(u);
+        return segs.length >= 2 && !/^[a-z]{2}(-[a-z]{2,4})?$/i.test(segs[0]) ? segs.slice(1).join("/") : null;
+    };
     const seen = new Set([norm(home)]);
     const groups = new Map();
     for (const url of urls) {
         if (seen.has(norm(url)))
             continue;
         seen.add(norm(url));
-        const path = new URL(url).pathname.replace(/\/$/, "");
-        const segs = path.split("/").filter(Boolean);
+        const segs = segments(url);
         const key = segs.length <= 1 ? `/${segs.join("/")}` : `/${segs.slice(0, -1).join("/")}/*`;
         if (!groups.has(key))
             groups.set(key, []);
         groups.get(key).push(url);
     }
     const picked = [home];
+    const tails = new Set();
+    const later = [];
     const lists = [...groups.values()];
     for (let round = 0; picked.length < max && lists.some((l) => l.length > round); round++) {
         for (const list of lists) {
             const url = list[round];
-            if (url && !picked.includes(url) && picked.length < max)
-                picked.push(url);
+            if (!url || picked.length >= max)
+                continue;
+            const tail = tailOf(url);
+            if (tail && tails.has(tail)) {
+                later.push(url);
+                continue;
+            }
+            if (tail)
+                tails.add(tail);
+            picked.push(url);
         }
     }
+    for (const url of later)
+        if (picked.length < max)
+            picked.push(url);
     return picked;
 }
 const isHtml = (f) => f.status === 200 && /html/i.test(f.headers.get("content-type") ?? "html");
@@ -91,6 +111,6 @@ export async function crawl(targetInput, baseInput, opts) {
         const probes = await pool(["/rss.xml", "/feed.xml", "/feed", "/atom.xml", "/index.xml"], conc, (p) => fetchUrl(`${target}${p}`, o, { accept: "application/rss+xml,application/atom+xml,application/xml" }));
         undeclaredFeed = probes.find((f) => f.status === 200 && /<(rss|feed)\b/i.test(f.body.slice(0, 2000)))?.publicUrl ?? null;
     }
-    return { target, base, robots, sitemap, pages, llms: llms.status === 200 ? llms : null, llmsFull: llmsFull.status === 200 ? llmsFull : null, feeds, asAgents, llmsLinks, undeclaredFeed };
+    return { target, base, robots, sitemap, pages, llms: llms.status === 200 ? llms : null, llmsAttempt: llms, llmsFull: llmsFull.status === 200 ? llmsFull : null, feeds, asAgents, llmsLinks, undeclaredFeed };
 }
 const p0 = (pages, base) => pages[0]?.fetched.publicUrl ?? base;

package/dist/i18n/en.d.ts

@@ -20,6 +20,7 @@ export declare const en: {
         more: (n: number) => string;
         checklist: string;
         legend: string;
+        notChecked: string;
         /** Findings of one rule in the checklist: «2 errors, 1 warning». */
         count: (o: {
             errors: number;
@@ -149,6 +150,12 @@ export declare const en: {
         introFirst: (q: string) => string;
         noLongParagraph: string;
         notFound: (path: string) => string;
+        answers: (path: string, status: string) => string;
+        skipNoArticles: string;
+        skipNoLlms: string;
+        skipNoFeed: string;
+        skipOneLanguage: string;
+        skipNoSitemap: string;
         returnsHtml: string;
         noH1: string;
         noSummary: string;

package/dist/i18n/en.js

@@ -12,7 +12,8 @@ export const en = {
         recommendation: "Recommendation",
         more: (n) => `…and ${n} more`,
         checklist: "Checklist",
-        legend: "✓ OK · ✖ error · ⚠ warning · ℹ note",
+        legend: "✓ OK · ✖ error · ⚠ warning · ℹ note · – not checked",
+        notChecked: "not checked",
         /** Findings of one rule in the checklist: «2 errors, 1 warning». */
         count: (o) => [
             o.errors && `${o.errors} ${o.errors === 1 ? "error" : "errors"}`,
@@ -144,6 +145,12 @@ export const en = {
         introFirst: (q) => `starts with an intro instead of the answer: ${q}`,
         noLongParagraph: "no paragraph of 25+ words among the first two",
         notFound: (path) => `${path} not found`,
+        answers: (path, status) => `${path} answers ${status}, so AI agents cannot read it`,
+        skipNoArticles: "no articles among the audited pages",
+        skipNoLlms: "no llms.txt",
+        skipNoFeed: "the site has no feed",
+        skipOneLanguage: "the site has one language",
+        skipNoSitemap: "no sitemap.xml",
         returnsHtml: "returns HTML, not Markdown",
         noH1: "does not start with an H1 `# Name`",
         noSummary: "no `> summary` line",

package/dist/i18n/index.d.ts

@@ -19,6 +19,7 @@ export declare const LANGS: {
             more: (n: number) => string;
             checklist: string;
             legend: string;
+            notChecked: string;
             count: (o: {
                 errors: number;
                 warnings: number;
@@ -146,6 +147,12 @@ export declare const LANGS: {
             introFirst: (q: string) => string;
             noLongParagraph: string;
             notFound: (path: string) => string;
+            answers: (path: string, status: string) => string;
+            skipNoArticles: string;
+            skipNoLlms: string;
+            skipNoFeed: string;
+            skipOneLanguage: string;
+            skipNoSitemap: string;
             returnsHtml: string;
             noH1: string;
             noSummary: string;
@@ -177,6 +184,7 @@ export declare const LANGS: {
             more: (n: number) => string;
             checklist: string;
             legend: string;
+            notChecked: string;
             count: (o: {
                 errors: number;
                 warnings: number;
@@ -304,6 +312,12 @@ export declare const LANGS: {
             introFirst: (q: string) => string;
             noLongParagraph: string;
             notFound: (path: string) => string;
+            answers: (path: string, status: string) => string;
+            skipNoArticles: string;
+            skipNoLlms: string;
+            skipNoFeed: string;
+            skipOneLanguage: string;
+            skipNoSitemap: string;
             returnsHtml: string;
             noH1: string;
             noSummary: string;

package/dist/i18n/ru.js

@@ -8,7 +8,8 @@ export const ru = {
         recommendation: "Рекомендация",
         more: (n) => `…и ещё ${n}`,
         checklist: "Чек-лист",
-        legend: "✓ в порядке · ✖ ошибка · ⚠ предупреждение · ℹ заметка",
+        legend: "✓ в порядке · ✖ ошибка · ⚠ предупреждение · ℹ заметка · – не проверено",
+        notChecked: "не проверено",
         count: (o) => [o.errors && `ошибок: ${o.errors}`, o.warnings && `предупреждений: ${o.warnings}`, o.notes && `заметок: ${o.notes}`].filter(Boolean).join(", "),
         site: "сайт",
         footer: (pages, date) => `Проверено страниц: ${pages}, ${date}. После каждого деплоя проверьте вручную: боевой CDN и защиту от ботов с настоящими AI-агентами (A-3), Google Search Console, Bing Webmaster Tools (поиск ChatGPT опирается на Bing), Яндекс Вебмастер.`,
@@ -132,6 +133,12 @@ export const ru = {
         introFirst: (q) => `начинается со вступления, а не с ответа: ${q}`,
         noLongParagraph: "среди первых двух абзацев нет абзаца от 25 слов",
         notFound: (path) => `${path} не найден`,
+        answers: (path, status) => `${path} отвечает ${status}, AI-агенты не могут его прочитать`,
+        skipNoArticles: "среди проверенных страниц нет статей",
+        skipNoLlms: "нет llms.txt",
+        skipNoFeed: "на сайте нет ленты",
+        skipOneLanguage: "сайт на одном языке",
+        skipNoSitemap: "нет sitemap.xml",
         returnsHtml: "отдаёт HTML, а не Markdown",
         noH1: "не начинается с заголовка `# Название`",
         noSummary: "нет строки `> описание`",

package/dist/index.d.ts

@@ -14,12 +14,14 @@ export interface Report extends Score {
     checkedAt: string;
     pages: string[];
     findings: Finding[];
+    /** `skipped` is the reason a check did not run on this site. */
     rules: {
         id: string;
         group: Group;
         level: Level;
         title: string;
         fix: string;
+        skipped?: string;
     }[];
 }
 export declare function audit(target: string, opts?: {

package/dist/index.js

@@ -11,7 +11,9 @@ export async function audit(target, opts = {}) {
     const t = messages(config.lang);
     const site = await crawl(target, opts.base, { maxPages: config.maxPages, urls: opts.urls, log: opts.log });
     const active = rules.filter((r) => !config.disable.includes(r.id));
-    const findings = active.flatMap((r) => r.run(site, config, t.m));
+    // A check that cannot run here is reported as «not checked» with the reason, never as passed.
+    const skipped = new Map(active.map((r) => [r.id, r.applies?.(site, t.m) ?? null]));
+    const findings = active.filter((r) => !skipped.get(r.id)).flatMap((r) => r.run(site, config, t.m));
     return {
         site: site.base,
         lang: config.lang,
@@ -19,6 +21,6 @@ export async function audit(target, opts = {}) {
         pages: site.pages.map((p) => p.fetched.publicUrl),
         ...scoreOf(findings),
         findings,
-        rules: active.map(({ id, group, level }) => ({ id, group, level, ...t.rules[id] })),
+        rules: active.map(({ id, group, level }) => ({ id, group, level, ...t.rules[id], ...(skipped.get(id) ? { skipped: skipped.get(id) } : {}) })),
     };
 }

package/dist/report.js

@@ -37,6 +37,10 @@ export function toMarkdown(r) {
             continue;
         lines.push(`**${g}. ${t.groups[g]}**`, "");
         for (const rule of list) {
+            if (rule.skipped) {
+                lines.push(`- – ${rule.id} ${rule.title} — ${t.notChecked}: ${rule.skipped}`);
+                continue;
+            }
             const found = byRule.get(rule.id) ?? [];
             const n = (level) => found.filter((f) => f.level === level).length;
             const icon = found.length ? ICON[found.reduce((w, f) => (ORDER[f.level] < ORDER[w] ? f.level : w), "info")] : "✓";

package/dist/rules/access.js

@@ -81,6 +81,9 @@ export const accessRules = [
         id: "A-5",
         group: "A",
         level: "info",
+        applies(site, t) {
+            return site.feeds.length || site.undeclaredFeed ? null : t.skipNoFeed;
+        },
         run(site, _config, t) {
             const { out, add } = finder(this);
             if (site.undeclaredFeed)

package/dist/rules/content.js

@@ -13,11 +13,16 @@ const TO_AI = [
     /игнорируй(те)? (все )?(предыдущие|прошлые) инструкции/iu,
 ];
 const datePart = (s) => s.slice(0, 10);
+/** llms.txt that answered 200 with text, not an HTML page served at that address (a common SPA fallback). */
+const llmsReadable = (site) => Boolean(site.llms && !/^\s*<(!doctype|html)/i.test(site.llms.body));
 export const contentRules = [
     {
         id: "D-2",
         group: "D",
         level: "warn",
+        applies(site, t) {
+            return site.pages.some(isArticle) ? null : t.skipNoArticles;
+        },
         run(site, _config, t) {
             const { out, add } = finder(this);
             for (const page of site.pages) {
@@ -39,7 +44,8 @@ export const contentRules = [
         run(site, _config, t) {
             const { out, add } = finder(this);
             if (!site.llms) {
-                add("site", t.notFound("/llms.txt"));
+                const a = site.llmsAttempt;
+                add("site", a.status === 404 || a.status === 410 ? t.notFound("/llms.txt") : t.answers("/llms.txt", a.error ?? `HTTP ${a.status}`));
                 return out;
             }
             const body = site.llms.body;
@@ -61,6 +67,9 @@ export const contentRules = [
         id: "E-2",
         group: "E",
         level: "error",
+        applies(site, t) {
+            return llmsReadable(site) ? null : t.skipNoLlms;
+        },
         run(site, _config, t) {
             const { out, add } = finder(this);
             const inSitemap = new Set((site.sitemap?.urls ?? []).map((u) => u.loc.replace(/\/$/, "")));
@@ -77,6 +86,12 @@ export const contentRules = [
         id: "E-3",
         group: "E",
         level: "info",
+        applies(site, t) {
+            if (!llmsReadable(site))
+                return t.skipNoLlms;
+            const langs = new Set(site.pages.flatMap((p) => p.hreflang.map((h) => h.lang)).filter((l) => l !== "x-default"));
+            return langs.size > 1 ? null : t.skipOneLanguage;
+        },
         run(site, _config, t) {
             const { out, add } = finder(this);
             const langs = new Set(site.pages.flatMap((p) => p.hreflang.map((h) => h.lang)).filter((l) => l !== "x-default"));
@@ -89,6 +104,9 @@ export const contentRules = [
         id: "E-5",
         group: "E",
         level: "info",
+        applies(site, t) {
+            return llmsReadable(site) ? null : t.skipNoLlms;
+        },
         run(site, _config, t) {
             const { out, add } = finder(this);
             if (!site.llmsFull) {
@@ -110,6 +128,11 @@ export const contentRules = [
         id: "F-1",
         group: "F",
         level: "warn",
+        applies(site, t) {
+            if (!site.sitemap)
+                return t.skipNoSitemap;
+            return site.pages.some(isArticle) ? null : t.skipNoArticles;
+        },
         run(site, _config, t) {
             const { out, add } = finder(this);
             if (!site.sitemap)

package/dist/rules/entities.js

@@ -1,5 +1,5 @@
 import { types } from "../html.js";
-import { ENTITY_TYPES, articleNode, finder, isA, str } from "./util.js";
+import { ENTITY_TYPES, articleNode, finder, isA, isArticle, str } from "./util.js";
 const idOf = (v) => (v && typeof v === "object" ? str(v["@id"]) : "");
 const authors = (node) => {
     const a = node.author;
@@ -48,6 +48,9 @@ export const entityRules = [
         id: "C-2",
         group: "C",
         level: "warn",
+        applies(site, t) {
+            return site.pages.some(isArticle) ? null : t.skipNoArticles;
+        },
         run(site, _config, t) {
             const { out, add } = finder(this);
             const ids = new Set(definitions(site).map(({ n }) => str(n["@id"])).filter(Boolean));
@@ -70,6 +73,9 @@ export const entityRules = [
         id: "C-4",
         group: "C",
         level: "error",
+        applies(site, t) {
+            return site.pages.some(isArticle) ? null : t.skipNoArticles;
+        },
         run(site, _config, t) {
             const { out, add } = finder(this);
             for (const page of site.pages) {

package/dist/types.d.ts

@@ -80,7 +80,9 @@ export interface Site {
     } | null;
     sitemap: Sitemap | null;
     pages: Page[];
+    /** /llms.txt when it answered 200, else null; llmsAttempt keeps the raw answer for the message (404, 403…). */
     llms: Fetched | null;
+    llmsAttempt: Fetched;
     llmsFull: Fetched | null;
     feeds: Fetched[];
     /** Same page fetched with each AI user agent (rule A-3). */
@@ -110,5 +112,10 @@ export interface Rule {
     id: RuleId;
     group: Group;
     level: Level;
+    /**
+     * Why the check cannot run on this site («no articles among the audited pages», «no llms.txt»), or null when it can.
+     * A check that does not apply is shown as «not checked» instead of a green tick.
+     */
+    applies?(site: Site, t: Messages["m"]): string | null;
     run(site: Site, config: Config, t: Messages["m"]): Finding[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-search-auditor",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Checks whether AI search (ChatGPT, Claude, Perplexity, Google AI Overviews) can read, understand and cite your site: robots.txt for AI agents, text without JavaScript, JSON-LD authorship, llms.txt, freshness.",
   "keywords": [
     "ai search audit",