@nurkamol/seo-audit 1.40.1 → 1.41.0

package/README.md

@@ -279,13 +279,17 @@ change to anything above it.
 ```
 Preview a Site     how big is this, and is it the right one — ~1s, 3 requests
 Audit a Site       crawl it and list what to change, worst first
-Recent Reports     runs the macOS app has already kept
+Recent Reports     runs the desktop app has already kept
 ```
 
-`raycast/` is a Raycast extension that imports the engine the same way the
-Worker does — `import { preview } from "../../src/audit.mjs"` — so it
-re-implements nothing and its reports match the terminal's. Raycast runs Node,
-so unlike the hosted version the certificate checks work there.
+`raycast/` is a Raycast extension for macOS and Windows. It imports the engine
+as the published `@nurkamol/seo-audit` package, so it re-implements nothing and
+its reports match the terminal's. Raycast runs Node, so unlike the hosted
+version the certificate checks work there.
+
+It is waiting for review in the Raycast Store. Until it is listed,
+[docs/raycast.md](docs/raycast.md) explains how to run it from this repository
+in about two minutes, on either platform.
 
 **Preview is the command it exists for.** A crawl takes minutes and a launcher
 is built for the second you spend in it, so the headline command is the engine's
@@ -867,6 +871,7 @@ Findings come at three levels: **error** (wrong, and costing traffic), **warning
 | `og:image` is not WebP — LinkedIn won't render it, WhatsApp is unreliable | warning |
 | `og:image` declares width and height | note |
 | `hreflang` codes are well formed — `en_US` with an underscore is the usual slip | error |
+| `hreflang` declared in the XML sitemap counts as declared — Google reads both places, and a finding says which file to fix | — |
 | `hreflang` lists the page itself, not only its translations | warning |
 | `<html lang>` agrees with what the page's own `hreflang` calls it | warning |
 | `<html lang>` agrees with the `Content-Language` header, compared by primary subtag — a header listing several languages agrees if the page's is one of them | warning |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurkamol/seo-audit",
-  "version": "1.40.1",
+  "version": "1.41.0",
   "description": "Crawl a site's sitemap and check every page for SEO, metadata and structured-data problems that single-page graders miss. Zero dependencies.",
   "type": "module",
   "bin": {

package/src/audit.mjs

@@ -165,6 +165,38 @@ async function crawlByLinks(origin, fetcher, { limit, concurrency, robotsGroups,
  * @param {string} target site origin, or a sitemap URL
  * @param {{limit?: number, concurrency?: number, sitemap?: string}} opts
  */
+/** Hreflang the sitemap declared, given to the pages it names.
+ *
+ *  Google reads hreflang from the markup **or** from the sitemap, and treats
+ *  them the same. This engine only ever read the markup, so a site that chose
+ *  the sitemap was told "No page declares hreflang" — stated as a fact about
+ *  the site, under checks reported as not applying. A check that could not run
+ *  must say so honestly, and that one was saying something false.
+ *
+ *  Only for a page whose own markup declares none. A page that declares both is
+ *  answering for itself, and quietly merging a second set into it would invent
+ *  a set neither source contains — which is how a reciprocity check starts
+ *  reporting pairs nobody wrote.
+ *
+ *  `from` travels with them so a finding can say where to go and fix it: the
+ *  line to edit is in an XML file, not in the page somebody has open.
+ */
+export function adoptSitemapHreflang(pages, entries = []) {
+  const bare = (url) => url.replace(/\/$/, '');
+  const declared = new Map(
+    entries.filter((e) => e.alternates?.length).map((e) => [bare(e.loc), e.alternates]),
+  );
+  if (!declared.size) return;
+
+  for (const page of pages) {
+    if (!page.doc || page.doc.hreflang.length) continue;
+    const alternates = declared.get(bare(page.url));
+    if (!alternates) continue;
+    page.doc.hreflang = alternates;
+    page.doc.hreflangFrom = 'sitemap';
+  }
+}
+
 export async function audit(target, opts = {}) {
   const started = Date.now();
   const fetcher = new Fetcher({ concurrency: opts.concurrency ?? 6, userAgent: opts.userAgent });
@@ -446,6 +478,8 @@ export async function audit(target, opts = {}) {
 
   onProgress?.({ phase: 'crawl', detail: `${pages.length} pages in ${((Date.now() - started) / 1000).toFixed(1)}s` });
 
+  adoptSitemapHreflang(pages, entries);
+
   for (const page of pages) findings.push(...pageChecks(page, opts.limits));
   // Click depth is measured from the homepage, and a sitemap need not list it.
   // Fetched here only when the crawl did not already have it, and the fetcher

package/src/checks.mjs

@@ -164,6 +164,18 @@ export const anchorPhrase = (name) =>
     .trim();
 
 // --- hreflang ---------------------------------------------------------------
+
+/** A sentence naming where a page's hreflang was declared, or nothing.
+ *
+ *  Only when it was not the page itself. `adoptSitemapHreflang()` in audit.mjs
+ *  gives a page the alternates its sitemap declared for it, because Google
+ *  reads both; a finding that then sends somebody to a template with no
+ *  annotation in it would be a correct finding with the wrong address on it. */
+export const hreflangSource = (doc) =>
+  doc?.hreflangFrom === 'sitemap'
+    ? ' This set is declared in the sitemap rather than in the page, so that is the file to fix.'
+    : '';
+
 // A language, optionally a script, optionally a region, joined by hyphens:
 // en, en-GB, zh-Hant, zh-Hant-TW, en-419. Case is not significant to Google.
 // Only the shape is checked, not whether the codes exist — that would mean
@@ -485,12 +497,16 @@ export function pageChecks(page, limits = DEFAULT_LIMITS) {
   // from the page alone is whether the annotation is well formed and whether
   // the page agrees with it about what the page is.
   if (doc.hreflang.length) {
+    // Where the set was declared, when it was not the page. Somebody sent to
+    // fix a malformed code should not be reading a template that never had one
+    // in it — the line to edit is in the sitemap.
+    const where = hreflangSource(doc);
     const malformed = doc.hreflang.filter((alt) => !isLanguageTag(alt.lang));
     for (const alt of malformed) {
       out.push(f('error', 'hreflang-invalid', `Malformed hreflang code: "${alt.lang}"`,
         'Google ignores an annotation it cannot parse, so this version is invisible to it. The form is ' +
           'a language, optionally a script and a region, joined by hyphens — en, en-GB, zh-Hant-TW. ' +
-          'An underscore instead of a hyphen is the usual cause.', url));
+          'An underscore instead of a hyphen is the usual cause.' + where, url));
     }
 
     // Every version has to list itself alongside the others, or the set is
@@ -499,14 +515,15 @@ export function pageChecks(page, limits = DEFAULT_LIMITS) {
     if (!self) {
       out.push(f('warn', 'hreflang-no-self', 'hreflang does not list this page',
         `It points at ${doc.hreflang.map((a) => a.lang).join(', ')} but never at itself. A version that ` +
-          'omits its own self-reference leaves the set incomplete.', url));
+          'omits its own self-reference leaves the set incomplete.' + where, url));
     } else if (doc.lang && primaryLanguage(self.lang) !== primaryLanguage(doc.lang)) {
       // The page's two statements about its own language, disagreeing. This is
       // only ever visible on a translated page, which is the kind of page a
       // homepage grader never opens.
       out.push(f('warn', 'hreflang-lang-mismatch', 'The page disagrees with its own hreflang about its language',
         `<html lang="${doc.lang}"> but hreflang calls this page "${self.lang}". Google reads both, and one ` +
-          'of them is wrong — usually a template that hardcodes lang while the annotation is generated.', url));
+          'of them is wrong — usually a template that hardcodes lang while the annotation is generated.' + where,
+        url));
     }
   }
 
@@ -1259,7 +1276,8 @@ export function crossPageChecks(pages, opts = {}) {
     if (!hasDefault) {
       out.push(f('info', 'hreflang-no-x-default', 'No x-default in the hreflang set',
         `${translated.length} pages declare alternates and none names an x-default — the version to serve ` +
-          'a visitor whose language matches none of the others. Usually the English or the country selector.',
+          'a visitor whose language matches none of the others. Usually the English or the country selector.'
+          + hreflangSource(translated[0].doc),
         translated[0].url));
     }
   }
@@ -1276,7 +1294,8 @@ export function crossPageChecks(pages, opts = {}) {
       );
       if (!returns) {
         out.push(f('error', 'hreflang-one-way', 'hreflang is not reciprocal',
-          `${p.url} → ${alt.href} (${alt.lang}), but the target does not link back. Google drops one-way pairs.`, p.url));
+          `${p.url} → ${alt.href} (${alt.lang}), but the target does not link back. Google drops one-way pairs.`
+            + hreflangSource(p.doc), p.url));
       }
     }
   }

package/src/parse.mjs

@@ -364,11 +364,18 @@ export function parseHtml(rawHtml, pageUrl) {
 
 /** URLs from a sitemap or sitemap index. Returns {urls, sitemaps, entries}.
  *
- *  `entries` pairs each <loc> with its own <lastmod>, read from inside the
- *  <url> block so a date cannot drift onto a neighbouring URL. It is additional
- *  rather than a replacement: `urls` stays a plain list of strings, because
- *  every caller wants exactly that and changing it would ripple through
- *  discovery for no gain. */
+ *  `entries` pairs each <loc> with its own <lastmod> and its own hreflang
+ *  alternates, read from inside the <url> block so neither can drift onto a
+ *  neighbouring URL. It is additional rather than a replacement: `urls` stays a
+ *  plain list of strings, because every caller wants exactly that and changing
+ *  it would ripple through discovery for no gain.
+ *
+ *  `alternates` is the same `{ lang, href }` shape `parseHtml` returns for
+ *  `<link rel="alternate" hreflang>`, because the sitemap is the other place
+ *  Google reads hreflang from and the checks should not care which one a site
+ *  chose. A site that declares them here and not in its markup was previously
+ *  told "no page declares hreflang" — a sentence about the site that was not
+ *  true of it. */
 export function parseSitemap(xml) {
   const locs = [...xml.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/gi)].map((m) => decode(m[1]));
   const isIndex = /<sitemapindex/i.test(xml);
@@ -378,12 +385,30 @@ export function parseSitemap(xml) {
     .map((m) => ({
       loc: decode(m[1].match(/<loc>\s*([^<\s]+)\s*<\/loc>/i)?.[1] ?? ''),
       lastmod: m[1].match(/<lastmod>\s*([^<\s]+)\s*<\/lastmod>/i)?.[1] ?? null,
+      alternates: sitemapAlternates(m[1]),
     }))
     .filter((entry) => entry.loc);
 
   return { urls: locs, sitemaps: [], entries };
 }
 
+/** The hreflang alternates declared inside one <url> block.
+ *
+ *  The prefix is whatever the file bound the XHTML namespace to — `xhtml:link`
+ *  is the convention Google documents, and a bare `<link>` is what a generator
+ *  that declared the namespace as the default emits. Matching any prefix costs
+ *  nothing here: a `<url>` block has no other kind of link in it.
+ *
+ *  `rel` is required to be `alternate` rather than assumed, and an entry with
+ *  no `hreflang` or no `href` is dropped — half a declaration is not one. */
+function sitemapAlternates(block) {
+  return [...block.matchAll(/<(?:[a-z0-9]+:)?link\b[^>]*>/gi)]
+    .map((m) => m[0])
+    .filter((tag) => (attr(tag, 'rel') ?? '').toLowerCase() === 'alternate')
+    .map((tag) => ({ lang: attr(tag, 'hreflang'), href: decode(attr(tag, 'href') ?? '') }))
+    .filter((alt) => alt.lang && alt.href);
+}
+
 /**
  * What a response body actually is, when the server has already claimed it is
  * HTML. Returns `null` for anything that might be HTML, and a noun for the

package/src/site.mjs

@@ -5,7 +5,7 @@ import { mapLimit } from './http.mjs';
 import { parseRobots, robotsVerdict } from './robots.mjs';
 import { aiAccess, describeAccess } from './agents-ai.mjs';
 import { parseHtml } from './parse.mjs';
-import { schemaNodes, seriesOf, paginatedCanonical } from './checks.mjs';
+import { schemaNodes, seriesOf, paginatedCanonical, hreflangSource } from './checks.mjs';
 import { similarity } from './dupes.mjs';
 import {
   resolve as resolveDns, certificateNames, collapseFleets, rankHosts, looksLikeStaging, NXDOMAIN,
@@ -638,9 +638,13 @@ export async function siteChecks(origin, fetcher, pages, opts = {}) {
   }
   for (const [source, dead] of deadByPage) {
     const shown = dead.slice(0, 3).join(', ');
+    // Same reason as the page-level hreflang findings: a set adopted from the
+    // sitemap is fixed in the sitemap, not on the page that carries it.
+    const doc = pages.find((p) => p.url === source)?.doc;
     out.push(f('error', 'hreflang-dead', `${plural(dead.length, 'hreflang target')} do not load`,
       `${shown}${dead.length > 3 ? `, and ${dead.length - 3} more` : ''} — declared on ${source}. Each ` +
-        'version that does not load drops out of the set, and the pages pointing at it lose the annotation.',
+        'version that does not load drops out of the set, and the pages pointing at it lose the annotation.'
+        + hreflangSource(doc),
       source));
   }