search-auditor 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (2026-11-04)
+
+
+### New checks and features
+
+* classic SEO and AI search checks in one report ([#1](https://github.com/a-bibikov/search-auditor/issues/1)) ([450ff97](https://github.com/a-bibikov/search-auditor/commit/450ff97db5f950e2708500ccd3389f4b97d5ab90))
+* classic SEO and AI search checks in one report ([#1](https://github.com/a-bibikov/search-auditor/issues/1)) ([c272847](https://github.com/a-bibikov/search-auditor/commit/c272847b6b4ecaf5910e89bbc4e203480e00d324))
+
+
+### Fixes
+
+* start versions at 0.1.0 ([#4](https://github.com/a-bibikov/search-auditor/issues/4)) ([d1d10c5](https://github.com/a-bibikov/search-auditor/commit/d1d10c5c25435f5eabdffd8c104473e82254ef45))
+* start versions at 0.1.0 ([#4](https://github.com/a-bibikov/search-auditor/issues/4)) ([acbccc4](https://github.com/a-bibikov/search-auditor/commit/acbccc44da99a0eed0b2eeb42dbfa41d3330ccfc))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Bibikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+# search-auditor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Can Google, Bing and AI search find, read and cite your site?** One crawl, one report: classic SEO checks — status codes, canonical, sitemap, titles, headings, broken links, hreflang, HTTPS — and the AI search checks of [ai-search-auditor](https://github.com/a-bibikov/ai-search-audit), with a score for each and one overall.
+
+```bash
+npx search-auditor https://example.com
+```
+
+No sign-up, no API keys. Node.js 22.18+.
+
+## Why both in one report
+
+People find sites in two ways now: a list of links in Google, Bing or Yandex, and an answer from ChatGPT, Claude, Perplexity or Google AI Overviews that cites a few sources. Both start from the same thing — a crawler that can reach the page, read it and tell what it is about — and then they diverge. A broken canonical drops a page from Google; a heading that glues words together makes AI search misquote it.
+
+Running two tools means two crawls, two reports and two scores that never meet. search-auditor crawls once, runs both rule sets on the same pages and puts the results side by side, so the first three things to fix are the three that cost the most, whichever kind of search they hurt.
+
+## What it checks
+
+24 classic search checks in ten groups, plus the 20 AI search checks of ai-search-auditor (turn them off with `--no-ai`). Nothing is checked twice: robots.txt for search crawlers, `noindex` and link cards are part of the AI search set.
+
+**IDX. Indexing**
+- **IDX-1** Audited pages answer 200
+- **IDX-2** A page that does not exist answers 404, and no «not found» page answers 200
+
+**SEC. HTTPS** (live sites only)
+- **SEC-1** The site is on https, and http:// redirects to it
+- **SEC-2** Pages do not load anything over http://
+
+**CAN. Canonical**
+- **CAN-1** Every page has a canonical
+- **CAN-2** The canonical is an absolute address on this site
+- **CAN-3** The canonical leads to a page that answers 200, not to an error or a redirect
+
+**MAP. Sitemap**
+- **MAP-1** There is a sitemap, and robots.txt points to it
+- **MAP-2** Sitemap addresses do not redirect
+- **MAP-3** Sitemap pages are their own canonical
+
+**META. Titles and descriptions**
+- **META-1** Every page has a title of about 10–60 characters
+- **META-2** Every page has a description of about 50–160 characters
+- **META-3** Titles and descriptions are not repeated across pages
+
+**STR. Page structure**
+- **STR-1** One H1 per page
+- **STR-2** Heading levels do not skip
+- **STR-3** The page declares its language
+- **STR-4** Pages are set up for mobile
+
+**LNK. Links**
+- **LNK-1** Internal links work
+- **LNK-2** Internal links do not go through redirects
+
+**IMG. Images**
+- **IMG-1** Images have alt text
+
+**DATA. Structured data**
+- **DATA-1** JSON-LD has no syntax errors
+
+**LANG. Language versions** (sites with hreflang)
+- **LANG-1** hreflang codes are valid
+- **LANG-2** Language versions point at each other
+- **LANG-3** There is an x-default
+
+Levels: `error` — search engines cannot index the page or index the wrong one; `warn` — lowers rankings or clicks; `info` — a recommendation.
+
+The report opens with the overall score and one per part («Classic search», «AI search»), then what to do first — the three changes worth the most, in plain words and with how many pages they touch — then the findings with fixes, and ends with a checklist of every check by group: ✓ OK, ✖ error, ⚠ warning, ℹ note, – not checked. A check that cannot run on a site — hreflang on a site in one language, HTTPS on a local build — is marked «not checked» with the reason, never as passed.
+
+**Score:** each part is scored like ai-search-auditor: 100 minus 15 for each check with an error and 5 for each check with a warning; a warning that covers at least half of the audited pages costs 10. The overall score is the mean of the parts. A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F below; if fewer than two thirds of the checks could run, the grade is capped at B.
+
+## Usage
+
+```bash
+# A live site
+npx search-auditor https://example.com
+
+# A local build: requests go to localhost, the report shows public URLs
+npx search-auditor http://127.0.0.1:3000 --base https://example.com
+
+# Every page in the sitemap instead of a sample of 20
+npx search-auditor https://example.com --pages all
+
+# Classic search only, report in Russian
+npx search-auditor https://example.com --no-ai --lang ru
+
+# JSON for scripts and agents
+npx search-auditor https://example.com --json --out report.json
+```
+
+| Option | |
+|---|---|
+| `--base <url>` | Public origin when auditing a local build |
+| `--pages <n\|all>` | Pages to audit: a number sampled across templates (default 20), or `all` for every page in the sitemap |
+| `--max-links <n>` | Internal links to request (default 100) |
+| `--no-ai` | Classic search checks only |
+| `--fail-on <level>` | Exit 1 on `error` (default), `warn` or `never` |
+| `--lang <lang>` | Report language: `en` (default), `ru` |
+| `--json` | JSON instead of Markdown |
+| `--out <file>` | Also write the report to a file |
+| `--config <file>` | Config file (default `search-auditor.config.json`) |
+| `-v`, `--verbose` | Show progress |
+
+Config — the options of ai-search-auditor plus two of its own:
+
+```json
+{
+  "disable": ["STR-2", "C-7"],
+  "maxPages": 20,
+  "maxLinks": 100,
+  "ai": true,
+  "trainingBots": "any",
+  "lang": "en"
+}
+```
+
+`maxPages`: a number or `"all"`. With `"all"` every page in the sitemap is audited, so raise `maxLinks` too if you want every internal link checked.
+
+In CI the Markdown report also goes to the job summary (`GITHUB_STEP_SUMMARY`).
+
+## As a library
+
+```js
+import { auditSearch, toMarkdown } from "search-auditor";
+
+const report = await auditSearch("https://example.com", { config: { lang: "en", ai: true } });
+console.log(report.score, report.sections);
+console.log(toMarkdown(report));
+```
+
+`ai-search-auditor` is a peer dependency: the crawl, the scoring and the report come from it, so both parts always run on the same engine version. The SEO checks are also exported as `seoPlugin` — rules, texts, groups and the extra requests they need — for runners that bring their own crawl.
+
+## Roadmap
+
+- **IDX-3** `noindex` and canonical do not contradict each other
+- **IDX-4** robots.txt does not block CSS and JavaScript the page needs to render
+- **CAN-4** Canonical chains: a canonical target whose own canonical points further
+- **MAP-4** Every audited page is in the sitemap; the sitemap has no pages blocked by robots.txt
+- **LNK-3** Orphan pages: in the sitemap, but no internal link leads to them
+- **LNK-4** Redirect chains of more than one hop
+- **IMG-2** Images are sized and lazy-loaded, so they do not slow the page down
+- **PERF-1** Server response time and page weight
+- **SOC-1** Twitter / X cards in addition to Open Graph
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { DEFAULT_LANG, LANGS, isLang, parsePages, toMarkdown } from "ai-search-auditor";
+import { auditSearch } from "./index.js";
+const HELP = `search-auditor — one crawl, one report: can Google, Bing and AI search (ChatGPT, Claude, Perplexity) find, read and cite your site?
+
+Usage:
+  search-auditor <url> [options]
+
+Options:
+  --base <url>        public origin when auditing a local build (links in sitemap point there)
+  --pages <n|all>     pages to audit: a number sampled across templates (default 20), or all pages in the sitemap
+  --max-links <n>     internal links to request (default 100)
+  --no-ai             classic search checks only
+  --fail-on <level>   exit 1 on: error (default), warn, never
+  --lang <lang>       report language: ${Object.keys(LANGS).join(", ")} (default ${DEFAULT_LANG})
+  --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: search-auditor.config.json if present)
+  -v, --verbose       show progress
+  -h, --help
+
+Examples:
+  npx search-auditor https://example.com
+  npx search-auditor http://127.0.0.1:3000 --base https://example.com --fail-on warn
+  npx search-auditor https://example.com --lang ru --no-ai
+  npx search-auditor https://example.com --pages all
+`;
+// An unknown or malformed flag gets one line with the help hint, not a stack trace.
+let parsed;
+try {
+    parsed = parseArgs({
+        allowPositionals: true,
+        allowNegative: true,
+        options: {
+            base: { type: "string" },
+            pages: { type: "string" },
+            "max-links": { type: "string" },
+            ai: { type: "boolean" },
+            "fail-on": { type: "string", default: "error" },
+            lang: { type: "string" },
+            json: { type: "boolean", default: false },
+            out: { type: "string" },
+            config: { type: "string" },
+            verbose: { type: "boolean", short: "v", default: false },
+            help: { type: "boolean", short: "h", default: false },
+        },
+    });
+}
+catch (e) {
+    process.stderr.write(`search-auditor: ${e.message.split(". To specify")[0]}\nRun with --help to see the options.\n`);
+    process.exit(2);
+}
+const { values, positionals } = parsed;
+const target = positionals[0];
+if (values.help || !target) {
+    process.stdout.write(HELP);
+    process.exit(values.help ? 0 : 2);
+}
+// A function declaration, not an arrow: TypeScript treats only declared `never` functions as the end of a branch.
+function fail(message) {
+    process.stderr.write(`search-auditor: ${message}\n`);
+    process.exit(2);
+}
+const count = (name, v) => {
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 1)
+        fail(`--${name} must be a whole number above 0, got «${v}»`);
+    return n;
+};
+const url = /^https?:\/\//.test(target) ? target : `https://${target}`;
+const configPath = values.config ?? (existsSync("search-auditor.config.json") ? "search-auditor.config.json" : undefined);
+const fileConfig = configPath ? JSON.parse(readFileSync(configPath, "utf8")) : {};
+// Flags win over the config file; an unknown language stops before any request is made.
+const lang = values.lang ?? fileConfig.lang ?? DEFAULT_LANG;
+if (!isLang(lang))
+    fail(`unknown language «${lang}», use one of: ${Object.keys(LANGS).join(", ")}`);
+if (!["error", "warn", "never"].includes(values["fail-on"]))
+    fail(`--fail-on must be error, warn or never, got «${values["fail-on"]}»`);
+const pagesRaw = values.pages ?? fileConfig.maxPages;
+const maxPages = pagesRaw === undefined ? undefined : parsePages(pagesRaw);
+if (maxPages === null)
+    fail(`${values.pages !== undefined ? "--pages" : "maxPages in the config"} must be a whole number above 0 or «all», got «${pagesRaw}»`);
+const maxLinks = count("max-links", values["max-links"]);
+const config = {
+    ...fileConfig,
+    lang,
+    ...(maxPages ? { maxPages } : {}),
+    ...(maxLinks ? { maxLinks } : {}),
+    ...(values.ai === false ? { ai: false } : {}),
+};
+// Progress goes to stderr, so `--json > report.json` stays clean.
+const log = values.verbose ? (line) => process.stderr.write(`· ${line}\n`) : undefined;
+let report;
+try {
+    report = await auditSearch(url, { base: values.base, config, log });
+}
+catch (e) {
+    fail(e.message);
+}
+const markdown = toMarkdown(report);
+process.stdout.write(values.json ? JSON.stringify(report, null, 2) + "\n" : markdown);
+if (values.out)
+    writeFileSync(values.out, values.out.endsWith(".json") ? JSON.stringify(report, null, 2) : markdown);
+if (process.env.GITHUB_STEP_SUMMARY)
+    appendFileSync(process.env.GITHUB_STEP_SUMMARY, markdown);
+const failOn = values["fail-on"];
+const failed = failOn === "never" ? false : failOn === "warn" ? report.counts.error + report.counts.warn > 0 : report.counts.error > 0;
+process.exit(failed ? 1 : 0);

package/dist/collect.d.ts

@@ -0,0 +1,14 @@
+import { type Site } from "ai-search-auditor";
+import type { SeoExtras, SeoSite } from "./types.ts";
+export interface CollectOptions {
+    maxLinks: number;
+    concurrency?: number;
+    log?: (line: string) => void;
+}
+/**
+ * Extra requests for the SEO checks, in the same run as the shared crawl: a made-up URL that must answer 404,
+ * canonical targets outside the sample, internal links (capped by maxLinks) and, for a live https site,
+ * the home page over plain http://.
+ */
+export declare function collect(site: Site, opts: CollectOptions): Promise<SeoSite>;
+export declare const seoOf: (site: Site) => SeoExtras;

package/dist/collect.js

@@ -0,0 +1,74 @@
+import { fetchUrl, isSameSite, pool } from "ai-search-auditor";
+import { norm } from "./rules/util.js";
+const probeOf = (f, from) => ({
+    status: f.status,
+    redirected: Boolean(f.redirected),
+    finalUrl: f.finalUrl ?? f.publicUrl,
+    ...(f.error ? { error: f.error } : {}),
+    ...(from ? { from } : {}),
+});
+/** Links worth requesting: pages, not files a crawler would not index anyway. */
+const isPageLike = (url) => !/\.(png|jpe?g|gif|webp|avif|svg|ico|css|js|mjs|map|woff2?|ttf|otf|mp4|webm|mp3|zip|gz)(\?|$)/i.test(new URL(url).pathname);
+/**
+ * Extra requests for the SEO checks, in the same run as the shared crawl: a made-up URL that must answer 404,
+ * canonical targets outside the sample, internal links (capped by maxLinks) and, for a live https site,
+ * the home page over plain http://.
+ */
+export async function collect(site, opts) {
+    const o = { target: site.target, base: site.base };
+    const conc = opts.concurrency ?? 6;
+    const log = opts.log ?? (() => { });
+    // A local build (--base) or a dev server: HTTPS and the http:// redirect are the live site's business.
+    const local = site.target !== site.base || /^(localhost|127\.\d+\.\d+\.\d+|\[::1\])$/.test(new URL(site.base).hostname);
+    // Everything the crawl already requested, so nothing is fetched twice.
+    const known = new Map();
+    for (const p of site.pages)
+        known.set(norm(p.fetched.publicUrl), probeOf(p.fetched));
+    for (const f of site.failed)
+        known.set(norm(f.publicUrl), probeOf(f));
+    const canonicalTargets = [
+        ...new Set(site.pages
+            .map((p) => {
+            try {
+                return p.canonical ? new URL(p.canonical, p.fetched.publicUrl).href : "";
+            }
+            catch {
+                return "";
+            }
+        })
+            .filter((u) => u && isSameSite(u, o) && !known.has(norm(u)))),
+    ].slice(0, 20);
+    const firstSeen = new Map();
+    for (const p of site.pages)
+        for (const href of p.links)
+            if (isSameSite(href, o) && isPageLike(href) && !firstSeen.has(norm(href)))
+                firstSeen.set(norm(href), p.fetched.publicUrl);
+    const linkTargets = [...firstSeen.keys()].filter((u) => !known.has(u));
+    const toCheck = linkTargets.slice(0, opts.maxLinks);
+    log(`${canonicalTargets.length} canonical targets, ${toCheck.length} of ${firstSeen.size} internal links`);
+    const light = { maxBytes: 65_536, timeoutMs: 10_000 };
+    const [probe404, httpHome, canonicals, linked] = await Promise.all([
+        fetchUrl(`${site.target}/__search-auditor-${Math.random().toString(36).slice(2, 10)}`, o, light),
+        !local && site.base.startsWith("https://") ? fetchUrl(`http://${new URL(site.base).host}/`, o, light) : Promise.resolve(null),
+        pool(canonicalTargets, conc, (u) => fetchUrl(u, o, light)),
+        pool(toCheck, conc, (u) => fetchUrl(u, o, light)),
+    ]);
+    const links = new Map();
+    for (const [url, from] of firstSeen) {
+        const done = known.get(url);
+        if (done)
+            links.set(url, { ...done, from });
+    }
+    toCheck.forEach((url, i) => links.set(url, probeOf(linked[i], firstSeen.get(url))));
+    const seo = {
+        local,
+        probe404,
+        httpHome,
+        canonicals: new Map(canonicalTargets.map((u, i) => [norm(u), probeOf(canonicals[i])])),
+        links,
+        linksFound: firstSeen.size,
+        linksChecked: links.size,
+    };
+    return Object.assign(site, { seo });
+}
+export const seoOf = (site) => site.seo;

package/dist/i18n/en.d.ts

@@ -0,0 +1,194 @@
+/**
+ * English texts of the SEO checks: the reference for every other language. A new language is a file typed as
+ * `SeoMessages` (TypeScript lists what is missing) plus a line in ./index.ts. AI search texts come from ai-search-auditor.
+ */
+export declare const en: {
+    report: {
+        title: (site: string) => string;
+        clean: string;
+        footer: (pages: number, date: string) => string;
+        classic: string;
+        ai: string;
+    };
+    groups: {
+        IDX: string;
+        CAN: string;
+        MAP: string;
+        META: string;
+        STR: string;
+        LNK: string;
+        IMG: string;
+        DATA: string;
+        LANG: string;
+        SEC: string;
+    };
+    rules: {
+        "IDX-1": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "IDX-2": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "CAN-1": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "CAN-2": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "CAN-3": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "MAP-1": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "MAP-2": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "MAP-3": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "META-1": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "META-2": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "META-3": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "STR-1": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "STR-2": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "STR-3": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "STR-4": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "LNK-1": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "LNK-2": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "IMG-1": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "DATA-1": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "LANG-1": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "LANG-2": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "LANG-3": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "SEC-1": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+        "SEC-2": {
+            title: string;
+            fix: string;
+            impact: string;
+        };
+    };
+    /** Finding messages. URLs and quotes come in already formatted. */
+    m: {
+        status: (status: string) => string;
+        soft404Probe: (url: string) => string;
+        soft404Page: (title: string) => string;
+        noCanonical: string;
+        relativeCanonical: (href: string) => string;
+        foreignCanonical: (href: string) => string;
+        canonicalStatus: (href: string, status: string) => string;
+        canonicalRedirects: (href: string, to: string) => string;
+        noSitemap: string;
+        sitemapNotInRobots: string;
+        sitemapRedirects: (to: string) => string;
+        sitemapCanonicalElsewhere: (href: string) => string;
+        noTitle: string;
+        titleLength: (n: number, title: string) => string;
+        noDescription: string;
+        descriptionLength: (n: number) => string;
+        sameTitle: (n: number, title: string) => string;
+        sameDescription: (n: number, text: string) => string;
+        noH1: string;
+        manyH1: (n: number) => string;
+        skippedLevel: (from: number, to: number, text: string) => string;
+        noLang: string;
+        noViewport: string;
+        brokenLink: (status: string, from: string) => string;
+        redirectLink: (to: string, from: string) => string;
+        linksNotChecked: (checked: number, found: number) => string;
+        imagesNoAlt: (n: number, total: number, example: string) => string;
+        jsonLdError: (error: string) => string;
+        badHreflang: (code: string) => string;
+        oneWayHreflang: (lang: string, href: string) => string;
+        noXDefault: (langs: string) => string;
+        notHttps: string;
+        httpNoRedirect: (to: string) => string;
+        mixedContent: (n: number, example: string) => string;
+        skipLocal: string;
+        skipNoSitemap: string;
+        skipNoHreflang: string;
+        skipOneLanguage: string;
+        skipNoImages: string;
+        skipNoJsonLd: string;
+        skipNoLinks: string;
+        skipNotHttps: string;
+    };
+};
+export type SeoMessages = typeof en;
+export type SeoRuleId = keyof SeoMessages["rules"];